orikik/frostfs-api
1
0
Fork 0
forked from TrueCloudLab/frostfs-api
Code Pull requests 1 Activity Actions

[#227] *: Regenerate docs

Browse source 
Signed-off-by: Pavel Karpy <carpawell@nspcc.ru>
This commit is contained in:
Pavel Karpy 2022-06-21 14:32:14 +03:00 committed by Pavel Karpy
parent 2f52216400
commit 1bc50fc2a9
13 changed files with 214 additions and 141 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
proto-docs/accounting.md
View file

@ -39,7 +39,7 @@ Accounting service provides methods for interaction with NeoFS sidechain via
other NeoFS nodes to get information about the account balance. Deposit and other NeoFS nodes to get information about the account balance. Deposit and
Withdraw operations can't be implemented here, as they require Mainnet NeoFS Withdraw operations can't be implemented here, as they require Mainnet NeoFS
smart contract invocation. Transfer operations between internal NeoFS smart contract invocation. Transfer operations between internal NeoFS
accounts are possible, if both use the same token type. accounts are possible if both use the same token type.
``` ```
rpc Balance(BalanceRequest) returns (BalanceResponse); rpc Balance(BalanceRequest) returns (BalanceResponse);
@ -77,7 +77,7 @@ BalanceRequest message
<a name="neo.fs.v2.accounting.BalanceRequest.Body"></a> <a name="neo.fs.v2.accounting.BalanceRequest.Body"></a>
### Message BalanceRequest.Body ### Message BalanceRequest.Body
To indicate the account for which the balance is requested, it's identifier To indicate the account for which the balance is requested, its identifier
is used. It can be any existing account in NeoFS sidechain `Balance` smart is used. It can be any existing account in NeoFS sidechain `Balance` smart
contract. If omitted, client implementation MUST set it to the request's contract. If omitted, client implementation MUST set it to the request's
signer `OwnerID`. signer `OwnerID`.
@ -105,7 +105,7 @@ BalanceResponse message
### Message BalanceResponse.Body ### Message BalanceResponse.Body
The amount of funds in GAS token for the `OwnerID`'s account requested. The amount of funds in GAS token for the `OwnerID`'s account requested.
Balance is `Decimal` format to avoid precision issues with rounding. Balance is given in the `Decimal` format to avoid precision issues with rounding.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -141,7 +141,7 @@ description.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| value | [int64](#int64) | | Number in smallest Token fractions. | | value | [int64](#int64) | | Number in the smallest Token fractions. |
| precision | [uint32](#uint32) | | Precision value indicating how many smallest fractions can be in one integer. | | precision | [uint32](#uint32) | | Precision value indicating how many smallest fractions can be in one integer. |
<!-- end messages --> <!-- end messages -->

26
proto-docs/acl.md
View file

@ -38,8 +38,8 @@ like [JWT](https://jwt.io), it has a limited lifetime and scope, hence can be
used in the similar use cases, like providing authorisation to externally used in the similar use cases, like providing authorisation to externally
authenticated party. authenticated party.
BearerToken can be issued only by container's owner and must be signed using BearerToken can be issued only by the container's owner and must be signed using
the key associated with container's `OwnerID`. the key associated with the container's `OwnerID`.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -51,14 +51,14 @@ the key associated with container's `OwnerID`.
<a name="neo.fs.v2.acl.BearerToken.Body"></a> <a name="neo.fs.v2.acl.BearerToken.Body"></a>
### Message BearerToken.Body ### Message BearerToken.Body
Bearer Token body structure contains Extended ACL table issued by container Bearer Token body structure contains Extended ACL table issued by the container
owner with additional information preventing token's abuse. owner with additional information preventing token abuse.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| eacl_table | [EACLTable](#neo.fs.v2.acl.EACLTable) | | Table of Extended ACL rules to use instead of the ones attached to the container | | eacl_table | [EACLTable](#neo.fs.v2.acl.EACLTable) | | Table of Extended ACL rules to use instead of the ones attached to the container. If it contains `container_id` field, bearer token is only valid for this specific container. Otherwise, any container of the same owner is allowed. |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | `OwnerID` to whom the token was issued. Must match the request originator's `OwnerID`. If empty, any token bearer will be accepted. | | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | `OwnerID` defines to whom the token was issued. It must match the request originator's `OwnerID`. If empty, any token bearer will be accepted. |
| lifetime | [BearerToken.Body.TokenLifetime](#neo.fs.v2.acl.BearerToken.Body.TokenLifetime) | | Token expiration and valid time period parameters | | lifetime | [BearerToken.Body.TokenLifetime](#neo.fs.v2.acl.BearerToken.Body.TokenLifetime) | | Token expiration and valid time period parameters |
@ -93,7 +93,7 @@ Describes a single eACL rule.
<a name="neo.fs.v2.acl.EACLRecord.Filter"></a> <a name="neo.fs.v2.acl.EACLRecord.Filter"></a>
### Message EACLRecord.Filter ### Message EACLRecord.Filter
Filter to check particular properties of the request or object. Filter to check particular properties of the request or the object.
By default `key` field refers to the corresponding object's `Attribute`. By default `key` field refers to the corresponding object's `Attribute`.
Some Object's header fields can also be accessed by adding `$Object:` Some Object's header fields can also be accessed by adding `$Object:`
@ -149,15 +149,15 @@ keys to match.
<a name="neo.fs.v2.acl.EACLTable"></a> <a name="neo.fs.v2.acl.EACLTable"></a>
### Message EACLTable ### Message EACLTable
Extended ACL rules table. Defined a list of ACL rules additionally to Basic Extended ACL rules table. A list of ACL rules defined additionally to Basic
ACL. Extended ACL rules can be attached to the container and can be updated ACL. Extended ACL rules can be attached to a container and can be updated
or may be defined in `BearerToken` structure. Please see the corresponding or may be defined in `BearerToken` structure. Please see the corresponding
NeoFS Technical Specification's section for detailed description. NeoFS Technical Specification section for detailed description.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | eACL format version. Effectively the version of API library used to create eACL Table. | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | eACL format version. Effectively, the version of API library used to create eACL Table. |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container that should use given access control rules | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container that should use given access control rules |
| records | [EACLRecord](#neo.fs.v2.acl.EACLRecord) | repeated | List of Extended ACL rules | | records | [EACLRecord](#neo.fs.v2.acl.EACLRecord) | repeated | List of Extended ACL rules |
@ -233,8 +233,8 @@ Target role of the access control rule in access control list.
| ---- | ------ | ----------- | | ---- | ------ | ----------- |
| ROLE_UNSPECIFIED | 0 | Unspecified role, default value | | ROLE_UNSPECIFIED | 0 | Unspecified role, default value |
| USER | 1 | User target rule is applied if sender is the owner of the container | | USER | 1 | User target rule is applied if sender is the owner of the container |
| SYSTEM | 2 | System target rule is applied if sender is the storage node within the container or inner ring node | | SYSTEM | 2 | System target rule is applied if sender is a storage node within the container or an inner ring node |
| OTHERS | 3 | Others target rule is applied if sender is not user nor system target | | OTHERS | 3 | Others target rule is applied if sender is neither a user nor a system target |
<!-- end enums --> <!-- end enums -->

8
proto-docs/audit.md
View file

@ -31,7 +31,7 @@ generated separately.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Data Audit Result format version. Effectively the version of API library used to report DataAuditResult structure. | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Data Audit Result format version. Effectively, the version of API library used to report DataAuditResult structure. |
| audit_epoch | [fixed64](#fixed64) | | Epoch number when the Data Audit was conducted | | audit_epoch | [fixed64](#fixed64) | | Epoch number when the Data Audit was conducted |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Container under audit | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Container under audit |
| public_key | [bytes](#bytes) | | Public key of the auditing InnerRing node in a binary format | | public_key | [bytes](#bytes) | | Public key of the auditing InnerRing node in a binary format |
@ -40,9 +40,9 @@ generated separately.
| retries | [uint32](#uint32) | | Number of retries done at PoR stage | | retries | [uint32](#uint32) | | Number of retries done at PoR stage |
| pass_sg | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of Storage Groups that passed audit PoR stage | | pass_sg | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of Storage Groups that passed audit PoR stage |
| fail_sg | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of Storage Groups that failed audit PoR stage | | fail_sg | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of Storage Groups that failed audit PoR stage |
| hit | [uint32](#uint32) | | Number of sampled objects under audit placed in an optimal way according to the containers placement policy when checking PoP | | hit | [uint32](#uint32) | | Number of sampled objects under the audit placed in an optimal way according to the containers placement policy when checking PoP |
| miss | [uint32](#uint32) | | Number of sampled objects under audit placed in suboptimal way according to the containers placement policy, but still at a satisfactory level when checking PoP | | miss | [uint32](#uint32) | | Number of sampled objects under the audit placed in suboptimal way according to the containers placement policy, but still at a satisfactory level when checking PoP |
| fail | [uint32](#uint32) | | Number of sampled objects under audit stored in a way not confirming placement policy or not found at all when checking PoP | | fail | [uint32](#uint32) | | Number of sampled objects under the audit stored inconsistently with the placement policy or not found at all when checking PoP |
| pass_nodes | [bytes](#bytes) | repeated | List of storage node public keys that passed at least one PDP | | pass_nodes | [bytes](#bytes) | repeated | List of storage node public keys that passed at least one PDP |
| fail_nodes | [bytes](#bytes) | repeated | List of storage node public keys that failed at least one PDP | | fail_nodes | [bytes](#bytes) | repeated | List of storage node public keys that failed at least one PDP |

62
proto-docs/container.md
View file

@ -81,7 +81,7 @@ rpc AnnounceUsedSpace(AnnounceUsedSpaceRequest) returns (AnnounceUsedSpaceRespon
`Put` invokes `Container` smart contract's `Put` method and returns `Put` invokes `Container` smart contract's `Put` method and returns
response immediately. After a new block is issued in sidechain, request is response immediately. After a new block is issued in sidechain, request is
verified by Inner Ring nodes. After one more block in sidechain, container verified by Inner Ring nodes. After one more block in sidechain, the container
is added into smart contract storage. is added into smart contract storage.
Statuses: Statuses:
@ -96,7 +96,7 @@ Statuses:
`Delete` invokes `Container` smart contract's `Delete` method and returns `Delete` invokes `Container` smart contract's `Delete` method and returns
response immediately. After a new block is issued in sidechain, request is response immediately. After a new block is issued in sidechain, request is
verified by Inner Ring nodes. After one more block in sidechain, container verified by Inner Ring nodes. After one more block in sidechain, the container
is added into smart contract storage. is added into smart contract storage.
Statuses: Statuses:
@ -136,7 +136,7 @@ Statuses:
#### Method SetExtendedACL #### Method SetExtendedACL
Invokes 'SetEACL' method of 'Container` smart contract and returns response Invokes 'SetEACL' method of 'Container` smart contract and returns response
immediately. After one more block in sidechain, Extended ACL changes are immediately. After one more block in sidechain, changes in an Extended ACL are
added into smart contract storage. added into smart contract storage.
Statuses: Statuses:
@ -164,7 +164,7 @@ Statuses:
| GetExtendedACL | [GetExtendedACLRequest](#neo.fs.v2.container.GetExtendedACLRequest) | [GetExtendedACLResponse](#neo.fs.v2.container.GetExtendedACLResponse) | | GetExtendedACL | [GetExtendedACLRequest](#neo.fs.v2.container.GetExtendedACLRequest) | [GetExtendedACLResponse](#neo.fs.v2.container.GetExtendedACLResponse) |
#### Method AnnounceUsedSpace #### Method AnnounceUsedSpace
Announce container used space values for P2P synchronization. Announces the space values used by the container for P2P synchronization.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
@ -198,20 +198,20 @@ Container used space announcement body.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| announcements | [AnnounceUsedSpaceRequest.Body.Announcement](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement) | repeated | List of announcements. If nodes share several containers, then announcements transferred in a batch. | | announcements | [AnnounceUsedSpaceRequest.Body.Announcement](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement) | repeated | List of announcements. If nodes share several containers, announcements are transferred in a batch. |
<a name="neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement"></a> <a name="neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement"></a>
### Message AnnounceUsedSpaceRequest.Body.Announcement ### Message AnnounceUsedSpaceRequest.Body.Announcement
Announcement contains used space information about single container. Announcement contains used space information for a single container.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| epoch | [uint64](#uint64) | | Epoch number for which container size estimation was produced. | | epoch | [uint64](#uint64) | | Epoch number for which the container size estimation was produced. |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container. | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container. |
| used_space | [uint64](#uint64) | | Used space is a sum of object payload sizes of specified container, stored in the node. It must not include inhumed objects. | | used_space | [uint64](#uint64) | | Used space is a sum of object payload sizes of a specified container, stored in the node. It must not include inhumed objects. |
<a name="neo.fs.v2.container.AnnounceUsedSpaceResponse"></a> <a name="neo.fs.v2.container.AnnounceUsedSpaceResponse"></a>
@ -251,8 +251,8 @@ Container removal request
<a name="neo.fs.v2.container.DeleteRequest.Body"></a> <a name="neo.fs.v2.container.DeleteRequest.Body"></a>
### Message DeleteRequest.Body ### Message DeleteRequest.Body
Container removal request body has a signed `ContainerID` as a proof of Container removal request body has signed `ContainerID` as a proof of
container owner's intent. The signature will be verified by `Container` the container owner's intent. The signature will be verified by `Container`
smart contract, so signing algorithm must be supported by NeoVM. smart contract, so signing algorithm must be supported by NeoVM.
@ -324,9 +324,9 @@ Get Extended ACL
<a name="neo.fs.v2.container.GetExtendedACLResponse.Body"></a> <a name="neo.fs.v2.container.GetExtendedACLResponse.Body"></a>
### Message GetExtendedACLResponse.Body ### Message GetExtendedACLResponse.Body
Get Extended ACL Response body can be empty if the requested container did Get Extended ACL Response body can be empty if the requested container does
not have Extended ACL Table attached or Extended ACL was not allowed at not have Extended ACL Table attached or Extended ACL has not been allowed at
container creation. the time of container creation.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -377,14 +377,14 @@ Get container structure
### Message GetResponse.Body ### Message GetResponse.Body
Get container response body does not have container structure signature. It Get container response body does not have container structure signature. It
was already verified on container creation. has been already verified upon container creation.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| container | [Container](#neo.fs.v2.container.Container) | | Requested container structure | | container | [Container](#neo.fs.v2.container.Container) | | Requested container structure |
| signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of a stable-marshalled container according to RFC-6979. | | signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of a stable-marshalled container according to RFC-6979. |
| session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) | | Session token if the container was created within a session | | session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) | | Session token if the container has been created within the session |
<a name="neo.fs.v2.container.ListRequest"></a> <a name="neo.fs.v2.container.ListRequest"></a>
@ -483,7 +483,7 @@ New NeoFS Container creation response
Container put response body contains information about the newly registered Container put response body contains information about the newly registered
container as seen by `Container` smart contract. `ContainerID` can be container as seen by `Container` smart contract. `ContainerID` can be
calculated beforehand from the container structure and compared to the one calculated beforehand from the container structure and compared to the one
returned here to make sure everything was done as expected. returned here to make sure everything has been done as expected.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -513,7 +513,7 @@ reference. It will be taken from `EACLTable.container_id` field.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) | | Extended ACL table to set for container | | eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) | | Extended ACL table to set for the container |
| signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of stable-marshalled Extended ACL table according to RFC-6979. | | signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of stable-marshalled Extended ACL table according to RFC-6979. |
@ -534,7 +534,7 @@ Set Extended ACL
### Message SetExtendedACLResponse.Body ### Message SetExtendedACLResponse.Body
`SetExtendedACLResponse` has an empty body because the operation is `SetExtendedACLResponse` has an empty body because the operation is
asynchronous and update should be reflected in `Container` smart contract's asynchronous and the update should be reflected in `Container` smart contract's
storage after next block is issued in sidechain. storage after next block is issued in sidechain.
@ -558,16 +558,16 @@ storage after next block is issued in sidechain.
### Message Container ### Message Container
Container is a structure that defines object placement behaviour. Objects can Container is a structure that defines object placement behaviour. Objects can
be stored only within containers. They define placement rule, attributes and be stored only within containers. They define placement rule, attributes and
access control information. ID of the container is a 32 byte long SHA256 hash access control information. An ID of a container is a 32 byte long SHA256 hash
of stable-marshalled container message. of stable-marshalled container message.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Container format version. Effectively the version of API library used to create container. | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Container format version. Effectively, the version of API library used to create the container. |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Identifier of the container owner | | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Identifier of the container owner |
| nonce | [bytes](#bytes) | | Nonce is a 16 byte UUIDv4, used to avoid collisions of `ContainerID`s | | 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 owner, system, others groups and permission bits for `BearerToken` and `Extended ACL` | | 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](#neo.fs.v2.container.Container.Attribute) | repeated | Attributes represent immutable container's meta data | | attributes | [Container.Attribute](#neo.fs.v2.container.Container.Attribute) | repeated | Attributes represent immutable container's meta data |
| placement_policy | [neo.fs.v2.netmap.PlacementPolicy](#neo.fs.v2.netmap.PlacementPolicy) | | Placement policy for the object inside the container | | placement_policy | [neo.fs.v2.netmap.PlacementPolicy](#neo.fs.v2.netmap.PlacementPolicy) | | Placement policy for the object inside the container |
@ -576,8 +576,8 @@ of stable-marshalled container message.
### Message Container.Attribute ### Message Container.Attribute
`Attribute` is a user-defined Key-Value metadata pair attached to the `Attribute` is a user-defined Key-Value metadata pair attached to the
container. Container attributes are immutable. They are set at container container. Container attributes are immutable. They are set at the moment of
creation and can never be added or updated. container creation and can never be added or updated.
Key name must be a container-unique valid UTF-8 string. Value can't be 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 empty. Containers with duplicated attribute names or attributes with empty
@ -586,14 +586,20 @@ values will be considered invalid.
There are some "well-known" attributes affecting system behaviour: There are some "well-known" attributes affecting system behaviour:
* __NEOFS__SUBNET \ * __NEOFS__SUBNET \
String ID of container's storage subnet. Container can be attached to String ID of a container's storage subnet. Any container can be attached to
only one subnet. one subnet only.
* __NEOFS__NAME \ * __NEOFS__NAME \
String of human-friendly container name registered as the domain in String of a human-friendly container name registered as a domain in
NNS contract. NNS contract.
* __NEOFS__ZONE \ * __NEOFS__ZONE \
String of zone for `__NEOFS__NAME`. Used as TLD of domain name in NNS String of a zone for `__NEOFS__NAME`. Used as a TLD of a domain name in NNS
contract. If zone is not specified, use default zone: `container`. contract. If no zone is specified, use default zone: `container`.
* __NEOFS__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 NeoFS 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: And some well-known attributes used by applications only:

5
proto-docs/lock.md
View file

@ -25,9 +25,10 @@
<a name="neo.fs.v2.lock.Lock"></a> <a name="neo.fs.v2.lock.Lock"></a>
### Message Lock ### Message Lock
Lock objects protects a list of objects from being deleted. Lifetime of the Lock objects protects a list of objects from being deleted. The lifetime of a
lock object is limited similar to regular objects in lock object is limited similar to regular objects in
`__NEOFS__EXPIRATION_EPOCH` attribute. `__NEOFS__EXPIRATION_EPOCH` attribute. Lock object MUST have expiration epoch.
It is impossible to delete a lock object via ObjectService.Delete RPC call.
| Field | Type | Label | Description | | Field | Type | Label | Description |

30
proto-docs/netmap.md
View file

@ -47,7 +47,7 @@
<a name="neo.fs.v2.netmap.NetmapService"></a> <a name="neo.fs.v2.netmap.NetmapService"></a>
### Service "neo.fs.v2.netmap.NetmapService" ### Service "neo.fs.v2.netmap.NetmapService"
`NetmapService` provides methods to work with `Network Map` and information `NetmapService` provides methods to work with `Network Map` and the information
required to build it. The resulting `Network Map` is stored in sidechain required to build it. The resulting `Network Map` is stored in sidechain
`Netmap` smart contract, while related information can be obtained from other `Netmap` smart contract, while related information can be obtained from other
NeoFS nodes. NeoFS nodes.
@ -60,11 +60,11 @@ rpc NetworkInfo(NetworkInfoRequest) returns (NetworkInfoResponse);
#### Method LocalNodeInfo #### Method LocalNodeInfo
Get NodeInfo structure from the particular node directly. Node information Get NodeInfo structure from the particular node directly.
can be taken from `Netmap` smart contract, but in some cases the one may Node information can be taken from `Netmap` smart contract. In some cases, though,
want to get recent information directly, or to talk to the node not yet one may 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 present in the `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. further communication. This can be also used to check if a node is up and running.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): - **OK** (0, SECTION_SUCCESS):
@ -92,7 +92,7 @@ information about the current network state has been successfully read;
<a name="neo.fs.v2.netmap.LocalNodeInfoRequest"></a> <a name="neo.fs.v2.netmap.LocalNodeInfoRequest"></a>
### Message LocalNodeInfoRequest ### Message LocalNodeInfoRequest
Get NodeInfo structure from the particular node directly Get NodeInfo structure directly from a particular node
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -137,7 +137,7 @@ Local Node Info, including API Version in use.
<a name="neo.fs.v2.netmap.NetworkInfoRequest"></a> <a name="neo.fs.v2.netmap.NetworkInfoRequest"></a>
### Message NetworkInfoRequest ### Message NetworkInfoRequest
Get NetworkInfo structure with the network view from particular node. Get NetworkInfo structure with the network view from a particular node.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -196,13 +196,13 @@ Information about the network.
<a name="neo.fs.v2.netmap.Filter"></a> <a name="neo.fs.v2.netmap.Filter"></a>
### Message Filter ### Message Filter
Filter will return the subset of nodes from `NetworkMap` or another filter's This filter will return the subset of nodes from `NetworkMap` or another filter's
results, that will satisfy filter's conditions. results that will satisfy filter's conditions.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| name | [string](#string) | | Name of the filter or a reference to the named filter. '*' means application to the whole unfiltered NetworkMap. At top level it's used as a filter name. At lower levels it's considered to be a reference to another named filter | | name | [string](#string) | | Name of the filter or a reference to a named filter. '*' means application to the whole unfiltered NetworkMap. At top level it's used as a filter name. At lower levels it's considered to be a reference to another named filter |
| key | [string](#string) | | Key to filter | | key | [string](#string) | | Key to filter |
| op | [Operation](#neo.fs.v2.netmap.Operation) | | Filtering operation | | op | [Operation](#neo.fs.v2.netmap.Operation) | | Filtering operation |
| value | [string](#string) | | Value to match | | value | [string](#string) | | Value to match |
@ -332,7 +332,7 @@ explicitly set:
automatically from `UN-LOCODE` attribute. automatically from `UN-LOCODE` attribute.
For detailed description of each well-known attribute please see the For detailed description of each well-known attribute please see the
corresponding section in NeoFS Technical specification. corresponding section in NeoFS Technical Specification.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -363,7 +363,7 @@ storage policy definition languages.
### Message Replica ### Message Replica
Number of object replicas in a set of nodes from the defined selector. If no Number of object replicas in a set of nodes from the defined selector. If no
selector set the root bucket containing all possible nodes will be used by selector set, the root bucket containing all possible nodes will be used by
default. default.
@ -385,7 +385,7 @@ to the provided `ContainerID` by hash distance.
| name | [string](#string) | | Selector name to reference in object placement section | | name | [string](#string) | | Selector name to reference in object placement section |
| count | [uint32](#uint32) | | How many nodes to select from the bucket | | count | [uint32](#uint32) | | How many nodes to select from the bucket |
| clause | [Clause](#neo.fs.v2.netmap.Clause) | | Selector modifier showing how to form a bucket | | clause | [Clause](#neo.fs.v2.netmap.Clause) | | Selector modifier showing how to form a bucket |
| attribute | [string](#string) | | Attribute bucket to select from | | attribute | [string](#string) | | Bucket attribute to select from |
| filter | [string](#string) | | Filter reference to select from | | filter | [string](#string) | | Filter reference to select from |
<!-- end messages --> <!-- end messages -->
@ -400,7 +400,7 @@ hash distance.
| Name | Number | Description | | Name | Number | Description |
| ---- | ------ | ----------- | | ---- | ------ | ----------- |
| CLAUSE_UNSPECIFIED | 0 | No modifier defined. Will select nodes from bucket randomly. | | CLAUSE_UNSPECIFIED | 0 | No modifier defined. Nodes will be selected from the bucket randomly |
| SAME | 1 | SAME will select only nodes having the same value of bucket attribute | | SAME | 1 | SAME will select only nodes having the same value of bucket attribute |
| DISTINCT | 2 | DISTINCT will select nodes having different values of bucket attribute | | DISTINCT | 2 | DISTINCT will select nodes having different values of bucket attribute |

125
proto-docs/object.md
View file

@ -70,7 +70,7 @@
### Service "neo.fs.v2.object.ObjectService" ### Service "neo.fs.v2.object.ObjectService"
`ObjectService` provides API for manipulating objects. Object operations do `ObjectService` provides API for manipulating objects. Object operations do
not interact with sidechain and are only served by nodes in p2p style. not affect the sidechain and are only served by nodes in p2p style.
``` ```
rpc Get(GetRequest) returns (stream GetResponse); rpc Get(GetRequest) returns (stream GetResponse);
@ -86,11 +86,22 @@ rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
#### Method Get #### Method Get
Receive full object structure, including Headers and payload. Response uses Receive full object structure, including Headers and payload. Response uses
gRPC stream. First response message carries object with requested address. gRPC stream. First response message carries the object with the requested address.
Chunk messages are parts of the object's payload if it is needed. All Chunk messages are parts of the object's payload if it is needed. All
messages, except the first one, carry payload chunks. Requested object can messages, except the first one, carry payload chunks. The requested object can
be restored by concatenation of object message payload and all chunks be restored by concatenation of object message payload and all chunks
keeping receiving order. keeping the receiving order.
Extended headers can change `Get` behaviour:
* __NEOFS__NETMAP_EPOCH \
Will use the requsted version of Network Map for object placement
calculation.
* __NEOFS__NETMAP_LOOKUP_DEPTH \
Will try older versions (starting from `__NEOFS__NETMAP_EPOCH` if specified or
the latest one otherwise) of Network Map to find an object until the depth
limit is reached.
Please refer to detailed `XHeader` description.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
@ -117,7 +128,14 @@ SHOULD be of PutHeader type. `ContainerID` and `OwnerID` of an object
SHOULD be set. Session token SHOULD be obtained before `PUT` operation (see SHOULD be set. Session token SHOULD be obtained before `PUT` operation (see
session package). Chunk messages are considered by server as a part of an session package). Chunk messages are considered by server as a part of an
object payload. All messages, except first one, SHOULD be payload chunks. object payload. All messages, except first one, SHOULD be payload chunks.
Chunk messages SHOULD be sent in direct order of fragmentation. Chunk messages SHOULD be sent in the direct order of fragmentation.
Extended headers can change `Put` behaviour:
* __NEOFS__NETMAP_EPOCH \
Will use the requsted version of Network Map for object placement
calculation.
Please refer to detailed `XHeader` description.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
@ -147,6 +165,13 @@ been deleted;
Delete the object from a container. There is no immediate removal Delete the object from a container. There is no immediate removal
guarantee. Object will be marked for removal and deleted eventually. guarantee. Object will be marked for removal and deleted eventually.
Extended headers can change `Delete` behaviour:
* __NEOFS__NETMAP_EPOCH \
Will use the requsted version of Network Map for object placement
calculation.
Please refer to detailed `XHeader` description.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
object has been successfully marked to be removed from the container; object has been successfully marked to be removed from the container;
@ -167,7 +192,14 @@ Statuses:
Returns the object Headers without data payload. By default full header is 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 returned. If `main_only` request field is set, the short header with only
the very minimal information would be returned instead. the very minimal information will be returned instead.
Extended headers can change `Head` behaviour:
* __NEOFS__NETMAP_EPOCH \
Will use the requsted version of Network Map for object placement
calculation.
Please refer to detailed `XHeader` description.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
@ -193,6 +225,13 @@ Search objects in container. Search query allows to match by Object
Header's filed values. Please see the corresponding NeoFS Technical Header's filed values. Please see the corresponding NeoFS Technical
Specification section for more details. Specification section for more details.
Extended headers can change `Search` behaviour:
* __NEOFS__NETMAP_EPOCH \
Will use the requsted version of Network Map for object placement
calculation.
Please refer to detailed `XHeader` description.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
objects have been successfully selected; objects have been successfully selected;
@ -211,9 +250,19 @@ Statuses:
Get byte range of data payload. Range is set as an (offset, length) tuple. 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 Like in `Get` method, the response uses gRPC stream. Requested range can be
restored by concatenation of all received payload chunks keeping receiving restored by concatenation of all received payload chunks keeping the receiving
order. order.
Extended headers can change `GetRange` behaviour:
* __NEOFS__NETMAP_EPOCH \
Will use the requsted version of Network Map for object placement
calculation.
* __NEOFS__NETMAP_LOOKUP_DEPTH \
Will try older versions of Network Map to find an object until the depth
limit is reached.
Please refer to detailed `XHeader` description.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
data range of the object payload has been successfully read; data range of the object payload has been successfully read;
@ -228,6 +277,8 @@ Statuses:
provided session token has expired; provided session token has expired;
- **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \ - **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \
the requested object has been marked as deleted. the requested object has been marked as deleted.
- **OUT_OF_RANGE** (2053, SECTION_OBJECT): \
the requested range is out of bounds.
| Name | Input | Output | | Name | Input | Output |
| ---- | ----- | ------ | | ---- | ----- | ------ |
@ -236,8 +287,18 @@ Statuses:
Returns homomorphic or regular hash of object's payload range after Returns homomorphic or regular hash of object's payload range after
applying XOR operation with the provided `salt`. Ranges are set of (offset, applying XOR operation with the provided `salt`. Ranges are set of (offset,
length) tuples. Hashes order in response corresponds to ranges order in length) tuples. Hashes order in response corresponds to the ranges order in
request. Note that hash is calculated for XORed data. the request. Note that hash is calculated for XORed data.
Extended headers can change `GetRangeHash` behaviour:
* __NEOFS__NETMAP_EPOCH \
Will use the requsted version of Network Map for object placement
calculation.
* __NEOFS__NETMAP_LOOKUP_DEPTH \
Will try older versions of Network Map to find an object until the depth
limit is reached.
Please refer to detailed `XHeader` description.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
@ -249,6 +310,8 @@ Statuses:
access to operation RANGEHASH of the object is denied; access to operation RANGEHASH of the object is denied;
- **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \ - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
object not found in container; object not found in container;
- **OUT_OF_RANGE** (2053, SECTION_OBJECT): \
the requested range is out of bounds.
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. provided session token has expired.
@ -533,12 +596,12 @@ Object HEAD response body
<a name="neo.fs.v2.object.HeaderWithSignature"></a> <a name="neo.fs.v2.object.HeaderWithSignature"></a>
### Message HeaderWithSignature ### Message HeaderWithSignature
Tuple of full object header and signature of `ObjectID`. \ Tuple of a full object header and signature of an `ObjectID`. \
Signed `ObjectID` is present to verify full header's authenticity through the Signed `ObjectID` is present to verify full header's authenticity through the
following steps: following steps:
1. Calculate `SHA-256` of marshalled `Header` structure 1. Calculate `SHA-256` of the marshalled `Header` structure
2. Check if the resulting hash matched `ObjectID` 2. Check if the resulting hash matches `ObjectID`
3. Check if `ObjectID` signature in `signature` field is correct 3. Check if `ObjectID` signature in `signature` field is correct
@ -653,13 +716,13 @@ Object Search request body
<a name="neo.fs.v2.object.SearchRequest.Body.Filter"></a> <a name="neo.fs.v2.object.SearchRequest.Body.Filter"></a>
### Message SearchRequest.Body.Filter ### Message SearchRequest.Body.Filter
Filter structure checks if object header field or attribute content Filter structure checks if the object header field or the attribute content
matches a value. matches a value.
If no filters set, search request will return all objects of the If no filters are set, search request will return all objects of the
container, including Regular object, Tombstones and Storage Group container, including Regular object, Tombstones and Storage Group
objects. Most human users expect to get only object they can directly objects. Most human users expect to get only object they can directly
work with. In that case the `$Object:ROOT` filter should be used. work with. In that case, `$Object:ROOT` filter should be used.
By default `key` field refers to the corresponding object's `Attribute`. By default `key` field refers to the corresponding object's `Attribute`.
Some Object's header fields can also be accessed by adding `$Object:` Some Object's header fields can also be accessed by adding `$Object:`
@ -692,10 +755,10 @@ There are some well-known filter aliases to match objects by certain
properties: properties:
* $Object:ROOT \ * $Object:ROOT \
Returns only `REGULAR` type objects that are not split or are the top Returns only `REGULAR` type objects that are not split or that are the top
level root objects in a split hierarchy. This includes objects not level root objects in a split hierarchy. This includes objects not
present physically, like large objects split into smaller objects present physically, like large objects split into smaller objects
without separate top-level root object. Other type objects like without a separate top-level root object. Objects of other types like
StorageGroups and Tombstones will not be shown. This filter may be StorageGroups and Tombstones will not be shown. This filter may be
useful for listing objects like `ls` command of some virtual file useful for listing objects like `ls` command of some virtual file
system. This filter is activated if the `key` exists, disregarding the system. This filter is activated if the `key` exists, disregarding the
@ -762,7 +825,7 @@ Object Header
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Object format version. Effectively the version of API library used to create particular object | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Object format version. Effectively, the version of API library used to create particular object |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Object's container | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Object's container |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Object's owner | | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Object's owner |
| creation_epoch | [uint64](#uint64) | | Object creation Epoch | | creation_epoch | [uint64](#uint64) | | Object creation Epoch |
@ -778,10 +841,10 @@ Object Header
<a name="neo.fs.v2.object.Header.Attribute"></a> <a name="neo.fs.v2.object.Header.Attribute"></a>
### Message Header.Attribute ### Message Header.Attribute
`Attribute` is a user-defined Key-Value metadata pair attached to the `Attribute` is a user-defined Key-Value metadata pair attached to an
object. object.
Key name must be a object-unique valid UTF-8 string. Value can't be empty. Key name must be an object-unique valid UTF-8 string. Value can't be empty.
Objects with duplicated attribute names or attributes with empty values Objects with duplicated attribute names or attributes with empty values
will be considered invalid. will be considered invalid.
@ -812,7 +875,7 @@ And some well-known attributes used by applications only:
MIME Content Type of object's payload MIME Content Type of object's payload
For detailed description of each well-known attribute please see the For detailed description of each well-known attribute please see the
corresponding section in NeoFS Technical specification. corresponding section in NeoFS Technical Specification.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -844,8 +907,8 @@ must be within the same container.
### Message Object ### Message Object
Object structure. Object is immutable and content-addressed. It means Object structure. Object is immutable and content-addressed. It means
`ObjectID` will change if header or payload changes. It's calculated as a `ObjectID` will change if the header or the payload changes. It's calculated as a
hash of header field, which contains hash of object's payload. hash of header field which contains hash of the object's payload.
For non-regular object types payload format depends on object type specified For non-regular object types payload format depends on object type specified
in the header. in the header.
@ -867,7 +930,7 @@ Short header fields
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Object format version. Effectively the version of API library used to create particular object. | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Object format version. Effectively, the version of API library used to create particular object. |
| creation_epoch | [uint64](#uint64) | | Epoch when the object was created | | creation_epoch | [uint64](#uint64) | | Epoch when the object was created |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Object's owner | | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Object's owner |
| object_type | [ObjectType](#neo.fs.v2.object.ObjectType) | | Type of the object payload content | | object_type | [ObjectType](#neo.fs.v2.object.ObjectType) | | Type of the object payload content |
@ -879,17 +942,17 @@ Short header fields
<a name="neo.fs.v2.object.SplitInfo"></a> <a name="neo.fs.v2.object.SplitInfo"></a>
### Message SplitInfo ### Message SplitInfo
Meta information of split hierarchy for object assembly. With last part Meta information of split hierarchy for object assembly. With the last part
one can traverse linked list of split hierarchy back to first part and one can traverse linked list of split hierarchy back to the first part and
assemble original object. With linking object one can assembly object assemble the original object. With a linking object one can assemble an object
straight away from the object parts. right from the object parts.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| split_id | [bytes](#bytes) | | 16 byte UUID used to identify the split object hierarchy parts. | | split_id | [bytes](#bytes) | | 16 byte UUID used to identify the split object hierarchy parts. |
| last_part | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the last object in split hierarchy parts. It contains split header with original object header. | | last_part | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | The identifier of the last object in split hierarchy parts. It contains split header with the original object header. |
| link | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of linking object for split hierarchy parts. It contains split header with original object header and sorted list of object parts. | | link | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | The identifier of a linking object for split hierarchy parts. It contains split header with the original object header and a sorted list of object parts. |
<!-- end messages --> <!-- end messages -->
@ -913,7 +976,7 @@ Type of match expression
### ObjectType ### ObjectType
Type of the object payload content. Only `REGULAR` type objects can be split, Type of the object payload content. Only `REGULAR` type objects can be split,
hence `TOMBSTONE`, `STORAGE_GROUP` and `LOCK` payload is limited by maximal hence `TOMBSTONE`, `STORAGE_GROUP` and `LOCK` payload is limited by the maximum
object size. object size.
String presentation of object type is the same as definition: String presentation of object type is the same as definition:

25
proto-docs/refs.md
View file

@ -35,7 +35,7 @@
### Message Address ### Message Address
Objects in NeoFS are addressed by their ContainerID and ObjectID. Objects in NeoFS are addressed by their ContainerID and ObjectID.
String presentation of `Address` is the concatenation of string encoded String presentation of `Address` is a concatenation of string encoded
`ContainerID` and `ObjectID` delimited by '/' character. `ContainerID` and `ObjectID` delimited by '/' character.
@ -49,7 +49,7 @@ String presentation of `Address` is the concatenation of string encoded
### Message Checksum ### Message Checksum
Checksum message. Checksum message.
Depending on checksum algorithm type the string presentation may vary: Depending on checksum algorithm type, the string presentation may vary:
* TZ \ * TZ \
Hex encoded string without `0x` prefix Hex encoded string without `0x` prefix
@ -73,10 +73,10 @@ content-addressed.
[SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of
stable-marshalled container message. stable-marshalled container message.
String presentation is String presentation is a
[base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string.
JSON value will be the data encoded as a string using standard base64 JSON value will be data encoded as a string using standard base64
encoding with paddings. Either encoding with paddings. Either
[standard](https://tools.ietf.org/html/rfc4648#section-4) or [standard](https://tools.ietf.org/html/rfc4648#section-4) or
[URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding
@ -92,17 +92,17 @@ with/without paddings are accepted.
### Message ObjectID ### Message ObjectID
NeoFS Object unique identifier. Objects are immutable and content-addressed. NeoFS Object unique identifier. Objects are immutable and content-addressed.
It means `ObjectID` will change if `header` or `payload` changes. It means `ObjectID` will change if the `header` or the `payload` changes.
`ObjectID` is a 32 byte long `ObjectID` is a 32 byte long
[SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of
object's `header` field, which, in it's turn, contains hash of object's the object's `header` field, which, in it's turn, contains the hash of the object's
payload. payload.
String presentation is String presentation is a
[base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string.
JSON value will be the data encoded as a string using standard base64 JSON value will be data encoded as a string using standard base64
encoding with paddings. Either encoding with paddings. Either
[standard](https://tools.ietf.org/html/rfc4648#section-4) or [standard](https://tools.ietf.org/html/rfc4648#section-4) or
[URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding
@ -124,10 +124,10 @@ be directly used as `OwnerID`.
`OwnerID` is a 25 bytes sequence starting with Neo version prefix byte `OwnerID` is a 25 bytes sequence starting with Neo version prefix byte
followed by 20 bytes of ScrptHash and 4 bytes of checksum. followed by 20 bytes of ScrptHash and 4 bytes of checksum.
String presentation is [Base58 String presentation is a [Base58
Check](https://en.bitcoin.it/wiki/Base58Check_encoding) Encoded string. Check](https://en.bitcoin.it/wiki/Base58Check_encoding) Encoded string.
JSON value will be the data encoded as a string using standard base64 JSON value will be data encoded as a string using standard base64
encoding with paddings. Either encoding with paddings. Either
[standard](https://tools.ietf.org/html/rfc4648#section-4) or [standard](https://tools.ietf.org/html/rfc4648#section-4) or
[URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding
@ -171,7 +171,7 @@ NeoFS subnetwork identifier.
String representation of a value is base-10 integer. String representation of a value is base-10 integer.
JSON representation is an object containing single `value` number field. JSON representation is an object containing a single `value` number field.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -185,7 +185,7 @@ JSON representation is an object containing single `value` number field.
API version used by a node. API version used by a node.
String presentation is a Semantic Versioning 2.0.0 compatible version string String presentation is a Semantic Versioning 2.0.0 compatible version string
with 'v' prefix. I.e. `vX.Y`, where `X` - major number, `Y` - minor number. with 'v' prefix. i.e. `vX.Y`, where `X` is the major number, `Y` is the minor number.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -218,6 +218,7 @@ Signature scheme describes digital signing scheme used for (key, signature) pair
| ---- | ------ | ----------- | | ---- | ------ | ----------- |
| ECDSA_SHA512 | 0 | ECDSA with SHA-512 hashing (FIPS 186-3) | | ECDSA_SHA512 | 0 | ECDSA with SHA-512 hashing (FIPS 186-3) |
| ECDSA_RFC6979_SHA256 | 1 | Deterministic ECDSA with SHA-256 hashing (RFC 6979) | | ECDSA_RFC6979_SHA256 | 1 | Deterministic ECDSA with SHA-256 hashing (RFC 6979) |
| ECDSA_RFC6979_SHA256_WALLET_CONNECT | 2 | Deterministic ECDSA with SHA-256 hashing using WalletConnect API. Here the algorithm is the same, but the message format differs. |
<!-- end enums --> <!-- end enums -->

24
proto-docs/reputation.md
View file

@ -69,7 +69,7 @@ local trust has been successfully announced;
| AnnounceLocalTrust | [AnnounceLocalTrustRequest](#neo.fs.v2.reputation.AnnounceLocalTrustRequest) | [AnnounceLocalTrustResponse](#neo.fs.v2.reputation.AnnounceLocalTrustResponse) | | AnnounceLocalTrust | [AnnounceLocalTrustRequest](#neo.fs.v2.reputation.AnnounceLocalTrustRequest) | [AnnounceLocalTrustResponse](#neo.fs.v2.reputation.AnnounceLocalTrustResponse) |
#### Method AnnounceIntermediateResult #### Method AnnounceIntermediateResult
Announces the intermediate result of the iterative algorithm for Announce the intermediate result of the iterative algorithm for
calculating the global reputation of the node in NeoFS network. calculating the global reputation of the node in NeoFS network.
Statuses: Statuses:
@ -112,7 +112,7 @@ Announce intermediate global trust information.
<a name="neo.fs.v2.reputation.AnnounceIntermediateResultResponse"></a> <a name="neo.fs.v2.reputation.AnnounceIntermediateResultResponse"></a>
### Message AnnounceIntermediateResultResponse ### Message AnnounceIntermediateResultResponse
Intermediate global trust information announce response. Intermediate global trust information announcement response.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -125,9 +125,9 @@ Intermediate global trust information announce response.
<a name="neo.fs.v2.reputation.AnnounceIntermediateResultResponse.Body"></a> <a name="neo.fs.v2.reputation.AnnounceIntermediateResultResponse.Body"></a>
### Message AnnounceIntermediateResultResponse.Body ### Message AnnounceIntermediateResultResponse.Body
Response to the node's intermediate global trust information announce has Response to the node's intermediate global trust information announcement has
an empty body because the trust exchange operation is asynchronous. If an empty body because the trust exchange operation is asynchronous. If
Trust information will not pass sanity checks it is silently ignored. Trust information does not pass sanity checks, it is silently ignored.
@ -153,13 +153,13 @@ Announce node's local trust information.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| epoch | [uint64](#uint64) | | Trust assessment Epoch number | | epoch | [uint64](#uint64) | | Trust assessment Epoch number |
| trusts | [Trust](#neo.fs.v2.reputation.Trust) | repeated | List of normalized local trust values to other NeoFS nodes. The value is calculated according to EigenTrust++ algorithm and must be a floating point number in the [0;1] range. | | trusts | [Trust](#neo.fs.v2.reputation.Trust) | repeated | List of normalized local trust values to other NeoFS nodes. The value is calculated according to EigenTrust++ algorithm and must be a floating point number in [0;1] range. |
<a name="neo.fs.v2.reputation.AnnounceLocalTrustResponse"></a> <a name="neo.fs.v2.reputation.AnnounceLocalTrustResponse"></a>
### Message AnnounceLocalTrustResponse ### Message AnnounceLocalTrustResponse
Node's local trust information announce response. Node's local trust information announcement response.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -172,9 +172,9 @@ Node's local trust information announce response.
<a name="neo.fs.v2.reputation.AnnounceLocalTrustResponse.Body"></a> <a name="neo.fs.v2.reputation.AnnounceLocalTrustResponse.Body"></a>
### Message AnnounceLocalTrustResponse.Body ### Message AnnounceLocalTrustResponse.Body
Response to the node's local trust information announce has an empty body Response to the node's local trust information announcement has an empty body
because the trust exchange operation is asynchronous. If Trust information because the trust exchange operation is asynchronous. If Trust information
will not pass sanity checks it is silently ignored. does not pass sanity checks, it is silently ignored.
<!-- end messages --> <!-- end messages -->
@ -200,7 +200,7 @@ Global trust level to NeoFS node.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Message format version. Effectively the version of API library used to create the message. | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Message format version. Effectively, the version of API library used to create the message. |
| body | [GlobalTrust.Body](#neo.fs.v2.reputation.GlobalTrust.Body) | | Message body | | body | [GlobalTrust.Body](#neo.fs.v2.reputation.GlobalTrust.Body) | | Message body |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of the binary `body` field by the manager. | | signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of the binary `body` field by the manager. |
@ -220,13 +220,13 @@ Message body structure.
<a name="neo.fs.v2.reputation.PeerID"></a> <a name="neo.fs.v2.reputation.PeerID"></a>
### Message PeerID ### Message PeerID
NeoFS unique peer identifier is 33 byte long compressed public key of the NeoFS unique peer identifier is a 33 byte long compressed public key of the
node, the same as the one stored in the network map. node, the same as the one stored in the network map.
String presentation is String presentation is a
[base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string.
JSON value will be the data encoded as a string using standard base64 JSON value will be data encoded as a string using standard base64
encoding with paddings. Either encoding with paddings. Either
[standard](https://tools.ietf.org/html/rfc4648#section-4) or [standard](https://tools.ietf.org/html/rfc4648#section-4) or
[URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding

22
proto-docs/session.md
View file

@ -56,7 +56,7 @@ rpc Create(CreateRequest) returns (CreateResponse);
#### Method Create #### Method Create
Opens a new session between two peers. Open a new session between two peers.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): - **OK** (0, SECTION_SUCCESS):
@ -77,7 +77,7 @@ Information necessary for opening a session.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| body | [CreateRequest.Body](#neo.fs.v2.session.CreateRequest.Body) | | Body of create session token request message. | | body | [CreateRequest.Body](#neo.fs.v2.session.CreateRequest.Body) | | Body of a create session token request message. |
| meta_header | [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | | meta_header | [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
| verify_header | [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | | verify_header | [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
@ -180,12 +180,12 @@ request meta headers are folded in matryoshka style.
<a name="neo.fs.v2.session.RequestVerificationHeader"></a> <a name="neo.fs.v2.session.RequestVerificationHeader"></a>
### Message RequestVerificationHeader ### Message RequestVerificationHeader
Verification info for request signed by all intermediate nodes. Verification info for the request signed by all intermediate nodes.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Body signature. Should be generated once by request initiator. | | body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Body signature. Should be generated once by the request initiator. |
| meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Meta signature is added and signed by each intermediate node | | meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Meta signature is added and signed by each intermediate node |
| origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of previous hops | | origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of previous hops |
| origin | [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Chain of previous hops signatures | | origin | [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Chain of previous hops signatures |
@ -210,12 +210,12 @@ Information about the response
<a name="neo.fs.v2.session.ResponseVerificationHeader"></a> <a name="neo.fs.v2.session.ResponseVerificationHeader"></a>
### Message ResponseVerificationHeader ### Message ResponseVerificationHeader
Verification info for response signed by all intermediate nodes Verification info for the response signed by all intermediate nodes
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Body signature. Should be generated once by answering node. | | body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Body signature. Should be generated once by an answering node. |
| meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Meta signature is added and signed by each intermediate node | | meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Meta signature is added and signed by each intermediate node |
| origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of previous hops | | origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of previous hops |
| origin | [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Chain of previous hops signatures | | origin | [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Chain of previous hops signatures |
@ -265,10 +265,10 @@ Lifetime parameters of the token. Field names taken from rfc7519.
<a name="neo.fs.v2.session.XHeader"></a> <a name="neo.fs.v2.session.XHeader"></a>
### Message XHeader ### Message XHeader
Extended headers for Request/Response. May contain any user-defined headers Extended headers for Request/Response. They may contain any user-defined headers
to be interpreted on application level. to be interpreted on application level.
Key name must be unique valid UTF-8 string. Value can't be empty. Requests or Key name must be a unique valid UTF-8 string. Value can't be empty. Requests or
Responses with duplicated header names or headers with empty values will be Responses with duplicated header names or headers with empty values will be
considered invalid. considered invalid.
@ -281,9 +281,9 @@ affect system behaviour:
current epoch only will be used. current epoch only will be used.
* __NEOFS__NETMAP_LOOKUP_DEPTH \ * __NEOFS__NETMAP_LOOKUP_DEPTH \
If object can't be found using current epoch's netmap, this header limits If object can't be found using current epoch's netmap, this header limits
how many past epochs back the node can lookup. The `value` is string how many past epochs the node can look up through. The `value` is string
encoded `uint64` in decimal presentation. If set to '0' or not set, the encoded `uint64` in decimal presentation. If set to '0' or not set, only the
current epoch only will be used. current epoch will be used.
| Field | Type | Label | Description | | Field | Type | Label | Description |

8
proto-docs/status.md
View file

@ -44,12 +44,12 @@ is defined for each section. Values can be referred to in the following ways:
All outcomes are divided into successful and failed, which corresponds All outcomes are divided into successful and failed, which corresponds
to the success or failure of the operation. The definition of success to the success or failure of the operation. The definition of success
follows from the semantics of RPC and the description of its purpose. follows the semantics of RPC and the description of its purpose.
The server must not attach code that is the opposite of outcome type. The server must not attach code that is the opposite of the outcome type.
See the set of return codes in the description for calls. See the set of return codes in the description for calls.
Each status can carry developer-facing error message. It should be human Each status can carry a developer-facing error message. It should be a human
readable text in English. The server should not transmit (and the client readable text in English. The server should not transmit (and the client
should not expect) useful information in the message. Field `details` should not expect) useful information in the message. Field `details`
should make the return more detailed. should make the return more detailed.
@ -88,6 +88,7 @@ Section of failed statuses independent of the operation.
| ---- | ------ | ----------- | | ---- | ------ | ----------- |
| 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. | | 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. |
| WRONG_MAGIC_NUMBER | 1 | [**1025**] Wrong magic of the NeoFS network. Details: - [**0**] Magic number of the served NeoFS network (big-endian 64-bit unsigned integer). | | WRONG_MAGIC_NUMBER | 1 | [**1025**] Wrong magic of the NeoFS network. Details: - [**0**] Magic number of the served NeoFS network (big-endian 64-bit unsigned integer). |
| SIGNATURE_VERIFICATION_FAIL | 2 | [**1026**] Signature verification failure. |
@ -114,6 +115,7 @@ Section of statuses for object-related operations.
| LOCKED | 2 | [**2050**] Operation rejected by the object lock. | | LOCKED | 2 | [**2050**] Operation rejected by the object lock. |
| LOCK_NON_REGULAR_OBJECT | 3 | [**2051**] Locking an object with a non-REGULAR type rejected. | | LOCK_NON_REGULAR_OBJECT | 3 | [**2051**] Locking an object with a non-REGULAR type rejected. |
| OBJECT_ALREADY_REMOVED | 4 | [**2052**] Object has been marked deleted. | | OBJECT_ALREADY_REMOVED | 4 | [**2052**] Object has been marked deleted. |
| OUT_OF_RANGE | 5 | [**2053**] Invalid range has been requested for an object. |

6
proto-docs/storagegroup.md
View file

@ -26,8 +26,8 @@
### Message StorageGroup ### Message StorageGroup
StorageGroup keeps verification information for Data Audit sessions. Objects StorageGroup keeps verification information for Data Audit sessions. Objects
that require payed storage guaranties are gathered in `StorageGroups` with that require paid storage guarantees are gathered in `StorageGroups` with
additional information used for proof of storage. `StorageGroup` only additional information used for the proof of storage. `StorageGroup` only
contains objects from the same container. contains objects from the same container.
Being an object payload, StorageGroup may have expiration Epoch set with Being an object payload, StorageGroup may have expiration Epoch set with
@ -41,7 +41,7 @@ deleted by Storage Nodes.
| validation_data_size | [uint64](#uint64) | | Total size of the payloads of objects in the storage group | | validation_data_size | [uint64](#uint64) | | Total size of the payloads of objects in the storage group |
| validation_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Homomorphic hash from the concatenation of the payloads of the storage group members. The order of concatenation is the same as the order of the members in the `members` field. | | validation_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Homomorphic hash from the concatenation of the payloads of the storage group members. The order of concatenation is the same as the order of the members in the `members` field. |
| expiration_epoch | [uint64](#uint64) | | DEPRECATED. Last NeoFS epoch number of the storage group lifetime | | expiration_epoch | [uint64](#uint64) | | DEPRECATED. Last NeoFS epoch number of the storage group lifetime |
| members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Strictly ordered list of storage group member objects | | members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Strictly ordered list of storage group member objects. Members MUST be unique |
<!-- end messages --> <!-- end messages -->

6
proto-docs/tombstone.md
View file

@ -25,14 +25,14 @@
<a name="neo.fs.v2.tombstone.Tombstone"></a> <a name="neo.fs.v2.tombstone.Tombstone"></a>
### Message Tombstone ### Message Tombstone
Tombstone keeps record of deleted objects for few epochs until they are Tombstone keeps record of deleted objects for a few epochs until they are
purged from the NeoFS network. purged from the NeoFS network.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| expiration_epoch | [uint64](#uint64) | | Last NeoFS epoch number of the tombstone lifetime. It's set by tombstone creator depending on current NeoFS network settings. Tombstone object must have the same expiration epoch value in `__NEOFS__EXPIRATION_EPOCH` attribute. Otherwise tombstone will be rejected by storage node. | | expiration_epoch | [uint64](#uint64) | | Last NeoFS epoch number of the tombstone lifetime. It's set by the tombstone creator depending on the current NeoFS network settings. A tombstone object must have the same expiration epoch value in `__NEOFS__EXPIRATION_EPOCH` attribute. Otherwise, the tombstone will be rejected by a storage node. |
| split_id | [bytes](#bytes) | | 16 byte UUID used to identify the split object hierarchy parts. Must be unique inside container. All objects participating in the split must have the same `split_id` value. | | split_id | [bytes](#bytes) | | 16 byte UUID used to identify the split object hierarchy parts. Must be unique inside a container. All objects participating in the split must have the same `split_id` value. |
| members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of objects to be deleted. | | members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of objects to be deleted. |
<!-- end messages --> <!-- end messages -->