forked from TrueCloudLab/frostfs-api
fd316479e2
* Replace `parentSplitIndex` by `parentSplitParentID` as the first one is inappropriate; * Regenerate docs. Signed-off-by: Airat Arifullin <aarifullin@yadro.com>
1201 lines
53 KiB
Markdown
1201 lines
53 KiB
Markdown
# Protocol Documentation
|
|
<a name="top"></a>
|
|
|
|
## Table of Contents
|
|
|
|
- [object/service.proto](#object/service.proto)
|
|
- Services
|
|
- [ObjectService](#neo.fs.v2.object.ObjectService)
|
|
|
|
- Messages
|
|
- [DeleteRequest](#neo.fs.v2.object.DeleteRequest)
|
|
- [DeleteRequest.Body](#neo.fs.v2.object.DeleteRequest.Body)
|
|
- [DeleteResponse](#neo.fs.v2.object.DeleteResponse)
|
|
- [DeleteResponse.Body](#neo.fs.v2.object.DeleteResponse.Body)
|
|
- [GetRangeHashRequest](#neo.fs.v2.object.GetRangeHashRequest)
|
|
- [GetRangeHashRequest.Body](#neo.fs.v2.object.GetRangeHashRequest.Body)
|
|
- [GetRangeHashResponse](#neo.fs.v2.object.GetRangeHashResponse)
|
|
- [GetRangeHashResponse.Body](#neo.fs.v2.object.GetRangeHashResponse.Body)
|
|
- [GetRangeRequest](#neo.fs.v2.object.GetRangeRequest)
|
|
- [GetRangeRequest.Body](#neo.fs.v2.object.GetRangeRequest.Body)
|
|
- [GetRangeResponse](#neo.fs.v2.object.GetRangeResponse)
|
|
- [GetRangeResponse.Body](#neo.fs.v2.object.GetRangeResponse.Body)
|
|
- [GetRequest](#neo.fs.v2.object.GetRequest)
|
|
- [GetRequest.Body](#neo.fs.v2.object.GetRequest.Body)
|
|
- [GetResponse](#neo.fs.v2.object.GetResponse)
|
|
- [GetResponse.Body](#neo.fs.v2.object.GetResponse.Body)
|
|
- [GetResponse.Body.Init](#neo.fs.v2.object.GetResponse.Body.Init)
|
|
- [HeadRequest](#neo.fs.v2.object.HeadRequest)
|
|
- [HeadRequest.Body](#neo.fs.v2.object.HeadRequest.Body)
|
|
- [HeadResponse](#neo.fs.v2.object.HeadResponse)
|
|
- [HeadResponse.Body](#neo.fs.v2.object.HeadResponse.Body)
|
|
- [HeaderWithSignature](#neo.fs.v2.object.HeaderWithSignature)
|
|
- [PutRequest](#neo.fs.v2.object.PutRequest)
|
|
- [PutRequest.Body](#neo.fs.v2.object.PutRequest.Body)
|
|
- [PutRequest.Body.Init](#neo.fs.v2.object.PutRequest.Body.Init)
|
|
- [PutResponse](#neo.fs.v2.object.PutResponse)
|
|
- [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)
|
|
- [SearchRequest](#neo.fs.v2.object.SearchRequest)
|
|
- [SearchRequest.Body](#neo.fs.v2.object.SearchRequest.Body)
|
|
- [SearchRequest.Body.Filter](#neo.fs.v2.object.SearchRequest.Body.Filter)
|
|
- [SearchResponse](#neo.fs.v2.object.SearchResponse)
|
|
- [SearchResponse.Body](#neo.fs.v2.object.SearchResponse.Body)
|
|
|
|
|
|
- [object/types.proto](#object/types.proto)
|
|
|
|
- Messages
|
|
- [ECInfo](#neo.fs.v2.object.ECInfo)
|
|
- [ECInfo.Chunk](#neo.fs.v2.object.ECInfo.Chunk)
|
|
- [Header](#neo.fs.v2.object.Header)
|
|
- [Header.Attribute](#neo.fs.v2.object.Header.Attribute)
|
|
- [Header.EC](#neo.fs.v2.object.Header.EC)
|
|
- [Header.Split](#neo.fs.v2.object.Header.Split)
|
|
- [Object](#neo.fs.v2.object.Object)
|
|
- [ShortHeader](#neo.fs.v2.object.ShortHeader)
|
|
- [SplitInfo](#neo.fs.v2.object.SplitInfo)
|
|
|
|
|
|
- [Scalar Value Types](#scalar-value-types)
|
|
|
|
|
|
|
|
<a name="object/service.proto"></a>
|
|
<p align="right"><a href="#top">Top</a></p>
|
|
|
|
## object/service.proto
|
|
|
|
|
|
|
|
|
|
<a name="neo.fs.v2.object.ObjectService"></a>
|
|
|
|
### Service "neo.fs.v2.object.ObjectService"
|
|
`ObjectService` provides API for manipulating objects. Object operations do
|
|
not affect the sidechain and are only served by nodes in p2p style.
|
|
|
|
```
|
|
rpc Get(GetRequest) returns (stream GetResponse);
|
|
rpc Put(stream PutRequest) returns (PutResponse);
|
|
rpc Delete(DeleteRequest) returns (DeleteResponse);
|
|
rpc Head(HeadRequest) returns (HeadResponse);
|
|
rpc Search(SearchRequest) returns (stream SearchResponse);
|
|
rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse);
|
|
rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
|
|
rpc PutSingle(PutSingleRequest) returns (PutSingleResponse);
|
|
|
|
```
|
|
|
|
#### Method Get
|
|
|
|
Receive full object structure, including Headers and payload. Response uses
|
|
gRPC stream. First response message carries the object with the requested
|
|
address. Chunk messages are parts of the object's payload if it is needed.
|
|
All messages, except the first one, carry payload chunks. The requested
|
|
object can be restored by concatenation of object message payload and all
|
|
chunks keeping the receiving order.
|
|
|
|
Extended headers can change `Get` behaviour:
|
|
* [ __SYSTEM__NETMAP_EPOCH ] \
|
|
(`__NEOFS__NETMAP_EPOCH` is deprecated) \
|
|
Will use the requsted version of Network Map for object placement
|
|
calculation.
|
|
* [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \
|
|
(`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
|
|
Will try older versions (starting from `__SYSTEM__NETMAP_EPOCH`
|
|
(`__NEOFS__NETMAP_EPOCH` is deprecated) if specified or the latest one
|
|
otherwise) of Network Map to find an object until the depth limit is
|
|
reached.
|
|
|
|
Please refer to detailed `XHeader` description.
|
|
|
|
Statuses:
|
|
- **OK** (0, SECTION_SUCCESS): \
|
|
object has been successfully read;
|
|
- Common failures (SECTION_FAILURE_COMMON);
|
|
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
|
|
read access to the object is denied;
|
|
- **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
|
|
object not found in container;
|
|
- **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \
|
|
the requested object has been marked as deleted;
|
|
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
|
|
object container not found;
|
|
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
|
|
access to container is denied;
|
|
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
|
|
provided session token has expired.
|
|
|
|
| Name | Input | Output |
|
|
| ---- | ----- | ------ |
|
|
| Get | [GetRequest](#neo.fs.v2.object.GetRequest) | [GetResponse](#neo.fs.v2.object.GetResponse) |
|
|
#### Method Put
|
|
|
|
Put the object into container. Request uses gRPC stream. First message
|
|
SHOULD be of PutHeader type. `ContainerID` and `OwnerID` of an object
|
|
SHOULD be set. Session token SHOULD be obtained before `PUT` operation (see
|
|
session package). Chunk messages are considered by server as a part of an
|
|
object payload. All messages, except first one, SHOULD be payload chunks.
|
|
Chunk messages SHOULD be sent in the direct order of fragmentation.
|
|
|
|
Extended headers can change `Put` behaviour:
|
|
* [ __SYSTEM__NETMAP_EPOCH \
|
|
(`__NEOFS__NETMAP_EPOCH` is deprecated) \
|
|
Will use the requsted 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 |
|
|
| ---- | ----- | ------ |
|
|
| Put | [PutRequest](#neo.fs.v2.object.PutRequest) | [PutResponse](#neo.fs.v2.object.PutResponse) |
|
|
#### Method Delete
|
|
|
|
Delete the object from a container. There is no immediate removal
|
|
guarantee. Object will be marked for removal and deleted eventually.
|
|
|
|
Extended headers can change `Delete` 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 marked to be removed from the container;
|
|
- Common failures (SECTION_FAILURE_COMMON);
|
|
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
|
|
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): \
|
|
deleting a locked object is prohibited;
|
|
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
|
|
object container not found;
|
|
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
|
|
access to container is denied;
|
|
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
|
|
provided session token has expired.
|
|
|
|
| Name | Input | Output |
|
|
| ---- | ----- | ------ |
|
|
| Delete | [DeleteRequest](#neo.fs.v2.object.DeleteRequest) | [DeleteResponse](#neo.fs.v2.object.DeleteResponse) |
|
|
#### Method Head
|
|
|
|
Returns the object Headers without data payload. By default full header is
|
|
returned. If `main_only` request field is set, the short header with only
|
|
the very minimal information will be returned instead.
|
|
|
|
Extended headers can change `Head` 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 header has been successfully read;
|
|
- Common failures (SECTION_FAILURE_COMMON);
|
|
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
|
|
access to operation HEAD of the object is denied;
|
|
- **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
|
|
object not found in container;
|
|
- **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \
|
|
the requested object has been marked as deleted;
|
|
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
|
|
object container not found;
|
|
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
|
|
access to container is denied;
|
|
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
|
|
provided session token has expired.
|
|
|
|
| Name | Input | Output |
|
|
| ---- | ----- | ------ |
|
|
| Head | [HeadRequest](#neo.fs.v2.object.HeadRequest) | [HeadResponse](#neo.fs.v2.object.HeadResponse) |
|
|
#### Method Search
|
|
|
|
Search objects in container. Search query allows to match by Object
|
|
Header's filed values. Please see the corresponding NeoFS Technical
|
|
Specification section for more details.
|
|
|
|
Extended headers can change `Search` 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): \
|
|
objects have been successfully selected;
|
|
- Common failures (SECTION_FAILURE_COMMON);
|
|
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
|
|
access to operation SEARCH of the object is denied;
|
|
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
|
|
search container not found;
|
|
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
|
|
access to container is denied;
|
|
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
|
|
provided session token has expired.
|
|
|
|
| Name | Input | Output |
|
|
| ---- | ----- | ------ |
|
|
| Search | [SearchRequest](#neo.fs.v2.object.SearchRequest) | [SearchResponse](#neo.fs.v2.object.SearchResponse) |
|
|
#### Method GetRange
|
|
|
|
Get byte range of data payload. Range is set as an (offset, length) tuple.
|
|
Like in `Get` method, the response uses gRPC stream. Requested range can be
|
|
restored by concatenation of all received payload chunks keeping the
|
|
receiving order.
|
|
|
|
Extended headers can change `GetRange` behaviour:
|
|
* [ __SYSTEM__NETMAP_EPOCH ] \
|
|
(`__NEOFS__NETMAP_EPOCH` is deprecated) \
|
|
Will use the requested version of Network Map for object placement
|
|
calculation.
|
|
* [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \
|
|
(`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
|
|
Will try older versions of Network Map to find an object until the depth
|
|
limit is reached.
|
|
|
|
Please refer to detailed `XHeader` description.
|
|
|
|
Statuses:
|
|
- **OK** (0, SECTION_SUCCESS): \
|
|
data range of the object payload has been successfully read;
|
|
- Common failures (SECTION_FAILURE_COMMON);
|
|
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
|
|
access to operation RANGE of the object is denied;
|
|
- **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
|
|
object not found in container;
|
|
- **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \
|
|
the requested object has been marked as deleted.
|
|
- **OUT_OF_RANGE** (2053, SECTION_OBJECT): \
|
|
the requested range is out of bounds;
|
|
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
|
|
object container not found;
|
|
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
|
|
access to container is denied;
|
|
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
|
|
provided session token has expired.
|
|
|
|
| Name | Input | Output |
|
|
| ---- | ----- | ------ |
|
|
| GetRange | [GetRangeRequest](#neo.fs.v2.object.GetRangeRequest) | [GetRangeResponse](#neo.fs.v2.object.GetRangeResponse) |
|
|
#### Method GetRangeHash
|
|
|
|
Returns homomorphic or regular hash of object's payload range after
|
|
applying XOR operation with the provided `salt`. Ranges are set of (offset,
|
|
length) tuples. Hashes order in response corresponds to the ranges order in
|
|
the request. Note that hash is calculated for XORed data.
|
|
|
|
Extended headers can change `GetRangeHash` behaviour:
|
|
* [ __SYSTEM__NETMAP_EPOCH ] \
|
|
(`__NEOFS__NETMAP_EPOCH` is deprecated) \
|
|
Will use the requested version of Network Map for object placement
|
|
calculation.
|
|
* [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \
|
|
(`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
|
|
Will try older versions of Network Map to find an object until the depth
|
|
limit is reached.
|
|
|
|
Please refer to detailed `XHeader` description.
|
|
|
|
Statuses:
|
|
- **OK** (0, SECTION_SUCCESS): \
|
|
data range of the object payload has been successfully hashed;
|
|
- Common failures (SECTION_FAILURE_COMMON);
|
|
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
|
|
access to operation RANGEHASH of the object is denied;
|
|
- **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
|
|
object not found in container;
|
|
- **OUT_OF_RANGE** (2053, SECTION_OBJECT): \
|
|
the requested range is out of bounds;
|
|
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
|
|
object container not found;
|
|
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
|
|
access to container is denied;
|
|
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
|
|
provided session token has expired.
|
|
|
|
| Name | Input | Output |
|
|
| ---- | ----- | ------ |
|
|
| 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 -->
|
|
|
|
|
|
<a name="neo.fs.v2.object.DeleteRequest"></a>
|
|
|
|
### Message DeleteRequest
|
|
Object DELETE request
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [DeleteRequest.Body](#neo.fs.v2.object.DeleteRequest.Body) | | Body of delete 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.DeleteRequest.Body"></a>
|
|
|
|
### Message DeleteRequest.Body
|
|
Object DELETE request body
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address of the object to be deleted |
|
|
|
|
|
|
<a name="neo.fs.v2.object.DeleteResponse"></a>
|
|
|
|
### Message DeleteResponse
|
|
DeleteResponse body is empty because we cannot guarantee permanent object
|
|
removal in distributed system.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [DeleteResponse.Body](#neo.fs.v2.object.DeleteResponse.Body) | | Body of delete 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.DeleteResponse.Body"></a>
|
|
|
|
### Message DeleteResponse.Body
|
|
Object DELETE Response has an empty body.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| tombstone | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address of the tombstone created for the deleted object |
|
|
|
|
|
|
<a name="neo.fs.v2.object.GetRangeHashRequest"></a>
|
|
|
|
### Message GetRangeHashRequest
|
|
Get hash of object's payload part
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [GetRangeHashRequest.Body](#neo.fs.v2.object.GetRangeHashRequest.Body) | | Body of get range hash 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.GetRangeHashRequest.Body"></a>
|
|
|
|
### Message GetRangeHashRequest.Body
|
|
Get hash of object's payload part request body.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address of the object that containing the requested payload range |
|
|
| ranges | [Range](#neo.fs.v2.object.Range) | repeated | List of object's payload ranges to calculate homomorphic hash |
|
|
| salt | [bytes](#bytes) | | Binary salt to XOR object's payload ranges before hash calculation |
|
|
| type | [neo.fs.v2.refs.ChecksumType](#neo.fs.v2.refs.ChecksumType) | | Checksum algorithm type |
|
|
|
|
|
|
<a name="neo.fs.v2.object.GetRangeHashResponse"></a>
|
|
|
|
### Message GetRangeHashResponse
|
|
Get hash of object's payload part
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [GetRangeHashResponse.Body](#neo.fs.v2.object.GetRangeHashResponse.Body) | | Body of get range hash 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.GetRangeHashResponse.Body"></a>
|
|
|
|
### Message GetRangeHashResponse.Body
|
|
Get hash of object's payload part response body.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| type | [neo.fs.v2.refs.ChecksumType](#neo.fs.v2.refs.ChecksumType) | | Checksum algorithm type |
|
|
| hash_list | [bytes](#bytes) | repeated | List of range hashes in a binary format |
|
|
|
|
|
|
<a name="neo.fs.v2.object.GetRangeRequest"></a>
|
|
|
|
### Message GetRangeRequest
|
|
Request part of object's payload
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [GetRangeRequest.Body](#neo.fs.v2.object.GetRangeRequest.Body) | | Body of get range 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.GetRangeRequest.Body"></a>
|
|
|
|
### Message GetRangeRequest.Body
|
|
Byte range of object's payload request body
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address of the object containing the requested payload range |
|
|
| range | [Range](#neo.fs.v2.object.Range) | | Requested payload range |
|
|
| raw | [bool](#bool) | | If `raw` flag is set, request will work only with objects that are physically stored on the peer node. |
|
|
|
|
|
|
<a name="neo.fs.v2.object.GetRangeResponse"></a>
|
|
|
|
### Message GetRangeResponse
|
|
Get part of object's payload
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [GetRangeResponse.Body](#neo.fs.v2.object.GetRangeResponse.Body) | | Body of get range 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.GetRangeResponse.Body"></a>
|
|
|
|
### Message GetRangeResponse.Body
|
|
Get Range response body uses streams to transfer the response. Because
|
|
object payload considered a byte sequence, there is no need to have some
|
|
initial preamble message. The requested byte range is sent as a series
|
|
chunks.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| chunk | [bytes](#bytes) | | Chunked object payload's range. |
|
|
| 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>
|
|
|
|
### Message GetRequest
|
|
GET object request
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [GetRequest.Body](#neo.fs.v2.object.GetRequest.Body) | | Body of get 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.GetRequest.Body"></a>
|
|
|
|
### Message GetRequest.Body
|
|
GET Object request body
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address of the requested object |
|
|
| raw | [bool](#bool) | | If `raw` flag is set, request will work only with objects that are physically stored on the peer node |
|
|
|
|
|
|
<a name="neo.fs.v2.object.GetResponse"></a>
|
|
|
|
### Message GetResponse
|
|
GET object response
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [GetResponse.Body](#neo.fs.v2.object.GetResponse.Body) | | Body of get 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.GetResponse.Body"></a>
|
|
|
|
### Message GetResponse.Body
|
|
GET Object Response body
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| init | [GetResponse.Body.Init](#neo.fs.v2.object.GetResponse.Body.Init) | | Initial part of the object stream |
|
|
| chunk | [bytes](#bytes) | | Chunked object payload |
|
|
| 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>
|
|
|
|
### Message GetResponse.Body.Init
|
|
Initial part of the `Object` structure stream. Technically it's a
|
|
set of all `Object` structure's fields except `payload`.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Object's unique identifier. |
|
|
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signed `ObjectID` |
|
|
| header | [Header](#neo.fs.v2.object.Header) | | Object metadata headers |
|
|
|
|
|
|
<a name="neo.fs.v2.object.HeadRequest"></a>
|
|
|
|
### Message HeadRequest
|
|
Object HEAD request
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [HeadRequest.Body](#neo.fs.v2.object.HeadRequest.Body) | | Body of head 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.HeadRequest.Body"></a>
|
|
|
|
### Message HeadRequest.Body
|
|
Object HEAD request body
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Address of the object with the requested Header |
|
|
| main_only | [bool](#bool) | | Return only minimal header subset |
|
|
| raw | [bool](#bool) | | If `raw` flag is set, request will work only with objects that are physically stored on the peer node |
|
|
|
|
|
|
<a name="neo.fs.v2.object.HeadResponse"></a>
|
|
|
|
### Message HeadResponse
|
|
Object HEAD response
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [HeadResponse.Body](#neo.fs.v2.object.HeadResponse.Body) | | Body of head 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.HeadResponse.Body"></a>
|
|
|
|
### Message HeadResponse.Body
|
|
Object HEAD response body
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| 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 |
|
|
| 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>
|
|
|
|
### Message HeaderWithSignature
|
|
Tuple of a full object header and signature of an `ObjectID`. \
|
|
Signed `ObjectID` is present to verify full header's authenticity through the
|
|
following steps:
|
|
|
|
1. Calculate `SHA-256` of the marshalled `Header` structure
|
|
2. Check if the resulting hash matches `ObjectID`
|
|
3. Check if `ObjectID` signature in `signature` field is correct
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| header | [Header](#neo.fs.v2.object.Header) | | Full object header |
|
|
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signed `ObjectID` to verify full header's authenticity |
|
|
|
|
|
|
<a name="neo.fs.v2.object.PutRequest"></a>
|
|
|
|
### Message PutRequest
|
|
PUT object request
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [PutRequest.Body](#neo.fs.v2.object.PutRequest.Body) | | Body of put 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.PutRequest.Body"></a>
|
|
|
|
### Message PutRequest.Body
|
|
PUT request body
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| init | [PutRequest.Body.Init](#neo.fs.v2.object.PutRequest.Body.Init) | | Initial part of the object stream |
|
|
| chunk | [bytes](#bytes) | | Chunked object payload |
|
|
|
|
|
|
<a name="neo.fs.v2.object.PutRequest.Body.Init"></a>
|
|
|
|
### Message PutRequest.Body.Init
|
|
Newly created object structure parameters. If some optional parameters
|
|
are not set, they will be calculated by a peer node.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | ObjectID if available. |
|
|
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Object signature if available |
|
|
| header | [Header](#neo.fs.v2.object.Header) | | Object's Header |
|
|
| copies_number | [uint32](#uint32) | 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. Can be one of: 1. A single number; applied to the whole request and is treated as a minimal number of nodes that must store an object to complete the request successfully. 2. An ordered array; 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.PutResponse"></a>
|
|
|
|
### Message PutResponse
|
|
PUT Object response
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [PutResponse.Body](#neo.fs.v2.object.PutResponse.Body) | | Body of put 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.PutResponse.Body"></a>
|
|
|
|
### Message PutResponse.Body
|
|
PUT Object response body
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| 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>
|
|
|
|
### Message Range
|
|
Object payload range.Ranges of zero length SHOULD be considered as invalid.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| offset | [uint64](#uint64) | | Offset of the range from the object payload start |
|
|
| length | [uint64](#uint64) | | Length in bytes of the object payload range |
|
|
|
|
|
|
<a name="neo.fs.v2.object.SearchRequest"></a>
|
|
|
|
### Message SearchRequest
|
|
Object Search request
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [SearchRequest.Body](#neo.fs.v2.object.SearchRequest.Body) | | Body of search 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.SearchRequest.Body"></a>
|
|
|
|
### Message SearchRequest.Body
|
|
Object Search request body
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Container identifier were to search |
|
|
| version | [uint32](#uint32) | | Version of the Query Language used |
|
|
| filters | [SearchRequest.Body.Filter](#neo.fs.v2.object.SearchRequest.Body.Filter) | repeated | List of search expressions |
|
|
|
|
|
|
<a name="neo.fs.v2.object.SearchRequest.Body.Filter"></a>
|
|
|
|
### Message SearchRequest.Body.Filter
|
|
Filter structure checks if the object header field or the attribute
|
|
content matches a value.
|
|
|
|
If no filters are set, search request will return all objects of the
|
|
container, including Regular object and Tombstone
|
|
objects. Most human users expect to get only object they can directly
|
|
work with. In that case, `$Object:ROOT` filter should be used.
|
|
|
|
By default `key` field refers to the corresponding object's `Attribute`.
|
|
Some Object's header fields can also be accessed by adding `$Object:`
|
|
prefix to the name. Here is the list of fields available via this prefix:
|
|
|
|
* $Object:version \
|
|
version
|
|
* $Object:objectID \
|
|
object_id
|
|
* $Object:containerID \
|
|
container_id
|
|
* $Object:ownerID \
|
|
owner_id
|
|
* $Object:creationEpoch \
|
|
creation_epoch
|
|
* $Object:payloadLength \
|
|
payload_length
|
|
* $Object:payloadHash \
|
|
payload_hash
|
|
* $Object:objectType \
|
|
object_type
|
|
* $Object:homomorphicHash \
|
|
homomorphic_hash
|
|
* $Object:split.parent \
|
|
object_id of parent
|
|
* $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.
|
|
|
|
There are some well-known filter aliases to match objects by certain
|
|
properties:
|
|
|
|
* $Object:ROOT \
|
|
Returns only `REGULAR` type objects that are not split or that are the
|
|
top level root objects in a split hierarchy. This includes objects not
|
|
present physically, like large objects split into smaller objects
|
|
without a separate top-level root object. Objects of other types like
|
|
Locks and Tombstones will not be shown. This filter may be
|
|
useful for listing objects like `ls` command of some virtual file
|
|
system. This filter is activated if the `key` exists, disregarding the
|
|
value and matcher type.
|
|
* $Object:PHY \
|
|
Returns only objects physically stored in the system. This filter is
|
|
activated if the `key` exists, disregarding the value and matcher 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. Behavior when processing this kind of filters is undefined.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| match_type | [MatchType](#neo.fs.v2.object.MatchType) | | Match type to use |
|
|
| key | [string](#string) | | Attribute or Header fields to match |
|
|
| value | [string](#string) | | Value to match |
|
|
|
|
|
|
<a name="neo.fs.v2.object.SearchResponse"></a>
|
|
|
|
### Message SearchResponse
|
|
Search response
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| body | [SearchResponse.Body](#neo.fs.v2.object.SearchResponse.Body) | | Body of search 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.SearchResponse.Body"></a>
|
|
|
|
### Message SearchResponse.Body
|
|
Object Search response body
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| id_list | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of `ObjectID`s that match the search query |
|
|
|
|
<!-- end messages -->
|
|
|
|
<!-- end enums -->
|
|
|
|
|
|
|
|
<a name="object/types.proto"></a>
|
|
<p align="right"><a href="#top">Top</a></p>
|
|
|
|
## object/types.proto
|
|
|
|
|
|
<!-- 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>
|
|
|
|
### Message Header
|
|
Object Header
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Object format version. Effectively, the version of API library used to create particular object |
|
|
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Object's container |
|
|
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Object's owner |
|
|
| creation_epoch | [uint64](#uint64) | | Object creation Epoch |
|
|
| payload_length | [uint64](#uint64) | | Size of payload in bytes. `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown. |
|
|
| payload_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Hash of payload bytes |
|
|
| object_type | [ObjectType](#neo.fs.v2.object.ObjectType) | | Type of the object payload content |
|
|
| homomorphic_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Homomorphic hash of the object payload |
|
|
| session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) | | Session token, if it was used during Object creation. Need it to verify integrity and authenticity out of Request scope. |
|
|
| attributes | [Header.Attribute](#neo.fs.v2.object.Header.Attribute) | repeated | User-defined object attributes |
|
|
| split | [Header.Split](#neo.fs.v2.object.Header.Split) | | Position of the object in the split hierarchy |
|
|
| ec | [Header.EC](#neo.fs.v2.object.Header.EC) | | Erasure code chunk information. |
|
|
|
|
|
|
<a name="neo.fs.v2.object.Header.Attribute"></a>
|
|
|
|
### Message Header.Attribute
|
|
`Attribute` is a user-defined Key-Value metadata pair attached to an
|
|
object.
|
|
|
|
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
|
|
will be considered invalid.
|
|
|
|
There are some "well-known" attributes starting with `__SYSTEM__`
|
|
(`__NEOFS__` is deprecated) prefix that affect system behaviour:
|
|
|
|
* [ __SYSTEM__UPLOAD_ID ] \
|
|
(`__NEOFS__UPLOAD_ID` is deprecated) \
|
|
Marks smaller parts of a split bigger object
|
|
* [ __SYSTEM__EXPIRATION_EPOCH ] \
|
|
(`__NEOFS__EXPIRATION_EPOCH` is deprecated) \
|
|
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 ] \
|
|
(`__NEOFS__TICK_EPOCH` is deprecated) \
|
|
Decimal number that defines what epoch must produce
|
|
object notification with UTF-8 object address in a
|
|
body (`0` value produces notification right after
|
|
object put)
|
|
* [ __SYSTEM__TICK_TOPIC ] \
|
|
(`__NEOFS__TICK_TOPIC` is deprecated) \
|
|
UTF-8 string topic ID that is used for object notification
|
|
|
|
And some well-known attributes used by applications only:
|
|
|
|
* Name \
|
|
Human-friendly name
|
|
* FileName \
|
|
File name to be associated with the object on saving
|
|
* FilePath \
|
|
Full path to be associated with the object on saving. Should start with a
|
|
'/' and use '/' as a delimiting symbol. Trailing '/' should be
|
|
interpreted as a virtual directory marker. If an object has conflicting
|
|
FilePath and FileName, FilePath should have higher priority, because it
|
|
is used to construct the directory tree. FilePath with trailing '/' and
|
|
non-empty FileName attribute should not be used together.
|
|
* Timestamp \
|
|
User-defined local time of object creation in Unix Timestamp format
|
|
* Content-Type \
|
|
MIME Content Type of object's payload
|
|
|
|
For detailed description of each well-known attribute please see the
|
|
corresponding section in NeoFS Technical Specification.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| key | [string](#string) | | string key to 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. |
|
|
| parent_split_id | [bytes](#bytes) | | As the origin object is EC-splitted its identifier is known to all chunks as parent. But parent itself can be a part of Split (does not relate to EC-split). In this case parent_split_id should be set. |
|
|
| parent_split_parent_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | EC-parent's parent ID. parent_split_parent_id is set if EC-parent, itself, is a part of Split and if an object ID of its parent is presented.The field allows to determine how EC-chunk is placed in Split hierarchy. |
|
|
|
|
|
|
<a name="neo.fs.v2.object.Header.Split"></a>
|
|
|
|
### Message Header.Split
|
|
Bigger objects can be split into a chain of smaller objects. Information
|
|
about inter-dependencies between spawned objects and how to re-construct
|
|
the original one is in the `Split` headers. Parent and children objects
|
|
must be within the same container.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| parent | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the origin object. Known only to the minor child. |
|
|
| previous | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the left split neighbor |
|
|
| parent_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | `signature` field of the parent object. Used to reconstruct parent. |
|
|
| parent_header | [Header](#neo.fs.v2.object.Header) | | `header` field of the parent object. Used to reconstruct parent. |
|
|
| children | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of identifiers of the objects generated by splitting current one. |
|
|
| split_id | [bytes](#bytes) | | 16 byte UUIDv4 used to identify the split object hierarchy parts. Must be unique inside container. All objects participating in the split must have the same `split_id` value. |
|
|
|
|
|
|
<a name="neo.fs.v2.object.Object"></a>
|
|
|
|
### Message Object
|
|
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 hash of header field which contains hash of the object's payload.
|
|
|
|
For non-regular object types payload format depends on object type specified
|
|
in the header.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Object's unique identifier. |
|
|
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signed object_id |
|
|
| header | [Header](#neo.fs.v2.object.Header) | | Object metadata headers |
|
|
| payload | [bytes](#bytes) | | Payload bytes |
|
|
|
|
|
|
<a name="neo.fs.v2.object.ShortHeader"></a>
|
|
|
|
### Message ShortHeader
|
|
Short header fields
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Object format version. Effectively, the version of API library used to create particular object. |
|
|
| creation_epoch | [uint64](#uint64) | | Epoch when the object was created |
|
|
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Object's owner |
|
|
| object_type | [ObjectType](#neo.fs.v2.object.ObjectType) | | Type of the object payload content |
|
|
| payload_length | [uint64](#uint64) | | Size of payload in bytes. `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown |
|
|
| payload_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Hash of payload bytes |
|
|
| homomorphic_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Homomorphic hash of the object payload |
|
|
|
|
|
|
<a name="neo.fs.v2.object.SplitInfo"></a>
|
|
|
|
### Message SplitInfo
|
|
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
|
|
assemble the original object. With a linking object one can assemble an
|
|
object right from the object parts.
|
|
|
|
|
|
| Field | Type | Label | Description |
|
|
| ----- | ---- | ----- | ----------- |
|
|
| split_id | [bytes](#bytes) | | 16 byte UUID used to identify the split object hierarchy parts. |
|
|
| last_part | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | The identifier of the last object in split hierarchy parts. It contains split header with the original object header. |
|
|
| link | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | The identifier of a linking object for split hierarchy parts. It contains split header with the original object header and a sorted list of object parts. |
|
|
|
|
<!-- end messages -->
|
|
|
|
|
|
<a name="neo.fs.v2.object.MatchType"></a>
|
|
|
|
### MatchType
|
|
Type of match expression
|
|
|
|
| Name | Number | Description |
|
|
| ---- | ------ | ----------- |
|
|
| MATCH_TYPE_UNSPECIFIED | 0 | Unknown. Not used |
|
|
| STRING_EQUAL | 1 | Full string match |
|
|
| STRING_NOT_EQUAL | 2 | Full string mismatch |
|
|
| NOT_PRESENT | 3 | Lack of key |
|
|
| COMMON_PREFIX | 4 | String prefix match |
|
|
|
|
|
|
|
|
<a name="neo.fs.v2.object.ObjectType"></a>
|
|
|
|
### ObjectType
|
|
Type of the object payload content. Only `REGULAR` type objects can be split,
|
|
hence `TOMBSTONE` and `LOCK` payload is limited by the
|
|
maximum object size.
|
|
|
|
String presentation of object type is the same as definition:
|
|
* REGULAR
|
|
* TOMBSTONE
|
|
* LOCK
|
|
|
|
| Name | Number | Description |
|
|
| ---- | ------ | ----------- |
|
|
| REGULAR | 0 | Just a normal object |
|
|
| TOMBSTONE | 1 | Used internally to identify deleted objects |
|
|
| LOCK | 3 | Object lock |
|
|
|
|
|
|
<!-- end enums -->
|
|
|
|
|
|
|
|
## Scalar Value Types
|
|
|
|
| .proto Type | Notes | C++ Type | Java Type | Python Type |
|
|
| ----------- | ----- | -------- | --------- | ----------- |
|
|
| <a name="double" /> double | | double | double | float |
|
|
| <a name="float" /> float | | float | float | float |
|
|
| <a name="int32" /> 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 |
|
|
| <a name="int64" /> 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 |
|
|
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
|
|
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
|
|
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
|
|
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
|
|
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
|
|
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
|
|
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
|
|
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
|
|
| <a name="bool" /> bool | | bool | boolean | boolean |
|
|
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
|
|
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
|
|
|