Skip to content

Latest commit

 

History

History
663 lines (450 loc) · 31.4 KB

container.md

File metadata and controls

663 lines (450 loc) · 31.4 KB
Raw

Protocol Documentation

Table of Contents

Top

container/service.proto

Service "neo.fs.v2.container.ContainerService"

ContainerService provides API to interact with Container smart contract in FS chain via other NeoFS nodes. All of those actions can be done equivalently by directly issuing transactions and RPC calls to FS chain nodes.

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);

Method Put

Put invokes Container smart contract's Put method and returns response immediately. After a new block is issued in FS chain, request is verified by Inner Ring nodes. After one more block in FS chain, the container is added into smart contract storage.

Statuses:

  • OK (0, SECTION_SUCCESS):
    request to save the container has been sent to FS chain;
  • Common failures (SECTION_FAILURE_COMMON).
Name Input Output
Put PutRequest PutResponse

Method Delete

Delete invokes Container smart contract's Delete method and returns response immediately. After a new block is issued in FS chain, request is verified by Inner Ring nodes. After one more block in FS chain, the container is added into smart contract storage. NOTE: a container deletion leads to the removal of every object in that container, regardless of any restrictions on the object removal (e.g. lock/locked object would be also removed).

Statuses:

  • OK (0, SECTION_SUCCESS):
    request to remove the container has been sent to FS chain;
  • Common failures (SECTION_FAILURE_COMMON).
Name Input Output
Delete DeleteRequest DeleteResponse

Method Get

Returns container structure from Container smart contract storage.

Statuses:

  • OK (0, SECTION_SUCCESS):
    container has been successfully read;
  • Common failures (SECTION_FAILURE_COMMON);
  • CONTAINER_NOT_FOUND (3072, SECTION_CONTAINER):
    requested container not found.
Name Input Output
Get GetRequest GetResponse

Method List

Returns all owner's containers from 'Container` smart contract' storage.

Statuses:

  • OK (0, SECTION_SUCCESS):
    container list has been successfully read;
  • Common failures (SECTION_FAILURE_COMMON).
Name Input Output
List ListRequest ListResponse

Method SetExtendedACL

Invokes 'SetEACL' method of 'Container` smart contract and returns response immediately. After one more block in FS chain, 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 FS chain;
  • Common failures (SECTION_FAILURE_COMMON).
Name Input Output
SetExtendedACL SetExtendedACLRequest 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.
Name Input Output
GetExtendedACL GetExtendedACLRequest 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 AnnounceUsedSpaceResponse

Message AnnounceUsedSpaceRequest

Announce container used space

Field Type Label Description
body AnnounceUsedSpaceRequest.Body Body of announce used space request message.
meta_header 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 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 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 Epoch number for which the container size estimation was produced.
container_id neo.fs.v2.refs.ContainerID Identifier of the container.
used_space 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 Body of announce used space response message.
meta_header 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 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

Container removal request

Field Type Label Description
body DeleteRequest.Body Body of container delete request message.
meta_header 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 Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message DeleteRequest.Body

Container removal request body has signed ContainerID as a proof of the container owner's intent. The signature will be verified by Container smart contract, so signing algorithm must be supported by NeoVM.

Field Type Label Description
container_id neo.fs.v2.refs.ContainerID Identifier of the container to delete from NeoFS
signature neo.fs.v2.refs.SignatureRFC6979 ContainerID signed with the container owner's key according to RFC-6979.

Message DeleteResponse

DeleteResponse has an empty body because delete operation is asynchronous and done via consensus in Inner Ring nodes.

Field Type Label Description
body DeleteResponse.Body Body of container delete response message.
meta_header 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 Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message DeleteResponse.Body

DeleteResponse has an empty body because delete operation is asynchronous and done via consensus in Inner Ring nodes.

Message GetExtendedACLRequest

Get Extended ACL

Field Type Label Description
body GetExtendedACLRequest.Body Body of get extended acl request message.
meta_header 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 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 Identifier of the container having Extended ACL

Message GetExtendedACLResponse

Get Extended ACL

Field Type Label Description
body GetExtendedACLResponse.Body Body of get extended acl response message.
meta_header 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 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 Extended ACL requested, if available
signature neo.fs.v2.refs.SignatureRFC6979 Signature of stable-marshalled Extended ACL according to RFC-6979.
session_token neo.fs.v2.session.SessionToken Session token if Extended ACL was set within a session

Message GetRequest

Get container structure

Field Type Label Description
body GetRequest.Body Body of container get request message.
meta_header 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 Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message GetRequest.Body

Get container structure request body.

Field Type Label Description
container_id neo.fs.v2.refs.ContainerID Identifier of the container to get

Message GetResponse

Get container structure

Field Type Label Description
body GetResponse.Body Body of container get response message.
meta_header 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 Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message GetResponse.Body

