From 27f4b1ad63740745a7093d000b198136c75f270b Mon Sep 17 00:00:00 2001 From: Stanislav Bogatyrev Date: Thu, 15 Oct 2020 21:28:19 +0300 Subject: [PATCH] Update object package docs Signed-off-by: Stanislav Bogatyrev --- object/service.proto | 293 +++++++++++++++++++++++-------------------- object/types.proto | 45 +++---- 2 files changed, 177 insertions(+), 161 deletions(-) diff --git a/object/service.proto b/object/service.proto index 020e1d5..4ce47ed 100644 --- a/object/service.proto +++ b/object/service.proto @@ -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; } diff --git a/object/types.proto b/object/types.proto index 0c44c89..b3fe8b9 100644 --- a/object/types.proto +++ b/object/types.proto @@ -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