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;
-}