d.zayakin/frostfs-api
1
0
Fork 0
forked from TrueCloudLab/frostfs-api
Code Pull requests Activity

[#40] status: Introduce CONTAINER_ACCESS_DENIED status

Browse source 
* Add a new status CONTAINER_ACCESS_DENIED.
* Fix descriptions for methods of container and object services.
* Also regenerate md docs.

Signed-off-by: Airat Arifullin <aarifullin@yadro.com>
This commit is contained in:
Airat Arifullin 2024-03-05 12:36:58 +03:00
parent 46dd3885d2
commit 07eb6a438c
12 changed files with 411 additions and 194 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
container/service.proto
View file

@ -23,7 +23,9 @@ service ContainerService {
// Statuses: // Statuses:
// - **OK** (0, SECTION_SUCCESS): \ // - **OK** (0, SECTION_SUCCESS): \
// request to save the container has been sent to the sidechain; // request to save the container has been sent to the sidechain;
// - Common failures (SECTION_FAILURE_COMMON). // - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// container create access denied.
rpc Put(PutRequest) returns (PutResponse); rpc Put(PutRequest) returns (PutResponse);
// `Delete` invokes `Container` smart contract's `Delete` method and returns // `Delete` invokes `Container` smart contract's `Delete` method and returns
@ -34,7 +36,9 @@ service ContainerService {
// Statuses: // Statuses:
// - **OK** (0, SECTION_SUCCESS): \ // - **OK** (0, SECTION_SUCCESS): \
// request to remove the container has been sent to the sidechain; // request to remove the container has been sent to the sidechain;
// - Common failures (SECTION_FAILURE_COMMON). // - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// container delete access denied.
rpc Delete(DeleteRequest) returns (DeleteResponse); rpc Delete(DeleteRequest) returns (DeleteResponse);
// Returns container structure from `Container` smart contract storage. // Returns container structure from `Container` smart contract storage.
@ -44,7 +48,9 @@ service ContainerService {
// container has been successfully read; // container has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON); // - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// requested container not found. // requested container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied.
rpc Get(GetRequest) returns (GetResponse); rpc Get(GetRequest) returns (GetResponse);
// Returns all owner's containers from 'Container` smart contract' storage. // Returns all owner's containers from 'Container` smart contract' storage.
@ -52,7 +58,9 @@ service ContainerService {
// Statuses: // Statuses:
// - **OK** (0, SECTION_SUCCESS): \ // - **OK** (0, SECTION_SUCCESS): \
// container list has been successfully read; // container list has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON). // - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// container list access denied.
rpc List(ListRequest) returns (ListResponse); rpc List(ListRequest) returns (ListResponse);
// Invokes 'SetEACL' method of 'Container` smart contract and returns response // Invokes 'SetEACL' method of 'Container` smart contract and returns response
@ -62,7 +70,9 @@ service ContainerService {
// Statuses: // Statuses:
// - **OK** (0, SECTION_SUCCESS): \ // - **OK** (0, SECTION_SUCCESS): \
// request to save container eACL has been sent to the sidechain; // request to save container eACL has been sent to the sidechain;
// - Common failures (SECTION_FAILURE_COMMON). // - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// set container eACL access denied.
rpc SetExtendedACL(SetExtendedACLRequest) returns (SetExtendedACLResponse); rpc SetExtendedACL(SetExtendedACLRequest) returns (SetExtendedACLResponse);
// Returns Extended ACL table and signature from `Container` smart contract // Returns Extended ACL table and signature from `Container` smart contract
@ -75,7 +85,9 @@ service ContainerService {
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// container not found; // container not found;
// - **EACL_NOT_FOUND** (3073, SECTION_CONTAINER): \ // - **EACL_NOT_FOUND** (3073, SECTION_CONTAINER): \
// eACL table not found. // eACL table not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container eACL is denied.
rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse); rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse);
// Announces the space values used by the container for P2P synchronization. // Announces the space values used by the container for P2P synchronization.

16
object/service.proto
View file

@ -45,6 +45,8 @@ service ObjectService {
// the requested object has been marked as deleted; // the requested object has been marked as deleted;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found; // object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired. // provided session token has expired.
rpc Get(GetRequest) returns (stream GetResponse); rpc Get(GetRequest) returns (stream GetResponse);
@ -78,6 +80,8 @@ service ObjectService {
// type other than REGULAR is prohibited; // type other than REGULAR is prohibited;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object storage container not found; // object storage container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \ // - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \
// (for trusted object preparation) session private key does not exist or // (for trusted object preparation) session private key does not exist or
// has // has
@ -110,6 +114,8 @@ service ObjectService {
// deleting a locked object is prohibited; // deleting a locked object is prohibited;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found; // object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired. // provided session token has expired.
rpc Delete(DeleteRequest) returns (DeleteResponse); rpc Delete(DeleteRequest) returns (DeleteResponse);
@ -138,6 +144,8 @@ service ObjectService {
// the requested object has been marked as deleted; // the requested object has been marked as deleted;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found; // object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired. // provided session token has expired.
rpc Head(HeadRequest) returns (HeadResponse); rpc Head(HeadRequest) returns (HeadResponse);
@ -162,6 +170,8 @@ service ObjectService {
// access to operation SEARCH of the object is denied; // access to operation SEARCH of the object is denied;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// search container not found; // search container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired. // provided session token has expired.
rpc Search(SearchRequest) returns (stream SearchResponse); rpc Search(SearchRequest) returns (stream SearchResponse);
@ -197,6 +207,8 @@ service ObjectService {
// the requested range is out of bounds; // the requested range is out of bounds;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found; // object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired. // provided session token has expired.
rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse); rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse);
@ -230,6 +242,8 @@ service ObjectService {
// the requested range is out of bounds; // the requested range is out of bounds;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found; // object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired. // provided session token has expired.
rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse); rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
@ -260,6 +274,8 @@ service ObjectService {
// type other than REGULAR is prohibited; // type other than REGULAR is prohibited;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object storage container not found; // object storage container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \ // - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \
// (for trusted object preparation) session private key does not exist or // (for trusted object preparation) session private key does not exist or
// has // has

3
proto-docs/accounting.md
View file

@ -105,7 +105,8 @@ BalanceResponse message
### Message BalanceResponse.Body ### Message BalanceResponse.Body
The amount of funds in GAS token for the `OwnerID`'s account requested. The amount of funds in GAS token for the `OwnerID`'s account requested.
Balance is given in the `Decimal` format to avoid precision issues with rounding. Balance is given in the `Decimal` format to avoid precision issues with
rounding.
| Field | Type | Label | Description | | Field | Type | Label | Description |

8
proto-docs/acl.md
View file

@ -38,8 +38,8 @@ like [JWT](https://jwt.io), it has a limited lifetime and scope, hence can be
used in the similar use cases, like providing authorisation to externally used in the similar use cases, like providing authorisation to externally
authenticated party. authenticated party.
BearerToken can be issued only by the container's owner and must be signed using BearerToken can be issued only by the container's owner and must be signed
the key associated with the container's `OwnerID`. using the key associated with the container's `OwnerID`.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -51,8 +51,8 @@ the key associated with the container's `OwnerID`.
<a name="neo.fs.v2.acl.BearerToken.Body"></a> <a name="neo.fs.v2.acl.BearerToken.Body"></a>
### Message BearerToken.Body ### Message BearerToken.Body
Bearer Token body structure contains Extended ACL table issued by the container Bearer Token body structure contains Extended ACL table issued by the
owner with additional information preventing token abuse. container owner with additional information preventing token abuse.
| Field | Type | Label | Description | | Field | Type | Label | Description |

155
proto-docs/container.md
View file

@ -3,50 +3,50 @@
## Table of Contents ## Table of Contents
- [Protocol Documentation](#protocol-documentation) - [container/service.proto](#container/service.proto)
- [Table of Contents](#table-of-contents) - Services
- [container/service.proto](#containerserviceproto) - [ContainerService](#neo.fs.v2.container.ContainerService)
- [Service "neo.fs.v2.container.ContainerService"](#service-neofsv2containercontainerservice)
- [Method Put](#method-put) - Messages
- [Method Delete](#method-delete) - [AnnounceUsedSpaceRequest](#neo.fs.v2.container.AnnounceUsedSpaceRequest)
- [Method Get](#method-get) - [AnnounceUsedSpaceRequest.Body](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body)
- [Method List](#method-list) - [AnnounceUsedSpaceRequest.Body.Announcement](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement)
- [Method SetExtendedACL](#method-setextendedacl) - [AnnounceUsedSpaceResponse](#neo.fs.v2.container.AnnounceUsedSpaceResponse)
- [Method GetExtendedACL](#method-getextendedacl) - [AnnounceUsedSpaceResponse.Body](#neo.fs.v2.container.AnnounceUsedSpaceResponse.Body)
- [Method AnnounceUsedSpace](#method-announceusedspace) - [DeleteRequest](#neo.fs.v2.container.DeleteRequest)
- [Message AnnounceUsedSpaceRequest](#message-announceusedspacerequest) - [DeleteRequest.Body](#neo.fs.v2.container.DeleteRequest.Body)
- [Message AnnounceUsedSpaceRequest.Body](#message-announceusedspacerequestbody) - [DeleteResponse](#neo.fs.v2.container.DeleteResponse)
- [Message AnnounceUsedSpaceRequest.Body.Announcement](#message-announceusedspacerequestbodyannouncement) - [DeleteResponse.Body](#neo.fs.v2.container.DeleteResponse.Body)
- [Message AnnounceUsedSpaceResponse](#message-announceusedspaceresponse) - [GetExtendedACLRequest](#neo.fs.v2.container.GetExtendedACLRequest)
- [Message AnnounceUsedSpaceResponse.Body](#message-announceusedspaceresponsebody) - [GetExtendedACLRequest.Body](#neo.fs.v2.container.GetExtendedACLRequest.Body)
- [Message DeleteRequest](#message-deleterequest) - [GetExtendedACLResponse](#neo.fs.v2.container.GetExtendedACLResponse)
- [Message DeleteRequest.Body](#message-deleterequestbody) - [GetExtendedACLResponse.Body](#neo.fs.v2.container.GetExtendedACLResponse.Body)
- [Message DeleteResponse](#message-deleteresponse) - [GetRequest](#neo.fs.v2.container.GetRequest)
- [Message DeleteResponse.Body](#message-deleteresponsebody) - [GetRequest.Body](#neo.fs.v2.container.GetRequest.Body)
- [Message GetExtendedACLRequest](#message-getextendedaclrequest) - [GetResponse](#neo.fs.v2.container.GetResponse)
- [Message GetExtendedACLRequest.Body](#message-getextendedaclrequestbody) - [GetResponse.Body](#neo.fs.v2.container.GetResponse.Body)
- [Message GetExtendedACLResponse](#message-getextendedaclresponse) - [ListRequest](#neo.fs.v2.container.ListRequest)
- [Message GetExtendedACLResponse.Body](#message-getextendedaclresponsebody) - [ListRequest.Body](#neo.fs.v2.container.ListRequest.Body)
- [Message GetRequest](#message-getrequest) - [ListResponse](#neo.fs.v2.container.ListResponse)
- [Message GetRequest.Body](#message-getrequestbody) - [ListResponse.Body](#neo.fs.v2.container.ListResponse.Body)
- [Message GetResponse](#message-getresponse) - [PutRequest](#neo.fs.v2.container.PutRequest)
- [Message GetResponse.Body](#message-getresponsebody) - [PutRequest.Body](#neo.fs.v2.container.PutRequest.Body)
- [Message ListRequest](#message-listrequest) - [PutResponse](#neo.fs.v2.container.PutResponse)
- [Message ListRequest.Body](#message-listrequestbody) - [PutResponse.Body](#neo.fs.v2.container.PutResponse.Body)
- [Message ListResponse](#message-listresponse) - [SetExtendedACLRequest](#neo.fs.v2.container.SetExtendedACLRequest)
- [Message ListResponse.Body](#message-listresponsebody) - [SetExtendedACLRequest.Body](#neo.fs.v2.container.SetExtendedACLRequest.Body)
- [Message PutRequest](#message-putrequest) - [SetExtendedACLResponse](#neo.fs.v2.container.SetExtendedACLResponse)
- [Message PutRequest.Body](#message-putrequestbody) - [SetExtendedACLResponse.Body](#neo.fs.v2.container.SetExtendedACLResponse.Body)
- [Message PutResponse](#message-putresponse)
- [Message PutResponse.Body](#message-putresponsebody)
- [Message SetExtendedACLRequest](#message-setextendedaclrequest) - [container/types.proto](#container/types.proto)
- [Message SetExtendedACLRequest.Body](#message-setextendedaclrequestbody)
- [Message SetExtendedACLResponse](#message-setextendedaclresponse) - Messages
- [Message SetExtendedACLResponse.Body](#message-setextendedaclresponsebody) - [Container](#neo.fs.v2.container.Container)
- [container/types.proto](#containertypesproto) - [Container.Attribute](#neo.fs.v2.container.Container.Attribute)
- [Message Container](#message-container)
- [Message Container.Attribute](#message-containerattribute)
- [Scalar Value Types](#scalar-value-types) - [Scalar Value Types](#scalar-value-types)
@ -81,13 +81,15 @@ rpc AnnounceUsedSpace(AnnounceUsedSpaceRequest) returns (AnnounceUsedSpaceRespon
`Put` invokes `Container` smart contract's `Put` method and returns `Put` invokes `Container` smart contract's `Put` method and returns
response immediately. After a new block is issued in sidechain, request is response immediately. After a new block is issued in sidechain, request is
verified by Inner Ring nodes. After one more block in sidechain, the container verified by Inner Ring nodes. After one more block in sidechain, the
is added into smart contract storage. container is added into smart contract storage.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
request to save the container has been sent to the sidechain; request to save the container has been sent to the sidechain;
- Common failures (SECTION_FAILURE_COMMON). - Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
container create access denied.
| Name | Input | Output | | Name | Input | Output |
| ---- | ----- | ------ | | ---- | ----- | ------ |
@ -96,13 +98,15 @@ Statuses:
`Delete` invokes `Container` smart contract's `Delete` method and returns `Delete` invokes `Container` smart contract's `Delete` method and returns
response immediately. After a new block is issued in sidechain, request is response immediately. After a new block is issued in sidechain, request is
verified by Inner Ring nodes. After one more block in sidechain, the container verified by Inner Ring nodes. After one more block in sidechain, the
is added into smart contract storage. container is added into smart contract storage.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
request to remove the container has been sent to the sidechain; request to remove the container has been sent to the sidechain;
- Common failures (SECTION_FAILURE_COMMON). - Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
container delete access denied.
| Name | Input | Output | | Name | Input | Output |
| ---- | ----- | ------ | | ---- | ----- | ------ |
@ -116,7 +120,9 @@ Statuses:
container has been successfully read; container has been successfully read;
- Common failures (SECTION_FAILURE_COMMON); - Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
requested container not found. requested container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied.
| Name | Input | Output | | Name | Input | Output |
| ---- | ----- | ------ | | ---- | ----- | ------ |
@ -128,7 +134,9 @@ Returns all owner's containers from 'Container` smart contract' storage.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
container list has been successfully read; container list has been successfully read;
- Common failures (SECTION_FAILURE_COMMON). - Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
container list access denied.
| Name | Input | Output | | Name | Input | Output |
| ---- | ----- | ------ | | ---- | ----- | ------ |
@ -136,13 +144,15 @@ Statuses:
#### Method SetExtendedACL #### Method SetExtendedACL
Invokes 'SetEACL' method of 'Container` smart contract and returns response Invokes 'SetEACL' method of 'Container` smart contract and returns response
immediately. After one more block in sidechain, changes in an Extended ACL are immediately. After one more block in sidechain, changes in an Extended ACL
added into smart contract storage. are added into smart contract storage.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
request to save container eACL has been sent to the sidechain; request to save container eACL has been sent to the sidechain;
- Common failures (SECTION_FAILURE_COMMON). - Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
set container eACL access denied.
| Name | Input | Output | | Name | Input | Output |
| ---- | ----- | ------ | | ---- | ----- | ------ |
@ -159,7 +169,9 @@ Statuses:
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
container not found; container not found;
- **EACL_NOT_FOUND** (3073, SECTION_CONTAINER): \ - **EACL_NOT_FOUND** (3073, SECTION_CONTAINER): \
eACL table not found. eACL table not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container eACL is denied.
| Name | Input | Output | | Name | Input | Output |
| ---- | ----- | ------ | | ---- | ----- | ------ |
@ -327,8 +339,8 @@ Get Extended ACL
### Message GetExtendedACLResponse.Body ### Message GetExtendedACLResponse.Body
Get Extended ACL Response body can be empty if the requested container does 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 not have Extended ACL Table attached or Extended ACL has not been allowed
the time of container creation. at the time of container creation.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -536,8 +548,8 @@ Set Extended ACL
### Message SetExtendedACLResponse.Body ### Message SetExtendedACLResponse.Body
`SetExtendedACLResponse` has an empty body because the operation is `SetExtendedACLResponse` has an empty body because the operation is
asynchronous and the update should be reflected in `Container` smart contract's asynchronous and the update should be reflected in `Container` smart
storage after next block is issued in sidechain. contract's storage after next block is issued in sidechain.
<!-- end messages --> <!-- end messages -->
@ -560,8 +572,8 @@ storage after next block is issued in sidechain.
### Message Container ### Message Container
Container is a structure that defines object placement behaviour. Objects can Container is a structure that defines object placement behaviour. Objects can
be stored only within containers. They define placement rule, attributes and be stored only within containers. They define placement rule, attributes and
access control information. An ID of a container is a 32 byte long SHA256 hash access control information. An ID of a container is a 32 byte long SHA256
of stable-marshalled container message. hash of stable-marshalled container message.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -578,8 +590,8 @@ of stable-marshalled container message.
### Message Container.Attribute ### Message Container.Attribute
`Attribute` is a user-defined Key-Value metadata pair attached to the `Attribute` is a user-defined Key-Value metadata pair attached to the
container. Container attributes are immutable. They are set at the moment of container. Container attributes are immutable. They are set at the moment
container creation and can never be added or updated. of container creation and can never be added or updated.
Key name must be a container-unique valid UTF-8 string. Value can't be Key name must be a container-unique valid UTF-8 string. Value can't be
empty. Containers with duplicated attribute names or attributes with empty empty. Containers with duplicated attribute names or attributes with empty
@ -593,15 +605,16 @@ There are some "well-known" attributes affecting system behaviour:
NNS contract. NNS contract.
* [ __SYSTEM__ZONE ] \ * [ __SYSTEM__ZONE ] \
(`__NEOFS__ZONE` is deprecated) \ (`__NEOFS__ZONE` is deprecated) \
String of a zone for `__SYSTEM__NAME` (`__NEOFS__NAME` is deprecated). Used as a TLD of a domain name in NNS String of a zone for `__SYSTEM__NAME` (`__NEOFS__NAME` is deprecated).
contract. If no zone is specified, use default zone: `container`. Used as a TLD of a domain name in NNS contract. If no zone is specified,
use default zone: `container`.
* [ __SYSTEM__DISABLE_HOMOMORPHIC_HASHING ] \ * [ __SYSTEM__DISABLE_HOMOMORPHIC_HASHING ] \
(`__NEOFS__DISABLE_HOMOMORPHIC_HASHING` is deprecated) \ (`__NEOFS__DISABLE_HOMOMORPHIC_HASHING` is deprecated) \
Disables homomorphic hashing for the container if the value equals "true" string. Disables homomorphic hashing for the container if the value equals "true"
Any other values are interpreted as missing attribute. Container could be string. Any other values are interpreted as missing attribute. Container
accepted in a NeoFS network only if the global network hashing configuration could be accepted in a NeoFS network only if the global network hashing
value corresponds with that attribute's value. After container inclusion, network configuration value corresponds with that attribute's value. After
setting is ignored. container inclusion, network setting is ignored.
And some well-known attributes used by applications only: And some well-known attributes used by applications only:

5
proto-docs/lock.md
View file

@ -27,8 +27,9 @@
### Message Lock ### Message Lock
Lock objects protects a list of objects from being deleted. The lifetime of a Lock objects protects a list of objects from being deleted. The lifetime of a
lock object is limited similar to regular objects in lock object is limited similar to regular objects in
`__SYSTEM__EXPIRATION_EPOCH` (`__NEOFS__EXPIRATION_EPOCH` is deprecated) attribute. Lock object MUST have expiration epoch. `__SYSTEM__EXPIRATION_EPOCH` (`__NEOFS__EXPIRATION_EPOCH` is deprecated)
It is impossible to delete a lock object via ObjectService.Delete RPC call. attribute. Lock object MUST have expiration epoch. It is impossible to delete
a lock object via ObjectService.Delete RPC call.
| Field | Type | Label | Description | | Field | Type | Label | Description |

112
proto-docs/netmap.md
View file

@ -3,40 +3,41 @@
## Table of Contents ## Table of Contents
- [Protocol Documentation](#protocol-documentation) - [netmap/service.proto](#netmap/service.proto)
- [Table of Contents](#table-of-contents) - Services
- [netmap/service.proto](#netmapserviceproto) - [NetmapService](#neo.fs.v2.netmap.NetmapService)
- [Service "neo.fs.v2.netmap.NetmapService"](#service-neofsv2netmapnetmapservice)
- [Method LocalNodeInfo](#method-localnodeinfo) - Messages
- [Method NetworkInfo](#method-networkinfo) - [LocalNodeInfoRequest](#neo.fs.v2.netmap.LocalNodeInfoRequest)
- [Method NetmapSnapshot](#method-netmapsnapshot) - [LocalNodeInfoRequest.Body](#neo.fs.v2.netmap.LocalNodeInfoRequest.Body)
- [Message LocalNodeInfoRequest](#message-localnodeinforequest) - [LocalNodeInfoResponse](#neo.fs.v2.netmap.LocalNodeInfoResponse)
- [Message LocalNodeInfoRequest.Body](#message-localnodeinforequestbody) - [LocalNodeInfoResponse.Body](#neo.fs.v2.netmap.LocalNodeInfoResponse.Body)
- [Message LocalNodeInfoResponse](#message-localnodeinforesponse) - [NetmapSnapshotRequest](#neo.fs.v2.netmap.NetmapSnapshotRequest)
- [Message LocalNodeInfoResponse.Body](#message-localnodeinforesponsebody) - [NetmapSnapshotRequest.Body](#neo.fs.v2.netmap.NetmapSnapshotRequest.Body)
- [Message NetmapSnapshotRequest](#message-netmapsnapshotrequest) - [NetmapSnapshotResponse](#neo.fs.v2.netmap.NetmapSnapshotResponse)
- [Message NetmapSnapshotRequest.Body](#message-netmapsnapshotrequestbody) - [NetmapSnapshotResponse.Body](#neo.fs.v2.netmap.NetmapSnapshotResponse.Body)
- [Message NetmapSnapshotResponse](#message-netmapsnapshotresponse) - [NetworkInfoRequest](#neo.fs.v2.netmap.NetworkInfoRequest)
- [Message NetmapSnapshotResponse.Body](#message-netmapsnapshotresponsebody) - [NetworkInfoRequest.Body](#neo.fs.v2.netmap.NetworkInfoRequest.Body)
- [Message NetworkInfoRequest](#message-networkinforequest) - [NetworkInfoResponse](#neo.fs.v2.netmap.NetworkInfoResponse)
- [Message NetworkInfoRequest.Body](#message-networkinforequestbody) - [NetworkInfoResponse.Body](#neo.fs.v2.netmap.NetworkInfoResponse.Body)
- [Message NetworkInfoResponse](#message-networkinforesponse)
- [Message NetworkInfoResponse.Body](#message-networkinforesponsebody)
- [netmap/types.proto](#netmaptypesproto) - [netmap/types.proto](#netmap/types.proto)
- [Message Filter](#message-filter)
- [Message Netmap](#message-netmap) - Messages
- [Message NetworkConfig](#message-networkconfig) - [Filter](#neo.fs.v2.netmap.Filter)
- [Message NetworkConfig.Parameter](#message-networkconfigparameter) - [Netmap](#neo.fs.v2.netmap.Netmap)
- [Message NetworkInfo](#message-networkinfo) - [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig)
- [Message NodeInfo](#message-nodeinfo) - [NetworkConfig.Parameter](#neo.fs.v2.netmap.NetworkConfig.Parameter)
- [Message NodeInfo.Attribute](#message-nodeinfoattribute) - [NetworkInfo](#neo.fs.v2.netmap.NetworkInfo)
- [Message PlacementPolicy](#message-placementpolicy) - [NodeInfo](#neo.fs.v2.netmap.NodeInfo)
- [Message Replica](#message-replica) - [NodeInfo.Attribute](#neo.fs.v2.netmap.NodeInfo.Attribute)
- [Message Selector](#message-selector) - [PlacementPolicy](#neo.fs.v2.netmap.PlacementPolicy)
- [Clause](#clause) - [Replica](#neo.fs.v2.netmap.Replica)
- [NodeInfo.State](#nodeinfostate) - [Selector](#neo.fs.v2.netmap.Selector)
- [Operation](#operation)
- [Scalar Value Types](#scalar-value-types)
- [Scalar Value Types](#scalar-value-types)
@ -51,10 +52,10 @@
<a name="neo.fs.v2.netmap.NetmapService"></a> <a name="neo.fs.v2.netmap.NetmapService"></a>
### Service "neo.fs.v2.netmap.NetmapService" ### Service "neo.fs.v2.netmap.NetmapService"
`NetmapService` provides methods to work with `Network Map` and the information `NetmapService` provides methods to work with `Network Map` and the
required to build it. The resulting `Network Map` is stored in sidechain information required to build it. The resulting `Network Map` is stored in
`Netmap` smart contract, while related information can be obtained from other sidechain `Netmap` smart contract, while related information can be obtained
NeoFS nodes. from other NeoFS nodes.
``` ```
rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse); rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
@ -66,10 +67,11 @@ rpc NetmapSnapshot(NetmapSnapshotRequest) returns (NetmapSnapshotResponse);
#### Method LocalNodeInfo #### Method LocalNodeInfo
Get NodeInfo structure from the particular node directly. Get NodeInfo structure from the particular node directly.
Node information can be taken from `Netmap` smart contract. In some cases, though, Node information can be taken from `Netmap` smart contract. In some cases,
one may want to get recent information directly or to talk to the node not yet though, one may want to get recent information directly or to talk to the
present in the `Network Map` to find out what API version can be used for node not yet present in the `Network Map` to find out what API version can
further communication. This can be also used to check if a node is up and running. be used for further communication. This can be also used to check if a node
is up and running.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): - **OK** (0, SECTION_SUCCESS):
@ -257,8 +259,8 @@ Information about the network.
<a name="neo.fs.v2.netmap.Filter"></a> <a name="neo.fs.v2.netmap.Filter"></a>
### Message Filter ### Message Filter
This filter will return the subset of nodes from `NetworkMap` or another filter's This filter will return the subset of nodes from `NetworkMap` or another
results that will satisfy filter's conditions. filter's results that will satisfy filter's conditions.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -330,6 +332,12 @@ System parameters:
- **WithdrawFee** \ - **WithdrawFee** \
Fee paid for withdrawal of funds paid by the account owner. Fee paid for withdrawal of funds paid by the account owner.
Value: little-endian integer. Default: 0. Value: little-endian integer. Default: 0.
- **MaxECDataCount** \
Maximum number of data shards for EC placement policy.
Value: little-endian integer. Default: 0.
- **MaxECParityCount** \
Maximum number of parity shards for EC placement policy.
Value: little-endian integer. Default: 0.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -375,15 +383,15 @@ Administrator-defined Attributes of the NeoFS Storage Node.
string. Value can't be empty. string. Value can't be empty.
Attributes can be constructed into a chain of attributes: any attribute can 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 have a parent attribute and a child attribute (except the first and the
one). A string representation of the chain of attributes in NeoFS Storage last one). A string representation of the chain of attributes in NeoFS
Node configuration uses ":" and "/" symbols, e.g.: Storage Node configuration uses ":" and "/" symbols, e.g.:
`NEOFS_NODE_ATTRIBUTE_1=key1:val1/key2:val2` `NEOFS_NODE_ATTRIBUTE_1=key1:val1/key2:val2`
Therefore the string attribute representation in the Node configuration must Therefore the string attribute representation in the Node configuration
use "\:", "\/" and "\\" escaped symbols if any of them appears in an attribute's must use "\:", "\/" and "\\" escaped symbols if any of them appears in an
key or value. attribute's key or value.
Node's attributes are mostly used during Storage Policy evaluation to Node's attributes are mostly used during Storage Policy evaluation to
calculate object's placement and find a set of nodes satisfying policy calculate object's placement and find a set of nodes satisfying policy
@ -459,6 +467,7 @@ storage policy definition languages.
| 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 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 | | 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 | | 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 |
<a name="neo.fs.v2.netmap.Replica"></a> <a name="neo.fs.v2.netmap.Replica"></a>
@ -473,6 +482,8 @@ default.
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| count | [uint32](#uint32) | | How many object replicas to put | | count | [uint32](#uint32) | | How many object replicas to put |
| selector | [string](#string) | | Named selector bucket to put replicas | | selector | [string](#string) | | Named selector bucket to put replicas |
| ec_data_count | [uint32](#uint32) | | Data shards count |
| ec_parity_count | [uint32](#uint32) | | Parity shards count |
<a name="neo.fs.v2.netmap.Selector"></a> <a name="neo.fs.v2.netmap.Selector"></a>
@ -538,6 +549,7 @@ Operations on filters
| LE | 6 | Less or equal | | LE | 6 | Less or equal |
| OR | 7 | Logical OR | | OR | 7 | Logical OR |
| AND | 8 | Logical AND | | AND | 8 | Logical AND |
| NOT | 9 | Logical negation |
<!-- end enums --> <!-- end enums -->

220
proto-docs/object.md
View file

@ -35,6 +35,10 @@
- [PutRequest.Body.Init](#neo.fs.v2.object.PutRequest.Body.Init) - [PutRequest.Body.Init](#neo.fs.v2.object.PutRequest.Body.Init)
- [PutResponse](#neo.fs.v2.object.PutResponse) - [PutResponse](#neo.fs.v2.object.PutResponse)
- [PutResponse.Body](#neo.fs.v2.object.PutResponse.Body) - [PutResponse.Body](#neo.fs.v2.object.PutResponse.Body)
- [PutSingleRequest](#neo.fs.v2.object.PutSingleRequest)
- [PutSingleRequest.Body](#neo.fs.v2.object.PutSingleRequest.Body)
- [PutSingleResponse](#neo.fs.v2.object.PutSingleResponse)
- [PutSingleResponse.Body](#neo.fs.v2.object.PutSingleResponse.Body)
- [Range](#neo.fs.v2.object.Range) - [Range](#neo.fs.v2.object.Range)
- [SearchRequest](#neo.fs.v2.object.SearchRequest) - [SearchRequest](#neo.fs.v2.object.SearchRequest)
- [SearchRequest.Body](#neo.fs.v2.object.SearchRequest.Body) - [SearchRequest.Body](#neo.fs.v2.object.SearchRequest.Body)
@ -46,8 +50,11 @@
- [object/types.proto](#object/types.proto) - [object/types.proto](#object/types.proto)
- Messages - Messages
- [ECInfo](#neo.fs.v2.object.ECInfo)
- [ECInfo.Chunk](#neo.fs.v2.object.ECInfo.Chunk)
- [Header](#neo.fs.v2.object.Header) - [Header](#neo.fs.v2.object.Header)
- [Header.Attribute](#neo.fs.v2.object.Header.Attribute) - [Header.Attribute](#neo.fs.v2.object.Header.Attribute)
- [Header.EC](#neo.fs.v2.object.Header.EC)
- [Header.Split](#neo.fs.v2.object.Header.Split) - [Header.Split](#neo.fs.v2.object.Header.Split)
- [Object](#neo.fs.v2.object.Object) - [Object](#neo.fs.v2.object.Object)
- [ShortHeader](#neo.fs.v2.object.ShortHeader) - [ShortHeader](#neo.fs.v2.object.ShortHeader)
@ -80,17 +87,18 @@ rpc Head(HeadRequest) returns (HeadResponse);
rpc Search(SearchRequest) returns (stream SearchResponse); rpc Search(SearchRequest) returns (stream SearchResponse);
rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse); rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse);
rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse); rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
rpc PutSingle(PutSingleRequest) returns (PutSingleResponse);
``` ```
#### Method Get #### Method Get
Receive full object structure, including Headers and payload. Response uses Receive full object structure, including Headers and payload. Response uses
gRPC stream. First response message carries the object with the requested address. gRPC stream. First response message carries the object with the requested
Chunk messages are parts of the object's payload if it is needed. All address. Chunk messages are parts of the object's payload if it is needed.
messages, except the first one, carry payload chunks. The requested object can All messages, except the first one, carry payload chunks. The requested
be restored by concatenation of object message payload and all chunks object can be restored by concatenation of object message payload and all
keeping the receiving order. chunks keeping the receiving order.
Extended headers can change `Get` behaviour: Extended headers can change `Get` behaviour:
* [ __SYSTEM__NETMAP_EPOCH ] \ * [ __SYSTEM__NETMAP_EPOCH ] \
@ -99,9 +107,10 @@ Extended headers can change `Get` behaviour:
calculation. calculation.
* [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \
(`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \ (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
Will try older versions (starting from `__SYSTEM__NETMAP_EPOCH` (`__NEOFS__NETMAP_EPOCH` is deprecated) if specified or Will try older versions (starting from `__SYSTEM__NETMAP_EPOCH`
the latest one otherwise) of Network Map to find an object until the depth (`__NEOFS__NETMAP_EPOCH` is deprecated) if specified or the latest one
limit is reached. otherwise) of Network Map to find an object until the depth limit is
reached.
Please refer to detailed `XHeader` description. Please refer to detailed `XHeader` description.
@ -117,6 +126,8 @@ Statuses:
the requested object has been marked as deleted; the requested object has been marked as deleted;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found; object container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. provided session token has expired.
@ -147,15 +158,18 @@ Statuses:
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \ - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
write access to the container is denied; write access to the container is denied;
- **LOCKED** (2050, SECTION_OBJECT): \ - **LOCKED** (2050, SECTION_OBJECT): \
placement of an object of type TOMBSTONE that includes at least one locked placement of an object of type TOMBSTONE that includes at least one
object is prohibited; locked object is prohibited;
- **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \ - **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \
placement of an object of type LOCK that includes at least one object of placement of an object of type LOCK that includes at least one object of
type other than REGULAR is prohibited; type other than REGULAR is prohibited;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object storage container not found; object storage container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \ - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \
(for trusted object preparation) session private key does not exist or has (for trusted object preparation) session private key does not exist or
has
been deleted; been deleted;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. provided session token has expired.
@ -182,10 +196,15 @@ Statuses:
- Common failures (SECTION_FAILURE_COMMON); - Common failures (SECTION_FAILURE_COMMON);
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \ - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
delete access to the object is denied; delete access to the object is denied;
- **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
the object could not be deleted because it has not been \
found within the container;
- **LOCKED** (2050, SECTION_OBJECT): \ - **LOCKED** (2050, SECTION_OBJECT): \
deleting a locked object is prohibited; deleting a locked object is prohibited;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found; object container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. provided session token has expired.
@ -218,6 +237,8 @@ Statuses:
the requested object has been marked as deleted; the requested object has been marked as deleted;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found; object container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. provided session token has expired.
@ -246,6 +267,8 @@ Statuses:
access to operation SEARCH of the object is denied; access to operation SEARCH of the object is denied;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
search container not found; search container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. provided session token has expired.
@ -256,8 +279,8 @@ Statuses:
Get byte range of data payload. Range is set as an (offset, length) tuple. Get byte range of data payload. Range is set as an (offset, length) tuple.
Like in `Get` method, the response uses gRPC stream. Requested range can be Like in `Get` method, the response uses gRPC stream. Requested range can be
restored by concatenation of all received payload chunks keeping the receiving restored by concatenation of all received payload chunks keeping the
order. receiving order.
Extended headers can change `GetRange` behaviour: Extended headers can change `GetRange` behaviour:
* [ __SYSTEM__NETMAP_EPOCH ] \ * [ __SYSTEM__NETMAP_EPOCH ] \
@ -285,6 +308,8 @@ Statuses:
the requested range is out of bounds; the requested range is out of bounds;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found; object container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. provided session token has expired.
@ -322,12 +347,54 @@ Statuses:
the requested range is out of bounds; the requested range is out of bounds;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found; object container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. provided session token has expired.
| Name | Input | Output | | Name | Input | Output |
| ---- | ----- | ------ | | ---- | ----- | ------ |
| GetRangeHash | [GetRangeHashRequest](#neo.fs.v2.object.GetRangeHashRequest) | [GetRangeHashResponse](#neo.fs.v2.object.GetRangeHashResponse) | | GetRangeHash | [GetRangeHashRequest](#neo.fs.v2.object.GetRangeHashRequest) | [GetRangeHashResponse](#neo.fs.v2.object.GetRangeHashResponse) |
#### Method PutSingle
Put the prepared object into container.
`ContainerID`, `ObjectID`, `OwnerID`, `PayloadHash` and `PayloadLength` of
an object MUST be set.
Extended headers can change `Put` behaviour:
* [ __SYSTEM__NETMAP_EPOCH \
(`__NEOFS__NETMAP_EPOCH` is deprecated) \
Will use the requested version of Network Map for object placement
calculation.
Please refer to detailed `XHeader` description.
Statuses:
- **OK** (0, SECTION_SUCCESS): \
object has been successfully saved in the container;
- Common failures (SECTION_FAILURE_COMMON);
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
write access to the container is denied;
- **LOCKED** (2050, SECTION_OBJECT): \
placement of an object of type TOMBSTONE that includes at least one
locked object is prohibited;
- **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \
placement of an object of type LOCK that includes at least one object of
type other than REGULAR is prohibited;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object storage container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \
(for trusted object preparation) session private key does not exist or
has
been deleted;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired.
| Name | Input | Output |
| ---- | ----- | ------ |
| PutSingle | [PutSingleRequest](#neo.fs.v2.object.PutSingleRequest) | [PutSingleResponse](#neo.fs.v2.object.PutSingleResponse) |
<!-- end services --> <!-- end services -->
@ -484,6 +551,7 @@ chunks.
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| chunk | [bytes](#bytes) | | Chunked object payload's range. | | chunk | [bytes](#bytes) | | Chunked object payload's range. |
| split_info | [SplitInfo](#neo.fs.v2.object.SplitInfo) | | Meta information of split hierarchy. | | split_info | [SplitInfo](#neo.fs.v2.object.SplitInfo) | | Meta information of split hierarchy. |
| ec_info | [ECInfo](#neo.fs.v2.object.ECInfo) | | Meta information for EC object assembly. |
<a name="neo.fs.v2.object.GetRequest"></a> <a name="neo.fs.v2.object.GetRequest"></a>
@ -535,6 +603,7 @@ GET Object Response body
| init | [GetResponse.Body.Init](#neo.fs.v2.object.GetResponse.Body.Init) | | Initial part of the object stream | | init | [GetResponse.Body.Init](#neo.fs.v2.object.GetResponse.Body.Init) | | Initial part of the object stream |
| chunk | [bytes](#bytes) | | Chunked object payload | | chunk | [bytes](#bytes) | | Chunked object payload |
| split_info | [SplitInfo](#neo.fs.v2.object.SplitInfo) | | Meta information of split hierarchy for object assembly. | | split_info | [SplitInfo](#neo.fs.v2.object.SplitInfo) | | Meta information of split hierarchy for object assembly. |
| ec_info | [ECInfo](#neo.fs.v2.object.ECInfo) | | Meta information for EC object assembly. |
<a name="neo.fs.v2.object.GetResponse.Body.Init"></a> <a name="neo.fs.v2.object.GetResponse.Body.Init"></a>
@ -601,6 +670,7 @@ Object HEAD response body
| header | [HeaderWithSignature](#neo.fs.v2.object.HeaderWithSignature) | | Full object's `Header` with `ObjectID` 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 | | short_header | [ShortHeader](#neo.fs.v2.object.ShortHeader) | | Short object header |
| split_info | [SplitInfo](#neo.fs.v2.object.SplitInfo) | | Meta information of split hierarchy. | | split_info | [SplitInfo](#neo.fs.v2.object.SplitInfo) | | Meta information of split hierarchy. |
| ec_info | [ECInfo](#neo.fs.v2.object.ECInfo) | | Meta information for EC object assembly. |
<a name="neo.fs.v2.object.HeaderWithSignature"></a> <a name="neo.fs.v2.object.HeaderWithSignature"></a>
@ -685,6 +755,51 @@ PUT Object response body
| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the saved object | | object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the saved object |
<a name="neo.fs.v2.object.PutSingleRequest"></a>
### Message PutSingleRequest
Object PUT Single request
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [PutSingleRequest.Body](#neo.fs.v2.object.PutSingleRequest.Body) | | Body of put single object 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. |
<a name="neo.fs.v2.object.PutSingleRequest.Body"></a>
### Message PutSingleRequest.Body
PUT Single request body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| object | [Object](#neo.fs.v2.object.Object) | | Prepared object with payload. |
| copies_number | [uint32](#uint32) | repeated | Number of copies of the object to store within the RPC call. By default, object is processed according to the container's placement policy. Every number is treated as a minimal number of nodes in a corresponding placement vector that must store an object to complete the request successfully. The length MUST equal the placement vectors number, otherwise request is considered malformed. |
<a name="neo.fs.v2.object.PutSingleResponse"></a>
### Message PutSingleResponse
Object PUT Single response
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [PutSingleResponse.Body](#neo.fs.v2.object.PutSingleResponse.Body) | | Body of put single object 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. |
<a name="neo.fs.v2.object.PutSingleResponse.Body"></a>
### Message PutSingleResponse.Body
PUT Single Object response body
<a name="neo.fs.v2.object.Range"></a> <a name="neo.fs.v2.object.Range"></a>
### Message Range ### Message Range
@ -726,11 +841,11 @@ Object Search request body
<a name="neo.fs.v2.object.SearchRequest.Body.Filter"></a> <a name="neo.fs.v2.object.SearchRequest.Body.Filter"></a>
### Message SearchRequest.Body.Filter ### Message SearchRequest.Body.Filter
Filter structure checks if the object header field or the attribute content Filter structure checks if the object header field or the attribute
matches a value. content matches a value.
If no filters are set, search request will return all objects of the If no filters are set, search request will return all objects of the
container, including Regular object, Tombstones and Storage Group container, including Regular object and Tombstone
objects. Most human users expect to get only object they can directly objects. Most human users expect to get only object they can directly
work with. In that case, `$Object:ROOT` filter should be used. work with. In that case, `$Object:ROOT` filter should be used.
@ -765,11 +880,11 @@ There are some well-known filter aliases to match objects by certain
properties: properties:
* $Object:ROOT \ * $Object:ROOT \
Returns only `REGULAR` type objects that are not split or that are the top Returns only `REGULAR` type objects that are not split or that are the
level root objects in a split hierarchy. This includes objects not top level root objects in a split hierarchy. This includes objects not
present physically, like large objects split into smaller objects present physically, like large objects split into smaller objects
without a separate top-level root object. Objects of other types like without a separate top-level root object. Objects of other types like
StorageGroups and Tombstones will not be shown. This filter may be Locks and Tombstones will not be shown. This filter may be
useful for listing objects like `ls` command of some virtual file useful for listing objects like `ls` command of some virtual file
system. This filter is activated if the `key` exists, disregarding the system. This filter is activated if the `key` exists, disregarding the
value and matcher type. value and matcher type.
@ -778,8 +893,8 @@ properties:
activated if the `key` exists, disregarding the value and matcher type. activated if the `key` exists, disregarding the value and matcher type.
Note: using filters with a key with prefix `$Object:` and match type Note: using filters with a key with prefix `$Object:` and match type
`NOT_PRESENT `is not recommended since this is not a cross-version approach. `NOT_PRESENT `is not recommended since this is not a cross-version
Behavior when processing this kind of filters is undefined. approach. Behavior when processing this kind of filters is undefined.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -827,6 +942,30 @@ Object Search response body
<!-- end services --> <!-- end services -->
<a name="neo.fs.v2.object.ECInfo"></a>
### Message ECInfo
Meta information for the erasure-encoded object.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| chunks | [ECInfo.Chunk](#neo.fs.v2.object.ECInfo.Chunk) | repeated | Chunk stored on the node. |
<a name="neo.fs.v2.object.ECInfo.Chunk"></a>
### Message ECInfo.Chunk
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Object ID of the chunk. |
| index | [uint32](#uint32) | | Index of the chunk. |
| total | [uint32](#uint32) | | Total number of chunks in this split. |
<a name="neo.fs.v2.object.Header"></a> <a name="neo.fs.v2.object.Header"></a>
### Message Header ### Message Header
@ -846,6 +985,7 @@ Object Header
| 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. | | 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 | | 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 |
| ec | [Header.EC](#neo.fs.v2.object.Header.EC) | | Erasure code chunk information. |
<a name="neo.fs.v2.object.Header.Attribute"></a> <a name="neo.fs.v2.object.Header.Attribute"></a>
@ -858,15 +998,16 @@ Key name must be an object-unique valid UTF-8 string. Value can't be empty.
Objects with duplicated attribute names or attributes with empty values Objects with duplicated attribute names or attributes with empty values
will be considered invalid. will be considered invalid.
There are some "well-known" attributes starting with `__SYSTEM__` (`__NEOFS__` is deprecated) prefix There are some "well-known" attributes starting with `__SYSTEM__`
that affect system behaviour: (`__NEOFS__` is deprecated) prefix that affect system behaviour:
* [ __SYSTEM__UPLOAD_ID ] \ * [ __SYSTEM__UPLOAD_ID ] \
(`__NEOFS__UPLOAD_ID` is deprecated) \ (`__NEOFS__UPLOAD_ID` is deprecated) \
Marks smaller parts of a split bigger object Marks smaller parts of a split bigger object
* [ __SYSTEM__EXPIRATION_EPOCH ] \ * [ __SYSTEM__EXPIRATION_EPOCH ] \
(`__NEOFS__EXPIRATION_EPOCH` is deprecated) \ (`__NEOFS__EXPIRATION_EPOCH` is deprecated) \
Tells GC to delete object after that epoch The epoch after which object with no LOCKs on it becomes unavailable.
Locked object continues to be available until each of the LOCKs expire.
* [ __SYSTEM__TICK_EPOCH ] \ * [ __SYSTEM__TICK_EPOCH ] \
(`__NEOFS__TICK_EPOCH` is deprecated) \ (`__NEOFS__TICK_EPOCH` is deprecated) \
Decimal number that defines what epoch must produce Decimal number that defines what epoch must produce
@ -905,6 +1046,23 @@ corresponding section in NeoFS Technical Specification.
| value | [string](#string) | | string value of the object attribute | | value | [string](#string) | | string value of the object attribute |
<a name="neo.fs.v2.object.Header.EC"></a>
### Message Header.EC
Erasure code can be applied to any object.
Information about encoded object structure is stored in `EC` header.
All objects belonging to a single EC group have the same `parent` field.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| parent | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the origin object. Known to all chunks. |
| index | [uint32](#uint32) | | Index of this chunk. |
| total | [uint32](#uint32) | | Total number of chunks in this split. |
| header_length | [uint32](#uint32) | | Total length of a parent header. Used to trim padding zeroes. |
| header | [bytes](#bytes) | | Chunk of a parent header. |
<a name="neo.fs.v2.object.Header.Split"></a> <a name="neo.fs.v2.object.Header.Split"></a>
### Message Header.Split ### Message Header.Split
@ -928,8 +1086,8 @@ must be within the same container.
### Message Object ### Message Object
Object structure. Object is immutable and content-addressed. It means Object structure. Object is immutable and content-addressed. It means
`ObjectID` will change if the header or the payload changes. It's calculated as a `ObjectID` will change if the header or the payload changes. It's calculated
hash of header field which contains hash of the object's payload. as a hash of header field which contains hash of the object's payload.
For non-regular object types payload format depends on object type specified For non-regular object types payload format depends on object type specified
in the header. in the header.
@ -965,8 +1123,8 @@ Short header fields
### Message SplitInfo ### Message SplitInfo
Meta information of split hierarchy for object assembly. With the last part Meta information of split hierarchy for object assembly. With the last part
one can traverse linked list of split hierarchy back to the first part and one can traverse linked list of split hierarchy back to the first part and
assemble the original object. With a linking object one can assemble an object assemble the original object. With a linking object one can assemble an
right from the object parts. object right from the object parts.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -997,20 +1155,18 @@ Type of match expression
### ObjectType ### ObjectType
Type of the object payload content. Only `REGULAR` type objects can be split, Type of the object payload content. Only `REGULAR` type objects can be split,
hence `TOMBSTONE`, `STORAGE_GROUP` and `LOCK` payload is limited by the maximum hence `TOMBSTONE` and `LOCK` payload is limited by the
object size. maximum object size.
String presentation of object type is the same as definition: String presentation of object type is the same as definition:
* REGULAR * REGULAR
* TOMBSTONE * TOMBSTONE
* STORAGE_GROUP
* LOCK * LOCK
| Name | Number | Description | | Name | Number | Description |
| ---- | ------ | ----------- | | ---- | ------ | ----------- |
| REGULAR | 0 | Just a normal object | | REGULAR | 0 | Just a normal object |
| TOMBSTONE | 1 | Used internally to identify deleted objects | | TOMBSTONE | 1 | Used internally to identify deleted objects |
| STORAGE_GROUP | 2 | StorageGroup information |
| LOCK | 3 | Object lock | | LOCK | 3 | Object lock |

38
proto-docs/refs.md
View file

@ -3,20 +3,20 @@
## Table of Contents ## Table of Contents
- [Protocol Documentation](#protocol-documentation) - [refs/types.proto](#refs/types.proto)
- [Table of Contents](#table-of-contents)
- [refs/types.proto](#refstypesproto) - Messages
- [Message Address](#message-address) - [Address](#neo.fs.v2.refs.Address)
- [Message Checksum](#message-checksum) - [Checksum](#neo.fs.v2.refs.Checksum)
- [Message ContainerID](#message-containerid) - [ContainerID](#neo.fs.v2.refs.ContainerID)
- [Message ObjectID](#message-objectid) - [ObjectID](#neo.fs.v2.refs.ObjectID)
- [Message OwnerID](#message-ownerid) - [OwnerID](#neo.fs.v2.refs.OwnerID)
- [Message Signature](#message-signature) - [Signature](#neo.fs.v2.refs.Signature)
- [Message SignatureRFC6979](#message-signaturerfc6979) - [SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979)
- [Message Version](#message-version) - [Version](#neo.fs.v2.refs.Version)
- [ChecksumType](#checksumtype)
- [SignatureScheme](#signaturescheme)
- [Scalar Value Types](#scalar-value-types) - [Scalar Value Types](#scalar-value-types)
@ -95,8 +95,8 @@ It means `ObjectID` will change if the `header` or the `payload` changes.
`ObjectID` is a 32 byte long `ObjectID` is a 32 byte long
[SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of
the object's `header` field, which, in it's turn, contains the hash of the object's the object's `header` field, which, in it's turn, contains the hash of the
payload. object's payload.
String presentation is a String presentation is a
[base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string.
@ -169,7 +169,8 @@ RFC 6979 signature.
API version used by a node. API version used by a node.
String presentation is a Semantic Versioning 2.0.0 compatible version string String presentation is a Semantic Versioning 2.0.0 compatible version string
with 'v' prefix. i.e. `vX.Y`, where `X` is the major number, `Y` is the minor number. with 'v' prefix. i.e. `vX.Y`, where `X` is the major number, `Y` is the minor
number.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -196,7 +197,8 @@ Checksum algorithm type.
<a name="neo.fs.v2.refs.SignatureScheme"></a> <a name="neo.fs.v2.refs.SignatureScheme"></a>
### SignatureScheme ### SignatureScheme
Signature scheme describes digital signing scheme used for (key, signature) pair. Signature scheme describes digital signing scheme used for (key, signature)
pair.
| Name | Number | Description | | Name | Number | Description |
| ---- | ------ | ----------- | | ---- | ------ | ----------- |

18
proto-docs/session.md
View file

@ -278,15 +278,15 @@ Lifetime parameters of the token. Field names taken from rfc7519.
<a name="neo.fs.v2.session.XHeader"></a> <a name="neo.fs.v2.session.XHeader"></a>
### Message XHeader ### Message XHeader
Extended headers for Request/Response. They may contain any user-defined headers Extended headers for Request/Response. They may contain any user-defined
to be interpreted on application level. headers to be interpreted on application level.
Key name must be a unique valid UTF-8 string. Value can't be empty. Requests or Key name must be a unique valid UTF-8 string. Value can't be empty. Requests
Responses with duplicated header names or headers with empty values will be or Responses with duplicated header names or headers with empty values will
considered invalid. be considered invalid.
There are some "well-known" headers starting with `__SYSTEM__` (`__NEOFS__` is deprecated) prefix that There are some "well-known" headers starting with `__SYSTEM__` (`__NEOFS__`
affect system behaviour: is deprecated) prefix that affect system behaviour:
* [ __SYSTEM__NETMAP_EPOCH ] \ * [ __SYSTEM__NETMAP_EPOCH ] \
(`__NEOFS__NETMAP_EPOCH` is deprecated) \ (`__NEOFS__NETMAP_EPOCH` is deprecated) \
@ -297,8 +297,8 @@ affect system behaviour:
(`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \ (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
If object can't be found using current epoch's netmap, this header limits If object can't be found using current epoch's netmap, this header limits
how many past epochs the node can look up through. The `value` is string how many past epochs the node can look up through. The `value` is string
encoded `uint64` in decimal presentation. If set to '0' or not set, only the encoded `uint64` in decimal presentation. If set to '0' or not set, only
current epoch will be used. the current epoch will be used.
| Field | Type | Label | Description | | Field | Type | Label | Description |

1
proto-docs/status.md
View file

@ -102,6 +102,7 @@ Section of statuses for container-related operations.
| ---- | ------ | ----------- | | ---- | ------ | ----------- |
| CONTAINER_NOT_FOUND | 0 | [**3072**] Container not found. | | CONTAINER_NOT_FOUND | 0 | [**3072**] Container not found. |
| EACL_NOT_FOUND | 1 | [**3073**] eACL table not found. | | EACL_NOT_FOUND | 1 | [**3073**] eACL table not found. |
| CONTAINER_ACCESS_DENIED | 2 | [**3074**] Container access denied. |

3
status/types.proto
View file

@ -133,6 +133,9 @@ enum Container {
// [**3073**] eACL table not found. // [**3073**] eACL table not found.
EACL_NOT_FOUND = 1; EACL_NOT_FOUND = 1;
// [**3074**] Container access denied.
CONTAINER_ACCESS_DENIED = 2;
} }
// Section of statuses for session-related operations. // Section of statuses for session-related operations.