From 7ea5a1d2f143c2760bf87aee1773484fdb67729c Mon Sep 17 00:00:00 2001 From: Leonard Lyubich Date: Fri, 12 Nov 2021 19:10:39 +0300 Subject: [PATCH] [#150] *: Write status-related docs Signed-off-by: Leonard Lyubich --- accounting/service.proto | 5 ++ container/service.proto | 35 ++++++++++ netmap/service.proto | 10 +++ object/service.proto | 35 ++++++++++ proto-docs/accounting.md | 5 ++ proto-docs/container.md | 35 ++++++++++ proto-docs/netmap.md | 10 +++ proto-docs/object.md | 35 ++++++++++ proto-docs/reputation.md | 10 +++ proto-docs/session.md | 6 ++ proto-docs/status.md | 138 +++++++++++++++++++++++++++++++++++++++ reputation/service.proto | 10 +++ session/service.proto | 5 ++ session/types.proto | 1 + status/types.proto | 61 +++++++++++++++-- 15 files changed, 395 insertions(+), 6 deletions(-) create mode 100644 proto-docs/status.md diff --git a/accounting/service.proto b/accounting/service.proto index f648970..d2f99df 100644 --- a/accounting/service.proto +++ b/accounting/service.proto @@ -16,6 +16,11 @@ import "session/types.proto"; // accounts are possible, if both use the same token type. service AccountingService { // Returns the amount of funds in GAS token for the requested NeoFS account. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // balance has been successfully read; + // - Common failures (SECTION_FAILURE_COMMON). rpc Balance (BalanceRequest) returns (BalanceResponse); } diff --git a/container/service.proto b/container/service.proto index 9a23258..41c88eb 100644 --- a/container/service.proto +++ b/container/service.proto @@ -19,30 +19,65 @@ service ContainerService { // response immediately. After a new block is issued in sidechain, request is // verified by Inner Ring nodes. After one more block in sidechain, container // is added into smart contract storage. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // request to save the container has been sent to the sidechain; + // - Common failures (SECTION_FAILURE_COMMON). rpc Put(PutRequest) returns (PutResponse); // `Delete` invokes `Container` smart contract's `Delete` method and returns // response immediately. After a new block is issued in sidechain, request is // verified by Inner Ring nodes. After one more block in sidechain, container // is added into smart contract storage. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // request to remove the container has been sent to the sidechain; + // - Common failures (SECTION_FAILURE_COMMON). rpc Delete(DeleteRequest) returns (DeleteResponse); // Returns container structure from `Container` smart contract storage. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // container has been successfully read; + // - Common failures (SECTION_FAILURE_COMMON). rpc Get(GetRequest) returns (GetResponse); // Returns all owner's containers from 'Container` smart contract' storage. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // container list has been successfully read; + // - Common failures (SECTION_FAILURE_COMMON). rpc List(ListRequest) returns (ListResponse); // Invokes 'SetEACL' method of 'Container` smart contract and returns response // immediately. After one more block in sidechain, Extended ACL changes are // added into smart contract storage. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // request to save container eACL has been sent to the sidechain; + // - Common failures (SECTION_FAILURE_COMMON). rpc SetExtendedACL(SetExtendedACLRequest) returns (SetExtendedACLResponse); // Returns Extended ACL table and signature from `Container` smart contract // storage. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // container eACL has been successfully read; + // - Common failures (SECTION_FAILURE_COMMON). rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse); // Announce container used space values for P2P synchronization. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // estimation of used space has been successfully announced; + // - Common failures (SECTION_FAILURE_COMMON). rpc AnnounceUsedSpace(AnnounceUsedSpaceRequest) returns (AnnounceUsedSpaceResponse); } diff --git a/netmap/service.proto b/netmap/service.proto index 95e21a1..5a573c6 100644 --- a/netmap/service.proto +++ b/netmap/service.proto @@ -19,9 +19,19 @@ service NetmapService { // want to get recent information directly, or to talk to the node not yet // present in `Network Map` to find out what API version can be used for // further communication. Can also be used to check if node is up and running. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // information about the server has been successfully read; + // - Common failures (SECTION_FAILURE_COMMON). rpc LocalNodeInfo (LocalNodeInfoRequest) returns (LocalNodeInfoResponse); // Read recent information about the NeoFS network. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // information about the current network state has been successfully read; + // - Common failures (SECTION_FAILURE_COMMON). rpc NetworkInfo (NetworkInfoRequest) returns (NetworkInfoResponse); } diff --git a/object/service.proto b/object/service.proto index 8f94049..c608e98 100644 --- a/object/service.proto +++ b/object/service.proto @@ -18,6 +18,11 @@ service ObjectService { // messages, except the first one, carry payload chunks. Requested object can // be restored by concatenation of object message payload and all chunks // keeping receiving order. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // object has been successfully read; + // - Common failures (SECTION_FAILURE_COMMON). rpc Get(GetRequest) returns (stream GetResponse); // Put the object into container. Request uses gRPC stream. First message @@ -26,32 +31,62 @@ service ObjectService { // session package). Chunk messages are considered by server as a part of an // object payload. All messages, except first one, SHOULD be payload chunks. // Chunk messages SHOULD be sent in direct order of fragmentation. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // object has been successfully saved in the container; + // - Common failures (SECTION_FAILURE_COMMON). rpc Put(stream PutRequest) returns (PutResponse); // Delete the object from a container. There is no immediate removal // guarantee. Object will be marked for removal and deleted eventually. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // object has been successfully marked to be removed from the container; + // - Common failures (SECTION_FAILURE_COMMON). rpc Delete(DeleteRequest) returns (DeleteResponse); // Returns the object Headers without data payload. By default full header is // returned. If `main_only` request field is set, the short header with only // the very minimal information would be returned instead. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // object header has been successfully read; + // - Common failures (SECTION_FAILURE_COMMON). rpc Head(HeadRequest) returns (HeadResponse); // Search objects in container. Search query allows to match by Object // Header's filed values. Please see the corresponding NeoFS Technical // Specification section for more details. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // objects have been successfully selected; + // - Common failures (SECTION_FAILURE_COMMON). rpc Search(SearchRequest) returns (stream SearchResponse); // Get byte range of data payload. Range is set as an (offset, length) tuple. // Like in `Get` method, the response uses gRPC stream. Requested range can be // restored by concatenation of all received payload chunks keeping receiving // order. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // data range of the object payload has been successfully read; + // - Common failures (SECTION_FAILURE_COMMON). rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse); // Returns homomorphic or regular hash of object's payload range after // applying XOR operation with the provided `salt`. Ranges are set of (offset, // length) tuples. Hashes order in response corresponds to ranges order in // request. Note that hash is calculated for XORed data. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // data range of the object payload has been successfully hashed; + // - Common failures (SECTION_FAILURE_COMMON). rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse); } diff --git a/proto-docs/accounting.md b/proto-docs/accounting.md index 8050a1a..6d36189 100644 --- a/proto-docs/accounting.md +++ b/proto-docs/accounting.md @@ -50,6 +50,11 @@ rpc Balance(BalanceRequest) returns (BalanceResponse); Returns the amount of funds in GAS token for the requested NeoFS account. +Statuses: +- **OK** (0, SECTION_SUCCESS): +balance has been successfully read; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | Balance | [BalanceRequest](#neo.fs.v2.accounting.BalanceRequest) | [BalanceResponse](#neo.fs.v2.accounting.BalanceResponse) | diff --git a/proto-docs/container.md b/proto-docs/container.md index dd99da0..13bd4db 100644 --- a/proto-docs/container.md +++ b/proto-docs/container.md @@ -84,6 +84,11 @@ response immediately. After a new block is issued in sidechain, request is verified by Inner Ring nodes. After one more block in sidechain, container is added into smart contract storage. +Statuses: +- **OK** (0, SECTION_SUCCESS): +request to save the container has been sent to the sidechain; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | Put | [PutRequest](#neo.fs.v2.container.PutRequest) | [PutResponse](#neo.fs.v2.container.PutResponse) | @@ -94,6 +99,11 @@ response immediately. After a new block is issued in sidechain, request is verified by Inner Ring nodes. After one more block in sidechain, container is added into smart contract storage. +Statuses: +- **OK** (0, SECTION_SUCCESS): +request to remove the container has been sent to the sidechain; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | Delete | [DeleteRequest](#neo.fs.v2.container.DeleteRequest) | [DeleteResponse](#neo.fs.v2.container.DeleteResponse) | @@ -101,6 +111,11 @@ is added into smart contract storage. Returns container structure from `Container` smart contract storage. +Statuses: +- **OK** (0, SECTION_SUCCESS): +container has been successfully read; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | Get | [GetRequest](#neo.fs.v2.container.GetRequest) | [GetResponse](#neo.fs.v2.container.GetResponse) | @@ -108,6 +123,11 @@ Returns container structure from `Container` smart contract storage. Returns all owner's containers from 'Container` smart contract' storage. +Statuses: +- **OK** (0, SECTION_SUCCESS): +container list has been successfully read; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | List | [ListRequest](#neo.fs.v2.container.ListRequest) | [ListResponse](#neo.fs.v2.container.ListResponse) | @@ -117,6 +137,11 @@ Invokes 'SetEACL' method of 'Container` smart contract and returns response immediately. After one more block in sidechain, Extended ACL changes are added into smart contract storage. +Statuses: +- **OK** (0, SECTION_SUCCESS): +request to save container eACL has been sent to the sidechain; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | SetExtendedACL | [SetExtendedACLRequest](#neo.fs.v2.container.SetExtendedACLRequest) | [SetExtendedACLResponse](#neo.fs.v2.container.SetExtendedACLResponse) | @@ -125,6 +150,11 @@ added into smart contract storage. Returns Extended ACL table and signature from `Container` smart contract storage. +Statuses: +- **OK** (0, SECTION_SUCCESS): +container eACL has been successfully read; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | GetExtendedACL | [GetExtendedACLRequest](#neo.fs.v2.container.GetExtendedACLRequest) | [GetExtendedACLResponse](#neo.fs.v2.container.GetExtendedACLResponse) | @@ -132,6 +162,11 @@ storage. Announce container used space values for P2P synchronization. +Statuses: +- **OK** (0, SECTION_SUCCESS): +estimation of used space has been successfully announced; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | AnnounceUsedSpace | [AnnounceUsedSpaceRequest](#neo.fs.v2.container.AnnounceUsedSpaceRequest) | [AnnounceUsedSpaceResponse](#neo.fs.v2.container.AnnounceUsedSpaceResponse) | diff --git a/proto-docs/netmap.md b/proto-docs/netmap.md index 8b8b6d3..6a9ceb7 100644 --- a/proto-docs/netmap.md +++ b/proto-docs/netmap.md @@ -66,6 +66,11 @@ want to get recent information directly, or to talk to the node not yet present in `Network Map` to find out what API version can be used for further communication. Can also be used to check if node is up and running. +Statuses: +- **OK** (0, SECTION_SUCCESS): +information about the server has been successfully read; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | LocalNodeInfo | [LocalNodeInfoRequest](#neo.fs.v2.netmap.LocalNodeInfoRequest) | [LocalNodeInfoResponse](#neo.fs.v2.netmap.LocalNodeInfoResponse) | @@ -73,6 +78,11 @@ further communication. Can also be used to check if node is up and running. Read recent information about the NeoFS network. +Statuses: +- **OK** (0, SECTION_SUCCESS): +information about the current network state has been successfully read; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | NetworkInfo | [NetworkInfoRequest](#neo.fs.v2.netmap.NetworkInfoRequest) | [NetworkInfoResponse](#neo.fs.v2.netmap.NetworkInfoResponse) | diff --git a/proto-docs/object.md b/proto-docs/object.md index 2226eb8..a860242 100644 --- a/proto-docs/object.md +++ b/proto-docs/object.md @@ -92,6 +92,11 @@ messages, except the first one, carry payload chunks. Requested object can be restored by concatenation of object message payload and all chunks keeping receiving order. +Statuses: +- **OK** (0, SECTION_SUCCESS): +object has been successfully read; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | Get | [GetRequest](#neo.fs.v2.object.GetRequest) | [GetResponse](#neo.fs.v2.object.GetResponse) | @@ -104,6 +109,11 @@ session package). Chunk messages are considered by server as a part of an object payload. All messages, except first one, SHOULD be payload chunks. Chunk messages SHOULD be sent in direct order of fragmentation. +Statuses: +- **OK** (0, SECTION_SUCCESS): +object has been successfully saved in the container; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | Put | [PutRequest](#neo.fs.v2.object.PutRequest) | [PutResponse](#neo.fs.v2.object.PutResponse) | @@ -112,6 +122,11 @@ Chunk messages SHOULD be sent in direct order of fragmentation. Delete the object from a container. There is no immediate removal guarantee. Object will be marked for removal and deleted eventually. +Statuses: +- **OK** (0, SECTION_SUCCESS): +object has been successfully marked to be removed from the container; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | Delete | [DeleteRequest](#neo.fs.v2.object.DeleteRequest) | [DeleteResponse](#neo.fs.v2.object.DeleteResponse) | @@ -121,6 +136,11 @@ Returns the object Headers without data payload. By default full header is returned. If `main_only` request field is set, the short header with only the very minimal information would be returned instead. +Statuses: +- **OK** (0, SECTION_SUCCESS): +object header has been successfully read; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | Head | [HeadRequest](#neo.fs.v2.object.HeadRequest) | [HeadResponse](#neo.fs.v2.object.HeadResponse) | @@ -130,6 +150,11 @@ Search objects in container. Search query allows to match by Object Header's filed values. Please see the corresponding NeoFS Technical Specification section for more details. +Statuses: +- **OK** (0, SECTION_SUCCESS): +objects have been successfully selected; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | Search | [SearchRequest](#neo.fs.v2.object.SearchRequest) | [SearchResponse](#neo.fs.v2.object.SearchResponse) | @@ -140,6 +165,11 @@ Like in `Get` method, the response uses gRPC stream. Requested range can be restored by concatenation of all received payload chunks keeping receiving order. +Statuses: +- **OK** (0, SECTION_SUCCESS): +data range of the object payload has been successfully read; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | GetRange | [GetRangeRequest](#neo.fs.v2.object.GetRangeRequest) | [GetRangeResponse](#neo.fs.v2.object.GetRangeResponse) | @@ -150,6 +180,11 @@ applying XOR operation with the provided `salt`. Ranges are set of (offset, length) tuples. Hashes order in response corresponds to ranges order in request. Note that hash is calculated for XORed data. +Statuses: +- **OK** (0, SECTION_SUCCESS): +data range of the object payload has been successfully hashed; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | GetRangeHash | [GetRangeHashRequest](#neo.fs.v2.object.GetRangeHashRequest) | [GetRangeHashResponse](#neo.fs.v2.object.GetRangeHashResponse) | diff --git a/proto-docs/reputation.md b/proto-docs/reputation.md index 12a9d57..3802c39 100644 --- a/proto-docs/reputation.md +++ b/proto-docs/reputation.md @@ -59,6 +59,11 @@ rpc AnnounceIntermediateResult(AnnounceIntermediateResultRequest) returns (Annou Announce local client trust information to any node in NeoFS network. +Statuses: +- **OK** (0, SECTION_SUCCESS): +local trust has been successfully announced; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | AnnounceLocalTrust | [AnnounceLocalTrustRequest](#neo.fs.v2.reputation.AnnounceLocalTrustRequest) | [AnnounceLocalTrustResponse](#neo.fs.v2.reputation.AnnounceLocalTrustResponse) | @@ -67,6 +72,11 @@ Announce local client trust information to any node in NeoFS network. Announces the intermediate result of the iterative algorithm for calculating the global reputation of the node in NeoFS network. +Statuses: +- **OK** (0, SECTION_SUCCESS): +intermediate trust estimation has been successfully announced; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | AnnounceIntermediateResult | [AnnounceIntermediateResultRequest](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest) | [AnnounceIntermediateResultResponse](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse) | diff --git a/proto-docs/session.md b/proto-docs/session.md index ee4798c..7fb532a 100644 --- a/proto-docs/session.md +++ b/proto-docs/session.md @@ -58,6 +58,11 @@ rpc Create(CreateRequest) returns (CreateResponse); Opens a new session between two peers. +Statuses: +- **OK** (0, SECTION_SUCCESS): +session has been successfully opened; +- Common failures (SECTION_FAILURE_COMMON). + | Name | Input | Output | | ---- | ----- | ------ | | Create | [CreateRequest](#neo.fs.v2.session.CreateRequest) | [CreateResponse](#neo.fs.v2.session.CreateResponse) | @@ -198,6 +203,7 @@ Information about the response | ttl | [uint32](#uint32) | | Maximum number of intermediate nodes in the request route | | x_headers | [XHeader](#neo.fs.v2.session.XHeader) | repeated | Response X-Headers | | origin | [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | `ResponseMetaHeader` of the origin request | +| status | [neo.fs.v2.status.Status](#neo.fs.v2.status.Status) | | Status return. | diff --git a/proto-docs/status.md b/proto-docs/status.md new file mode 100644 index 0000000..7df4ca0 --- /dev/null +++ b/proto-docs/status.md @@ -0,0 +1,138 @@ +# Protocol Documentation + + +## Table of Contents + +- [status/types.proto](#status/types.proto) + + - Messages + - [Status](#neo.fs.v2.status.Status) + - [Status.Detail](#neo.fs.v2.status.Status.Detail) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

+ +## status/types.proto + + + + + + + +### Message Status +Declares the general format of the status returns of the NeoFS RPC protocol. +Status is present in all response messages. Each RPC of NeoFS protocol +describes the possible outcomes and details of the operation. + +Each status is assigned a one-to-one numeric code. Any unique result of an +operation in NeoFS is unambiguously associated with the code value. + +Numerical set of codes is split into 1024-element sections. An enumeration +is defined for each section. Values can be referred to in the following ways: + +* numerical value ranging from 0 to 4,294,967,295 (global code); + +* values from enumeration (local code). The formula for the ratio of the + local code (`L`) of a defined section (`S`) to the global one (`G`): + `G = 1024 * S + L`. + +All outcomes are divided into successful and failed, which corresponds +to the success or failure of the operation. The definition of success +follows from the semantics of RPC and the description of its purpose. +The server must not attach code that is the opposite of outcome type. + +See the set of return codes in the description for calls. + +Each status can carry developer-facing error message. It should be human +readable text in English. The server should not transmit (and the client +should not expect) useful information in the message. Field `details` +should make the return more detailed. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| code | [uint32](#uint32) | | The status code. | +| message | [string](#string) | | Developer-facing error message. | +| details | [Status.Detail](#neo.fs.v2.status.Status.Detail) | repeated | Data detailing the outcome of the operation. Must be unique by ID. | + + + + +### Message Status.Detail +Return detail. It contains additional information that can be used to +analyze the response. Each code defines a set of details that can be +attached to a status. Client should not handle details that are not +covered by the code. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| id | [uint32](#uint32) | | Detail ID. The identifier is required to determine the binary format of the detail and how to decode it. | +| value | [bytes](#bytes) | | Binary status detail. Must follow the format associated with ID. The possibility of missing a value must be explicitly allowed. | + + + + + + +### CommonFail +Section of failed statuses independent of the operation. + +| Name | Number | Description | +| ---- | ------ | ----------- | +| INTERNAL | 0 | [**1024**] Internal server error, default failure. Not detailed.. If the server cannot match failed outcome to the code , it should use this code. | + + + + + +### Section +Section identifiers. + +| Name | Number | Description | +| ---- | ------ | ----------- | +| SECTION_SUCCESS | 0 | Successful return codes. | +| SECTION_FAILURE_COMMON | 1 | Failure codes regardless of the operation. | + + + + + +### Success +Section of NeoFS successful return codes. + +| Name | Number | Description | +| ---- | ------ | ----------- | +| OK | 0 | [**0**] Default success. Not detailed. If the server cannot match successful outcome to the code, it should use this code. | + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/reputation/service.proto b/reputation/service.proto index 9dcf2a5..a556405 100644 --- a/reputation/service.proto +++ b/reputation/service.proto @@ -15,10 +15,20 @@ import "session/types.proto"; // final result is recorded. service ReputationService { // Announce local client trust information to any node in NeoFS network. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // local trust has been successfully announced; + // - Common failures (SECTION_FAILURE_COMMON). rpc AnnounceLocalTrust (AnnounceLocalTrustRequest) returns (AnnounceLocalTrustResponse); // Announces the intermediate result of the iterative algorithm for // calculating the global reputation of the node in NeoFS network. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // intermediate trust estimation has been successfully announced; + // - Common failures (SECTION_FAILURE_COMMON). rpc AnnounceIntermediateResult (AnnounceIntermediateResultRequest) returns (AnnounceIntermediateResultResponse); } diff --git a/session/service.proto b/session/service.proto index b959755..aff4959 100644 --- a/session/service.proto +++ b/session/service.proto @@ -14,6 +14,11 @@ import "session/types.proto"; // section of NeoFS Technical Specification for details. service SessionService { // Opens a new session between two peers. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // session has been successfully opened; + // - Common failures (SECTION_FAILURE_COMMON). rpc Create (CreateRequest) returns (CreateResponse); } diff --git a/session/types.proto b/session/types.proto index 7612128..256293d 100644 --- a/session/types.proto +++ b/session/types.proto @@ -186,6 +186,7 @@ message ResponseMetaHeader { // `ResponseMetaHeader` of the origin request ResponseMetaHeader origin = 5 [json_name = "origin"]; + // Status return neo.fs.v2.status.Status status = 6 [json_name = "status"]; } diff --git a/status/types.proto b/status/types.proto index c9c467d..dbf7e19 100644 --- a/status/types.proto +++ b/status/types.proto @@ -5,30 +5,79 @@ package neo.fs.v2.status; option go_package = "github.com/nspcc-dev/neofs-api-go/v2/status/grpc;status"; option csharp_namespace = "Neo.FileStorage.API.Status"; +// Declares the general format of the status returns of the NeoFS RPC protocol. +// Status is present in all response messages. Each RPC of NeoFS protocol +// describes the possible outcomes and details of the operation. +// +// Each status is assigned a one-to-one numeric code. Any unique result of an +// operation in NeoFS is unambiguously associated with the code value. +// +// Numerical set of codes is split into 1024-element sections. An enumeration +// is defined for each section. Values can be referred to in the following ways: +// +// * numerical value ranging from 0 to 4,294,967,295 (global code); +// +// * values from enumeration (local code). The formula for the ratio of the +// local code (`L`) of a defined section (`S`) to the global one (`G`): +// `G = 1024 * S + L`. +// +// All outcomes are divided into successful and failed, which corresponds +// to the success or failure of the operation. The definition of success +// follows from the semantics of RPC and the description of its purpose. +// The server must not attach code that is the opposite of outcome type. +// +// See the set of return codes in the description for calls. +// +// Each status can carry developer-facing error message. It should be human +// readable text in English. The server should not transmit (and the client +// should not expect) useful information in the message. Field `details` +// should make the return more detailed. message Status { + // The status code uint32 code = 1; + // Developer-facing error message string message = 2; + // Return detail. It contains additional information that can be used to + // analyze the response. Each code defines a set of details that can be + // attached to a status. Client should not handle details that are not + // covered by the code. message Detail { + // Detail ID. The identifier is required to determine the binary format + // of the detail and how to decode it. uint32 id = 1; + // Binary status detail. Must follow the format associated with ID. + // The possibility of missing a value must be explicitly allowed. bytes value = 2; } + // Data detailing the outcome of the operation. Must be unique by ID. repeated Detail details = 3; } +// Section identifiers. +enum Section { + // Successful return codes. + SECTION_SUCCESS = 0; + + // Failure codes regardless of the operation. + SECTION_FAILURE_COMMON = 1; +} + +// Section of NeoFS successful return codes. enum Success { + // [**0**] Default success. Not detailed. + // If the server cannot match successful outcome to the code, it should + // use this code. OK = 0; } +// Section of failed statuses independent of the operation. enum CommonFail { + // [**1024**] Internal server error, default failure. Not detailed. + // If the server cannot match failed outcome to the code, it should + // use this code. INTERNAL = 0; } - -enum Section { - SECTION_SUCCESS = 0; - - SECTION_FAILURE_COMMON = 1; -}