forked from TrueCloudLab/frostfs-api
432 lines
19 KiB
Markdown
432 lines
19 KiB
Markdown
# Protocol Documentation
|
|
<a name="top"></a>
|
|
|
|
## Table of Contents
|
|
|
|
- [container/service.proto](#container/service.proto)
|
|
- Services
|
|
- [ContainerService](#frost.fs.container.ContainerService)
|
|
|
|
- Messages
|
|
- [DeleteRequest](#frost.fs.container.DeleteRequest)
|
|
- [DeleteRequest.Body](#frost.fs.container.DeleteRequest.Body)
|
|
- [DeleteResponse](#frost.fs.container.DeleteResponse)
|
|
- [DeleteResponse.Body](#frost.fs.container.DeleteResponse.Body)
|
|
- [GetRequest](#frost.fs.container.GetRequest)
|
|
- [GetRequest.Body](#frost.fs.container.GetRequest.Body)
|
|
- [GetResponse](#frost.fs.container.GetResponse)
|
|
- [GetResponse.Body](#frost.fs.container.GetResponse.Body)
|
|
- [ListRequest](#frost.fs.container.ListRequest)
|
|
- [ListRequest.Body](#frost.fs.container.ListRequest.Body)
|
|
- [ListResponse](#frost.fs.container.ListResponse)
|
|
- [ListResponse.Body](#frost.fs.container.ListResponse.Body)
|
|
- [PutRequest](#frost.fs.container.PutRequest)
|
|
- [PutRequest.Body](#frost.fs.container.PutRequest.Body)
|
|
- [PutResponse](#frost.fs.container.PutResponse)
|
|
- [PutResponse.Body](#frost.fs.container.PutResponse.Body)
|
|
|
|
|
|
- [container/types.proto](#container/types.proto)
|
|
|
|
- Messages
|
|
- [Container](#frost.fs.container.Container)
|
|
- [Container.Attribute](#frost.fs.container.Container.Attribute)
|
|
|
|
|
|
- [Scalar Value Types](#scalar-value-types)
|
|
|
|
|
|
|
|
<a name="container/service.proto"></a>
|
|
<p align="right"><a href="#top">Top</a></p>
|
|
|
|
## container/service.proto
|
|
|
|
|
|
|
|
|
|
<a name="frost.fs.container.ContainerService"></a>
|
|
|
|
### Service "frost.fs.container.ContainerService"
|
|
`ContainerService` provides API to interact with `Container` smart contract
|
|
in FrostFS sidechain via other FrostFS nodes. All of those actions can be
|
|
done equivalently by directly issuing transactions and RPC calls to sidechain
|
|
nodes.
|
|
|
|
```
|
|
rpc Put(PutRequest) returns (PutResponse);
|
|
rpc Delete(DeleteRequest) returns (DeleteResponse);
|
|
rpc Get(GetRequest) returns (GetResponse);
|
|
rpc List(ListRequest) returns (ListResponse);
|
|
|
|
```
|
|
|
|
#### Method Put
|
|
|
|
`Put` invokes `Container` smart contract's `Put` 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, the
|
|
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);
|
|
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
|
|
container create access denied.
|
|
|
|
| Name | Input | Output |
|
|
| ---- | ----- | ------ |
|
|
| Put | [PutRequest](#frost.fs.container.PutRequest) | [PutResponse](#frost.fs.container.PutResponse) |
|
|
#### Method Delete
|
|
|
|
`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, the
|
|
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);
|
|
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
|
|
container delete access denied.
|
|
|
|
| Name | Input | Output |
|
|
| ---- | ----- | ------ |
|
|
| Delete | [DeleteRequest](#frost.fs.container.DeleteRequest) | [DeleteResponse](#frost.fs.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);
|
|
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
|
|
requested container not found;
|
|
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
|
|
access to container is denied.
|
|
|
|
| Name | Input | Output |
|
|
| ---- | ----- | ------ |
|
|
| Get | [GetRequest](#frost.fs.container.GetRequest) | [GetResponse](#frost.fs.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);
|
|
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
|
|
container list access denied.
|
|
|
|
| Name | Input | Output |
|
|
| ---- | ----- | ------ |
|
|
| List | [ListRequest](#frost.fs.container.ListRequest) | [ListResponse](#frost.fs.container.ListResponse) |
|
|
<!-- end services -->
|
|
|
|
|
|
<a name="frost.fs.container.DeleteRequest"></a>
|
|
|
|
### Message DeleteRequest
|
|
Container removal request
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [DeleteRequest.Body](#frost.fs.container.DeleteRequest.Body) | | Body of container delete request message. |
|
|
| meta_header | [frost.fs.session.RequestMetaHeader](#frost.fs.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
|
| verify_header | [frost.fs.session.RequestVerificationHeader](#frost.fs.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
|
|
|
|
|
<a name="frost.fs.container.DeleteRequest.Body"></a>
|
|
|
|
### Message DeleteRequest.Body
|
|
Container removal request body has signed `ContainerID` as a proof of
|
|
the container owner's intent. The signature will be verified by `Container`
|
|
smart contract, so signing algorithm must be supported by NeoVM.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| container_id | [frost.fs.refs.ContainerID](#frost.fs.refs.ContainerID) | | Identifier of the container to delete from FrostFS |
|
|
| signature | [frost.fs.refs.SignatureRFC6979](#frost.fs.refs.SignatureRFC6979) | | `ContainerID` signed with the container owner's key according to RFC-6979. |
|
|
|
|
|
|
<a name="frost.fs.container.DeleteResponse"></a>
|
|
|
|
### Message DeleteResponse
|
|
`DeleteResponse` has an empty body because delete operation is asynchronous
|
|
and done via consensus in Inner Ring nodes.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [DeleteResponse.Body](#frost.fs.container.DeleteResponse.Body) | | Body of container delete response message. |
|
|
| meta_header | [frost.fs.session.ResponseMetaHeader](#frost.fs.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
|
| verify_header | [frost.fs.session.ResponseVerificationHeader](#frost.fs.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
|
|
|
|
|
<a name="frost.fs.container.DeleteResponse.Body"></a>
|
|
|
|
### Message DeleteResponse.Body
|
|
`DeleteResponse` has an empty body because delete operation is asynchronous
|
|
and done via consensus in Inner Ring nodes.
|
|
|
|
|
|
|
|
<a name="frost.fs.container.GetRequest"></a>
|
|
|
|
### Message GetRequest
|
|
Get container structure
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [GetRequest.Body](#frost.fs.container.GetRequest.Body) | | Body of container get request message. |
|
|
| meta_header | [frost.fs.session.RequestMetaHeader](#frost.fs.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
|
| verify_header | [frost.fs.session.RequestVerificationHeader](#frost.fs.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
|
|
|
|
|
<a name="frost.fs.container.GetRequest.Body"></a>
|
|
|
|
### Message GetRequest.Body
|
|
Get container structure request body.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| container_id | [frost.fs.refs.ContainerID](#frost.fs.refs.ContainerID) | | Identifier of the container to get |
|
|
|
|
|
|
<a name="frost.fs.container.GetResponse"></a>
|
|
|
|
### Message GetResponse
|
|
Get container structure
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [GetResponse.Body](#frost.fs.container.GetResponse.Body) | | Body of container get response message. |
|
|
| meta_header | [frost.fs.session.ResponseMetaHeader](#frost.fs.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
|
| verify_header | [frost.fs.session.ResponseVerificationHeader](#frost.fs.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
|
|
|
|
|
<a name="frost.fs.container.GetResponse.Body"></a>
|
|
|
|
### Message GetResponse.Body
|
|
Get container response body does not have container structure signature. It
|
|
has been already verified upon container creation.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| container | [Container](#frost.fs.container.Container) | | Requested container structure |
|
|
| signature | [frost.fs.refs.SignatureRFC6979](#frost.fs.refs.SignatureRFC6979) | | Signature of a stable-marshalled container according to RFC-6979. |
|
|
| session_token | [frost.fs.session.SessionToken](#frost.fs.session.SessionToken) | | Session token if the container has been created within the session |
|
|
|
|
|
|
<a name="frost.fs.container.ListRequest"></a>
|
|
|
|
### Message ListRequest
|
|
List containers
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [ListRequest.Body](#frost.fs.container.ListRequest.Body) | | Body of list containers request message |
|
|
| meta_header | [frost.fs.session.RequestMetaHeader](#frost.fs.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
|
| verify_header | [frost.fs.session.RequestVerificationHeader](#frost.fs.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
|
|
|
|
|
<a name="frost.fs.container.ListRequest.Body"></a>
|
|
|
|
### Message ListRequest.Body
|
|
List containers request body.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| owner_id | [frost.fs.refs.OwnerID](#frost.fs.refs.OwnerID) | | Identifier of the container owner |
|
|
|
|
|
|
<a name="frost.fs.container.ListResponse"></a>
|
|
|
|
### Message ListResponse
|
|
List containers
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [ListResponse.Body](#frost.fs.container.ListResponse.Body) | | Body of list containers response message. |
|
|
| meta_header | [frost.fs.session.ResponseMetaHeader](#frost.fs.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
|
| verify_header | [frost.fs.session.ResponseVerificationHeader](#frost.fs.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
|
|
|
|
|
<a name="frost.fs.container.ListResponse.Body"></a>
|
|
|
|
### Message ListResponse.Body
|
|
List containers response body.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| container_ids | [frost.fs.refs.ContainerID](#frost.fs.refs.ContainerID) | repeated | List of `ContainerID`s belonging to the requested `OwnerID` |
|
|
|
|
|
|
<a name="frost.fs.container.PutRequest"></a>
|
|
|
|
### Message PutRequest
|
|
New FrostFS Container creation request
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [PutRequest.Body](#frost.fs.container.PutRequest.Body) | | Body of container put request message. |
|
|
| meta_header | [frost.fs.session.RequestMetaHeader](#frost.fs.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
|
| verify_header | [frost.fs.session.RequestVerificationHeader](#frost.fs.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
|
|
|
|
|
<a name="frost.fs.container.PutRequest.Body"></a>
|
|
|
|
### Message PutRequest.Body
|
|
Container creation request has container structure's signature as a
|
|
separate field. It's not stored in sidechain, just verified on container
|
|
creation by `Container` smart contract. `ContainerID` is a SHA256 hash of
|
|
the stable-marshalled container strucutre, hence there is no need for
|
|
additional signature checks.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| container | [Container](#frost.fs.container.Container) | | Container structure to register in FrostFS |
|
|
| signature | [frost.fs.refs.SignatureRFC6979](#frost.fs.refs.SignatureRFC6979) | | Signature of a stable-marshalled container according to RFC-6979. |
|
|
|
|
|
|
<a name="frost.fs.container.PutResponse"></a>
|
|
|
|
### Message PutResponse
|
|
New FrostFS Container creation response
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [PutResponse.Body](#frost.fs.container.PutResponse.Body) | | Body of container put response message. |
|
|
| meta_header | [frost.fs.session.ResponseMetaHeader](#frost.fs.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
|
| verify_header | [frost.fs.session.ResponseVerificationHeader](#frost.fs.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
|
|
|
|
|
<a name="frost.fs.container.PutResponse.Body"></a>
|
|
|
|
### Message PutResponse.Body
|
|
Container put response body contains information about the newly registered
|
|
container as seen by `Container` smart contract. `ContainerID` can be
|
|
calculated beforehand from the container structure and compared to the one
|
|
returned here to make sure everything has been done as expected.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| container_id | [frost.fs.refs.ContainerID](#frost.fs.refs.ContainerID) | | Unique identifier of the newly created container |
|
|
|
|
<!-- end messages -->
|
|
|
|
<!-- end enums -->
|
|
|
|
|
|
|
|
<a name="container/types.proto"></a>
|
|
<p align="right"><a href="#top">Top</a></p>
|
|
|
|
## container/types.proto
|
|
|
|
|
|
<!-- end services -->
|
|
|
|
|
|
<a name="frost.fs.container.Container"></a>
|
|
|
|
### Message Container
|
|
Container is a structure that defines object placement behaviour. Objects can
|
|
be stored only within containers. They define placement rule, attributes and
|
|
access control information. An ID of a container is a 32 byte long SHA256
|
|
hash of stable-marshalled container message.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| version | [frost.fs.refs.Version](#frost.fs.refs.Version) | | Container format version. Effectively, the version of API library used to create the container. |
|
|
| owner_id | [frost.fs.refs.OwnerID](#frost.fs.refs.OwnerID) | | Identifier of the container owner |
|
|
| nonce | [bytes](#bytes) | | Nonce is a 16 byte UUIDv4, used to avoid collisions of `ContainerID`s |
|
|
| basic_acl | [uint32](#uint32) | | `BasicACL` contains access control rules for the owner, system and others groups, as well as permission bits for `BearerToken` and `Extended ACL` |
|
|
| attributes | [Container.Attribute](#frost.fs.container.Container.Attribute) | repeated | Attributes represent immutable container's meta data |
|
|
| placement_policy | [frost.fs.netmap.PlacementPolicy](#frost.fs.netmap.PlacementPolicy) | | Placement policy for the object inside the container |
|
|
|
|
|
|
<a name="frost.fs.container.Container.Attribute"></a>
|
|
|
|
### Message Container.Attribute
|
|
`Attribute` is a user-defined Key-Value metadata pair attached to the
|
|
container. Container attributes are immutable. They are set at the moment
|
|
of container creation and can never be added or updated.
|
|
|
|
Key name must be a container-unique valid UTF-8 string. Value can't be
|
|
empty. Containers with duplicated attribute names or attributes with empty
|
|
values will be considered invalid.
|
|
|
|
There are some "well-known" attributes affecting system behaviour:
|
|
|
|
* [ __SYSTEM__NAME ] \
|
|
String of a human-friendly container name registered as a domain in
|
|
NNS contract.
|
|
* [ __SYSTEM__ZONE ] \
|
|
String of a zone for `__SYSTEM__NAME`.
|
|
Used as a TLD of a domain name in NNS contract. If no zone is specified,
|
|
use default zone: `container`.
|
|
* [ __SYSTEM__DISABLE_HOMOMORPHIC_HASHING ] \
|
|
Disables homomorphic hashing for the container if the value equals "true"
|
|
string. Any other values are interpreted as missing attribute. Container
|
|
could be accepted in a FrostFS network only if the global network hashing
|
|
configuration value corresponds with that attribute's value. After
|
|
container inclusion, network setting is ignored.
|
|
|
|
And some well-known attributes used by applications only:
|
|
|
|
* Name \
|
|
Human-friendly name
|
|
* Timestamp \
|
|
User-defined local time of container creation in Unix Timestamp format
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| key | [string](#string) | | Attribute name key |
|
|
| value | [string](#string) | | Attribute value |
|
|
|
|
<!-- end messages -->
|
|
|
|
<!-- 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 |
|