realloc/frostfs-api
1
0
Fork 0
forked from TrueCloudLab/frostfs-api
Code Issues Pull requests Projects Releases Packages Wiki Activity

[#150] *: Write status-related docs

Browse source 
Signed-off-by: Leonard Lyubich <leonard@nspcc.ru>
This commit is contained in:
Leonard Lyubich 2021-11-12 19:10:39 +03:00 • committed by LeL
parent f55f83fb24
commit 7ea5a1d2f1
15 changed files with 395 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

5
proto-docs/accounting.md
View file

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

35
proto-docs/container.md
View file

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

10
proto-docs/netmap.md
View file

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

35
proto-docs/object.md
View file

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

10
proto-docs/reputation.md
View file

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

6
proto-docs/session.md
View file

@ -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. |
<a name="neo.fs.v2.session.ResponseVerificationHeader"></a>

138
proto-docs/status.md Normal file
View file

@ -0,0 +1,138 @@
# Protocol Documentation
<a name="top"></a>
## 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)
<a name="status/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## status/types.proto
<!-- end services -->
<a name="neo.fs.v2.status.Status"></a>
### 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. |
<a name="neo.fs.v2.status.Status.Detail"></a>
### 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. |
<!-- end messages -->
<a name="neo.fs.v2.status.CommonFail"></a>
### 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. |
<a name="neo.fs.v2.status.Section"></a>
### Section
Section identifiers.
| Name | Number | Description |
| ---- | ------ | ----------- |
| SECTION_SUCCESS | 0 | Successful return codes. |
| SECTION_FAILURE_COMMON | 1 | Failure codes regardless of the operation. |
<a name="neo.fs.v2.status.Success"></a>
### 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. |
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> 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 |
| <a name="int64" /> 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 |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |