13 KiB
Protocol Documentation
Table of Contents
-
Services
-
Messages
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);
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 |
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 |
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 NodeInfo
NeoFS node description
| Field | Type | Label | Description |
|---|---|---|---|
| public_key | bytes | Public key of the NeoFS node in a binary format. | |
| address | string | 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. - Locode
Node's geographic location in UN/LOCODE format approximated to the nearest point defined in standard. - Country
Country code in ISO 3166-1_alpha-2 format. Calculated automatically fromLocodeattribute - Region
Country's administative subdivision where node is located. Calculated automatically fromLocodeattribute based onSubDivfield. Presented in ISO 3166-2 format. - City
City, town, village or rural area name where node is located written without diacritics . Calculated automatically fromLocodeattribute.
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 |