From a6ecab41b839a5a3bb0f72278fccc5220d48bab3 Mon Sep 17 00:00:00 2001 From: Stanislav Bogatyrev Date: Fri, 16 Oct 2020 14:40:12 +0300 Subject: [PATCH] Update auto-generated docs Signed-off-by: Stanislav Bogatyrev --- proto-docs/accounting.md | 45 ++++---- proto-docs/acl.md | 75 +++++++----- proto-docs/container.md | 145 +++++++++++++---------- proto-docs/netmap.md | 96 ++++++++++++---- proto-docs/object.md | 228 +++++++++++++++++++++---------------- proto-docs/refs.md | 42 ++++--- proto-docs/session.md | 86 +++++++------- proto-docs/storagegroup.md | 14 ++- 8 files changed, 433 insertions(+), 298 deletions(-) diff --git a/proto-docs/accounting.md b/proto-docs/accounting.md index 202d639..8050a1a 100644 --- a/proto-docs/accounting.md +++ b/proto-docs/accounting.md @@ -35,8 +35,11 @@ ### 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. ### 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. ### 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. | ### 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. ### 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. | @@ -126,13 +125,19 @@ Request body ### 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. | diff --git a/proto-docs/acl.md b/proto-docs/acl.md index 9707195..39653fa 100644 --- a/proto-docs/acl.md +++ b/proto-docs/acl.md @@ -31,7 +31,12 @@ ### 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 ### 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 | ### 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. ### 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 | ### 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 | ### 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 | ### 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 | @@ -124,11 +135,12 @@ EACLRecord carries the information about extended ACL rules. ### 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. ### 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. ### 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 | diff --git a/proto-docs/container.md b/proto-docs/container.md index 587ddb2..28982fb 100644 --- a/proto-docs/container.md +++ b/proto-docs/container.md @@ -56,8 +56,10 @@ ### 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 ### 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 | ### 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 ### 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 ### 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 | @@ -210,13 +214,15 @@ Get Extended ACL ### 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 | @@ -235,12 +241,12 @@ Get container structure ### 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 | @@ -259,12 +265,13 @@ Get container structure ### 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 | @@ -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 ### 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 | @@ -307,12 +314,12 @@ List containers ### 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` | @@ -331,13 +338,17 @@ New NeoFS Container creation request ### 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 | @@ -356,12 +367,15 @@ New NeoFS Container creation response ### 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 | @@ -380,13 +394,14 @@ Set Extended ACL ### 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 | @@ -405,7 +420,9 @@ Set Extended ACL ### 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. @@ -426,32 +443,40 @@ Response body ### 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 | ### 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 | diff --git a/proto-docs/netmap.md b/proto-docs/netmap.md index efe659e..30386ec 100644 --- a/proto-docs/netmap.md +++ b/proto-docs/netmap.md @@ -40,7 +40,10 @@ ### 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 ### 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 ### Message LocalNodeInfoRequest.Body -Request body +LocalNodeInfo request body is empty. ### 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 ### 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 | @@ -119,12 +126,13 @@ Response body ### 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 ### 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`. | ### 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 ### 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 | ### 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 ### 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 | diff --git a/proto-docs/object.md b/proto-docs/object.md index 941bca9..12d923a 100644 --- a/proto-docs/object.md +++ b/proto-docs/object.md @@ -68,7 +68,8 @@ ### 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. ### Message DeleteRequest -Object Delete request +Object DELETE request | Field | Type | Label | Description | @@ -167,19 +171,19 @@ Object Delete request ### 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 | ### 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. ### Message DeleteResponse.Body -Response body +Object DELETE Response has an empty body. @@ -212,14 +216,14 @@ Get hash of object's payload part ### 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 ### 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 | ### 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 ### 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 | @@ -289,18 +293,21 @@ Get part of object's payload ### 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 | ### Message GetRequest -Get object request +GET object request | Field | Type | Label | Description | @@ -313,19 +320,19 @@ Get object request ### 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 | ### Message GetResponse -get object response +GET object response | Field | Type | Label | Description | @@ -338,32 +345,33 @@ get object response ### 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 | ### 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 | ### Message HeadRequest -Object head request +Object HEAD request | Field | Type | Label | Description | @@ -376,20 +384,20 @@ Object head request ### 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 | ### Message HeadResponse -Head response +Object HEAD response | Field | Type | Label | Description | @@ -402,31 +410,37 @@ Head response ### 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 | ### 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 | ### Message PutRequest -Put object request +PUT object request | Field | Type | Label | Description | @@ -439,33 +453,34 @@ Put object request ### 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 | ### 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. | ### Message PutResponse -Put object response +PUT Object response | Field | Type | Label | Description | @@ -478,30 +493,30 @@ Put object response ### 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 | ### 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 | ### Message SearchRequest -Search objects request +Object Search request | Field | Type | Label | Description | @@ -514,12 +529,12 @@ Search objects request ### 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 ### 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 | @@ -578,7 +593,7 @@ Response body ### 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 | ### 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 ### 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. | ### 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 | @@ -669,13 +699,13 @@ Type of match expression ### 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 | diff --git a/proto-docs/refs.md b/proto-docs/refs.md index 57d5157..f53d36a 100644 --- a/proto-docs/refs.md +++ b/proto-docs/refs.md @@ -31,19 +31,20 @@ ### 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 | ### Message Checksum -Checksum message +Checksum message. | Field | Type | Label | Description | @@ -55,58 +56,65 @@ Checksum message ### 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. | ### 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 | ### 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 | ### 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 | ### 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 | @@ -114,12 +122,12 @@ Represents API version used by node. ### 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 | diff --git a/proto-docs/session.md b/proto-docs/session.md index 9a6ee57..c61855d 100644 --- a/proto-docs/session.md +++ b/proto-docs/session.md @@ -43,7 +43,10 @@ ### 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. ### 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. ### 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` | ### 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. ### 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 | @@ -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 | ### 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 | ### 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 | @@ -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 | ### 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 | ### 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 | @@ -239,13 +243,13 @@ Lifetime parameters of the token. Filed names taken from rfc7519. ### 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 | diff --git a/proto-docs/storagegroup.md b/proto-docs/storagegroup.md index 46dafdc..beb0811 100644 --- a/proto-docs/storagegroup.md +++ b/proto-docs/storagegroup.md @@ -25,16 +25,18 @@ ### 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 |