aarifullin/frostfs-api-go
1
0
Fork 0
forked from TrueCloudLab/frostfs-api-go
Code Pull requests Activity

docs: update proto doc comments to satisfy go-doc comment

Browse source
This commit is contained in:
Evgeniy Kulikov 2019-11-21 10:26:01 +03:00
parent 7c0fef06fd
commit 15b997bdb5
No known key found for this signature in database
GPG key ID: BF6AEE0A2A699BF2
8 changed files with 201 additions and 111 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
accounting/withdraw.proto
View file

@ -42,7 +42,7 @@ message GetRequest {
} }
message GetResponse { message GetResponse {
// Item is cheque with meta information // Withdraw is cheque with meta information
Item Withdraw = 1; Item Withdraw = 1;
} }
@ -73,7 +73,7 @@ message ListRequest {
} }
message ListResponse { message ListResponse {
// Item is a set of cheques with meta information // Items is a set of cheques with meta information
repeated Item Items = 1; repeated Item Items = 1;
} }

12
container/types.proto
View file

@ -9,8 +9,12 @@ option (gogoproto.stable_marshaler_all) = true;
// The Container service definition. // The Container service definition.
message Container { message Container {
bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; // OwnerID is a wallet address. // OwnerID is a wallet address.
bytes Salt = 2 [(gogoproto.customtype) = "UUID", (gogoproto.nullable) = false]; // Salt is a nonce for unique container id calculation. bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
uint64 Capacity = 3; // Capacity defines amount of data that can be stored in the container (doesn't used for now). // Salt is a nonce for unique container id calculation.
netmap.PlacementRule Rules = 4 [(gogoproto.nullable) = false]; // Rules define storage policy for the object inside the container. 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];
} }

117
object/service.proto
View file

