From 3f6c211fef002a507b61d737174f60bbaa260353 Mon Sep 17 00:00:00 2001 From: Stanislav Bogatyrev Date: Thu, 15 Oct 2020 10:50:36 +0300 Subject: [PATCH] Update netmap package docs Signed-off-by: Stanislav Bogatyrev --- netmap/service.proto | 33 ++++++++++++++++++++------------- netmap/types.proto | 40 ++++++++++++++++++++++++---------------- 2 files changed, 44 insertions(+), 29 deletions(-) diff --git a/netmap/service.proto b/netmap/service.proto index a388148..329cbb9 100644 --- a/netmap/service.proto +++ b/netmap/service.proto @@ -9,18 +9,25 @@ import "netmap/types.proto"; import "refs/types.proto"; import "session/types.proto"; -// Methods to work with NetworkMap +// `NetmapService` provides methods to work with `Network Map` and information +// required to build it. The resulting `Network Map` is stored in sidechain +// `Netmap` smart contract, while related information can be obtained from other +// NeoFS nodes. service NetmapService { - // Return information about Node + // Get NodeInfo structure from the particular node directly. Node information + // can be taken from `Netmap` smart contract, but in some cases the one may + // want to get recent information directly, or to talk to the node not yet + // present in `Network Map` to find out what API version can be used for + // further communication. Can also be used to check if node is up and running. rpc LocalNodeInfo (LocalNodeInfoRequest) returns (LocalNodeInfoResponse); } -// Get NodeInfo from the particular node directly +// Get NodeInfo structure from the particular node directly message LocalNodeInfoRequest { - //Request body + // LocalNodeInfo request body is empty. message Body { } - // Body of the balance request message. + // Body of the LocalNodeInfo request message Body body = 1; // Carries request meta information. Header data is used only to regulate @@ -28,19 +35,19 @@ message LocalNodeInfoRequest { 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. + // authenticate the nodes of the message route and check the correctness of + // transmission. neo.fs.v2.session.RequestVerificationHeader verify_header = 3; } -// Local nod Info, including API Version in use +// Local Node Info, including API Version in use message LocalNodeInfoResponse { - //Response body + // Local Node Info, including API Version in use. message Body { - // API version in use + // Latest NeoFS API version in use neo.fs.v2.refs.Version version = 1; - // NodeInfo from node itself + // NodeInfo structure with recent information from node itself NodeInfo node_info = 2; } // Body of the balance response message. @@ -51,7 +58,7 @@ message LocalNodeInfoResponse { 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/netmap/types.proto b/netmap/types.proto index dd5bfe3..ccfe546 100644 --- a/netmap/types.proto +++ b/netmap/types.proto @@ -35,9 +35,9 @@ enum Operation { AND = 8; } -// Selector modifier showing how the node set will be formed -// By default selector just groups by attribute into a bucket selecting nodes -// only by their hash distance. +// Selector modifier shows how the node set will be formed. By default selector +// just groups nodes into a bucket by attribute, selecting nodes only by their +// hash distance. enum Clause{ // No modifier defined. Will select nodes from bucket randomly. CLAUSE_UNSPECIFIED = 0; @@ -49,12 +49,13 @@ enum Clause{ DISTINCT = 2; } -// Filter +// Filter will return the subset of nodes from `NetworkMap` or another filter's +// results, that will satisfy filter's conditions. message Filter { - // Name of the filter or a reference to the named filter. - // '*' means application to the whole unfiltered NetworkMap - // At top level it's used as a filter name. At lower levels it's considered to - // be a reference to another named filter + // Name of the filter or a reference to the named filter. '*' means + // application to the whole unfiltered NetworkMap. At top level it's used as a + // filter name. At lower levels it's considered to be a reference to another + // named filter string name = 1; // Key to filter @@ -66,16 +67,18 @@ message Filter { // Value to match string value = 4; - // List of inner filters. Top level operation will be applied to the whole list. + // List of inner filters. Top level operation will be applied to the whole + // list. repeated Filter filters = 5; } -// Selector +// Selector chooses a number of nodes from the bucket taking the nearest nodes +// to the provided `ContainerID` by hash distance. message Selector { // Selector name to reference in object placement section string name = 1; - // How many nodes to select from bucket + // How many nodes to select from the bucket uint32 count = 2; // Selector modifier showing how to form a bucket @@ -88,22 +91,27 @@ message Selector { string filter = 5; } -// Exact bucket for each replica +// Number of object replicas in a set of nodes from the defined selector. If no +// selector set the root bucket containing all possible nodes will be used by +// default. message Replica { // How many object replicas to put uint32 count = 1; - // Named selector bucket to put in + // Named selector bucket to put replicas string selector = 2; } -// Set of rules to select a subset of nodes able to store container's objects +// Set of rules to select a subset of nodes from `NetworkMap` able to store +// container's objects. The format is simple enough to transpile from different +// storage policy definition languages. message PlacementPolicy { - // Rules to set number of object replicas and place each one into a particular bucket + // Rules to set number of object replicas and place each one into a named + // bucket repeated Replica replicas = 1; // Container backup factor controls how deep NeoFS will search for nodes - // alternatives to include into container. + // alternatives to include into container's nodes subset uint32 container_backup_factor = 2; // Set of Selectors to form the container's nodes subset