diff --git a/proto-docs/accounting.md b/proto-docs/accounting.md index cdc82a1..a8bfd16 100644 --- a/proto-docs/accounting.md +++ b/proto-docs/accounting.md @@ -35,11 +35,11 @@ ### Service "neo.fs.v2.accounting.AccountingService" -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. +Accounting service provides methods for interaction with FrostFS sidechain +via other FrostFS nodes to get information about the account balance. Deposit +and Withdraw operations can't be implemented here, as they require Mainnet +FrostFS smart contract invocation. Transfer operations between internal +FrostFS accounts are possible if both use the same token type. ``` rpc Balance(BalanceRequest) returns (BalanceResponse); @@ -48,7 +48,7 @@ rpc Balance(BalanceRequest) returns (BalanceResponse); #### Method Balance -Returns the amount of funds in GAS token for the requested NeoFS account. +Returns the amount of funds in GAS token for the requested FrostFS account. Statuses: - **OK** (0, SECTION_SUCCESS): @@ -78,9 +78,9 @@ BalanceRequest message ### Message BalanceRequest.Body To indicate the account for which the balance is requested, its identifier -is used. It can be any existing account in NeoFS sidechain `Balance` smart -contract. If omitted, client implementation MUST set it to the request's -signer `OwnerID`. +is used. It can be any existing account in FrostFS sidechain `Balance` +smart contract. If omitted, client implementation MUST set it to the +request's signer `OwnerID`. | Field | Type | Label | Description | @@ -131,7 +131,7 @@ rounding. ### Message Decimal -Standard floating point data type can't be used in NeoFS due to inexactness +Standard floating point data type can't be used in FrostFS 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. diff --git a/proto-docs/acl.md b/proto-docs/acl.md index bac7747..fdc7ade 100644 --- a/proto-docs/acl.md +++ b/proto-docs/acl.md @@ -71,11 +71,12 @@ Deprecated: eACL tables are no longer relevant - `APEOverrides` should be used i ### Message BearerToken.Body.APEOverride APEOverride is the list of APE chains defined for a target. -These chains are meant to serve as overrides to the already defined (or even undefined) -APE chains for the target (see contract `Policy`). +These chains are meant to serve as overrides to the already defined (or +even undefined) APE chains for the target (see contract `Policy`). -The server-side processing of the bearer token with set APE overrides must verify if a client is permitted -to override chains for the target, preventing unauthorized access through the APE mechanism. +The server-side processing of the bearer token with set APE overrides +must verify if a client is permitted to override chains for the target, +preventing unauthorized access through the APE mechanism. | Field | Type | Label | Description | @@ -106,7 +107,7 @@ Describes a single eACL rule. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| operation | [Operation](#neo.fs.v2.acl.Operation) | | NeoFS request Verb to match | +| operation | [Operation](#neo.fs.v2.acl.Operation) | | FrostFS 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 | @@ -174,7 +175,7 @@ keys to match. Extended ACL rules table. A list of ACL rules defined additionally to Basic ACL. Extended ACL rules can be attached to a container and can be updated or may be defined in `BearerToken` structure. Please see the corresponding -NeoFS Technical Specification section for detailed description. +FrostFS Technical Specification section for detailed description. | Field | Type | Label | Description | @@ -210,7 +211,7 @@ Enumeration of possible sources of Headers to apply filters. | HEADER_UNSPECIFIED | 0 | Unspecified header, default value. | | REQUEST | 1 | Filter request headers | | OBJECT | 2 | Filter object headers | -| SERVICE | 3 | Filter service headers. These are not processed by NeoFS nodes and exist for service use only. | +| SERVICE | 3 | Filter service headers. These are not processed by FrostFS nodes and exist for service use only. | diff --git a/proto-docs/ape.md b/proto-docs/ape.md index 39bc946..9795bc5 100644 --- a/proto-docs/ape.md +++ b/proto-docs/ape.md @@ -72,8 +72,8 @@ TargetType is a type target to which a rule chain is defined. | ----------- | ----- | -------- | --------- | ----------- | | double | | double | double | float | | float | | float | float | float | -| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers - if your field is likely to have negative values, use sint32 instead. | int32 | int | int | -| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers - if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | | uint32 | Uses variable-length encoding. | uint32 | int | int/long | | uint64 | Uses variable-length encoding. | uint64 | long | int/long | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | diff --git a/proto-docs/container.md b/proto-docs/container.md index 3df304f..76cc115 100644 --- a/proto-docs/container.md +++ b/proto-docs/container.md @@ -8,19 +8,10 @@ - [ContainerService](#neo.fs.v2.container.ContainerService) - Messages - - [AnnounceUsedSpaceRequest](#neo.fs.v2.container.AnnounceUsedSpaceRequest) - - [AnnounceUsedSpaceRequest.Body](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body) - - [AnnounceUsedSpaceRequest.Body.Announcement](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement) - - [AnnounceUsedSpaceResponse](#neo.fs.v2.container.AnnounceUsedSpaceResponse) - - [AnnounceUsedSpaceResponse.Body](#neo.fs.v2.container.AnnounceUsedSpaceResponse.Body) - [DeleteRequest](#neo.fs.v2.container.DeleteRequest) - [DeleteRequest.Body](#neo.fs.v2.container.DeleteRequest.Body) - [DeleteResponse](#neo.fs.v2.container.DeleteResponse) - [DeleteResponse.Body](#neo.fs.v2.container.DeleteResponse.Body) - - [GetExtendedACLRequest](#neo.fs.v2.container.GetExtendedACLRequest) - - [GetExtendedACLRequest.Body](#neo.fs.v2.container.GetExtendedACLRequest.Body) - - [GetExtendedACLResponse](#neo.fs.v2.container.GetExtendedACLResponse) - - [GetExtendedACLResponse.Body](#neo.fs.v2.container.GetExtendedACLResponse.Body) - [GetRequest](#neo.fs.v2.container.GetRequest) - [GetRequest.Body](#neo.fs.v2.container.GetRequest.Body) - [GetResponse](#neo.fs.v2.container.GetResponse) @@ -33,10 +24,6 @@ - [PutRequest.Body](#neo.fs.v2.container.PutRequest.Body) - [PutResponse](#neo.fs.v2.container.PutResponse) - [PutResponse.Body](#neo.fs.v2.container.PutResponse.Body) - - [SetExtendedACLRequest](#neo.fs.v2.container.SetExtendedACLRequest) - - [SetExtendedACLRequest.Body](#neo.fs.v2.container.SetExtendedACLRequest.Body) - - [SetExtendedACLResponse](#neo.fs.v2.container.SetExtendedACLResponse) - - [SetExtendedACLResponse.Body](#neo.fs.v2.container.SetExtendedACLResponse.Body) - [container/types.proto](#container/types.proto) @@ -62,8 +49,8 @@ ### Service "neo.fs.v2.container.ContainerService" `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 +in FrostFS sidechain via other FrostFS nodes. All of those actions can be +done equivalently by directly issuing transactions and RPC calls to sidechain nodes. ``` @@ -71,9 +58,6 @@ rpc Put(PutRequest) returns (PutResponse); rpc Delete(DeleteRequest) returns (DeleteResponse); rpc Get(GetRequest) returns (GetResponse); rpc List(ListRequest) returns (ListResponse); -rpc SetExtendedACL(SetExtendedACLRequest) returns (SetExtendedACLResponse); -rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse); -rpc AnnounceUsedSpace(AnnounceUsedSpaceRequest) returns (AnnounceUsedSpaceResponse); ``` @@ -141,114 +125,9 @@ Statuses: | Name | Input | Output | | ---- | ----- | ------ | | List | [ListRequest](#neo.fs.v2.container.ListRequest) | [ListResponse](#neo.fs.v2.container.ListResponse) | -#### Method SetExtendedACL - -Invokes 'SetEACL' method of 'Container` smart contract and returns response -immediately. After one more block in sidechain, changes in an Extended ACL -are added into smart contract storage. - -Statuses: -- **OK** (0, SECTION_SUCCESS): \ - request to save container eACL has been sent to the sidechain; -- Common failures (SECTION_FAILURE_COMMON); -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - set container eACL access denied. - -| Name | Input | Output | -| ---- | ----- | ------ | -| SetExtendedACL | [SetExtendedACLRequest](#neo.fs.v2.container.SetExtendedACLRequest) | [SetExtendedACLResponse](#neo.fs.v2.container.SetExtendedACLResponse) | -#### Method GetExtendedACL - -Returns Extended ACL table and signature from `Container` smart contract -storage. - -Statuses: -- **OK** (0, SECTION_SUCCESS): \ - container eACL has been successfully read; -- Common failures (SECTION_FAILURE_COMMON); -- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - container not found; -- **EACL_NOT_FOUND** (3073, SECTION_CONTAINER): \ - eACL table not found; -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - access to container eACL is denied. - -| Name | Input | Output | -| ---- | ----- | ------ | -| GetExtendedACL | [GetExtendedACLRequest](#neo.fs.v2.container.GetExtendedACLRequest) | [GetExtendedACLResponse](#neo.fs.v2.container.GetExtendedACLResponse) | -#### Method AnnounceUsedSpace - -Announces the space values used by the container for P2P synchronization. - -Statuses: -- **OK** (0, SECTION_SUCCESS): \ - estimation of used space has been successfully announced; -- Common failures (SECTION_FAILURE_COMMON). - -| Name | Input | Output | -| ---- | ----- | ------ | -| AnnounceUsedSpace | [AnnounceUsedSpaceRequest](#neo.fs.v2.container.AnnounceUsedSpaceRequest) | [AnnounceUsedSpaceResponse](#neo.fs.v2.container.AnnounceUsedSpaceResponse) | - - -### Message AnnounceUsedSpaceRequest -Announce container used space - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| body | [AnnounceUsedSpaceRequest.Body](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body) | | Body of announce used space 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. | - - - - -### Message AnnounceUsedSpaceRequest.Body -Container used space announcement body. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| announcements | [AnnounceUsedSpaceRequest.Body.Announcement](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement) | repeated | List of announcements. If nodes share several containers, announcements are transferred in a batch. | - - - - -### Message AnnounceUsedSpaceRequest.Body.Announcement -Announcement contains used space information for a single container. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| epoch | [uint64](#uint64) | | Epoch number for which the container size estimation was produced. | -| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container. | -| used_space | [uint64](#uint64) | | Used space is a sum of object payload sizes of a specified container, stored in the node. It must not include inhumed objects. | - - - - -### Message AnnounceUsedSpaceResponse -Announce container used space - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| body | [AnnounceUsedSpaceResponse.Body](#neo.fs.v2.container.AnnounceUsedSpaceResponse.Body) | | Body of announce used space response message. | -| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | -| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | - - - - -### Message AnnounceUsedSpaceResponse.Body -`AnnounceUsedSpaceResponse` has an empty body because announcements are -one way communication. - - - ### Message DeleteRequest @@ -272,7 +151,7 @@ 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) | | Identifier of the container to delete from NeoFS | +| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container to delete from FrostFS | | signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | `ContainerID` signed with the container owner's key according to RFC-6979. | @@ -298,58 +177,6 @@ and done via consensus in Inner Ring nodes. - - -### Message GetExtendedACLRequest -Get Extended ACL - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| body | [GetExtendedACLRequest.Body](#neo.fs.v2.container.GetExtendedACLRequest.Body) | | Body of get extended acl 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. | - - - - -### Message GetExtendedACLRequest.Body -Get Extended ACL request body - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container having Extended ACL | - - - - -### Message GetExtendedACLResponse -Get Extended ACL - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| body | [GetExtendedACLResponse.Body](#neo.fs.v2.container.GetExtendedACLResponse.Body) | | Body of get extended acl response message. | -| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | -| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | - - - - -### Message GetExtendedACLResponse.Body -Get Extended ACL Response body can be empty if the requested container does -not have Extended ACL Table attached or Extended ACL has not been allowed -at the time of container creation. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) | | Extended ACL requested, if available | -| signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of stable-marshalled Extended ACL according to RFC-6979. | -| session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) | | Session token if Extended ACL was set within a session | - - ### Message GetRequest @@ -452,7 +279,7 @@ List containers response body. ### Message PutRequest -New NeoFS Container creation request +New FrostFS Container creation request | Field | Type | Label | Description | @@ -474,14 +301,14 @@ additional signature checks. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| container | [Container](#neo.fs.v2.container.Container) | | Container structure to register in NeoFS | +| container | [Container](#neo.fs.v2.container.Container) | | Container structure to register in FrostFS | | signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of a stable-marshalled container according to RFC-6979. | ### Message PutResponse -New NeoFS Container creation response +New FrostFS Container creation response | Field | Type | Label | Description | @@ -504,54 +331,6 @@ returned here to make sure everything has been done as expected. | ----- | ---- | ----- | ----------- | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Unique identifier of the newly created container | - - - -### Message SetExtendedACLRequest -Set Extended ACL - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| body | [SetExtendedACLRequest.Body](#neo.fs.v2.container.SetExtendedACLRequest.Body) | | Body of set extended acl 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. | - - - - -### Message SetExtendedACLRequest.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 table to set for the container | -| signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of stable-marshalled Extended ACL table according to RFC-6979. | - - - - -### Message SetExtendedACLResponse -Set Extended ACL - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| body | [SetExtendedACLResponse.Body](#neo.fs.v2.container.SetExtendedACLResponse.Body) | | Body of set extended acl response message. | -| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | -| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | - - - - -### Message SetExtendedACLResponse.Body -`SetExtendedACLResponse` has an empty body because the operation is -asynchronous and the update should be reflected in `Container` smart -contract's storage after next block is issued in sidechain. - - @@ -612,7 +391,7 @@ There are some "well-known" attributes affecting system behaviour: (`__NEOFS__DISABLE_HOMOMORPHIC_HASHING` is deprecated) \ Disables homomorphic hashing for the container if the value equals "true" string. Any other values are interpreted as missing attribute. Container - could be accepted in a NeoFS network only if the global network hashing + could be accepted in a FrostFS network only if the global network hashing configuration value corresponds with that attribute's value. After container inclusion, network setting is ignored. diff --git a/proto-docs/netmap.md b/proto-docs/netmap.md index cbf5593..b49287c 100644 --- a/proto-docs/netmap.md +++ b/proto-docs/netmap.md @@ -55,7 +55,7 @@ `NetmapService` provides methods to work with `Network Map` and the 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. +from other FrostFS nodes. ``` rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse); @@ -83,7 +83,7 @@ information about the server has been successfully read; | LocalNodeInfo | [LocalNodeInfoRequest](#neo.fs.v2.netmap.LocalNodeInfoRequest) | [LocalNodeInfoResponse](#neo.fs.v2.netmap.LocalNodeInfoResponse) | #### Method NetworkInfo -Read recent information about the NeoFS network. +Read recent information about the FrostFS network. Statuses: - **OK** (0, SECTION_SUCCESS): @@ -95,7 +95,7 @@ information about the current network state has been successfully read; | NetworkInfo | [NetworkInfoRequest](#neo.fs.v2.netmap.NetworkInfoRequest) | [NetworkInfoResponse](#neo.fs.v2.netmap.NetworkInfoResponse) | #### Method NetmapSnapshot -Returns network map snapshot of the current NeoFS epoch. +Returns network map snapshot of the current FrostFS epoch. Statuses: - **OK** (0, SECTION_SUCCESS): @@ -149,7 +149,7 @@ Local Node Info, including API Version in use. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Latest NeoFS API version in use | +| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Latest FrostFS API version in use | | node_info | [NodeInfo](#neo.fs.v2.netmap.NodeInfo) | | NodeInfo structure with recent information from node itself | @@ -287,7 +287,7 @@ Network map structure ### Message NetworkConfig -NeoFS network configuration +FrostFS network configuration | Field | Type | Label | Description | @@ -315,7 +315,7 @@ System parameters: Fee paid for container creation by the container owner. Value: little-endian integer. Default: 0. - **EpochDuration** \ - NeoFS epoch duration measured in Sidechain blocks. + FrostFS epoch duration measured in Sidechain blocks. Value: little-endian integer. Default: 0. - **HomomorphicHashingDisabled** \ Flag of disabling the homomorphic hashing of objects' payload. @@ -327,8 +327,39 @@ System parameters: Flag allowing setting the MAINTENANCE state to storage nodes. Value: true if any byte != 0. Default: false. - **MaxObjectSize** \ - Maximum size of physically stored NeoFS object measured in bytes. + Maximum size of physically stored FrostFS object measured in bytes. Value: little-endian integer. Default: 0. + + This value refers to the maximum size of a **physically** stored object + in FrostFS. However, from a user's perspective, the **logical** size of a + stored object can be significantly larger. The relationship between the + physical and logical object sizes is governed by the following formula + + ```math + \mathrm{Stored\ Object\ Size} \le + \frac{ + \left(\mathrm{Max\ Object\ Size}\right)^2 + }{ + \mathrm{Object\ ID\ Size} + } + ``` + + This arises from the fact that a tombstone, also being an object, stores + the IDs of inhumed objects and cannot be divided into smaller objects, + thus having an upper limit for its size. + + For example, if: + * Max Object Size Size = 64 MiB; + * Object ID Size = 32 B; + + then: + ```math + \mathrm{Stored\ Object\ Size} \le + \frac{\left(64\ \mathrm{MiB}\right)^2}{32\ \mathrm{B}} = + \frac{2^{52}}{2^5}\ \mathrm{B} = + 2^{47}\ \mathrm{B} = + 128\ \mathrm{TiB} + ``` - **WithdrawFee** \ Fee paid for withdrawal of funds paid by the account owner. Value: little-endian integer. Default: 0. @@ -349,45 +380,45 @@ System parameters: ### Message NetworkInfo -Information about NeoFS network +Information about FrostFS network | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| current_epoch | [uint64](#uint64) | | Number of the current epoch in the NeoFS network | -| magic_number | [uint64](#uint64) | | Magic number of the sidechain of the NeoFS network | -| ms_per_block | [int64](#int64) | | MillisecondsPerBlock network parameter of the sidechain of the NeoFS network | -| network_config | [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig) | | NeoFS network configuration | +| current_epoch | [uint64](#uint64) | | Number of the current epoch in the FrostFS network | +| magic_number | [uint64](#uint64) | | Magic number of the sidechain of the FrostFS network | +| ms_per_block | [int64](#int64) | | MillisecondsPerBlock network parameter of the sidechain of the FrostFS network | +| network_config | [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig) | | FrostFS network configuration | ### Message NodeInfo -NeoFS node description +FrostFS node description | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| public_key | [bytes](#bytes) | | Public key of the NeoFS node in a binary format | +| public_key | [bytes](#bytes) | | Public key of the FrostFS node in a binary format | | addresses | [string](#string) | repeated | Ways to connect to a node | -| attributes | [NodeInfo.Attribute](#neo.fs.v2.netmap.NodeInfo.Attribute) | repeated | Carries list of the NeoFS node attributes in a key-value form. Key name must be a node-unique valid UTF-8 string. Value can't be empty. NodeInfo structures with duplicated attribute names or attributes with empty values will be considered invalid. | -| state | [NodeInfo.State](#neo.fs.v2.netmap.NodeInfo.State) | | Carries state of the NeoFS node | +| attributes | [NodeInfo.Attribute](#neo.fs.v2.netmap.NodeInfo.Attribute) | repeated | Carries list of the FrostFS node attributes in a key-value form. Key name must be a node-unique valid UTF-8 string. Value can't be empty. NodeInfo structures with duplicated attribute names or attributes with empty values will be considered invalid. | +| state | [NodeInfo.State](#neo.fs.v2.netmap.NodeInfo.State) | | Carries state of the FrostFS node | ### Message NodeInfo.Attribute -Administrator-defined Attributes of the NeoFS Storage Node. +Administrator-defined Attributes of the FrostFS Storage Node. `Attribute` is a Key-Value metadata pair. Key name must be a valid UTF-8 string. Value can't be empty. Attributes can be constructed into a chain of attributes: any attribute can have a parent attribute and a child attribute (except the first and the -last one). A string representation of the chain of attributes in NeoFS +last one). A string representation of the chain of attributes in FrostFS Storage Node configuration uses ":" and "/" symbols, e.g.: - `NEOFS_NODE_ATTRIBUTE_1=key1:val1/key2:val2` + `FrostFS_NODE_ATTRIBUTE_1=key1:val1/key2:val2` Therefore the string attribute representation in the Node configuration must use "\:", "\/" and "\\" escaped symbols if any of them appears in an @@ -434,8 +465,8 @@ explicitly set: [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). Calculated automatically from `UN-LOCODE` attribute. * Continent \ - Node's continent name according to the [Seven-Continent model] - (https://en.wikipedia.org/wiki/Continent#Number). Calculated + Node's continent name according to the [Seven-Continent + model](https://en.wikipedia.org/wiki/Continent#Number). Calculated automatically from `UN-LOCODE` attribute. * ExternalAddr Node's preferred way for communications with external clients. @@ -443,7 +474,7 @@ explicitly set: Must contain a comma-separated list of multi-addresses. For detailed description of each well-known attribute please see the -corresponding section in NeoFS Technical Specification. +corresponding section in FrostFS Technical Specification. | Field | Type | Label | Description | @@ -464,7 +495,7 @@ 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 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 | +| container_backup_factor | [uint32](#uint32) | | Container backup factor controls how deep FrostFS 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 | | unique | [bool](#bool) | | Unique flag defines non-overlapping application for replicas | @@ -522,7 +553,7 @@ hash distance. ### NodeInfo.State -Represents the enumeration of various states of the NeoFS node. +Represents the enumeration of various states of the FrostFS node. | Name | Number | Description | | ---- | ------ | ----------- | @@ -550,6 +581,7 @@ Operations on filters | OR | 7 | Logical OR | | AND | 8 | Logical AND | | NOT | 9 | Logical negation | +| LIKE | 10 | Matches pattern | diff --git a/proto-docs/object.md b/proto-docs/object.md index 27981e5..dd30ede 100644 --- a/proto-docs/object.md +++ b/proto-docs/object.md @@ -254,7 +254,7 @@ Statuses: #### Method Search Search objects in container. Search query allows to match by Object -Header's filed values. Please see the corresponding NeoFS Technical +Header's filed values. Please see the corresponding FrostFS Technical Specification section for more details. Extended headers can change `Search` behaviour: @@ -404,16 +404,20 @@ been deleted; #### Method Patch Patch the object. Request uses gRPC stream. First message must set -the address of the object that is going to get patched. If the object's attributes -are patched, then these attrubutes must be set only within the first stream message. +the address of the object that is going to get patched. If the object's +attributes are patched, then these attrubutes must be set only within the +first stream message. -If the patch request is performed by NOT the object's owner but if the actor has the permission -to perform the patch, then `OwnerID` of the object is changed. In this case the object's owner -loses the object's ownership after the patch request is successfully done. +If the patch request is performed by NOT the object's owner but if the +actor has the permission to perform the patch, then `OwnerID` of the object +is changed. In this case the object's owner loses the object's ownership +after the patch request is successfully done. -As objects are content-addressable the patching causes new object ID generation for the patched object. -This object id is set witihn `PatchResponse`. But the object id may remain unchanged in such cases: -1. The chunk of the applying patch contains the same value as the object's payload within the same range; +As objects are content-addressable the patching causes new object ID +generation for the patched object. This object id is set witihn +`PatchResponse`. But the object id may remain unchanged in such cases: +1. The chunk of the applying patch contains the same value as the object's +payload within the same range; 2. The patch that reverts the changes applied by preceding patch; 3. The application of the same patches for the object a few times. @@ -996,8 +1000,8 @@ prefix to the name. Here is the list of fields available via this prefix: * $Object:split.splitID \ 16 byte UUIDv4 used to identify the split object hierarchy parts * $Object:ec.parent \ - If the object is stored according to EC policy, then ec_parent attribute - is set to return an id list of all related EC chunks. + If the object is stored according to EC policy, then ec_parent + attribute is set to return an id list of all related EC chunks. There are some well-known filter aliases to match objects by certain properties: @@ -1160,7 +1164,7 @@ And some well-known attributes used by applications only: MIME Content Type of object's payload For detailed description of each well-known attribute please see the -corresponding section in NeoFS Technical Specification. +corresponding section in FrostFS Technical Specification. | Field | Type | Label | Description | diff --git a/proto-docs/refs.md b/proto-docs/refs.md index 5b559d3..3ad3126 100644 --- a/proto-docs/refs.md +++ b/proto-docs/refs.md @@ -32,7 +32,7 @@ ### Message Address -Objects in NeoFS are addressed by their ContainerID and ObjectID. +Objects in FrostFS are addressed by their ContainerID and ObjectID. String presentation of `Address` is a concatenation of string encoded `ContainerID` and `ObjectID` delimited by '/' character. @@ -65,7 +65,7 @@ Depending on checksum algorithm type, the string presentation may vary: ### Message ContainerID -NeoFS container identifier. Container structures are immutable and +FrostFS container identifier. Container structures are immutable and content-addressed. `ContainerID` is a 32 byte long @@ -90,8 +90,9 @@ with/without paddings are accepted. ### Message ObjectID -NeoFS Object unique identifier. Objects are immutable and content-addressed. -It means `ObjectID` will change if the `header` or the `payload` changes. +FrostFS Object unique identifier. Objects are immutable and +content-addressed. It means `ObjectID` will change if the `header` or the +`payload` changes. `ObjectID` is a 32 byte long [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of @@ -141,7 +142,7 @@ with/without paddings are accepted. ### Message Signature -Signature of something in NeoFS. +Signature of something in FrostFS. | Field | Type | Label | Description | diff --git a/proto-docs/session.md b/proto-docs/session.md index 36a73ea..984db48 100644 --- a/proto-docs/session.md +++ b/proto-docs/session.md @@ -48,7 +48,7 @@ `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. +section of FrostFS Technical Specification for details. ``` rpc Create(CreateRequest) returns (CreateResponse); @@ -168,7 +168,7 @@ Carries objects involved in the object session. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | container | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Indicates which container the session is spread to. Field MUST be set and correct. | -| objects | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Indicates which objects the session is spread to. Objects are expected to be stored in the NeoFS container referenced by `container` field. Each element MUST have correct format. | +| objects | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Indicates which objects the session is spread to. Objects are expected to be stored in the FrostFS container referenced by `container` field. Each element MUST have correct format. | @@ -187,7 +187,7 @@ request meta headers are folded in matryoshka style. | 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 | -| magic_number | [uint64](#uint64) | | NeoFS network magic. Must match the value for the network that the server belongs to. | +| magic_number | [uint64](#uint64) | | FrostFS network magic. Must match the value for the network that the server belongs to. | @@ -237,12 +237,12 @@ Verification info for the response signed by all intermediate nodes ### Message SessionToken -NeoFS Session Token. +FrostFS Session Token. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| 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. | +| 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 FrostFS Technical Specification for details. | | signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of `SessionToken` information | diff --git a/proto-docs/status.md b/proto-docs/status.md index 373a7a7..76534fb 100644 --- a/proto-docs/status.md +++ b/proto-docs/status.md @@ -26,12 +26,12 @@ ### Message Status -Declares the general format of the status returns of the NeoFS RPC protocol. -Status is present in all response messages. Each RPC of NeoFS protocol -describes the possible outcomes and details of the operation. +Declares the general format of the status returns of the FrostFS RPC +protocol. Status is present in all response messages. Each RPC of FrostFS +protocol describes the possible outcomes and details of the operation. Each status is assigned a one-to-one numeric code. Any unique result of an -operation in NeoFS is unambiguously associated with the code value. +operation in FrostFS is unambiguously associated with the code value. Numerical set of codes is split into 1024-element sections. An enumeration is defined for each section. Values can be referred to in the following ways: @@ -98,7 +98,7 @@ Section of failed statuses independent of the operation. | Name | Number | Description | | ---- | ------ | ----------- | | INTERNAL | 0 | [**1024**] Internal server error, default failure. Not detailed. If the server cannot match failed outcome to the code, it should use this code. | -| WRONG_MAGIC_NUMBER | 1 | [**1025**] Wrong magic of the NeoFS network. Details: - [**0**] Magic number of the served NeoFS network (big-endian 64-bit unsigned integer). | +| WRONG_MAGIC_NUMBER | 1 | [**1025**] Wrong magic of the FrostFS network. Details: - [**0**] Magic number of the served FrostFS network (big-endian 64-bit unsigned integer). | | SIGNATURE_VERIFICATION_FAIL | 2 | [**1026**] Signature verification failure. | | NODE_UNDER_MAINTENANCE | 3 | [**1027**] Node is under maintenance. | | INVALID_ARGUMENT | 4 | [**1028**] Invalid argument error. If the server fails on validation of a request parameter as the client sent it incorrectly, then this code should be used. | @@ -165,7 +165,7 @@ Section of statuses for session-related operations. ### Success -Section of NeoFS successful return codes. +Section of FrostFS successful return codes. | Name | Number | Description | | ---- | ------ | ----------- | diff --git a/proto-docs/tombstone.md b/proto-docs/tombstone.md index 268e9a2..467ad55 100644 --- a/proto-docs/tombstone.md +++ b/proto-docs/tombstone.md @@ -26,12 +26,12 @@ ### Message Tombstone Tombstone keeps record of deleted objects for a few epochs until they are -purged from the NeoFS network. +purged from the FrostFS network. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| expiration_epoch | [uint64](#uint64) | | Last NeoFS epoch number of the tombstone lifetime. It's set by the tombstone creator depending on the current NeoFS network settings. A tombstone object must have the same expiration epoch value in `__SYSTEM__EXPIRATION_EPOCH` (`__NEOFS__EXPIRATION_EPOCH` is deprecated) attribute. Otherwise, the tombstone will be rejected by a storage node. | +| expiration_epoch | [uint64](#uint64) | | Last FrostFS epoch number of the tombstone lifetime. It's set by the tombstone creator depending on the current FrostFS network settings. A tombstone object must have the same expiration epoch value in `__SYSTEM__EXPIRATION_EPOCH` (`__NEOFS__EXPIRATION_EPOCH` is deprecated) attribute. Otherwise, the tombstone will be rejected by a storage node. | | split_id | [bytes](#bytes) | | 16 byte UUID used to identify the split object hierarchy parts. Must be unique inside a container. All objects participating in the split must have the same `split_id` value. | | members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of objects to be deleted. |