Update netmap package docs

Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>
This commit is contained in:
Stanislav Bogatyrev 2020-10-15 10:50:36 +03:00 committed by Stanislav Bogatyrev
parent f51ee1ba9d
commit 3f6c211fef
2 changed files with 44 additions and 29 deletions

View file

@ -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;
}

View file

@ -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