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

Update auto-generated docs

Browse source 
Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>
This commit is contained in:
Stanislav Bogatyrev 2020-10-16 14:40:12 +03:00
parent 095a6cb043
commit a6ecab41b8
8 changed files with 433 additions and 298 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
proto-docs/accounting.md
View file

@ -35,8 +35,11 @@
<a name="neo.fs.v2.accounting.AccountingService"></a>
### Service "neo.fs.v2.accounting.AccountingService"
The service provides methods for obtaining information
about the account balance in NeoFS system.
Accounting service provides methods for interaction with NeoFS sidechain via
other NeoFS nodes to get information about the account balance. Deposit and
Withdraw operations can't be implemented here, as they require Mainnet NeoFS
smart contract invocation. Transfer operations between internal NeoFS
accounts are possible, if both use the same token type.
```
rpc Balance(BalanceRequest) returns (BalanceResponse);
@ -45,7 +48,7 @@ rpc Balance(BalanceRequest) returns (BalanceResponse);
#### Method Balance
Returns the amount of funds for the requested NeoFS account.
Returns the amount of funds in GAS token for the requested NeoFS account.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -56,13 +59,7 @@ Returns the amount of funds for the requested NeoFS account.
<a name="neo.fs.v2.accounting.BalanceRequest"></a>
### Message BalanceRequest
Message defines the request body of Balance method.
To indicate the account for which the balance is requested, it's identifier
is used.
To gain access to the requested information, the request body must be formed
according to the requirements from the system specification.
BalanceRequest message
| Field | Type | Label | Description |
@ -75,20 +72,21 @@ according to the requirements from the system specification.
<a name="neo.fs.v2.accounting.BalanceRequest.Body"></a>
### Message BalanceRequest.Body
Request body
To indicate the account for which the balance is requested, it's identifier
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
signer `OwnerID`.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Carries user identifier in NeoFS system for which the balance is requested. |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Valid user identifier in `OwnerID` format for which the balance is requested. Required field. |
<a name="neo.fs.v2.accounting.BalanceResponse"></a>
### Message BalanceResponse
Message defines the response body of Balance method.
The amount of funds is calculated in decimal numbers.
BalanceResponse message
| Field | Type | Label | Description |
@ -101,12 +99,13 @@ The amount of funds is calculated in decimal numbers.
<a name="neo.fs.v2.accounting.BalanceResponse.Body"></a>
### Message BalanceResponse.Body
Request body
The amount of funds in GAS token for the `OwnerID`'s account requested.
Balance is `Decimal` format to avoid precision issues with rounding.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| balance | [Decimal](#neo.fs.v2.accounting.Decimal) | | Carries the amount of funds on the account. |
| balance | [Decimal](#neo.fs.v2.accounting.Decimal) | | Amount of funds in GAS token for the requested account. |
<!-- end messages -->
@ -126,13 +125,19 @@ Request body
<a name="neo.fs.v2.accounting.Decimal"></a>
### Message Decimal
Decimal represents the decimal numbers.
Standard floating point data type can't be used in NeoFS due to inexactness
of the result when doing lots of small number operations. To solve the lost
precision issue, special `Decimal` format is used for monetary computations.
Please see [The General Decimal Arithmetic
Specification](http://speleotrove.com/decimal/) for detailed problem
description.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| value | [int64](#int64) | | value carries number value. |
| precision | [uint32](#uint32) | | precision carries value precision. |
| value | [int64](#int64) | | Number in smallest Token fractions. |
| precision | [uint32](#uint32) | | Precision value indicating how many smallest fractions can be in one integer. |
<!-- end messages -->

75
proto-docs/acl.md
View file

@ -31,7 +31,12 @@
<a name="neo.fs.v2.acl.BearerToken"></a>
### Message BearerToken
BearerToken has information about request ACL rules with limited lifetime
BearerToken allows to attach signed Extended ACL rules to the request in
`RequestMetaHeader`. If container's Basic ACL rules allow, the attached rule
set will be checked instead of one attached to the container itself. Just
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
authenticated party.
| Field | Type | Label | Description |
@ -43,20 +48,22 @@ BearerToken has information about request ACL rules with limited lifetime
<a name="neo.fs.v2.acl.BearerToken.Body"></a>
### Message BearerToken.Body
Bearer Token body
Bearer Token body structure contains Extended ACL table issued by container
owner with additional information preventing token's abuse.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| eacl_table | [EACLTable](#neo.fs.v2.acl.EACLTable) | | EACLTable carries table of extended ACL rules |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | OwnerID carries identifier of the token owner |
| eacl_table | [EACLTable](#neo.fs.v2.acl.EACLTable) | | Table of Extended ACL rules to use instead of the ones attached to the container |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | `OwnerID` to whom the token was issued. MUST match with the request originator's `OwnerID` |
| lifetime | [BearerToken.Body.TokenLifetime](#neo.fs.v2.acl.BearerToken.Body.TokenLifetime) | | Token expiration and valid time period parameters |
<a name="neo.fs.v2.acl.BearerToken.Body.TokenLifetime"></a>
### Message BearerToken.Body.TokenLifetime
Lifetime parameters of the token. Filed names taken from rfc7519.
Lifetime parameters of the token. Filed names taken from
[rfc7519](https://tools.ietf.org/html/rfc7519).
| Field | Type | Label | Description |
@ -69,54 +76,58 @@ Lifetime parameters of the token. Filed names taken from rfc7519.
<a name="neo.fs.v2.acl.EACLRecord"></a>
### Message EACLRecord
EACLRecord groups information about extended ACL rule.
Describes a single eACL rule.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| operation | [Operation](#neo.fs.v2.acl.Operation) | | Operation carries type of operation. |
| action | [Action](#neo.fs.v2.acl.Action) | | Action carries ACL target action. |
| filters | [EACLRecord.Filter](#neo.fs.v2.acl.EACLRecord.Filter) | repeated | filters carries set of filters. |
| targets | [EACLRecord.Target](#neo.fs.v2.acl.EACLRecord.Target) | repeated | targets carries information about extended ACL target list. |
| operation | [Operation](#neo.fs.v2.acl.Operation) | | NeoFS request Verb to match |
| action | [Action](#neo.fs.v2.acl.Action) | | Rule execution result. Either allows or denies access if filters match. |
| filters | [EACLRecord.Filter](#neo.fs.v2.acl.EACLRecord.Filter) | repeated | List of filters to match and see if rule is applicable |
| targets | [EACLRecord.Target](#neo.fs.v2.acl.EACLRecord.Target) | repeated | List of target subjects to apply ACL rule to |
<a name="neo.fs.v2.acl.EACLRecord.Filter"></a>
### Message EACLRecord.Filter
Filter definition
Filter to check particular properties of the request or object.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| header_type | [HeaderType](#neo.fs.v2.acl.HeaderType) | | Header carries type of header. |
| match_type | [MatchType](#neo.fs.v2.acl.MatchType) | | MatchType carries type of match. |
| header_name | [string](#string) | | header_name carries name of filtering header. |
| header_val | [string](#string) | | header_val carries value of filtering header. |
| header_type | [HeaderType](#neo.fs.v2.acl.HeaderType) | | Define if Object or Request header will be used |
| match_type | [MatchType](#neo.fs.v2.acl.MatchType) | | Match operation type |
| header_name | [string](#string) | | Name of the Header to use |
| header_val | [string](#string) | | Expected Header Value or pattern to match |
<a name="neo.fs.v2.acl.EACLRecord.Target"></a>
### Message EACLRecord.Target
Information about extended ACL target.
Target to apply ACL rule. Can be a subject's role class or a list of public
keys to match.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| role | [Role](#neo.fs.v2.acl.Role) | | target carries target of ACL rule. |
| key_list | [bytes](#bytes) | repeated | key_list carries public keys of ACL target. |
| role | [Role](#neo.fs.v2.acl.Role) | | Target subject's role class |
| key_list | [bytes](#bytes) | repeated | List of public keys to identify target subject |
<a name="neo.fs.v2.acl.EACLTable"></a>
### Message EACLTable
EACLRecord carries the information about extended ACL rules.
Extended ACL rules table. Defined a list of ACL rules additionally to Basic
ACL. Extended ACL rules can be attached to the container and can be updated
or may be defined in `BearerToken` structure. Please see the corresponding
NeoFS Technical Specification's section for detailed 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 |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Carries identifier of the container that should use given access control rules. |
| records | [EACLRecord](#neo.fs.v2.acl.EACLRecord) | repeated | Records carries list of extended ACL rule records. |
| 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 |
| records | [EACLRecord](#neo.fs.v2.acl.EACLRecord) | repeated | List of Extended ACL rules |
<!-- end messages -->
@ -124,11 +135,12 @@ EACLRecord carries the information about extended ACL rules.
<a name="neo.fs.v2.acl.Action"></a>
### Action
Action is an enumeration of EACL actions.
Rule execution result action. Either allows or denies access if the rule's
filters match.
| Name | Number | Description |
| ---- | ------ | ----------- |
| ACTION_UNSPECIFIED | 0 | Unspecified action, default value. |
| ACTION_UNSPECIFIED | 0 | Unspecified action, default value |
| ALLOW | 1 | Allow action |
| DENY | 2 | Deny action |
@ -137,7 +149,7 @@ Action is an enumeration of EACL actions.
<a name="neo.fs.v2.acl.HeaderType"></a>
### HeaderType
Header is an enumeration of filtering header types.
Enumeration of possible sources of Headers to apply filters.
| Name | Number | Description |
| ---- | ------ | ----------- |
@ -163,11 +175,12 @@ MatchType is an enumeration of match types.
<a name="neo.fs.v2.acl.Operation"></a>
### Operation
Operation is an enumeration of operation types.
Request's operation type to match if the rule is applicable to a particular
request.
| Name | Number | Description |
| ---- | ------ | ----------- |
| OPERATION_UNSPECIFIED | 0 | Unspecified operation, default value. |
| OPERATION_UNSPECIFIED | 0 | Unspecified operation, default value |
| GET | 1 | Get |
| HEAD | 2 | Head |
| PUT | 3 | Put |
@ -185,10 +198,10 @@ Target role of the access control rule in access control list.
| Name | Number | Description |
| ---- | ------ | ----------- |
| ROLE_UNSPECIFIED | 0 | Unspecified role, default value. |
| 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. |
| OTHERS | 3 | Others target rule is applied if sender is not user or system target. |
| ROLE_UNSPECIFIED | 0 | Unspecified role, default value |
| 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 |
| OTHERS | 3 | Others target rule is applied if sender is not user nor system target |
<!-- end enums -->

145
proto-docs/container.md
View file

@ -56,8 +56,10 @@
<a name="neo.fs.v2.container.ContainerService"></a>
### Service "neo.fs.v2.container.ContainerService"
ContainerService provides API to access container smart-contract in morph chain
via NeoFS node.
`ContainerService` provides API to interact with `Container` smart contract
in NeoFS sidechain via other NeoFS nodes. All of those actions can be done
equivalently by directly issuing transactions and RPC calls to sidechain
nodes.
```
rpc Put(PutRequest) returns (PutResponse);
@ -71,52 +73,51 @@ rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse);
#### Method Put
Put invokes 'Put' method in container smart-contract and returns
response immediately. After new block in morph chain, request is verified
by inner ring nodes. After one more block in morph chain, container
added into smart-contract storage.
`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, container
is added into smart contract storage.
| Name | Input | Output |
| ---- | ----- | ------ |
| Put | [PutRequest](#neo.fs.v2.container.PutRequest) | [PutResponse](#neo.fs.v2.container.PutResponse) |
#### Method Delete
Delete invokes 'Delete' method in container smart-contract and returns
response immediately. After new block in morph chain, request is verified
by inner ring nodes. After one more block in morph chain, container
removed from smart-contract storage.
`Delete` invokes `Container` smart contract's `Delete` method and returns
response immediately. After a new block is issued in sidechain, request is
verified by Inner Ring nodes. After one more block in sidechain, container
is added into smart contract storage.
| Name | Input | Output |
| ---- | ----- | ------ |
| Delete | [DeleteRequest](#neo.fs.v2.container.DeleteRequest) | [DeleteResponse](#neo.fs.v2.container.DeleteResponse) |
#### Method Get
Get returns container from container smart-contract storage.
Returns container structure from `Container` smart contract storage.
| Name | Input | Output |
| ---- | ----- | ------ |
| Get | [GetRequest](#neo.fs.v2.container.GetRequest) | [GetResponse](#neo.fs.v2.container.GetResponse) |
#### Method List
List returns all owner's containers from container smart-contract
storage.
Returns all owner's containers from 'Container` smart contract' storage.
| Name | Input | Output |
| ---- | ----- | ------ |
| List | [ListRequest](#neo.fs.v2.container.ListRequest) | [ListResponse](#neo.fs.v2.container.ListResponse) |
#### Method SetExtendedACL
SetExtendedACL invokes 'SetEACL' method in container smart-contract and
returns response immediately. After new block in morph chain,
Extended ACL added into smart-contract storage.
Invokes 'SetEACL' method of 'Container` smart contract and returns response
immediately. After one more block in sidechain, Extended ACL changes are
added into smart contract storage.
| Name | Input | Output |
| ---- | ----- | ------ |
| SetExtendedACL | [SetExtendedACLRequest](#neo.fs.v2.container.SetExtendedACLRequest) | [SetExtendedACLResponse](#neo.fs.v2.container.SetExtendedACLResponse) |
#### Method GetExtendedACL
GetExtendedACL returns Extended ACL table and signature from container
smart-contract storage.
Returns Extended ACL table and signature from `Container` smart contract
storage.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -140,20 +141,22 @@ Container removal request
<a name="neo.fs.v2.container.DeleteRequest.Body"></a>
### Message DeleteRequest.Body
Request body
Container removal request body has a signed `ContainerID` as a proof of
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 | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | container_id carries identifier of the container to delete from NeoFS. |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of container id according to RFC-6979. |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container to delete from NeoFS |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | `ContainerID` signed with the container owner's key according to RFC-6979 |
<a name="neo.fs.v2.container.DeleteResponse"></a>
### Message DeleteResponse
DeleteResponse is empty because delete operation is asynchronous and done
via consensus in inner ring nodes
`DeleteResponse` has an empty body because delete operation is asynchronous
and done via consensus in Inner Ring nodes.
| Field | Type | Label | Description |
@ -166,7 +169,8 @@ via consensus in inner ring nodes
<a name="neo.fs.v2.container.DeleteResponse.Body"></a>
### Message DeleteResponse.Body
Response body
`DeleteResponse` has an empty body because delete operation is asynchronous
and done via consensus in Inner Ring nodes.
@ -186,12 +190,12 @@ Get Extended ACL
<a name="neo.fs.v2.container.GetExtendedACLRequest.Body"></a>
### Message GetExtendedACLRequest.Body
Request body
Get Extended ACL request body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | container_id carries identifier of the container that has Extended ACL. |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container having Extended ACL |
<a name="neo.fs.v2.container.GetExtendedACLResponse"></a>
@ -210,13 +214,15 @@ Get Extended ACL
<a name="neo.fs.v2.container.GetExtendedACLResponse.Body"></a>
### Message GetExtendedACLResponse.Body
Response body
Get Extended ACL Response body can be empty if the requested container did
not have Extended ACL Table attached or Extended ACL was not allowed at
container creation.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) | | Extended ACL that has been requested if it was set up. |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of stable-marshalled Extended ACL according to RFC-6979. |
| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) | | Extended ACL requested, if available |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of stable-marshalled Extended ACL according to RFC-6979 |
<a name="neo.fs.v2.container.GetRequest"></a>
@ -235,12 +241,12 @@ Get container structure
<a name="neo.fs.v2.container.GetRequest.Body"></a>
### Message GetRequest.Body
Request body
Get container structure request body.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | container_id carries identifier of the container to get. |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container to get |
<a name="neo.fs.v2.container.GetResponse"></a>
@ -259,12 +265,13 @@ Get container structure
<a name="neo.fs.v2.container.GetResponse.Body"></a>
### Message GetResponse.Body
Response body
Get container response body does not have container structure signature. It
was already verified on container creation.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| container | [Container](#neo.fs.v2.container.Container) | | Container that has been requested. |
| container | [Container](#neo.fs.v2.container.Container) | | Requested container structure |
<a name="neo.fs.v2.container.ListRequest"></a>
@ -275,7 +282,7 @@ List containers
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [ListRequest.Body](#neo.fs.v2.container.ListRequest.Body) | | Body of list containers request message. |
| body | [ListRequest.Body](#neo.fs.v2.container.ListRequest.Body) | | Body of list containers request message |
| meta_header | [neo.fs.v2.session.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 | [neo.fs.v2.session.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. |
@ -283,12 +290,12 @@ List containers
<a name="neo.fs.v2.container.ListRequest.Body"></a>
### Message ListRequest.Body
Request body
List containers request body.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | owner_id carries identifier of the container owner. |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Identifier of the container owner |
<a name="neo.fs.v2.container.ListResponse"></a>
@ -307,12 +314,12 @@ List containers
<a name="neo.fs.v2.container.ListResponse.Body"></a>
### Message ListResponse.Body
Response body
List containers response body.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| container_ids | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | repeated | ContainerIDs carries list of identifiers of the containers that belong to the owner. |
| container_ids | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | repeated | List of `ContainerID`s belonging to the requested `OwnerID` |
<a name="neo.fs.v2.container.PutRequest"></a>
@ -331,13 +338,17 @@ New NeoFS Container creation request
<a name="neo.fs.v2.container.PutRequest.Body"></a>
### Message PutRequest.Body
Request 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](#neo.fs.v2.container.Container) | | Container to create in NeoFS. |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of stable-marshalled container according to RFC-6979. |
| container | [Container](#neo.fs.v2.container.Container) | | Container structure to register in NeoFS |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of a stable-marshalled container according to RFC-6979 |
<a name="neo.fs.v2.container.PutResponse"></a>
@ -356,12 +367,15 @@ New NeoFS Container creation response
<a name="neo.fs.v2.container.PutResponse.Body"></a>
### Message PutResponse.Body
Response 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 was done as expected.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | container_id carries identifier of the new container. |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Unique identifier of the newly created container |
<a name="neo.fs.v2.container.SetExtendedACLRequest"></a>
@ -380,13 +394,14 @@ Set Extended ACL
<a name="neo.fs.v2.container.SetExtendedACLRequest.Body"></a>
### Message SetExtendedACLRequest.Body
Request body
Set Extended ACL request body does not have separate `ContainerID`
reference. It will be taken from `EACLTable.container_id` field.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) | | Extended ACL to set for the container. |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of stable-marshalled Extended ACL according to RFC-6979. |
| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) | | Extended ACL table to set for container |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of stable-marshalled Extended ACL table according to RFC-6979 |
<a name="neo.fs.v2.container.SetExtendedACLResponse"></a>
@ -405,7 +420,9 @@ Set Extended ACL
<a name="neo.fs.v2.container.SetExtendedACLResponse.Body"></a>
### Message SetExtendedACLResponse.Body
Response body
`SetExtendedACLResponse` has an empty body because the operation is
asynchronous and update should be reflected in `Container` smart contract's
storage after next block is issued in sidechain.
<!-- end messages -->
@ -426,32 +443,40 @@ Response body
<a name="neo.fs.v2.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. ID of the container is a 32 byte long
SHA256 hash of stable-marshalled container message.
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. ID of the container is a 32 byte long SHA256 hash
of stable-marshalled container message.
| 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 |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | OwnerID carries identifier of the container owner. |
| nonce | [bytes](#bytes) | | Nonce is a 16 byte UUID, used to avoid collisions of container id. |
| basic_acl | [uint32](#uint32) | | BasicACL contains access control rules for owner, system, others groups and permission bits for bearer token and Extended ACL. |
| attributes | [Container.Attribute](#neo.fs.v2.container.Container.Attribute) | repeated | Attributes define any immutable characteristics of container. |
| placement_policy | [neo.fs.v2.netmap.PlacementPolicy](#neo.fs.v2.netmap.PlacementPolicy) | | Placement policy for the object inside the container. |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Container format version. Effectively the version of API library used to create container. |
| 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 UUID, used to avoid collisions of container id |
| basic_acl | [uint32](#uint32) | | `BasicACL` contains access control rules for owner, system, others groups and permission bits for `BearerToken` and `Extended ACL` |
| 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 |
<a name="neo.fs.v2.container.Container.Attribute"></a>
### Message Container.Attribute
Attribute is a key-value pair of strings.
`Attribute` is a user-defined Key-Value metadata pair attached to the
container. Container attribute are immutable. They are set at container
creation and cna never be added or updated.
There are some "well-known" attributes affecting system behaviour:
* Subnet \
String ID of container's storage subnet. Container can be attached to
only one subnet.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| key | [string](#string) | | Key of immutable container attribute. |
| value | [string](#string) | | Value of immutable container attribute. |
| key | [string](#string) | | Attribute name key |
| value | [string](#string) | | Attribute value |
<!-- end messages -->

96
proto-docs/netmap.md
View file

@ -40,7 +40,10 @@
<a name="neo.fs.v2.netmap.NetmapService"></a>
### Service "neo.fs.v2.netmap.NetmapService"
Methods to work with NetworkMap
`NetmapService` provides methods to work with `Network Map` and information
required to build it. The resulting `Network Map` is stored in sidechain
`Netmap` smart contract, while related information can be obtained from other
NeoFS nodes.
```
rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
@ -49,7 +52,11 @@ rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
#### Method LocalNodeInfo
Return information about Node
Get NodeInfo structure from the particular node directly. Node information
can be taken from `Netmap` smart contract, but in some cases the 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
further communication. Can also be used to check if node is up and running.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -60,12 +67,12 @@ Return information about Node
<a name="neo.fs.v2.netmap.LocalNodeInfoRequest"></a>
### Message LocalNodeInfoRequest
Get NodeInfo from the particular node directly
Get NodeInfo structure from the particular node directly
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [LocalNodeInfoRequest.Body](#neo.fs.v2.netmap.LocalNodeInfoRequest.Body) | | Body of the balance request message. |
| body | [LocalNodeInfoRequest.Body](#neo.fs.v2.netmap.LocalNodeInfoRequest.Body) | | Body of the LocalNodeInfo request message |
| meta_header | [neo.fs.v2.session.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 | [neo.fs.v2.session.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. |
@ -73,14 +80,14 @@ Get NodeInfo from the particular node directly
<a name="neo.fs.v2.netmap.LocalNodeInfoRequest.Body"></a>
### Message LocalNodeInfoRequest.Body
Request body
LocalNodeInfo request body is empty.
<a name="neo.fs.v2.netmap.LocalNodeInfoResponse"></a>
### Message LocalNodeInfoResponse
Local nod Info, including API Version in use
Local Node Info, including API Version in use
| Field | Type | Label | Description |
@ -93,13 +100,13 @@ Local nod Info, including API Version in use
<a name="neo.fs.v2.netmap.LocalNodeInfoResponse.Body"></a>
### Message LocalNodeInfoResponse.Body
Response body
Local Node Info, including API Version in use.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | API version in use |
| node_info | [NodeInfo](#neo.fs.v2.netmap.NodeInfo) | | NodeInfo from node itself |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Latest NeoFS API version in use |
| node_info | [NodeInfo](#neo.fs.v2.netmap.NodeInfo) | | NodeInfo structure with recent information from node itself |
<!-- end messages -->
@ -119,12 +126,13 @@ Response body
<a name="neo.fs.v2.netmap.Filter"></a>
### Message Filter
Filter
Filter will return the subset of nodes from `NetworkMap` or another filter's
results, that will satisfy filter's conditions.
| 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 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 |
| key | [string](#string) | | Key to filter |
| op | [Operation](#neo.fs.v2.netmap.Operation) | | Filtering operation |
| value | [string](#string) | | Value to match |
@ -148,26 +156,63 @@ NeoFS node description
<a name="neo.fs.v2.netmap.NodeInfo.Attribute"></a>
### Message NodeInfo.Attribute
Attributes of the NeoFS node.
Administrator-defined Attributes of the NeoFS Storage Node.
Node's attributes are mostly used during Storage Policy evaluation to
calculate object's placement and find a set of nodes satisfying policy
requirements. There are some "well-known" node attributes common to all the
Storage Nodes in the network and used implicitly with default values if not
explicitly set:
* Capacity \
Total available disk space in Gigabytes.
* Price \
Price in GAS tokens for storing one GB of data during one Epoch. In node
attributes it's a string presenting floating point number with comma or
point delimiter for decimal part. In the Network Map it will be saved as
64-bit unsigned integer representing number of minimal token fractions.
* Subnet \
String ID of Node's storage subnet. There can be only one subnet served
by the Storage Node.
* Locode \
Node's geographic location in
[UN/LOCODE](https://www.unece.org/cefact/codesfortrade/codes_index.html)
format approximated to the nearest point defined in standard.
* Country \
Country code in
[ISO 3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
format. Calculated automatically from `Locode` attribute
* Region \
Country's administative subdivision where node is located. Calculated
automatically from `Locode` attribute based on `SubDiv` field. Presented
in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format.
* City \
City, town, village or rural area name where node is located written
without diacritics . Calculated automatically from `Locode` attribute.
For detailed description of each well-known attribute please see the
corresponding section in NeoFS Technical specification.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| key | [string](#string) | | Key of the node attribute. |
| value | [string](#string) | | Value of the node attribute. |
| parents | [string](#string) | repeated | Parent keys, if any Example: For City it can be Region or Country |
| parents | [string](#string) | repeated | Parent keys, if any. For example for `City` it could be `Region` and `Country`. |
<a name="neo.fs.v2.netmap.PlacementPolicy"></a>
### Message PlacementPolicy
Set of rules to select a subset of nodes able to store container's objects
Set of rules to select a subset of nodes from `NetworkMap` able to store
container's objects. The format is simple enough to transpile from different
storage policy definition languages.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| replicas | [Replica](#neo.fs.v2.netmap.Replica) | repeated | Rules to set number of object replicas and place each one into a particular bucket |
| container_backup_factor | [uint32](#uint32) | | Container backup factor controls how deep NeoFS will search for nodes alternatives to include into container. |
| replicas | [Replica](#neo.fs.v2.netmap.Replica) | repeated | Rules to set number of object replicas and place each one into a named bucket |
| container_backup_factor | [uint32](#uint32) | | Container backup factor controls how deep NeoFS will search for nodes alternatives to include into container's nodes subset |
| selectors | [Selector](#neo.fs.v2.netmap.Selector) | repeated | Set of Selectors to form the container's nodes subset |
| filters | [Filter](#neo.fs.v2.netmap.Filter) | repeated | List of named filters to reference in selectors |
@ -175,25 +220,28 @@ Set of rules to select a subset of nodes able to store container's objects
<a name="neo.fs.v2.netmap.Replica"></a>
### Message Replica
Exact bucket for each replica
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
default.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| count | [uint32](#uint32) | | How many object replicas to put |
| selector | [string](#string) | | Named selector bucket to put in |
| selector | [string](#string) | | Named selector bucket to put replicas |
<a name="neo.fs.v2.netmap.Selector"></a>
### Message Selector
Selector
Selector chooses a number of nodes from the bucket taking the nearest nodes
to the provided `ContainerID` by hash distance.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| name | [string](#string) | | Selector name to reference in object placement section |
| count | [uint32](#uint32) | | How many nodes to select from 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 |
| attribute | [string](#string) | | Attribute bucket to select from |
| filter | [string](#string) | | Filter reference to select from |
@ -204,13 +252,13 @@ Selector
<a name="neo.fs.v2.netmap.Clause"></a>
### Clause
Selector modifier showing how the node set will be formed
By default selector just groups by attribute into a bucket selecting nodes
only by their hash distance.
Selector modifier shows how the node set will be formed. By default selector
just groups nodes into a bucket by attribute, selecting nodes only by their
hash distance.
| Name | Number | Description |
| ---- | ------ | ----------- |
| CLAUSE_UNSPECIFIED | 0 | No modifier defined |
| CLAUSE_UNSPECIFIED | 0 | No modifier defined. Will select nodes from bucket randomly. |
| 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 |

228
proto-docs/object.md
View file

@ -68,7 +68,8 @@
<a name="neo.fs.v2.object.ObjectService"></a>
### Service "neo.fs.v2.object.ObjectService"
Object service provides API for manipulating with the object.
`ObjectService` provides API for manipulating objects. Object operations do
not interact with sidechain and are only served by nodes in p2p style.
```
rpc Get(GetRequest) returns (stream GetResponse);
@ -83,11 +84,12 @@ rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
#### Method Get
Get the object from container. Response uses gRPC stream. First response
message carry object of requested address. Chunk messages are parts of
the object's payload if it is needed. All messages except first carry
chunks. Requested object can be restored by concatenation of object
message payload and all chunks keeping receiving order.
Receive full object structure, including Headers and payload. Response uses
gRPC stream. First response message carries object with requested address.
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
be restored by concatenation of object message payload and all chunks
keeping receiving order.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -95,55 +97,57 @@ message payload and all chunks keeping receiving order.
#### Method Put
Put the object into container. Request uses gRPC stream. First message
SHOULD BE type of PutHeader. Container id and Owner id of object SHOULD
BE set. Session token SHOULD BE obtained before put operation (see
session package). Chunk messages considered by server as part of object
payload. All messages except first SHOULD BE chunks. Chunk messages
SHOULD BE sent in direct order of fragmentation.
SHOULD be of PutHeader type. `ContainerID` and `OwnerID` of an object
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
object payload. All messages, except first one, SHOULD be payload chunks.
Chunk messages SHOULD be sent in direct order of fragmentation.
| Name | Input | Output |
| ---- | ----- | ------ |
| Put | [PutRequest](#neo.fs.v2.object.PutRequest) | [PutResponse](#neo.fs.v2.object.PutResponse) |
#### Method Delete
Delete the object from a container
Delete the object from a container. There is no immediate removal
guarantee. Object will be marked for removal and deleted eventually.
| Name | Input | Output |
| ---- | ----- | ------ |
| Delete | [DeleteRequest](#neo.fs.v2.object.DeleteRequest) | [DeleteResponse](#neo.fs.v2.object.DeleteResponse) |
#### Method Head
Head returns the object without data payload. Object in the
response has system header only. If full headers flag is set, extended
headers are also present.
Returns the object Headers without data payload. By default full header is
returned. If `main_only` request field is set, the short header with only
the very minimal information would be returned instead.
| Name | Input | Output |
| ---- | ----- | ------ |
| Head | [HeadRequest](#neo.fs.v2.object.HeadRequest) | [HeadResponse](#neo.fs.v2.object.HeadResponse) |
#### Method Search
Search objects in container. Version of query language format SHOULD BE
set to 1. Search query represented in serialized format (see query
package).
Search objects in container. Search query allows to match by Object
Header's filed values. Please see the corresponding NeoFS Technical
Specification section for more details.
| Name | Input | Output |
| ---- | ----- | ------ |
| Search | [SearchRequest](#neo.fs.v2.object.SearchRequest) | [SearchResponse](#neo.fs.v2.object.SearchResponse) |
#### Method GetRange
GetRange of data payload. Range is a pair (offset, length).
Requested range can be restored by concatenation of all chunks
keeping receiving order.
Get byte range of data payload. Range is set as an (offset, length) tuple.
Like in `Get` method, the response uses gRPC stream. Requested range can be
restored by concatenation of all received payload chunks keeping receiving
order.
| Name | Input | Output |
| ---- | ----- | ------ |
| GetRange | [GetRangeRequest](#neo.fs.v2.object.GetRangeRequest) | [GetRangeResponse](#neo.fs.v2.object.GetRangeResponse) |
#### Method GetRangeHash
GetRangeHash returns homomorphic hash of object payload range after XOR
operation. Ranges are set of pairs (offset, length). Hashes order in
response corresponds to ranges order in request. Homomorphic hash is
calculated for XORed data.
Returns homomorphic or regular hash of object's payload range after
applying XOR operation with the provided `salt`. Ranges are set of (offset,
length) tuples. Hashes order in response corresponds to ranges order in
request. Note that hash is calculated for XORed data.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -154,7 +158,7 @@ calculated for XORed data.
<a name="neo.fs.v2.object.DeleteRequest"></a>
### Message DeleteRequest
Object Delete request
Object DELETE request
| Field | Type | Label | Description |
@ -167,19 +171,19 @@ Object Delete request
<a name="neo.fs.v2.object.DeleteRequest.Body"></a>
### Message DeleteRequest.Body
Request body
Object DELETE request body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Carries the address of the object to be deleted. |
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address of the object to be deleted |
<a name="neo.fs.v2.object.DeleteResponse"></a>
### Message DeleteResponse
DeleteResponse is empty because we cannot guarantee permanent object removal
in distributed system.
DeleteResponse body is empty because we cannot guarantee permanent object
removal in distributed system.
| Field | Type | Label | Description |
@ -192,7 +196,7 @@ in distributed system.
<a name="neo.fs.v2.object.DeleteResponse.Body"></a>
### Message DeleteResponse.Body
Response body
Object DELETE Response has an empty body.
@ -212,14 +216,14 @@ Get hash of object's payload part
<a name="neo.fs.v2.object.GetRangeHashRequest.Body"></a>
### Message GetRangeHashRequest.Body
Request body
Get hash of object's payload part request body.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Carries address of the object that contains the requested payload range. |
| ranges | [Range](#neo.fs.v2.object.Range) | repeated | Carries the list of object payload range to calculate homomorphic hash. |
| salt | [bytes](#bytes) | | Carries binary salt to XOR object payload ranges before hash calculation. |
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address of the object that containing the requested payload range |
| ranges | [Range](#neo.fs.v2.object.Range) | repeated | List of object's payload ranges to calculate homomorphic hash |
| salt | [bytes](#bytes) | | Binary salt to XOR object's payload ranges before hash calculation |
| type | [neo.fs.v2.refs.ChecksumType](#neo.fs.v2.refs.ChecksumType) | | Checksum algorithm type |
@ -239,19 +243,19 @@ Get hash of object's payload part
<a name="neo.fs.v2.object.GetRangeHashResponse.Body"></a>
### Message GetRangeHashResponse.Body
Response body
Get hash of object's payload part response body.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| type | [neo.fs.v2.refs.ChecksumType](#neo.fs.v2.refs.ChecksumType) | | Checksum algorithm type |
| hash_list | [bytes](#bytes) | repeated | List of range hashes in a binary format. |
| hash_list | [bytes](#bytes) | repeated | List of range hashes in a binary format |
<a name="neo.fs.v2.object.GetRangeRequest"></a>
### Message GetRangeRequest
Request to get part of object's payload
Request part of object's payload
| Field | Type | Label | Description |
@ -264,13 +268,13 @@ Request to get part of object's payload
<a name="neo.fs.v2.object.GetRangeRequest.Body"></a>
### Message GetRangeRequest.Body
Request Body
Byte range of object's payload request body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address carries address of the object that contains the requested payload range. |
| range | [Range](#neo.fs.v2.object.Range) | | Range carries the parameters of the requested payload range. |
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address of the object containing the requested payload range |
| range | [Range](#neo.fs.v2.object.Range) | | Requested payload range |
<a name="neo.fs.v2.object.GetRangeResponse"></a>
@ -289,18 +293,21 @@ Get part of object's payload
<a name="neo.fs.v2.object.GetRangeResponse.Body"></a>
### Message GetRangeResponse.Body
Response body
Get Range response body uses streams to transfer the response. Because
object payload considered a byte sequence, there is no need to have some
initial preamble message. The requested byte range is sent as a series
chunks.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| chunk | [bytes](#bytes) | | Carries part of the object payload. |
| chunk | [bytes](#bytes) | | Chunked object payload's range |
<a name="neo.fs.v2.object.GetRequest"></a>
### Message GetRequest
Get object request
GET object request
| Field | Type | Label | Description |
@ -313,19 +320,19 @@ Get object request
<a name="neo.fs.v2.object.GetRequest.Body"></a>
### Message GetRequest.Body
Request body
GET Object request body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address of the requested object. |
| raw | [bool](#bool) | | Carries the raw option flag of the request. Raw request is sent to receive only the objects that are physically stored on the server. |
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address of the requested object |
| raw | [bool](#bool) | | If `raw` flag is set, request will work only with objects that are physically stored on the peer node |
<a name="neo.fs.v2.object.GetResponse"></a>
### Message GetResponse
get object response
GET object response
| Field | Type | Label | Description |
@ -338,32 +345,33 @@ get object response
<a name="neo.fs.v2.object.GetResponse.Body"></a>
### Message GetResponse.Body
Response body
GET Object Response body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| init | [GetResponse.Body.Init](#neo.fs.v2.object.GetResponse.Body.Init) | | Initialization parameters of the object stream. |
| chunk | [bytes](#bytes) | | Part of the object payload. |
| init | [GetResponse.Body.Init](#neo.fs.v2.object.GetResponse.Body.Init) | | Initial part of the object stream |
| chunk | [bytes](#bytes) | | Chunked object payload |
<a name="neo.fs.v2.object.GetResponse.Body.Init"></a>
### Message GetResponse.Body.Init
Initialization parameters of the object got from NeoFS.
Initial part of the `Object` structure stream. Technically it's a
set of all `Object` structure's fields except `payload`.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Object ID |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Object signature |
| header | [Header](#neo.fs.v2.object.Header) | | Object header. |
| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Object's unique identifier. |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signed `ObjectID` |
| header | [Header](#neo.fs.v2.object.Header) | | Object metadata headers |
<a name="neo.fs.v2.object.HeadRequest"></a>
### Message HeadRequest
Object head request
Object HEAD request
| Field | Type | Label | Description |
@ -376,20 +384,20 @@ Object head request
<a name="neo.fs.v2.object.HeadRequest.Body"></a>
### Message HeadRequest.Body
Request body
Object HEAD request body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address of the object with the requested header. |
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address of the object with the requested Header |
| main_only | [bool](#bool) | | Return only minimal header subset |
| raw | [bool](#bool) | | Carries the raw option flag of the request. Raw request is sent to receive only the headers of the objects that are physically stored on the server. |
| raw | [bool](#bool) | | If `raw` flag is set, request will work only with objects that are physically stored on the peer node |
<a name="neo.fs.v2.object.HeadResponse"></a>
### Message HeadResponse
Head response
Object HEAD response
| Field | Type | Label | Description |
@ -402,31 +410,37 @@ Head response
<a name="neo.fs.v2.object.HeadResponse.Body"></a>
### Message HeadResponse.Body
Response body
Object HEAD response body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| header | [HeaderWithSignature](#neo.fs.v2.object.HeaderWithSignature) | | Full object header with object ID signature |
| header | [HeaderWithSignature](#neo.fs.v2.object.HeaderWithSignature) | | Full object's `Header` with `ObjectID` signature |
| short_header | [ShortHeader](#neo.fs.v2.object.ShortHeader) | | Short object header |
<a name="neo.fs.v2.object.HeaderWithSignature"></a>
### Message HeaderWithSignature
Tuple of full object header and signature of object ID.
Tuple of full object header and signature of `ObjectID`. \
Signed `ObjectID` is present to verify full header's authenticity through the
following steps:
1. Calculate `SHA-256` of marshalled `Header` structure
2. Check if the resulting hash matched `ObjectID`
3. Check if `ObjectID` signature in `signature` field is correct
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| header | [Header](#neo.fs.v2.object.Header) | | Full object header |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signed object_id to verify full header's authenticity through following steps: 1. Calculate SHA-256 of marshalled Headers structure. 2. Check if the resulting hash matched ObjectID 3. Check if ObjectID's signature in signature field is correct. |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signed `ObjectID` to verify full header's authenticity |
<a name="neo.fs.v2.object.PutRequest"></a>
### Message PutRequest
Put object request
PUT object request
| Field | Type | Label | Description |
@ -439,33 +453,34 @@ Put object request
<a name="neo.fs.v2.object.PutRequest.Body"></a>
### Message PutRequest.Body
Request body
PUT request body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| init | [PutRequest.Body.Init](#neo.fs.v2.object.PutRequest.Body.Init) | | Carries the initialization parameters of the object stream. |
| chunk | [bytes](#bytes) | | Carries part of the object payload. |
| init | [PutRequest.Body.Init](#neo.fs.v2.object.PutRequest.Body.Init) | | Initial part of the object stream |
| chunk | [bytes](#bytes) | | Chunked object payload |
<a name="neo.fs.v2.object.PutRequest.Body.Init"></a>
### Message PutRequest.Body.Init
Groups initialization parameters of object placement in NeoFS.
Newly created object structure parameters. If some optional parameters
are not set, they will be calculated by a peer node.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Object ID, where available |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Object signature, were available |
| header | [Header](#neo.fs.v2.object.Header) | | Header of the object to save in the system. |
| copies_number | [uint32](#uint32) | | Number of the object copies to store within the RPC call. Default zero value is processed according to the container placement rules. |
| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | ObjectID if available. |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Object signature if available |
| header | [Header](#neo.fs.v2.object.Header) | | Object's Header |
| copies_number | [uint32](#uint32) | | Number of the object copies to store within the RPC call. By default object is processed according to the container's placement policy. |
<a name="neo.fs.v2.object.PutResponse"></a>
### Message PutResponse
Put object response
PUT Object response
| Field | Type | Label | Description |
@ -478,30 +493,30 @@ Put object response
<a name="neo.fs.v2.object.PutResponse.Body"></a>
### Message PutResponse.Body
Response body
PUT Object response body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Carries identifier of the saved object. It is used to access an object in the container. |
| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the saved object |
<a name="neo.fs.v2.object.Range"></a>
### Message Range
Range groups the parameters of object payload range.
Object payload range.Ranges of zero length SHOULD be considered as invalid.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| offset | [uint64](#uint64) | | Carries the offset of the range from the object payload start. |
| length | [uint64](#uint64) | | Carries the length of the object payload range. |
| offset | [uint64](#uint64) | | Offset of the range from the object payload start |
| length | [uint64](#uint64) | | Length in bytes of the object payload range |
<a name="neo.fs.v2.object.SearchRequest"></a>
### Message SearchRequest
Search objects request
Object Search request
| Field | Type | Label | Description |
@ -514,12 +529,12 @@ Search objects request
<a name="neo.fs.v2.object.SearchRequest.Body"></a>
### Message SearchRequest.Body
Request body
Object Search request body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Carries search container identifier. |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Container identifier were to search |
| version | [uint32](#uint32) | | Version of the Query Language used |
| filters | [SearchRequest.Body.Filter](#neo.fs.v2.object.SearchRequest.Body.Filter) | repeated | List of search expressions |
@ -553,12 +568,12 @@ Search response
<a name="neo.fs.v2.object.SearchResponse.Body"></a>
### Message SearchResponse.Body
Response body
Object Search response body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| id_list | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Carries list of object identifiers that match the search query |
| id_list | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of `ObjectID`s that match the search query |
<!-- end messages -->
@ -578,7 +593,7 @@ Response body
<a name="neo.fs.v2.object.Header"></a>
### Message Header
Object Headers
Object Header
| Field | Type | Label | Description |
@ -587,19 +602,29 @@ Object Headers
| 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 |
| creation_epoch | [uint64](#uint64) | | Object creation Epoch |
| payload_length | [uint64](#uint64) | | Size of payload in bytes. 0xFFFFFFFFFFFFFFFF means `payload_length` is unknown |
| payload_length | [uint64](#uint64) | | Size of payload in bytes. `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown |
| payload_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Hash of payload bytes |
| object_type | [ObjectType](#neo.fs.v2.object.ObjectType) | | Special object type |
| object_type | [ObjectType](#neo.fs.v2.object.ObjectType) | | Type of the object payload content |
| homomorphic_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Homomorphic hash of the object payload. |
| session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) | | Session token, if it was used during Object creation. Need it to verify integrity and authenticity out of Request scope. |
| attributes | [Header.Attribute](#neo.fs.v2.object.Header.Attribute) | repeated | User-defined object attributes |
| split | [Header.Split](#neo.fs.v2.object.Header.Split) | | Position of the object in the split hierarchy. |
| split | [Header.Split](#neo.fs.v2.object.Header.Split) | | Position of the object in the split hierarchy |
<a name="neo.fs.v2.object.Header.Attribute"></a>
### Message Header.Attribute
Attribute groups the user-defined Key-Value pairs attached to the object
`Attribute` is a user-defined Key-Value metadata pair attached to the
object.
There are some "well-known" attributes starting with `__NEOFS__` prefix
that affect system behaviour:
* __NEOFS__UPLOAD_ID
* __NEOFS__EXPIRATION_EPOCH
For detailed description of each well-known attribute please see the
corresponding section in NeoFS Technical specification.
| Field | Type | Label | Description |
@ -611,27 +636,32 @@ Attribute groups the user-defined Key-Value pairs attached to the object
<a name="neo.fs.v2.object.Header.Split"></a>
### Message Header.Split
Information about spawning the objects through a payload splitting.
Bigger objects can be split into a chain of smaller objects. Information
about inter-dependencies between spawned objects and how to re-construct
the original one is in the `Split` headers. Parent and children objects
must be within the same container.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| parent | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the origin object. Parent and children objects must be within the same container. Parent object_id is known only to the minor child. |
| previous | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Previous carries identifier of the left split neighbor. |
| parent | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the origin object. Known only to the minor child. |
| previous | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the left split neighbor |
| parent_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | `signature` field of the parent object. Used to reconstruct parent. |
| parent_header | [Header](#neo.fs.v2.object.Header) | | `header` field of the parent object. Used to reconstruct parent. |
| children | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Children carries list of identifiers of the objects generated by splitting the current. |
| children | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of identifiers of the objects generated by splitting current one. |
<a name="neo.fs.v2.object.Object"></a>
### Message Object
Object structure.
Object structure. Object is immutable and content-addressed. It means
`ObjectID` will change if header or payload changes. It's calculated as a
hash of header field, which contains hash of object's payload.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Object's unique identifier. Object is content-addressed. It means id will change if header or payload changes. It's calculated as a hash of header field, which contains hash of object's payload |
| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Object's unique identifier. |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signed object_id |
| header | [Header](#neo.fs.v2.object.Header) | | Object metadata headers |
| payload | [bytes](#bytes) | | Payload bytes. |
@ -645,11 +675,11 @@ Short header fields
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Object format version. |
| 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 |
| 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 |
| payload_length | [uint64](#uint64) | | Size of payload in bytes. 0xFFFFFFFFFFFFFFFF means `payload_length` is unknown |
| payload_length | [uint64](#uint64) | | Size of payload in bytes. `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown |
<!-- end messages -->
@ -669,13 +699,13 @@ Type of match expression
<a name="neo.fs.v2.object.ObjectType"></a>
### ObjectType
Type of the object payload content
Type of the object payload content.
| Name | Number | Description |
| ---- | ------ | ----------- |
| REGULAR | 0 | Just a normal object |
| TOMBSTONE | 1 | Used internally to identify deleted objects |
| STORAGE_GROUP | 2 | Identifies that the object holds StorageGroup information |
| STORAGE_GROUP | 2 | StorageGroup information |
<!-- end enums -->

42
proto-docs/refs.md
View file

@ -31,19 +31,20 @@
<a name="neo.fs.v2.refs.Address"></a>
### Message Address
Address of object (container id + object id)
Object in NeoFS can be addressed by it's ContainerID and ObjectID. In string
format there MUST be a '/' delimeter between them.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| container_id | [ContainerID](#neo.fs.v2.refs.ContainerID) | | container_id carries container identifier. |
| object_id | [ObjectID](#neo.fs.v2.refs.ObjectID) | | object_id carries object identifier. |
| container_id | [ContainerID](#neo.fs.v2.refs.ContainerID) | | Container identifier |
| object_id | [ObjectID](#neo.fs.v2.refs.ObjectID) | | Object identifier |
<a name="neo.fs.v2.refs.Checksum"></a>
### Message Checksum
Checksum message
Checksum message.
| Field | Type | Label | Description |
@ -55,58 +56,65 @@ Checksum message
<a name="neo.fs.v2.refs.ContainerID"></a>
### Message ContainerID
NeoFS container identifier.
NeoFS container identifier. Container structures are immutable and
content-addressed. `ContainerID` is a 32 byte long SHA256 hash of
stable-marshalled container message.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| value | [bytes](#bytes) | | value carries the container identifier in a binary format. |
| value | [bytes](#bytes) | | Container identifier in a binary format. |
<a name="neo.fs.v2.refs.ObjectID"></a>
### Message ObjectID
NeoFS object identifier.
NeoFS Object unique identifier. Objects are immutable and content-addressed.
It means `ObjectID` will change if `header` or `payload` changes. `ObjectID`
is calculated as a hash of `header` field, which contains hash of object's
payload.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| value | [bytes](#bytes) | | value carries the object identifier in a binary format. |
| value | [bytes](#bytes) | | Object identifier in a binary format |
<a name="neo.fs.v2.refs.OwnerID"></a>
### Message OwnerID
OwnerID group information about the owner of the NeoFS container.
OwnerID is a derivative of a user's main public key. The transformation
algorithm is the same as for Neo3 wallet addresses. Neo3 wallet address can
be directly used as `OwnerID`.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| value | [bytes](#bytes) | | value carries the identifier of the container owner in a binary format. |
| value | [bytes](#bytes) | | Identifier of the container owner in a binary format |
<a name="neo.fs.v2.refs.Signature"></a>
### Message Signature
Signature of something in NeoFS
Signature of something in NeoFS.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| key | [bytes](#bytes) | | Public key used for signing. |
| key | [bytes](#bytes) | | Public key used for signing |
| sign | [bytes](#bytes) | | Signature |
<a name="neo.fs.v2.refs.Version"></a>
### Message Version
Represents API version used by node.
API version used by a node.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| major | [uint32](#uint32) | | Major API version. |
| minor | [uint32](#uint32) | | Minor API version. |
| major | [uint32](#uint32) | | Major API version |
| minor | [uint32](#uint32) | | Minor API version |
<!-- end messages -->
@ -114,12 +122,12 @@ Represents API version used by node.
<a name="neo.fs.v2.refs.ChecksumType"></a>
### ChecksumType
Checksum algorithm type
Checksum algorithm type.
| Name | Number | Description |
| ---- | ------ | ----------- |
| CHECKSUM_TYPE_UNSPECIFIED | 0 | Unknown. Not used |
| TZ | 1 | Tillich-Zemor homomorphic hash funciton |
| TZ | 1 | Tillich-Zemor homomorphic hash function |
| SHA256 | 2 | SHA-256 |

86
proto-docs/session.md
View file

@ -43,7 +43,10 @@
<a name="neo.fs.v2.session.SessionService"></a>
### Service "neo.fs.v2.session.SessionService"
Create Session record on Node side
`SessionService` allows to establish a temporary trust relationship between
two peer nodes and generate a `SessionToken` as the proof of trust to be
attached in requests for further verification. Please see corresponding
section of NeoFS Technical Specification for details.
```
rpc Create(CreateRequest) returns (CreateResponse);
@ -52,7 +55,7 @@ rpc Create(CreateRequest) returns (CreateResponse);
#### Method Create
Create opens new session between the client and the server.
Opens a new session between two peers.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -63,7 +66,7 @@ Create opens new session between the client and the server.
<a name="neo.fs.v2.session.CreateRequest"></a>
### Message CreateRequest
CreateRequest carries an information necessary for opening a session.
Information necessary for opening a session.
| Field | Type | Label | Description |
@ -76,19 +79,19 @@ CreateRequest carries an information necessary for opening a session.
<a name="neo.fs.v2.session.CreateRequest.Body"></a>
### Message CreateRequest.Body
Request body
Session creation request body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Carries an identifier of a session initiator. |
| expiration | [uint64](#uint64) | | Expiration Epoch |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Dession initiating user's or node's key derived `OwnerID`. |
| expiration | [uint64](#uint64) | | Session expiration `Epoch` |
<a name="neo.fs.v2.session.CreateResponse"></a>
### Message CreateResponse
CreateResponse carries an information about the opened session.
Information about the opened session.
| Field | Type | Label | Description |
@ -101,13 +104,13 @@ CreateResponse carries an information about the opened session.
<a name="neo.fs.v2.session.CreateResponse.Body"></a>
### Message CreateResponse.Body
Response body
Session creation response body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| id | [bytes](#bytes) | | id carries an identifier of session token. |
| session_key | [bytes](#bytes) | | session_key carries a session public key. |
| id | [bytes](#bytes) | | Identifier of a newly created session |
| session_key | [bytes](#bytes) | | Public key used for session |
<!-- end messages -->
@ -132,38 +135,39 @@ Context information for Session Tokens related to ObjectService requests
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| verb | [ObjectSessionContext.Verb](#neo.fs.v2.session.ObjectSessionContext.Verb) | | Verb is a type of request for which the token is issued |
| verb | [ObjectSessionContext.Verb](#neo.fs.v2.session.ObjectSessionContext.Verb) | | Type of request for which the token is issued |
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Related Object address |
<a name="neo.fs.v2.session.RequestMetaHeader"></a>
### Message RequestMetaHeader
Information about the request
Meta information attached to the request. When forwarded between peers,
request meta headers are folded in matryoshka style.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Client API version. |
| epoch | [uint64](#uint64) | | Client local epoch number. Set to 0 if unknown. |
| ttl | [uint32](#uint32) | | Maximum number of nodes in the request route. |
| x_headers | [XHeader](#neo.fs.v2.session.XHeader) | repeated | Request X-Headers. |
| session_token | [SessionToken](#neo.fs.v2.session.SessionToken) | | Token is a token of the session within which the request is sent |
| bearer_token | [neo.fs.v2.acl.BearerToken](#neo.fs.v2.acl.BearerToken) | | Bearer is a Bearer token of the request |
| origin | [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | RequestMetaHeader of the origin request. |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Peer's API version used |
| epoch | [uint64](#uint64) | | Peer's local epoch number. Set to 0 if unknown. |
| ttl | [uint32](#uint32) | | Maximum number of intermediate nodes in the request route |
| x_headers | [XHeader](#neo.fs.v2.session.XHeader) | repeated | Request X-Headers |
| session_token | [SessionToken](#neo.fs.v2.session.SessionToken) | | Session token within which the request is sent |
| bearer_token | [neo.fs.v2.acl.BearerToken](#neo.fs.v2.acl.BearerToken) | | `BearerToken` with eACL overrides for the request |
| origin | [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | `RequestMetaHeader` of the origin request |
<a name="neo.fs.v2.session.RequestVerificationHeader"></a>
### Message RequestVerificationHeader
Verification info for request signed by all intermediate nodes
Verification info for request signed by all intermediate nodes.
| 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. |
| meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Meta signature is added and signed by any intermediate node |
| origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Sign previous hops |
| 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 | [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Chain of previous hops signatures |
@ -175,11 +179,11 @@ Information about the response
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Server API version. |
| epoch | [uint64](#uint64) | | Server local epoch number. |
| ttl | [uint32](#uint32) | | Maximum number of nodes in the response route. |
| x_headers | [XHeader](#neo.fs.v2.session.XHeader) | repeated | Response X-Headers. |
| origin | [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta header of the origin response. |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Peer's API version used |
| epoch | [uint64](#uint64) | | Peer's local epoch number |
| ttl | [uint32](#uint32) | | Maximum number of intermediate nodes in the request route |
| x_headers | [XHeader](#neo.fs.v2.session.XHeader) | repeated | Response X-Headers |
| origin | [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | `ResponseMetaHeader` of the origin request |
<a name="neo.fs.v2.session.ResponseVerificationHeader"></a>
@ -191,36 +195,36 @@ Verification info for response signed by all intermediate nodes
| 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. |
| meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Meta signature is added and signed by any intermediate node |
| origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Sign previous hops |
| 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 | [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Chain of previous hops signatures |
<a name="neo.fs.v2.session.SessionToken"></a>
### Message SessionToken
NeoFS session token.
NeoFS Session Token.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [SessionToken.Body](#neo.fs.v2.session.SessionToken.Body) | | Session Token body |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature is a signature of session token information |
| body | [SessionToken.Body](#neo.fs.v2.session.SessionToken.Body) | | Session Token contains the proof of trust between peers to be attached in requests for further verification. Please see corresponding section of NeoFS Technical Specification for details. |
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of `SessionToken` information |
<a name="neo.fs.v2.session.SessionToken.Body"></a>
### Message SessionToken.Body
Session token body
Session Token body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| id | [bytes](#bytes) | | ID is a token identifier. valid UUIDv4 represented in bytes |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | OwnerID carries identifier of the session initiator. |
| lifetime | [SessionToken.Body.TokenLifetime](#neo.fs.v2.session.SessionToken.Body.TokenLifetime) | | Lifetime is a lifetime of the session |
| session_key | [bytes](#bytes) | | SessionKey is a public key of session key |
| object | [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext) | | ObjectService session context. |
| id | [bytes](#bytes) | | Token identifier is a valid UUIDv4 in binary form |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Identifier of the session initiator |
| lifetime | [SessionToken.Body.TokenLifetime](#neo.fs.v2.session.SessionToken.Body.TokenLifetime) | | Lifetime of the session |
| session_key | [bytes](#bytes) | | Public key used in session |
| object | [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext) | | ObjectService session context |
<a name="neo.fs.v2.session.SessionToken.Body.TokenLifetime"></a>
@ -239,13 +243,13 @@ Lifetime parameters of the token. Filed names taken from rfc7519.
<a name="neo.fs.v2.session.XHeader"></a>
### Message XHeader
Extended headers for Request/Response
Extended headers for Request/Response.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| key | [string](#string) | | Key of the X-Header. |
| value | [string](#string) | | Value of the X-Header. |
| key | [string](#string) | | Key of the X-Header |
| value | [string](#string) | | Value of the X-Header |
<!-- end messages -->

14
proto-docs/storagegroup.md
View file

@ -25,16 +25,18 @@
<a name="neo.fs.v2.storagegroup.StorageGroup"></a>
### Message StorageGroup
StorageGroup groups the information about the NeoFS storage group.
The storage group consists of objects from single container.
StorageGroup keeps verification information for Data Audit sessions. Objects
that require payed storage guaranties are gathered in `StorageGroups` with
additional information used for proof of storage. `StorageGroup` only
contains objects from the same container.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| validation_data_size | [uint64](#uint64) | | validation_data_size carries the total size of the payloads of the storage group members. |
| validation_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | validation_hash carries 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) | | expiration_epoch carries last NeoFS epoch number of the storage group lifetime. |
| members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Members carries the list of identifiers of the object storage group members. The list is strictly ordered. |
| 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. |
| expiration_epoch | [uint64](#uint64) | | 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 |
<!-- end messages -->