frostfs-api/proto-docs/netmap.md
Leonard Lyubich 6846e300e7 [#160] netmap: Provide the ability to announce multiple addresses
Make `address` field of `netmap.NodeInfo` message repeated (with
corresponding renaming).

Signed-off-by: Leonard Lyubich <leonard@nspcc.ru>
2021-06-23 15:28:36 +03:00

17 KiB

Protocol Documentation

Table of Contents

Top

netmap/service.proto

Service "neo.fs.v2.netmap.NetmapService"

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.

rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
rpc NetworkInfo(NetworkInfoRequest) returns (NetworkInfoResponse);

Method LocalNodeInfo

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.

Name Input Output
LocalNodeInfo LocalNodeInfoRequest LocalNodeInfoResponse

Method NetworkInfo

Read recent information about the NeoFS network.

Name Input Output
NetworkInfo NetworkInfoRequest NetworkInfoResponse

Message LocalNodeInfoRequest

Get NodeInfo structure from the particular node directly

Field Type Label Description
body LocalNodeInfoRequest.Body Body of the LocalNodeInfo request message
meta_header neo.fs.v2.session.RequestMetaHeader Carries request meta information. Header data is used only to regulate message transport and does not affect request execution.
verify_header neo.fs.v2.session.RequestVerificationHeader Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message LocalNodeInfoRequest.Body

LocalNodeInfo request body is empty.

Message LocalNodeInfoResponse

Local Node Info, including API Version in use

Field Type Label Description
body LocalNodeInfoResponse.Body Body of the balance response message.
meta_header neo.fs.v2.session.ResponseMetaHeader Carries response meta information. Header data is used only to regulate message transport and does not affect response execution.
verify_header neo.fs.v2.session.ResponseVerificationHeader Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message LocalNodeInfoResponse.Body

Local Node Info, including API Version in use.

Field Type Label Description
version neo.fs.v2.refs.Version Latest NeoFS API version in use
node_info NodeInfo NodeInfo structure with recent information from node itself

Message NetworkInfoRequest

Get NetworkInfo structure with the network view from particular node.

Field Type Label Description
body NetworkInfoRequest.Body Body of the NetworkInfo request message
meta_header neo.fs.v2.session.RequestMetaHeader Carries request meta information. Header data is used only to regulate message transport and does not affect request execution.
verify_header neo.fs.v2.session.RequestVerificationHeader Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message NetworkInfoRequest.Body

NetworkInfo request body is empty.

Message NetworkInfoResponse

Response with NetworkInfo structure including current epoch and sidechain magic number.

Field Type Label Description
body NetworkInfoResponse.Body Body of the NetworkInfo response message.
meta_header neo.fs.v2.session.ResponseMetaHeader Carries response meta information. Header data is used only to regulate message transport and does not affect response execution.
verify_header neo.fs.v2.session.ResponseVerificationHeader Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message NetworkInfoResponse.Body

Information about the network.

Field Type Label Description
network_info NetworkInfo NetworkInfo structure with recent information.

Top

netmap/types.proto

Message Filter

Filter will return the subset of nodes from NetworkMap or another filter's results, that will satisfy filter's conditions.

Field Type Label Description
name string 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
key string Key to filter
op Operation Filtering operation
value string Value to match
filters Filter repeated List of inner filters. Top level operation will be applied to the whole list.

Message NetworkInfo

Information about NeoFS network

Field Type Label Description
current_epoch uint64 Number of the current epoch in the NeoFS network.
magic_number uint64 Magic number of the sidechain of the NeoFS network.

Message NodeInfo

NeoFS node description

Field Type Label Description
public_key bytes Public key of the NeoFS node in a binary format.
addresses string repeated Ways to connect to a node
attributes NodeInfo.Attribute repeated Carries list of the NeoFS node attributes in a key-value form. Key name must be a node-unique valid UTF-8 string. Value can't be empty. NodeInfo structures with duplicated attribute names or attributes with empty values will be considered invalid.
state NodeInfo.State Carries state of the NeoFS node.

Message NodeInfo.Attribute

Administrator-defined Attributes of the NeoFS Storage Node.

Attribute is a Key-Value metadata pair. Key name must be a valid UTF-8 string. Value can't be empty.

Node's attributes are mostly used during Storage Policy evaluation to calculate object's placement and find a set of nodes satisfying policy requirements. There are some "well-known" node attributes common to all the Storage Nodes in the network and used implicitly with default values if not explicitly set:

  • Capacity
    Total available disk space in Gigabytes.
  • Price
    Price in GAS tokens for storing one GB of data during one Epoch. In node attributes it's a string presenting floating point number with comma or point delimiter for decimal part. In the Network Map it will be saved as 64-bit unsigned integer representing number of minimal token fractions.
  • Subnet
    String ID of Node's storage subnet. There can be only one subnet served by the Storage Node.
  • UN-LOCODE
    Node's geographic location in UN/LOCODE format approximated to the nearest point defined in the standard.
  • CountryCode
    Country code in ISO 3166-1_alpha-2 format. Calculated automatically from UN-LOCODE attribute.
  • Country
    Country short name in English, as defined in ISO-3166. Calculated automatically from UN-LOCODE attribute.
  • Location
    Place names are given, whenever possible, in their national language versions as expressed in the Roman alphabet using the 26 characters of the character set adopted for international trade data interchange, written without diacritics . Calculated automatically from UN-LOCODE attribute.
  • SubDivCode
    Country's administrative subdivision where node is located. Calculated automatically from UN-LOCODE attribute based on SubDiv field. Presented in ISO 3166-2 format.
  • SubDiv
    Country's administrative subdivision name, as defined in ISO 3166-2. Calculated automatically from UN-LOCODE attribute.
  • Continent
    Node's continent name according to the [Seven-Continent model] (https://en.wikipedia.org/wiki/Continent#Number). Calculated automatically from UN-LOCODE attribute.

For detailed description of each well-known attribute please see the corresponding section in NeoFS Technical specification.

Field Type Label Description
key string Key of the node attribute.
value string Value of the node attribute.
parents string repeated Parent keys, if any. For example for City it could be Region and Country.

Message PlacementPolicy

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.

Field Type Label Description
replicas Replica repeated Rules to set number of object replicas and place each one into a named bucket
container_backup_factor uint32 Container backup factor controls how deep NeoFS will search for nodes alternatives to include into container's nodes subset
selectors Selector repeated Set of Selectors to form the container's nodes subset
filters Filter repeated List of named filters to reference in selectors

Message 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.

Field Type Label Description
count uint32 How many object replicas to put
selector string Named selector bucket to put replicas

Message Selector

Selector chooses a number of nodes from the bucket taking the nearest nodes to the provided ContainerID by hash distance.

Field Type Label Description
name string Selector name to reference in object placement section
count uint32 How many nodes to select from the bucket
clause Clause Selector modifier showing how to form a bucket
attribute string Attribute bucket to select from
filter string Filter reference to select from

Clause

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.

Name Number Description
CLAUSE_UNSPECIFIED 0 No modifier defined. Will select nodes from bucket randomly.
SAME 1 SAME will select only nodes having the same value of bucket attribute
DISTINCT 2 DISTINCT will select nodes having different values of bucket attribute

NodeInfo.State

Represents the enumeration of various states of the NeoFS node.

Name Number Description
UNSPECIFIED 0 Unknown state.
ONLINE 1 Active state in the network.
OFFLINE 2 Network unavailable state.

Operation

Operations on filters

Name Number Description
OPERATION_UNSPECIFIED 0 No Operation defined
EQ 1 Equal
NE 2 Not Equal
GT 3 Greater then
GE 4 Greater or equal
LT 5 Less then
LE 6 Less or equal
OR 7 Logical OR
AND 8 Logical AND

Scalar Value Types

.proto Type Notes C++ Type Java Type Python Type
double double double float
float float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long
uint32 Uses variable-length encoding. uint32 int int/long
uint64 Uses variable-length encoding. uint64 long int/long
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str