carpawell/frostfs-api
1
0
Fork 0
forked from TrueCloudLab/frostfs-api
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update object package docs

Browse source 
Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>
This commit is contained in:
Stanislav Bogatyrev 2020-10-15 21:28:19 +03:00 committed by Stanislav Bogatyrev
parent 3f6c211fef
commit 27f4b1ad63
2 changed files with 177 additions and 161 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

293
object/service.proto
View file

@ -9,93 +9,98 @@ import "object/types.proto";
import "refs/types.proto";
import "session/types.proto";
// Object service provides API for manipulating with the object.
// `ObjectService` provides API for manipulating objects. Object operations do
// not interact with sidechain and are only served by nodes in p2p style.
service ObjectService {
// 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.
// Receive full object structure, including Headers and payload. Response uses
// gRPC stream. First response message carries object with requested address.
// Chunk messages are parts of the object's payload if it is needed. All
// messages, except the first one, carry payload chunks. Requested object can
// be restored by concatenation of object message payload and all chunks
// keeping receiving order.
rpc Get(GetRequest) returns (stream GetResponse);
// 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.
// 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 direct order of fragmentation.
rpc Put(stream PutRequest) returns (PutResponse);
// Delete the object from a container
// Delete the object from a container. There is no immediate removal
// guarantee. Object will be marked for removal and deleted eventually.
rpc Delete(DeleteRequest) returns (DeleteResponse);
// 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.
// 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 would be returned instead.
rpc Head(HeadRequest) returns (HeadResponse);
// Search objects in container. Version of query language format SHOULD BE
// set to 1. Search query represented in serialized format (see query
// package).
// 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.
rpc Search(SearchRequest) returns (stream SearchResponse);
// GetRange of data payload. Range is a pair (offset, length).
// Requested range can be restored by concatenation of all chunks
// keeping receiving order.
// 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 receiving
// order.
rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse);
// 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.
// 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 ranges order in
// request. Note that hash is calculated for XORed data.
rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
}
// Get object request
// GET object request
message GetRequest {
// Request body
// GET Object request body
message Body {
// Address of the requested object.
// Address of the requested object
neo.fs.v2.refs.Address address = 1;
// Carries the raw option flag of the request.
// Raw request is sent to receive only the objects
// that are physically stored on the server.
// If `raw` flag is set, request will work only with objects that are
// physically stored on the peer node
bool raw = 2;
}
// Body of get object request message.
Body body = 1;
// Carries request meta information. Header data is used only to regulate message
// transport and does not affect request execution.
// Carries request meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
// Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
}
// get object response
// GET object response
message GetResponse {
// Response body
// GET Object Response body
message Body {
// Initialization parameters of the object got from NeoFS.
// Initial part of the `Object` structure stream. Technically it's a
// set of all `Object` structure's fields except `payload`.
message Init {
// Object ID
// Object's unique identifier.
neo.fs.v2.refs.ObjectID object_id = 1;
// Object signature
// Signed `ObjectID`
neo.fs.v2.refs.Signature signature = 2;
// Object header.
// Object metadata headers
Header header = 3;
}
// Carries the single message of the response stream.
// Single message in the response stream.
oneof object_part {
// Initialization parameters of the object stream.
// Initial part of the object stream
Init init = 1;
// Part of the object payload.
// Chunked object payload
bytes chunk = 2;
}
}
@ -107,58 +112,58 @@ message GetResponse {
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness
// of transmission.
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
}
// Put object request
// PUT object request
message PutRequest {
// Request body
// PUT request body
message Body {
// Groups initialization parameters of object placement in NeoFS.
// Newly created object structure parameters. If some optional parameters
// are not set, they will be calculated by a peer node.
message Init {
// Object ID, where available
// ObjectID if available.
neo.fs.v2.refs.ObjectID object_id = 1;
// Object signature, were available
// Object signature if available
neo.fs.v2.refs.Signature signature = 2;
// Header of the object to save in the system.
// Object's Header
Header header = 3;
// Number of the object copies to store within the RPC call.
// Default zero value is processed according to the
// container placement rules.
// Number of the object copies to store within the RPC call. By default
// object is processed according to the container's placement policy.
uint32 copies_number = 4;
}
// Carries the single part of the query stream.
// Single message in the request stream.
oneof object_part {
// Carries the initialization parameters of the object stream.
// Initial part of the object stream
Init init = 1;
// Carries part of the object payload.
// Chunked object payload
bytes chunk = 2;
}
}
// Body of put object request message.
Body body = 1;
// Carries request meta information. Header data is used only to regulate message
// transport and does not affect request execution.
// Carries request meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
// Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
}
// Put object response
// PUT Object response
message PutResponse {
// Response body
// PUT Object response body
message Body {
// Carries identifier of the saved object.
// It is used to access an object in the container.
// Identifier of the saved object
neo.fs.v2.refs.ObjectID object_id = 1;
}
// Body of put object response message.
@ -169,34 +174,35 @@ message PutResponse {
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness
// of transmission.
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
}
// Object Delete request
// Object DELETE request
message DeleteRequest {
// Request body
// Object DELETE request body
message Body {
// Carries the address of the object to be deleted.
// Address of the object to be deleted
neo.fs.v2.refs.Address address = 1;
}
// Body of delete object request message.
Body body = 1;
// Carries request meta information. Header data is used only to regulate message
// transport and does not affect request execution.
// Carries request meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
// Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
}
// DeleteResponse is empty because we cannot guarantee permanent object removal
// in distributed system.
// DeleteResponse body is empty because we cannot guarantee permanent object
// removal in distributed system.
message DeleteResponse {
// Response body
// Object DELETE Response has an empty body.
message Body { }
// Body of delete object response message.
@ -207,57 +213,60 @@ message DeleteResponse {
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness
// of transmission.
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
}
// Object head request
// Object HEAD request
message HeadRequest {
// Request body
// Object HEAD request body
message Body {
// Address of the object with the requested header.
// Address of the object with the requested Header
neo.fs.v2.refs.Address address = 1;
// Return only minimal header subset
bool main_only = 2;
// Carries the raw option flag of the request.
// Raw request is sent to receive only the headers of the objects
// that are physically stored on the server.
// If `raw` flag is set, request will work only with objects that are
// physically stored on the peer node
bool raw = 3;
}
// Body of head object request message.
Body body = 1;
// Carries request meta information. Header data is used only to regulate message
// transport and does not affect request execution.
// Carries request meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
// Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
}
// Tuple of full object header and signature of object ID.
// Tuple of full object header and signature of `ObjectID`. \
// Signed `ObjectID` is present to verify full header's authenticity through the
// following steps:
//
// 1. Calculate `SHA-256` of marshalled `Header` structure
// 2. Check if the resulting hash matched `ObjectID`
// 3. Check if `ObjectID` signature in `signature` field is correct
message HeaderWithSignature {
// Full object header
Header header = 1;
// Signed object_id to verify full header's authenticity through following steps:
// 1. Calculate SHA-256 of marshalled Headers structure.
// 2. Check if the resulting hash matched ObjectID
// 3. Check if ObjectID's signature in signature field is correct.
// Signed `ObjectID` to verify full header's authenticity
neo.fs.v2.refs.Signature signature = 2;
}
// Head response
// Object HEAD response
message HeadResponse {
// Response body
// Object HEAD response body
message Body {
// Carries the requested object header or it's part
// Requested object header or it's part.
oneof head{
// Full object header with object ID signature
// Full object's `Header` with `ObjectID` signature
HeaderWithSignature header = 1;
// Short object header
@ -272,16 +281,16 @@ message HeadResponse {
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness
// of transmission.
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
}
// Search objects request
// Object Search request
message SearchRequest {
// Request body
// Object Search request body
message Body {
// Carries search container identifier.
// Container identifier were to search
neo.fs.v2.refs.ContainerID container_id = 1;
// Version of the Query Language used
@ -303,20 +312,21 @@ message SearchRequest {
// Body of search object request message.
Body body = 1;
// Carries request meta information. Header data is used only to regulate message
// transport and does not affect request execution.
// Carries request meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
// Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
}
// Search response
message SearchResponse {
// Response body
// Object Search response body
message Body {
// Carries list of object identifiers that match the search query
// List of `ObjectID`s that match the search query
repeated neo.fs.v2.refs.ObjectID id_list = 1;
}
// Body of search object response message.
@ -327,48 +337,52 @@ message SearchResponse {
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness
// of transmission.
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
}
// Range groups the parameters of object payload range.
// Object payload range.Ranges of zero length SHOULD be considered as invalid.
message Range {
// Carries the offset of the range from the object payload start.
// Offset of the range from the object payload start
uint64 offset = 1;
// Carries the length of the object payload range.
// Length in bytes of the object payload range
uint64 length = 2;
}
// Request to get part of object's payload
// Request part of object's payload
message GetRangeRequest {
// Request Body
// Byte range of object's payload request body
message Body {
// Address carries address of the object that contains the requested payload range.
// Address of the object containing the requested payload range
neo.fs.v2.refs.Address address = 1;
// Range carries the parameters of the requested payload range.
// Requested payload range
Range range = 2;
}
// Body of get range object request message.
Body body = 1;
// Carries request meta information. Header data is used only to regulate message
// transport and does not affect request execution.
// Carries request meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
// Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
}
// Get part of object's payload
message GetRangeResponse {
// Response 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.
message Body {
// Carries part of the object payload.
// Chunked object payload's range
bytes chunk = 1;
}
@ -380,22 +394,22 @@ message GetRangeResponse {
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness
// of transmission.
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
}
// Get hash of object's payload part
message GetRangeHashRequest {
// Request body
// Get hash of object's payload part request body.
message Body {
// Carries address of the object that contains the requested payload range.
// Address of the object that containing the requested payload range
neo.fs.v2.refs.Address address = 1;
// Carries the list of object payload range to calculate homomorphic hash.
// List of object's payload ranges to calculate homomorphic hash
repeated Range ranges = 2;
// Carries binary salt to XOR object payload ranges before hash calculation.
// Binary salt to XOR object's payload ranges before hash calculation
bytes salt = 3;
// Checksum algorithm type
@ -404,23 +418,24 @@ message GetRangeHashRequest {
// Body of get range hash object request message.
Body body = 1;
// Carries request meta information. Header data is used only to regulate message
// transport and does not affect request execution.
// Carries request meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
// Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
}
// Get hash of object's payload part
message GetRangeHashResponse {
// Response body
// Get hash of object's payload part response body.
message Body {
// Checksum algorithm type
neo.fs.v2.refs.ChecksumType type = 1;
// List of range hashes in a binary format.
// List of range hashes in a binary format
repeated bytes hash_list = 2;
}
// Body of get range hash object response message.
@ -431,7 +446,7 @@ message GetRangeHashResponse {
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness
// of transmission.
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
}

45
object/types.proto
View file

@ -8,7 +8,7 @@ option csharp_namespace = "NeoFS.API.v2.Object";
import "refs/types.proto";
import "session/types.proto";
// Type of the object payload content
// Type of the object payload content.
enum ObjectType {
// Just a normal object
REGULAR = 0;
@ -16,7 +16,7 @@ enum ObjectType {
// Used internally to identify deleted objects
TOMBSTONE = 1;
// Identifies that the object holds StorageGroup information
// StorageGroup information
STORAGE_GROUP = 2;
}
@ -30,7 +30,8 @@ enum MatchType {
// Short header fields
message ShortHeader {
// Object format version.
// Object format version. Effectively the version of API library used to
// create particular object
neo.fs.v2.refs.Version version = 1;
// Epoch when the object was created
@ -43,14 +44,14 @@ message ShortHeader {
ObjectType object_type = 4;
// Size of payload in bytes.
// 0xFFFFFFFFFFFFFFFF means `payload_length` is unknown
// `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown
uint64 payload_length = 5;
}
// Object Headers
// Object Header
message Header {
// Object format version.
// Effectively the version of API library used to create particular object
// Object format version. Effectively the version of API library used to
// create particular object
neo.fs.v2.refs.Version version = 1;
// Object's container
@ -63,20 +64,20 @@ message Header {
uint64 creation_epoch = 4;
// Size of payload in bytes.
// 0xFFFFFFFFFFFFFFFF means `payload_length` is unknown
// `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown
uint64 payload_length = 5;
// Hash of payload bytes
neo.fs.v2.refs.Checksum payload_hash = 6;
// Special object type
// Type of the object payload content
ObjectType object_type = 7;
// Homomorphic hash of the object payload.
neo.fs.v2.refs.Checksum homomorphic_hash = 8;
// Session token, if it was used during Object creation.
// Need it to verify integrity and authenticity out of Request scope.
// Session token, if it was used during Object creation. Need it to verify
// integrity and authenticity out of Request scope.
neo.fs.v2.session.SessionToken session_token = 9;
// `Attribute` is a user-defined Key-Value metadata pair attached to the
@ -99,14 +100,15 @@ message Header {
// User-defined object attributes
repeated Attribute attributes = 10;
// Information about spawning the objects through a payload splitting.
// 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.
message Split {
// Identifier of the origin object.
// Parent and children objects must be within the same container.
// Parent object_id is known only to the minor child.
// Identifier of the origin object. Known only to the minor child.
neo.fs.v2.refs.ObjectID parent = 1;
// Previous carries identifier of the left split neighbor.
// Identifier of the left split neighbor
neo.fs.v2.refs.ObjectID previous = 2;
// `signature` field of the parent object. Used to reconstruct parent.
@ -115,19 +117,18 @@ message Header {
// `header` field of the parent object. Used to reconstruct parent.
Header parent_header = 4;
// Children carries list of identifiers of the objects generated by splitting the current.
// List of identifiers of the objects generated by splitting current one.
repeated neo.fs.v2.refs.ObjectID children = 5;
}
// Position of the object in the split hierarchy.
// Position of the object in the split hierarchy
Split split = 11;
}
// Object structure.
// Object structure. Object is immutable and content-addressed. It means
// `ObjectID` will change if header or payload changes. It's calculated as a
// hash of header field, which contains hash of object's payload.
message Object {
// Object's unique identifier.
// Object is content-addressed. It means id will change if header or payload
// changes. It's calculated as a hash of header field, which contains hash of
// object's payload
neo.fs.v2.refs.ObjectID object_id = 1;
// Signed object_id