From f80e52fbea8b5f2b441185482c1411deec4ff265 Mon Sep 17 00:00:00 2001 From: Evgenii Stratonikov Date: Thu, 19 May 2022 14:53:16 +0300 Subject: [PATCH] [#1334] services/tree: Document *.proto files Signed-off-by: Evgenii Stratonikov --- pkg/services/tree/service.proto | 90 ++++++++++++++++++++++++++++++++- pkg/services/tree/types.proto | 7 +++ 2 files changed, 96 insertions(+), 1 deletion(-) diff --git a/pkg/services/tree/service.proto b/pkg/services/tree/service.proto index af5bc1808..94741c4da 100644 --- a/pkg/services/tree/service.proto +++ b/pkg/services/tree/service.proto @@ -1,3 +1,6 @@ +/** + * Service for working with CRDT tree. + */ syntax = "proto3"; package tree; @@ -6,7 +9,6 @@ import "pkg/services/tree/types.proto"; option go_package = "github.com/nspcc-dev/neofs-node/pkg/services/tree"; -// `TreeService` provides an interface for working with distributed tree. service TreeService { /* Client API */ @@ -28,66 +30,95 @@ service TreeService { // Apply pushes log operation from another node to the current. // The request must be signed by a container node. rpc Apply (ApplyRequest) returns (ApplyResponse); + // GetOpLog returns a stream of logged operations starting from some height. rpc GetOpLog(GetOpLogRequest) returns (stream GetOpLogResponse); } message AddRequest { message Body { + // Container ID in V2 format. bytes container_id = 1; + // The name of the tree. string tree_id = 2; + // ID of the parent to attach node to. uint64 parent_id = 3; + // Key-Value pairs with meta information. repeated KeyValue meta = 4; + // Bearer token in V2 format. bytes bearer_token = 5; } + // Request body. Body body = 1; + // Request signature. Signature signature = 2; } message AddResponse { message Body { + // ID of the created node. uint64 node_id = 1; } + // Response body. Body body = 1; + // Response signature. Signature signature = 2; }; message AddByPathRequest { message Body { + // Container ID in V2 format. bytes container_id = 1; + // The name of the tree. string tree_id = 2; + // Attribute to build path with. Default: "FileName". string path_attribute = 3; + // List of path components. repeated string path = 4; + // Node meta-information. repeated KeyValue meta = 5; + // Bearer token in V2 format. bytes bearer_token = 6; } + // Request body. Body body = 1; + // Request signature. Signature signature = 2; } message AddByPathResponse { message Body { + // List of all created nodes. The first one is the leaf. repeated uint64 nodes = 1; + // ID of the parent node where new nodes were attached. uint64 parent_id = 2; } + // Response body. Body body = 1; + // Response signature. Signature signature = 2; }; message RemoveRequest { message Body { + // Container ID in V2 format. bytes container_id = 1; + // The name of the tree. string tree_id = 2; + // ID of the node to remove. uint64 node_id = 3; + // Bearer token in V2 format. bytes bearer_token = 4; } + // Request body. Body body = 1; + // Request signature. Signature signature = 2; } @@ -95,7 +126,9 @@ message RemoveResponse { message Body { } + // Response body. Body body = 1; + // Response signature. Signature signature = 2; }; @@ -103,15 +136,23 @@ message RemoveResponse { message MoveRequest { message Body { // TODO import neo.fs.v2.refs.ContainerID directly. + // Container ID in V2 format. bytes container_id = 1; + // The name of the tree. string tree_id = 2; + // ID of the new parent. uint64 parent_id = 3; + // ID of the node to move. uint64 node_id = 4; + // Node meta-information. repeated KeyValue meta = 5; + // Bearer token in V2 format. bytes bearer_token = 6; } + // Request body. Body body = 1; + // Request signature. Signature signature = 2; } @@ -119,78 +160,114 @@ message MoveResponse { message Body { } + // Response body. Body body = 1; + // Response signature. Signature signature = 2; }; message GetNodeByPathRequest { message Body { + // Container ID in V2 format. bytes container_id = 1; + // The name of the tree. string tree_id = 2; + // Attribute to build path with. Default: "FileName". string path_attribute = 3; + // List of path components. repeated string path = 4; + // List of attributes to include in response. repeated string attributes = 5; + // Flag to return only the latest version of node. bool latest_only = 6; + // Flag to return all stored attributes. bool all_attributes = 7; + // Bearer token in V2 format. bytes bearer_token = 8; } + // Request body. Body body = 1; + // Request signature. Signature signature = 2; } message GetNodeByPathResponse { + // Information about a single tree node. message Info { + // Node ID. uint64 node_id = 1; + // Timestamp of the last operation with the node. uint64 timestamp = 2; + // Node meta-information. repeated KeyValue meta = 3; } message Body { + // List of nodes stored by path. repeated Info nodes = 1; } + // Response body. Body body = 1; + // Response signature. Signature signature = 2; }; message GetSubTreeRequest { message Body { + // Container ID in V2 format. bytes container_id = 1; + // The name of the tree. string tree_id = 2; + // ID of the root node of a subtree. uint64 root_id = 3; // Optional depth of the traversal. Zero means return only root. // Maximum depth is 10. uint32 depth = 4; + // Bearer token in V2 format. bytes bearer_token = 5; } + // Request body. Body body = 1; + // Request signature. Signature signature = 2; } message GetSubTreeResponse { message Body { + // ID of the node. uint64 node_id = 1; + // ID of the parent. uint64 parent_id = 2; + // Time node was first added to a tree. uint64 timestamp = 3; + // Node meta-information. repeated KeyValue meta = 4; } + // Response body. Body body = 1; + // Response signature. Signature signature = 2; }; message ApplyRequest { message Body { + // Container ID in V2 format. bytes container_id = 1; + // The name of the tree. string tree_id = 2; + // Operation to be applied. LogMove operation = 3; } + // Request body. Body body = 1; + // Request signature. Signature signature = 2; } @@ -198,28 +275,39 @@ message ApplyResponse { message Body { } + // Response body. Body body = 1; + // Response signature. Signature signature = 2; }; message GetOpLogRequest { message Body { + // Container ID in V2 format. bytes container_id = 1; + // The name of the tree. string tree_id = 2; + // Starting height to return logs from. uint64 height = 3; + // Amount of operations to return. uint64 count = 4; } + // Request body. Body body = 1; + // Request signature. Signature signature = 2; } message GetOpLogResponse { message Body { + // Operation on a tree. LogMove operation = 1; } + // Response body. Body body = 1; + // Response signature. Signature signature = 2; }; diff --git a/pkg/services/tree/types.proto b/pkg/services/tree/types.proto index 546985c0c..317631bd5 100644 --- a/pkg/services/tree/types.proto +++ b/pkg/services/tree/types.proto @@ -1,3 +1,6 @@ +/** + * Auxiliary structures to use with tree service. + */ syntax = "proto3"; package tree; @@ -6,7 +9,9 @@ option go_package = "github.com/nspcc-dev/neofs-node/pkg/services/tree"; // KeyValue represents key-value pair attached to an object. message KeyValue { + // Attribute name. string key = 1 [json_name = "key"]; + // Attribute value. bytes value = 2 [json_name = "value"]; } @@ -22,6 +27,8 @@ message LogMove { // Signature of a message. message Signature { + // Serialized public key as defined in NeoFS API. bytes key = 1 [json_name = "key"]; + // Signature of a message body. bytes sign = 2 [json_name = "signature"]; }