[nspcc-dev#150] *: Write status-related docs

Signed-off-by: Leonard Lyubich <[email protected]>

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

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

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

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

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) |

proto-docs/acl.md

@@ -188,6 +188,7 @@ Enumeration of possible sources of Headers to apply filters.
 | HEADER_UNSPECIFIED | 0 | Unspecified header, default value. |
 | REQUEST | 1 | Filter request headers |
 | OBJECT | 2 | Filter object headers |
+| SERVICE | 3 | Filter service headers. These are not processed by NeoFS nodes and exist for service use only. |
 
 
 

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,20 +99,35 @@ 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) |
 #### Method Get
 
 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) |
 #### Method List
 
 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,13 +150,23 @@ 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) |
 #### Method AnnounceUsedSpace
 
 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) |

proto-docs/netmap.md

@@ -22,6 +22,8 @@
 
   - Messages
     - [Filter](#neo.fs.v2.netmap.Filter)
+    - [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig)
+    - [NetworkConfig.Parameter](#neo.fs.v2.netmap.NetworkConfig.Parameter)
     - [NetworkInfo](#neo.fs.v2.netmap.NetworkInfo)
     - [NodeInfo](#neo.fs.v2.netmap.NodeInfo)
     - [NodeInfo.Attribute](#neo.fs.v2.netmap.NodeInfo.Attribute)
@@ -64,13 +66,23 @@ 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) |
 #### Method NetworkInfo
 
 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) |
@@ -197,6 +209,29 @@ results, that will satisfy filter's conditions.
 | filters | [Filter](#neo.fs.v2.netmap.Filter) | repeated | List of inner filters. Top level operation will be applied to the whole list. |
 
 
+<a name="neo.fs.v2.netmap.NetworkConfig"></a>
+
+### Message NetworkConfig
+NeoFS network configuration
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| parameters | [NetworkConfig.Parameter](#neo.fs.v2.netmap.NetworkConfig.Parameter) | repeated | List of parameter values. |
+
+
+<a name="neo.fs.v2.netmap.NetworkConfig.Parameter"></a>
+
+### Message NetworkConfig.Parameter
+Single configuration parameter.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| key | [bytes](#bytes) |  | Parameter key. UTF-8 encoded string. |
+| value | [bytes](#bytes) |  | Parameter value. |
+
+
 <a name="neo.fs.v2.netmap.NetworkInfo"></a>
 
 ### Message NetworkInfo
@@ -207,6 +242,8 @@ Information about NeoFS network
 | ----- | ---- | ----- | ----------- |
 | current_epoch | [uint64](#uint64) |  | Number of the current epoch in the NeoFS network. |
 | magic_number | [uint64](#uint64) |  | Magic number of the sidechain of the NeoFS network. |
+| ms_per_block | [int64](#int64) |  | MillisecondsPerBlock network parameter of the sidechain of the NeoFS network. |
+| network_config | [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig) |  | NeoFS network configuration. |
 
 
 <a name="neo.fs.v2.netmap.NodeInfo"></a>