Get container response body does not have container structure signature. It has been already verified upon container creation.

Field Type Label Description
container Container Requested container structure
signature neo.fs.v2.refs.SignatureRFC6979 Signature of a stable-marshalled container according to RFC-6979.
session_token neo.fs.v2.session.SessionToken Session token if the container has been created within the session

Message ListRequest

List containers

Field Type Label Description
body ListRequest.Body Body of list containers request message
meta_header 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 Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message ListRequest.Body

List containers request body.

Field Type Label Description
owner_id neo.fs.v2.refs.OwnerID Identifier of the container owner

Message ListResponse

List containers

Field Type Label Description
body ListResponse.Body Body of list containers response message.
meta_header 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 Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message ListResponse.Body

List containers response body.

Field Type Label Description
container_ids neo.fs.v2.refs.ContainerID repeated List of ContainerIDs belonging to the requested OwnerID

Message PutRequest

New NeoFS Container creation request

Field Type Label Description
body PutRequest.Body Body of container put request message.
meta_header 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 Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message PutRequest.Body

Container creation request has container structure's signature as a separate field. It's not stored in FS chain, just verified on container creation by Container smart contract. ContainerID is a SHA256 hash of the stable-marshalled container strucutre, hence there is no need for additional signature checks.

Field Type Label Description
container Container Container structure to register in NeoFS
signature neo.fs.v2.refs.SignatureRFC6979 Signature of a stable-marshalled container according to RFC-6979.

Message PutResponse

New NeoFS Container creation response

Field Type Label Description
body PutResponse.Body Body of container put response message.
meta_header 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 Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message PutResponse.Body

Container put response body contains information about the newly registered container as seen by Container smart contract. ContainerID can be calculated beforehand from the container structure and compared to the one returned here to make sure everything has been done as expected.

Field Type Label Description
container_id neo.fs.v2.refs.ContainerID Unique identifier of the newly created container

Message SetExtendedACLRequest

Set Extended ACL

Field Type Label Description
body SetExtendedACLRequest.Body Body of set extended acl request message.
meta_header 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 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 Extended ACL table to set for the container
signature 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 Body of set extended acl response message.
meta_header 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 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 FS chain.

Top

container/types.proto

Message Container

Container is a structure that defines object placement behaviour. Objects can be stored only within containers. They define placement rule, attributes and access control information. An ID of a container is a 32 byte long SHA256 hash of stable-marshalled container message.

Field Type Label Description
version neo.fs.v2.refs.Version Container format version. Effectively, the version of API library used to create the container.
owner_id neo.fs.v2.refs.OwnerID Identifier of the container owner
nonce bytes Nonce is a 16 byte UUIDv4, used to avoid collisions of ContainerIDs
basic_acl uint32 BasicACL contains access control rules for the owner, system and others groups, as well as permission bits for BearerToken and Extended ACL
attributes Container.Attribute repeated Attributes represent immutable container's meta data
placement_policy neo.fs.v2.netmap.PlacementPolicy Placement policy for the object inside the container

Message Container.Attribute

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 creation and can never be added or updated.

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 values will be considered invalid.

There are some "well-known" attributes affecting system behaviour:

  • __NEOFS__SUBNET
    DEPRECATED. Was used for a string ID of a container's storage subnet. Currently doesn't affect anything.
  • __NEOFS__NAME
    String of a human-friendly container name registered as a domain in NNS contract.
  • __NEOFS__ZONE
    String of a zone for __NEOFS__NAME. Used as a TLD of a domain name in NNS contract. If no zone is specified, use default zone: container.
  • __NEOFS__DISABLE_HOMOMORPHIC_HASHING
    Disables homomorphic hashing for the container if the value equals "true" string. Any other values are interpreted as missing attribute. Container could be accepted in a NeoFS network only if the global network hashing configuration value corresponds with that attribute's value. After container inclusion, network setting is ignored.
  • __NEOFS__METAINFO_CONSISTENCY
    Policy rule that defines the condition under which an object is considered processed. Acceptable values and meanings:
    1. "strict": SN processes objects' meta information, it is validated, indexed and signed accordingly by a required minimal number of nodes that are included in the container, a corresponding object inclusion notification can be caught
    2. "optimistic": the same as "strict" but a successful PUT operation does not mean objects' meta information has been multi signed and indexed correctly, however, SNs will try to do it asynchronously; in general PUT operations are expected to be faster than in the "strict" case
    3. : SN does not process objects' meta information, it is not indexed and object presence/number of copies is not proven after a successful object PUT operation; the behavior is the same as it was before this attribute introduction

And some well-known attributes used by applications only:

  • Name
    Human-friendly name
  • Timestamp
    User-defined local time of container creation in Unix Timestamp format
Field Type Label Description
key string Attribute name key
value string Attribute value

Scalar Value Types

.proto Type Notes C++ Type Java Type Python Type
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
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
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str