frostfs-api-go/docs/object.md
alexvanin dea7002625 docs: Update doc for object proto file
Tombstone header in the object does not contain
timestamp now.
2020-01-15 17:13:25 +03:00

18 KiB

Protocol Documentation

Table of Contents

Top

object/service.proto

Service "object.Service"

Object service provides API for manipulating with the object.

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 (SearchResponse);
rpc GetRange(GetRangeRequest) returns (GetRangeResponse);
rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);

Method Get

Get the object from container. Response uses gRPC stream. First response message carry object of requested address. Chunk messages are parts of the object's payload if it is needed. All messages except first carry chunks. Requested object can be restored by concatenation of object message payload and all chunks keeping receiving order.

Name Input Output
Get GetRequest GetResponse

Method Put

Put the object into container. Request uses gRPC stream. First message SHOULD BE type of PutHeader. Container id and Owner id of object SHOULD BE set. Session token SHOULD BE obtained before put operation (see session package). Chunk messages considered by server as part of object payload. All messages except first SHOULD BE chunks. Chunk messages SHOULD BE sent in direct order of fragmentation.

Name Input Output
Put PutRequest PutResponse

Method Delete

Delete the object from a container

Name Input Output
Delete DeleteRequest DeleteResponse

Method Head

Head returns the object without data payload. Object in the response has system header only. If full headers flag is set, extended headers are also present.

Name Input Output
Head HeadRequest HeadResponse

Search objects in container. Version of query language format SHOULD BE set to 1. Search query represented in serialized format (see query package).

Name Input Output
Search SearchRequest SearchResponse

Method GetRange

GetRange of data payload. Ranges are set of pairs (offset, length). Fragments order in response corresponds to ranges order in request.

Name Input Output
GetRange GetRangeRequest GetRangeResponse

Method GetRangeHash

GetRangeHash returns homomorphic hash of object payload range after XOR operation. Ranges are set of pairs (offset, length). Hashes order in response corresponds to ranges order in request. Homomorphic hash is calculated for XORed data.

Name Input Output
GetRangeHash GetRangeHashRequest GetRangeHashResponse

Message DeleteRequest

Field Type Label Description
Address refs.Address Address of object (container id + object id)
OwnerID bytes OwnerID is a wallet address
Token session.Token Token with session public key and user's signature
Meta service.RequestMetaHeader RequestMetaHeader contains information about request meta headers (should be embedded into message)
Verify service.RequestVerificationHeader RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)

Message DeleteResponse

DeleteResponse is empty because we cannot guarantee permanent object removal in distributed system.

Message GetRangeHashRequest

Field Type Label Description
Address refs.Address Address of object (container id + object id)
Ranges Range repeated Ranges of object's payload to calculate homomorphic hash
Salt bytes Salt is used to XOR object's payload ranges before hashing, it can be nil
Meta service.RequestMetaHeader RequestMetaHeader contains information about request meta headers (should be embedded into message)
Verify service.RequestVerificationHeader RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)

Message GetRangeHashResponse

Field Type Label Description
Hashes bytes repeated Hashes is a homomorphic hashes of all ranges

Message GetRangeRequest

Field Type Label Description
Address refs.Address Address of object (container id + object id)
Ranges Range repeated Ranges of object's payload to return
Meta service.RequestMetaHeader RequestMetaHeader contains information about request meta headers (should be embedded into message)
Verify service.RequestVerificationHeader RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)

Message GetRangeResponse

Field Type Label Description
Fragments bytes repeated Fragments of object's payload

Message GetRequest

Field Type Label Description
Address refs.Address Address of object (container id + object id)
Meta service.RequestMetaHeader RequestMetaHeader contains information about request meta headers (should be embedded into message)
Verify service.RequestVerificationHeader RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)

Message GetResponse

Field Type Label Description
object Object Object header and some payload
Chunk bytes Chunk of remaining payload

Message HeadRequest

