From b930782fd3abb3bdcb5f5a66a53f47313edb1560 Mon Sep 17 00:00:00 2001 From: Stanislav Bogatyrev Date: Tue, 8 Dec 2020 18:08:32 +0300 Subject: [PATCH] [#84] Clarify various types encoding formats Signed-off-by: Stanislav Bogatyrev --- container/types.proto | 2 +- object/service.proto | 2 +- object/types.proto | 20 +++++++++++++------- refs/types.proto | 39 +++++++++++++++++++++++++++++++-------- 4 files changed, 46 insertions(+), 17 deletions(-) diff --git a/container/types.proto b/container/types.proto index b098680..d09d446 100644 --- a/container/types.proto +++ b/container/types.proto @@ -20,7 +20,7 @@ message Container { // Identifier of the container owner neo.fs.v2.refs.OwnerID owner_id = 2 [json_name = "ownerID"]; - // Nonce is a 16 byte UUID, used to avoid collisions of container id + // Nonce is a 16 byte UUIDv4, used to avoid collisions of `ContainerID`s bytes nonce = 3 [json_name = "nonce"]; // `BasicACL` contains access control rules for owner, system, others groups diff --git a/object/service.proto b/object/service.proto index c87517d..4a30bf7 100644 --- a/object/service.proto +++ b/object/service.proto @@ -323,7 +323,7 @@ message SearchRequest { // * $Object:split.parent \ // object_id of parent // * $Object:split.splitID \ - // 16 byte UUID used to identify the split object hierarchy parts + // 16 byte UUIDv4 used to identify the split object hierarchy parts // // There are some well-known filter aliases to match objects by certain // properties: diff --git a/object/types.proto b/object/types.proto index 6c4eb56..cf52a09 100644 --- a/object/types.proto +++ b/object/types.proto @@ -11,6 +11,12 @@ import "session/types.proto"; // Type of the object payload content. Only `REGULAR` type objects can be split, // hence `TOMBSTONE` and `STORAGEGROUP` payload is limited by maximal object // size. +// +// String presentation of object type is PascalCased `ObjectType` enumeration +// item name: +// * Regular +// * Tombstone +// * StorageGroup enum ObjectType { // Just a normal object REGULAR = 0; @@ -34,7 +40,7 @@ enum MatchType { // Short header fields message ShortHeader { // Object format version. Effectively the version of API library used to - // create particular object + // create particular object. neo.fs.v2.refs.Version version = 1 [json_name = "version"]; // Epoch when the object was created @@ -67,7 +73,7 @@ message Header { uint64 creation_epoch = 4 [json_name = "creationEpoch"]; // Size of payload in bytes. - // `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown + // `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown. uint64 payload_length = 5 [json_name = "payloadLength"]; // Hash of payload bytes @@ -76,7 +82,7 @@ message Header { // Type of the object payload content ObjectType object_type = 7 [json_name = "objectType"]; - // Homomorphic hash of the object payload. + // Homomorphic hash of the object payload neo.fs.v2.refs.Checksum homomorphic_hash = 8 [json_name = "homomorphicHash"]; // Session token, if it was used during Object creation. Need it to verify @@ -136,9 +142,9 @@ message Header { // List of identifiers of the objects generated by splitting current one. repeated neo.fs.v2.refs.ObjectID children = 5 [json_name = "children"]; - // 16 byte UUID 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. + // 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. bytes split_id = 6 [json_name = "splitID"]; } @@ -159,6 +165,6 @@ message Object { // Object metadata headers Header header = 3 [json_name = "header"]; - // Payload bytes. + // Payload bytes bytes payload = 4 [json_name = "payload"]; } diff --git a/refs/types.proto b/refs/types.proto index f56819e..a0716e4 100644 --- a/refs/types.proto +++ b/refs/types.proto @@ -5,8 +5,10 @@ package neo.fs.v2.refs; option go_package = "github.com/nspcc-dev/neofs-api-go/v2/refs/grpc;refs"; option csharp_namespace = "NeoFS.API.v2.Refs"; -// Object in NeoFS can be addressed by it's ContainerID and ObjectID. In string -// format there MUST be a '/' delimeter between them. +// Objects in NeoFS are addressed by their ContainerID and ObjectID. +// +// String presentation of `Address` is the concatenation of string encoded +// `ContainerID` and `ObjectID` delimited by '/' character. message Address { // Container identifier ContainerID container_id = 1 [json_name = "containerID"]; @@ -15,31 +17,46 @@ message Address { } // NeoFS Object unique identifier. Objects are immutable and content-addressed. -// It means `ObjectID` will change if `header` or `payload` changes. `ObjectID` -// is calculated as a hash of `header` field, which contains hash of object's -// payload. +// It means `ObjectID` will change if `header` or `payload` changes. +// +// `ObjectID` is a 32 byte long SHA256 hash of object's `header` field, which, +// in it's turn, contains hash of object's payload. +// +// String presentation is base58 encoded string. message ObjectID { // Object identifier in a binary format bytes value = 1 [json_name = "value"]; } // NeoFS container identifier. Container structures are immutable and -// content-addressed. `ContainerID` is a 32 byte long SHA256 hash of -// stable-marshalled container message. +// content-addressed. +// +// `ContainerID` is a 32 byte long SHA256 hash of stable-marshalled container +// message. +// +// String presentation is base58 encoded string. message ContainerID { // Container identifier in a binary format. bytes value = 1 [json_name = "value"]; } -// OwnerID is a derivative of a user's main public key. The transformation +// `OwnerID` is a derivative of a user's main public key. The transformation // algorithm is the same as for Neo3 wallet addresses. Neo3 wallet address can // be directly used as `OwnerID`. +// +// `OwnerID` is a 25 bytes sequence starting with Neo version prefix byte +// followed by 20 bytes of ScrptHash and 4 bytes of checksum. +// +// String presentation is Base58 Check Encoded string. message OwnerID { // Identifier of the container owner in a binary format bytes value = 1 [json_name = "value"]; } // API version used by a node. +// +// String presentation is a Semantic Versioning 2.0.0 compatible version string +// with 'v' prefix. I.e. `vX.Y`, where `X` - major number, `Y` - minor number. message Version { // Major API version uint32 major = 1 [json_name = "major"]; @@ -69,6 +86,12 @@ enum ChecksumType { } // Checksum message. +// Depending on checksum algorithm type the string presentation may vary: +// +// * TZ \ +// Hex encoded string without `0x` prefix +// * SHA256 \ +// Hex encoded string without `0x` prefix message Checksum { // Checksum algorithm type ChecksumType type = 1 [json_name = "type"];