From 15b997bdb51b2e3dbafab0a10e4b7c8c3b1f8b37 Mon Sep 17 00:00:00 2001 From: Evgeniy Kulikov Date: Thu, 21 Nov 2019 10:26:01 +0300 Subject: [PATCH] docs: update proto doc comments to satisfy go-doc comment --- accounting/withdraw.proto | 4 +- container/types.proto | 12 ++-- object/service.proto | 117 ++++++++++++++++++++----------- object/types.proto | 141 +++++++++++++++++++++++++------------- query/types.proto | 3 +- refs/types.proto | 2 +- session/service.proto | 17 +++-- session/types.proto | 16 ++--- 8 files changed, 201 insertions(+), 111 deletions(-) diff --git a/accounting/withdraw.proto b/accounting/withdraw.proto index 33ce402..8e10ef9 100644 --- a/accounting/withdraw.proto +++ b/accounting/withdraw.proto @@ -42,7 +42,7 @@ message GetRequest { } message GetResponse { - // Item is cheque with meta information + // Withdraw is cheque with meta information Item Withdraw = 1; } @@ -73,7 +73,7 @@ message ListRequest { } message ListResponse { - // Item is a set of cheques with meta information + // Items is a set of cheques with meta information repeated Item Items = 1; } diff --git a/container/types.proto b/container/types.proto index efcaee8..a601edd 100644 --- a/container/types.proto +++ b/container/types.proto @@ -9,8 +9,12 @@ option (gogoproto.stable_marshaler_all) = true; // The Container service definition. message Container { - bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; // OwnerID is a wallet address. - bytes Salt = 2 [(gogoproto.customtype) = "UUID", (gogoproto.nullable) = false]; // Salt is a nonce for unique container id calculation. - uint64 Capacity = 3; // Capacity defines amount of data that can be stored in the container (doesn't used for now). - netmap.PlacementRule Rules = 4 [(gogoproto.nullable) = false]; // Rules define storage policy for the object inside the container. + // OwnerID is a wallet address. + bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // Salt is a nonce for unique container id calculation. + bytes Salt = 2 [(gogoproto.customtype) = "UUID", (gogoproto.nullable) = false]; + // Capacity defines amount of data that can be stored in the container (doesn't used for now). + uint64 Capacity = 3; + // Rules define storage policy for the object inside the container. + netmap.PlacementRule Rules = 4 [(gogoproto.nullable) = false]; } diff --git a/object/service.proto b/object/service.proto index 6f13d55..5edf935 100644 --- a/object/service.proto +++ b/object/service.proto @@ -52,41 +52,58 @@ service Service { } message GetRequest { - uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value - refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id) - uint32 TTL = 3; // TTL must be larger than zero, it decreased in every neofs-node + // Epoch is set by user to 0, node set epoch to the actual value + uint64 Epoch = 1; + // Address of object (container id + object id) + refs.Address Address = 2 [(gogoproto.nullable) = false]; + // TTL must be larger than zero, it decreased in every neofs-node + uint32 TTL = 3; } message GetResponse { oneof R { - Object object = 1; // Object header and some payload - bytes Chunk = 2; // Chunk of remaining payload + // Object header and some payload + Object object = 1; + // Chunk of remaining payload + bytes Chunk = 2; } } message PutRequest { message PutHeader { - uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value - Object Object = 2; // Object with at least container id and owner id fields - uint32 TTL = 3; // TTL must be larger than zero, it decreased in every neofs-node - session.Token Token = 4; // Token with session public key and user's signature + // Epoch is set by user to 0, node set epoch to the actual value + uint64 Epoch = 1; + // Object with at least container id and owner id fields + Object Object = 2; + // TTL must be larger than zero, it decreased in every neofs-node + uint32 TTL = 3; + // Token with session public key and user's signature + session.Token Token = 4; } oneof R { - PutHeader Header = 1; // Header should be the first message in the stream - bytes Chunk = 2; // Chunk should be a remaining message in stream should be chunks + // Header should be the first message in the stream + PutHeader Header = 1; + // Chunk should be a remaining message in stream should be chunks + bytes Chunk = 2; } } message PutResponse { - refs.Address Address = 1 [(gogoproto.nullable) = false]; // Address of object (container id + object id) + // Address of object (container id + object id) + refs.Address Address = 1 [(gogoproto.nullable) = false]; } message DeleteRequest { - uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value - refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id) - bytes OwnerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "OwnerID"]; // OwnerID is a wallet address - uint32 TTL = 4; // TTL must be larger than zero, it decreased in every neofs-node - session.Token Token = 5; // Token with session public key and user's signature + // Epoch is set by user to 0, node set epoch to the actual value + uint64 Epoch = 1; + // Address of object (container id + object id) + refs.Address Address = 2 [(gogoproto.nullable) = false]; + // OwnerID is a wallet address + bytes OwnerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "OwnerID"]; + // TTL must be larger than zero, it decreased in every neofs-node + uint32 TTL = 4; + // Token with session public key and user's signature + session.Token Token = 5; } // DeleteResponse is empty because we cannot guarantee permanent object removal @@ -94,47 +111,69 @@ message DeleteRequest { message DeleteResponse {} message HeadRequest { - uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value - refs.Address Address = 2 [(gogoproto.nullable) = false, (gogoproto.customtype) = "Address"]; // Address of object (container id + object id) - bool FullHeaders = 3; // FullHeaders can be set true for extended headers in the object - uint32 TTL = 4; // TTL must be larger than zero, it decreased in every neofs-node + // Epoch should be empty on user side, node sets epoch to the actual value + uint64 Epoch = 1; + // Address of object (container id + object id) + refs.Address Address = 2 [(gogoproto.nullable) = false, (gogoproto.customtype) = "Address"]; + // FullHeaders can be set true for extended headers in the object + bool FullHeaders = 3; + // TTL must be larger than zero, it decreased in every neofs-node + uint32 TTL = 4; } message HeadResponse { - Object Object = 1; // Object without payload + // Object without payload + Object Object = 1; } message SearchRequest { - uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value - uint32 Version = 2; // Version of search query format - bytes ContainerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "CID"]; // ContainerID for searching the object - bytes Query = 4; // Query in the binary serialized format - uint32 TTL = 5; // TTL must be larger than zero, it decreased in every neofs-node + // Epoch is set by user to 0, node set epoch to the actual value + uint64 Epoch = 1; + // Version of search query format + uint32 Version = 2; + // ContainerID for searching the object + bytes ContainerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "CID"]; + // Query in the binary serialized format + bytes Query = 4; + // TTL must be larger than zero, it decreased in every neofs-node + uint32 TTL = 5; } message SearchResponse { - repeated refs.Address Addresses = 1 [(gogoproto.nullable) = false]; // Addresses of found objects + // Addresses of found objects + repeated refs.Address Addresses = 1 [(gogoproto.nullable) = false]; } message GetRangeRequest { - uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value - refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id) - repeated Range Ranges = 3 [(gogoproto.nullable) = false]; // Ranges of object's payload to return - uint32 TTL = 4; // TTL must be larger than zero, it decreased in every neofs-node + // Epoch is set by user to 0, node set epoch to the actual value + uint64 Epoch = 1; + // Address of object (container id + object id) + refs.Address Address = 2 [(gogoproto.nullable) = false]; + // Ranges of object's payload to return + repeated Range Ranges = 3 [(gogoproto.nullable) = false]; + // TTL must be larger than zero, it decreased in every neofs-node + uint32 TTL = 4; } message GetRangeResponse { - repeated bytes Fragments = 1; // Fragments of object's payload + // Fragments of object's payload + repeated bytes Fragments = 1; } message GetRangeHashRequest { - uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value - refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id) - repeated Range Ranges = 3 [(gogoproto.nullable) = false]; // Ranges of object's payload to calculate homomorphic hash - bytes Salt = 4; // Salt is used to XOR object's payload ranges before hashing, it can be nil - uint32 TTL = 5; // TTL must be larger than zero, it decreased in every neofs-node + // Epoch is set by user to 0, node set epoch to the actual value + uint64 Epoch = 1; + // Address of object (container id + object id) + refs.Address Address = 2 [(gogoproto.nullable) = false]; + // Ranges of object's payload to calculate homomorphic hash + repeated Range Ranges = 3 [(gogoproto.nullable) = false]; + // Salt is used to XOR object's payload ranges before hashing, it can be nil + bytes Salt = 4; + // TTL must be larger than zero, it decreased in every neofs-node + uint32 TTL = 5; } message GetRangeHashResponse { - repeated bytes Hashes = 1 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false]; // Homomorphic hashes of all ranges + // Hashes is a homomorphic hashes of all ranges + repeated bytes Hashes = 1 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false]; } diff --git a/object/types.proto b/object/types.proto index 30e468e..f3313a3 100644 --- a/object/types.proto +++ b/object/types.proto @@ -9,97 +9,144 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; message Range { - uint64 Offset = 1; // Offset of the data range - uint64 Length = 2; // Length of the data range + // Offset of the data range + uint64 Offset = 1; + // Length of the data range + uint64 Length = 2; } message UserHeader { - string Key = 1; // Key of the user's header - string Value = 2; // Value of the user's header + // Key of the user's header + string Key = 1; + // Value of the user's header + string Value = 2; } message Header { oneof Value { - Link Link = 1; // Link to other objects - refs.Address Redirect = 2; // RedirectNot used yet - UserHeader UserHeader = 3; // UserHeader defined by user - Transform Transform = 4; // Transform defines transform operation (e.g. payload split) - Tombstone Tombstone = 5; // Tombstone header that set up in deleted objects - session.VerificationHeader Verify = 6; // Verify header that contains session public key and user's signature - bytes HomoHash = 7 [(gogoproto.customtype) = "Hash"]; // Homomorphic hash of original object payload - bytes PayloadChecksum = 8; // PayloadChecksum of actual object's payload - IntegrityHeader Integrity = 9; // Integrity header with checksum of all above headers in the object - StorageGroup StorageGroup = 10; // StorageGroup contains meta information for the data audit + // Link to other objects + Link Link = 1; + // Redirect not used yet + refs.Address Redirect = 2; + // UserHeader is a set of KV headers defined by user + UserHeader UserHeader = 3; + // Transform defines transform operation (e.g. payload split) + Transform Transform = 4; + // Tombstone header that set up in deleted objects + Tombstone Tombstone = 5; + // Verify header that contains session public key and user's signature + session.VerificationHeader Verify = 6; + // HomoHash is a homomorphic hash of original object payload + bytes HomoHash = 7 [(gogoproto.customtype) = "Hash"]; + // PayloadChecksum of actual object's payload + bytes PayloadChecksum = 8; + // Integrity header with checksum of all above headers in the object + IntegrityHeader Integrity = 9; + // StorageGroup contains meta information for the data audit + StorageGroup StorageGroup = 10; } } message Tombstone { - uint64 Epoch = 1; // Epoch when tombstone was created + // Epoch when tombstone was created + uint64 Epoch = 1; } message SystemHeader { - uint64 Version = 1; // Version of the object structure - uint64 PayloadLength = 2; // Object payload length + // Version of the object structure + uint64 Version = 1; + // PayloadLength is an object payload length + uint64 PayloadLength = 2; - bytes ID = 3 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false]; // ObjectID is a UUID - bytes OwnerID = 4 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; // OwnerID is a wallet address - bytes CID = 5 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; // ContainerID is a SHA256 hash of the container structure - CreationPoint CreatedAt = 6 [(gogoproto.nullable) = false]; // Timestamp of object creation + // ID is an object identifier, is a valid UUIDv4 + bytes ID = 3 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false]; + // OwnerID is a wallet address + bytes OwnerID = 4 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // CID is a SHA256 hash of the container structure (container identifier) + bytes CID = 5 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; + // CreatedAt is a timestamp of object creation + CreationPoint CreatedAt = 6 [(gogoproto.nullable) = false]; } message CreationPoint { - int64 UnixTime = 1; // Date of creation in unixtime format - uint64 Epoch = 2; // Date of creation in NeoFS epochs + // UnixTime is a date of creation in unixtime format + int64 UnixTime = 1; + // Epoch is a date of creation in NeoFS epochs + uint64 Epoch = 2; } message IntegrityHeader { - bytes HeadersChecksum = 1; // Checksum of all above headers in the object - bytes ChecksumSignature = 2; // User's signature of checksum to verify if it is correct + // HeadersChecksum is a checksum of all above headers in the object + bytes HeadersChecksum = 1; + // ChecksumSignature is an user's signature of checksum to verify if it is correct + bytes ChecksumSignature = 2; } message Link { enum Type { 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 + // Parent object created during object transformation + Parent = 1; + // Previous object in the linked list created during object transformation + Previous = 2; + // Next object in the linked list created during object transformation + Next = 3; + // Child object created during object transformation + Child = 4; + // Object that included into this storage group + StorageGroup = 5; } - Type type = 1; // Link type - bytes ID = 2 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false]; // Object id + // Type of link + Type type = 1; + // ID is an object identifier, is a valid UUIDv4 + bytes ID = 2 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false]; } message Transform { enum Type { Unknown = 0; - Split = 1; // Object created after payload split - Sign = 2; // Object created after re-signing (doesn't used) - Mould = 3; // Object created after filling missing headers in the object + // Split sets when object created after payload split + Split = 1; + // Sign sets when object created after re-signing (doesn't used) + Sign = 2; + // Mould sets when object created after filling missing headers in the object + Mould = 3; } - Type type = 1; // Type of object transformation + // Type of object transformation + Type type = 1; } message Object { - SystemHeader SystemHeader = 1 [(gogoproto.nullable) = false]; // System header - repeated Header Headers = 2 [(gogoproto.nullable) = false]; // Extended headers - bytes Payload = 3; // Object's payload + // SystemHeader describes system header + SystemHeader SystemHeader = 1 [(gogoproto.nullable) = false]; + // Headers describes a set of an extended headers + repeated Header Headers = 2 [(gogoproto.nullable) = false]; + // Payload is an object's payload + bytes Payload = 3; } message StorageGroup { - uint64 ValidationDataSize = 1; // Size of the all object's payloads included into storage group - bytes ValidationHash = 2 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false]; // Homomorphic hash of all object's payloads included into storage group + // ValidationDataSize is size of the all object's payloads included into storage group + uint64 ValidationDataSize = 1; + // ValidationHash is homomorphic hash of all object's payloads included into storage group + bytes ValidationHash = 2 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false]; message Lifetime { enum Unit { - Unlimited = 0; // Storage group always valid - NeoFSEpoch = 1; // Storage group is valid until lifetime NeoFS epoch - UnixTime = 2; // Storage group is valid until lifetime unix timestamp + // Unlimited set if storage group always valid + Unlimited = 0; + // NeoFSEpoch set if storage group is valid until lifetime NeoFS epoch + NeoFSEpoch = 1; + // UnixTime set if storage group is valid until lifetime unix timestamp + UnixTime = 2; } - Unit unit = 1 [(gogoproto.customname) = "Unit"]; // Lifetime type - int64 Value = 2; // Lifetime value + // Unit is lifetime type + Unit unit = 1 [(gogoproto.customname) = "Unit"]; + // Value for lifetime + int64 Value = 2; } - Lifetime lifetime = 3 [(gogoproto.customname) = "Lifetime"]; // Time until storage group is valid + // Lifetime is time until storage group is valid + Lifetime lifetime = 3 [(gogoproto.customname) = "Lifetime"]; } diff --git a/query/types.proto b/query/types.proto index 884a6bd..6eaed5d 100644 --- a/query/types.proto +++ b/query/types.proto @@ -9,9 +9,10 @@ option (gogoproto.stable_marshaler_all) = true; message Filter { option (gogoproto.goproto_stringer) = false; - // Type can be Exact or Regex enum Type { + // Exact sets when value of filter should be equal to the header value Exact = 0; + // Regex sets when value of filter should match the header value by the regular expression Regex = 1; } diff --git a/refs/types.proto b/refs/types.proto index 15355ae..8c7d2eb 100644 --- a/refs/types.proto +++ b/refs/types.proto @@ -11,7 +11,7 @@ option (gogoproto.goproto_stringer_all) = false; // Address of object (container id + object id) message Address { - // ObjectID is an object identifier + // ObjectID is an object identifier, valid UUIDv4 represented in bytes bytes ObjectID = 1[(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false]; // CID is container identifier bytes CID = 2[(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; diff --git a/session/service.proto b/session/service.proto index 484425b..4b37aaf 100644 --- a/session/service.proto +++ b/session/service.proto @@ -9,17 +9,16 @@ option (gogoproto.stable_marshaler_all) = true; service Session { - // Open a trusted session to manipulate an object. In order to put or - // delete object client have to obtain session token with trusted node. - // Trusted node will modify client's object (add missing headers, checksums, - // homomorphic hash) and sign id with session key. Session is established - // during 4-step handshake in one gRPC stream - + // Create is a method that used to open a trusted session to manipulate + // an object. In order to put or delete object client have to obtain session + // token with trusted node. Trusted node will modify client's object + // (add missing headers, checksums, homomorphic hash) and sign id with + // session key. Session is established during 4-step handshake in one gRPC stream + // // - First client stream message SHOULD BE type of `CreateRequest_Init`. // - First server stream message SHOULD BE type of `CreateResponse_Unsigned`. // - Second client stream message SHOULD BE type of `CreateRequest_Signed`. // - Second server stream message SHOULD BE type of `CreateResponse_Result`. - rpc Create (stream CreateRequest) returns (stream CreateResponse); } @@ -27,7 +26,7 @@ service Session { message CreateRequest { // Message should be one of oneof Message { - // Message to init session opening. Carry: + // Init is a message to initialize session opening. Carry: // owner of manipulation object; // ID of manipulation object; // token lifetime bounds. @@ -41,7 +40,7 @@ message CreateResponse { oneof Message { // Unsigned token with token ID and session public key generated on server side session.Token Unsigned = 1; - // Resulting token which can be used for object placing through an trusted intermediary + // Result is a resulting token which can be used for object placing through an trusted intermediary session.Token Result = 2; } } diff --git a/session/types.proto b/session/types.proto index bf804bf..1ade791 100644 --- a/session/types.proto +++ b/session/types.proto @@ -7,9 +7,9 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; message VerificationHeader { - // Session public key + // PublicKey is a session public key bytes PublicKey = 1; - // Session public key signature. Signed by trusted side + // KeySignature is a session public key signature. Signed by trusted side bytes KeySignature = 2; } @@ -17,16 +17,16 @@ message VerificationHeader { message Token { // Header carries verification data of session key VerificationHeader Header = 1 [(gogoproto.nullable) = false]; - // Owner of manipulation object + // OwnerID is an owner of manipulation object bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; - // Initial epoch of token lifetime + // FirstEpoch is an initial epoch of token lifetime uint64 FirstEpoch = 3; - // Last epoch of token lifetime + // LastEpoch is a last epoch of token lifetime uint64 LastEpoch = 4; - // ID of manipulation object + // ObjectID is an object identifier of manipulation object repeated bytes ObjectID = 5 [(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false]; - // Token signature. Signed by owner of manipulation object + // Signature is a token signature, signed by owner of manipulation object bytes Signature = 6; - // Token ID (UUID) + // ID is a token identifier. valid UUIDv4 represented in bytes bytes ID = 7 [(gogoproto.customtype) = "TokenID", (gogoproto.nullable) = false]; }