Field Type Label Description
Address refs.Address Address of object (container id + object id)
FullHeaders bool FullHeaders can be set true for extended headers in the object
Meta service.RequestMetaHeader RequestMetaHeader contains information about request meta headers (should be embedded into message)
Verify service.RequestVerificationHeader RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)

Message HeadResponse

Field Type Label Description
Object Object Object without payload

Message PutRequest

Field Type Label Description
Header PutRequest.PutHeader Header should be the first message in the stream
Chunk bytes Chunk should be a remaining message in stream should be chunks
Meta service.RequestMetaHeader RequestMetaHeader contains information about request meta headers (should be embedded into message)
Verify service.RequestVerificationHeader RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)

Message PutRequest.PutHeader

Field Type Label Description
Object Object Object with at least container id and owner id fields
Token session.Token Token with session public key and user's signature

Message PutResponse

Field Type Label Description
Address refs.Address Address of object (container id + object id)

Message SearchRequest

Field Type Label Description
ContainerID bytes ContainerID for searching the object
Query bytes Query in the binary serialized format
QueryVersion uint32 QueryVersion is a version of search query format
Meta service.RequestMetaHeader RequestMetaHeader contains information about request meta headers (should be embedded into message)
Verify service.RequestVerificationHeader RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)

Message SearchResponse

Field Type Label Description
Addresses refs.Address repeated Addresses of found objects

Top

object/types.proto

Message CreationPoint

Field Type Label Description
UnixTime int64 UnixTime is a date of creation in unixtime format
Epoch uint64 Epoch is a date of creation in NeoFS epochs

Message Header

Field Type Label Description
Link Link Link to other objects
Redirect refs.Address Redirect not used yet
UserHeader UserHeader UserHeader is a set of KV headers defined by user
Transform Transform Transform defines transform operation (e.g. payload split)
Tombstone Tombstone Tombstone header that set up in deleted objects
Verify session.VerificationHeader Verify header that contains session public key and user's signature
HomoHash bytes HomoHash is a homomorphic hash of original object payload
PayloadChecksum bytes PayloadChecksum of actual object's payload
Integrity IntegrityHeader Integrity header with checksum of all above headers in the object
StorageGroup storagegroup.StorageGroup StorageGroup contains meta information for the data audit

Message IntegrityHeader

Field Type Label Description
HeadersChecksum bytes HeadersChecksum is a checksum of all above headers in the object
ChecksumSignature bytes ChecksumSignature is an user's signature of checksum to verify if it is correct

Field Type Label Description
type Link.Type Type of link
ID bytes ID is an object identifier, is a valid UUIDv4

Message Object

Field Type Label Description
SystemHeader SystemHeader SystemHeader describes system header
Headers Header repeated Headers describes a set of an extended headers
Payload bytes Payload is an object's payload

Message Range

Field Type Label Description
Offset uint64 Offset of the data range
Length uint64 Length of the data range

Message SystemHeader

Field Type Label Description
Version uint64 Version of the object structure
PayloadLength uint64 PayloadLength is an object payload length
ID bytes ID is an object identifier, is a valid UUIDv4
OwnerID bytes OwnerID is a wallet address
CID bytes CID is a SHA256 hash of the container structure (container identifier)
CreatedAt CreationPoint CreatedAt is a timestamp of object creation

Message Tombstone

Message Transform

Field Type Label Description
type Transform.Type Type of object transformation

Message UserHeader

Field Type Label Description
Key string Key of the user's header
Value string Value of the user's header

Name Number Description
Unknown 0
Parent 1 Parent object created during object transformation
Previous 2 Previous object in the linked list created during object transformation
Next 3 Next object in the linked list created during object transformation
Child 4 Child object created during object transformation
StorageGroup 5 Object that included into this storage group

Transform.Type

Name Number Description
Unknown 0
Split 1 Split sets when object created after payload split
Sign 2 Sign sets when object created after re-signing (doesn't used)
Mould 3 Mould sets when object created after filling missing headers in the object

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