@ -52,41 +52,58 @@ service Service {
} }
message GetRequest { message GetRequest {
uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value // 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) uint64 Epoch = 1;
uint32 TTL = 3; // TTL must be larger than zero, it decreased in every neofs-node // 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 { message GetResponse {
oneof R { oneof R {
Object object = 1; // Object header and some payload // Object header and some payload
bytes Chunk = 2; // Chunk of remaining payload Object object = 1;
// Chunk of remaining payload
bytes Chunk = 2;
} }
} }
message PutRequest { message PutRequest {
message PutHeader { message PutHeader {
uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value // 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 uint64 Epoch = 1;
uint32 TTL = 3; // TTL must be larger than zero, it decreased in every neofs-node // Object with at least container id and owner id fields
session.Token Token = 4; // Token with session public key and user's signature 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 { oneof R {
PutHeader Header = 1; // Header should be the first message in the stream // Header should be the first message in the stream
bytes Chunk = 2; // Chunk should be a remaining message in stream should be chunks PutHeader Header = 1;
// Chunk should be a remaining message in stream should be chunks
bytes Chunk = 2;
} }
} }
message PutResponse { 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 { message DeleteRequest {
uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value // 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) uint64 Epoch = 1;
bytes OwnerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "OwnerID"]; // OwnerID is a wallet address // Address of object (container id + object id)
uint32 TTL = 4; // TTL must be larger than zero, it decreased in every neofs-node refs.Address Address = 2 [(gogoproto.nullable) = false];
session.Token Token = 5; // Token with session public key and user's signature // 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 // DeleteResponse is empty because we cannot guarantee permanent object removal
@ -94,47 +111,69 @@ message DeleteRequest {
message DeleteResponse {} message DeleteResponse {}
message HeadRequest { message HeadRequest {
uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value // Epoch should be empty on user side, node sets epoch to the actual value
refs.Address Address = 2 [(gogoproto.nullable) = false, (gogoproto.customtype) = "Address"]; // Address of object (container id + object id) uint64 Epoch = 1;
bool FullHeaders = 3; // FullHeaders can be set true for extended headers in the object // Address of object (container id + object id)
uint32 TTL = 4; // TTL must be larger than zero, it decreased in every neofs-node 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 { message HeadResponse {
Object Object = 1; // Object without payload // Object without payload
Object Object = 1;
} }
message SearchRequest { message SearchRequest {
uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value // Epoch is set by user to 0, node set epoch to the actual value
uint32 Version = 2; // Version of search query format uint64 Epoch = 1;
bytes ContainerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "CID"]; // ContainerID for searching the object // Version of search query format
bytes Query = 4; // Query in the binary serialized format uint32 Version = 2;
uint32 TTL = 5; // TTL must be larger than zero, it decreased in every neofs-node // 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 { 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 { message GetRangeRequest {
uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value // 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) uint64 Epoch = 1;
repeated Range Ranges = 3 [(gogoproto.nullable) = false]; // Ranges of object's payload to return // Address of object (container id + object id)
uint32 TTL = 4; // TTL must be larger than zero, it decreased in every neofs-node 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 { message GetRangeResponse {
repeated bytes Fragments = 1; // Fragments of object's payload // Fragments of object's payload
repeated bytes Fragments = 1;
} }
message GetRangeHashRequest { message GetRangeHashRequest {
uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value // 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) uint64 Epoch = 1;
repeated Range Ranges = 3 [(gogoproto.nullable) = false]; // Ranges of object's payload to calculate homomorphic hash // Address of object (container id + object id)
bytes Salt = 4; // Salt is used to XOR object's payload ranges before hashing, it can be nil refs.Address Address = 2 [(gogoproto.nullable) = false];
uint32 TTL = 5; // TTL must be larger than zero, it decreased in every neofs-node // 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 { 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];
} }

141
object/types.proto
View file

@ -9,97 +9,144 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
message Range { message Range {
uint64 Offset = 1; // Offset of the data range // Offset of the data range
uint64 Length = 2; // Length of the data range uint64 Offset = 1;
// Length of the data range
uint64 Length = 2;
} }
message UserHeader { message UserHeader {
string Key = 1; // Key of the user's header // Key of the user's header
string Value = 2; // Value of the user's header string Key = 1;
// Value of the user's header
string Value = 2;
} }
message Header { message Header {
oneof Value { oneof Value {
Link Link = 1; // Link to other objects // Link to other objects
refs.Address Redirect = 2; // RedirectNot used yet Link Link = 1;
UserHeader UserHeader = 3; // UserHeader defined by user // Redirect not used yet
Transform Transform = 4; // Transform defines transform operation (e.g. payload split) refs.Address Redirect = 2;
Tombstone Tombstone = 5; // Tombstone header that set up in deleted objects // UserHeader is a set of KV headers defined by user
session.VerificationHeader Verify = 6; // Verify header that contains session public key and user's signature UserHeader UserHeader = 3;
bytes HomoHash = 7 [(gogoproto.customtype) = "Hash"]; // Homomorphic hash of original object payload // Transform defines transform operation (e.g. payload split)
bytes PayloadChecksum = 8; // PayloadChecksum of actual object's payload Transform Transform = 4;
IntegrityHeader Integrity = 9; // Integrity header with checksum of all above headers in the object // Tombstone header that set up in deleted objects
StorageGroup StorageGroup = 10; // StorageGroup contains meta information for the data audit 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 { message Tombstone {
uint64 Epoch = 1; // Epoch when tombstone was created // Epoch when tombstone was created
uint64 Epoch = 1;
} }
message SystemHeader { message SystemHeader {
uint64 Version = 1; // Version of the object structure // Version of the object structure
uint64 PayloadLength = 2; // Object payload length 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 // ID is an object identifier, is a valid UUIDv4
bytes OwnerID = 4 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; // OwnerID is a wallet address bytes ID = 3 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false];
bytes CID = 5 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; // ContainerID is a SHA256 hash of the container structure // OwnerID is a wallet address
CreationPoint CreatedAt = 6 [(gogoproto.nullable) = false]; // Timestamp of object creation 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 { message CreationPoint {
int64 UnixTime = 1; // Date of creation in unixtime format // UnixTime is a date of creation in unixtime format
uint64 Epoch = 2; // Date of creation in NeoFS epochs int64 UnixTime = 1;
// Epoch is a date of creation in NeoFS epochs
uint64 Epoch = 2;
} }
message IntegrityHeader { message IntegrityHeader {
bytes HeadersChecksum = 1; // Checksum of all above headers in the object // HeadersChecksum is a checksum of all above headers in the object
bytes ChecksumSignature = 2; // User's signature of checksum to verify if it is correct bytes HeadersChecksum = 1;
// ChecksumSignature is an user's signature of checksum to verify if it is correct
bytes ChecksumSignature = 2;
} }
message Link { message Link {
enum Type { enum Type {
Unknown = 0; Unknown = 0;
Parent = 1; // Parent object created during object transformation // Parent object created during object transformation
Previous = 2; // Previous object in the linked list created during object transformation Parent = 1;
Next = 3; // Next object in the linked list created during object transformation // Previous object in the linked list created during object transformation
Child = 4; // Child object created during object transformation Previous = 2;
StorageGroup = 5; // Object that included into this storage group // 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 // Type of link
bytes ID = 2 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false]; // Object id Type type = 1;
// ID is an object identifier, is a valid UUIDv4
bytes ID = 2 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false];
} }
message Transform { message Transform {
enum Type { enum Type {
Unknown = 0; Unknown = 0;
Split = 1; // Object created after payload split // Split sets when object created after payload split
Sign = 2; // Object created after re-signing (doesn't used) Split = 1;
Mould = 3; // Object created after filling missing headers in the object // 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 { message Object {
SystemHeader SystemHeader = 1 [(gogoproto.nullable) = false]; // System header // SystemHeader describes system header
repeated Header Headers = 2 [(gogoproto.nullable) = false]; // Extended headers SystemHeader SystemHeader = 1 [(gogoproto.nullable) = false];
bytes Payload = 3; // Object's payload // 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 { message StorageGroup {
uint64 ValidationDataSize = 1; // Size of the all object's payloads included into storage group // ValidationDataSize is 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 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 { message Lifetime {
enum Unit { enum Unit {
Unlimited = 0; // Storage group always valid // Unlimited set if storage group always valid
NeoFSEpoch = 1; // Storage group is valid until lifetime NeoFS epoch Unlimited = 0;
UnixTime = 2; // Storage group is valid until lifetime unix timestamp // 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 // Unit is lifetime type
int64 Value = 2; // Lifetime value 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"];
} }

3
query/types.proto
View file

@ -9,9 +9,10 @@ option (gogoproto.stable_marshaler_all) = true;
message Filter { message Filter {
option (gogoproto.goproto_stringer) = false; option (gogoproto.goproto_stringer) = false;
// Type can be Exact or Regex
enum Type { enum Type {
// Exact sets when value of filter should be equal to the header value
Exact = 0; Exact = 0;
// Regex sets when value of filter should match the header value by the regular expression
Regex = 1; Regex = 1;
} }

2
refs/types.proto
View file

@ -11,7 +11,7 @@ option (gogoproto.goproto_stringer_all) = false;
// Address of object (container id + object id) // Address of object (container id + object id)
message Address { 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]; bytes ObjectID = 1[(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false];
// CID is container identifier // CID is container identifier
bytes CID = 2[(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; bytes CID = 2[(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];

17
session/service.proto
View file

@ -9,17 +9,16 @@ option (gogoproto.stable_marshaler_all) = true;
service Session { service Session {
// Open a trusted session to manipulate an object. In order to put or // Create is a method that used to open a trusted session to manipulate
// delete object client have to obtain session token with trusted node. // an object. In order to put or delete object client have to obtain session
// Trusted node will modify client's object (add missing headers, checksums, // token with trusted node. Trusted node will modify client's object
// homomorphic hash) and sign id with session key. Session is established // (add missing headers, checksums, homomorphic hash) and sign id with
// during 4-step handshake in one gRPC stream // session key. Session is established during 4-step handshake in one gRPC stream
//
// - First client stream message SHOULD BE type of `CreateRequest_Init`. // - First client stream message SHOULD BE type of `CreateRequest_Init`.
// - First server stream message SHOULD BE type of `CreateResponse_Unsigned`. // - First server stream message SHOULD BE type of `CreateResponse_Unsigned`.
// - Second client stream message SHOULD BE type of `CreateRequest_Signed`. // - Second client stream message SHOULD BE type of `CreateRequest_Signed`.
// - Second server stream message SHOULD BE type of `CreateResponse_Result`. // - Second server stream message SHOULD BE type of `CreateResponse_Result`.
rpc Create (stream CreateRequest) returns (stream CreateResponse); rpc Create (stream CreateRequest) returns (stream CreateResponse);
} }
@ -27,7 +26,7 @@ service Session {
message CreateRequest { message CreateRequest {
// Message should be one of // Message should be one of
oneof Message { oneof Message {
// Message to init session opening. Carry: // Init is a message to initialize session opening. Carry:
// owner of manipulation object; // owner of manipulation object;
// ID of manipulation object; // ID of manipulation object;
// token lifetime bounds. // token lifetime bounds.
@ -41,7 +40,7 @@ message CreateResponse {
oneof Message { oneof Message {
// Unsigned token with token ID and session public key generated on server side // Unsigned token with token ID and session public key generated on server side
session.Token Unsigned = 1; 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; session.Token Result = 2;
} }
} }

16
session/types.proto
View file

@ -7,9 +7,9 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
message VerificationHeader { message VerificationHeader {
// Session public key // PublicKey is a session public key
bytes PublicKey = 1; 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; bytes KeySignature = 2;
} }
@ -17,16 +17,16 @@ message VerificationHeader {
message Token { message Token {
// Header carries verification data of session key // Header carries verification data of session key
VerificationHeader Header = 1 [(gogoproto.nullable) = false]; 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]; 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; uint64 FirstEpoch = 3;
// Last epoch of token lifetime // LastEpoch is a last epoch of token lifetime
uint64 LastEpoch = 4; 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]; 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; 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]; bytes ID = 7 [(gogoproto.customtype) = "TokenID", (gogoproto.nullable) = false];
} }