realloc/frostfs-api
1
0
Fork 0
forked from TrueCloudLab/frostfs-api
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update auto-generated docs

Browse source 
Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>
This commit is contained in:
Stanislav Bogatyrev 2020-10-16 14:40:12 +03:00
parent 095a6cb043
commit a6ecab41b8
8 changed files with 433 additions and 298 deletions
Download patch file Download diff file Expand all files Collapse all files

96
proto-docs/netmap.md
View file

@ -40,7 +40,10 @@
<a name="neo.fs.v2.netmap.NetmapService"></a>
### Service "neo.fs.v2.netmap.NetmapService"
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.
```
rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
@ -49,7 +52,11 @@ rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
#### Method LocalNodeInfo
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.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -60,12 +67,12 @@ Return information about Node
<a name="neo.fs.v2.netmap.LocalNodeInfoRequest"></a>
### Message LocalNodeInfoRequest
Get NodeInfo from the particular node directly
Get NodeInfo structure from the particular node directly
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [LocalNodeInfoRequest.Body](#neo.fs.v2.netmap.LocalNodeInfoRequest.Body) | | Body of the balance request message. |
| body | [LocalNodeInfoRequest.Body](#neo.fs.v2.netmap.LocalNodeInfoRequest.Body) | | Body of the LocalNodeInfo request message |
| meta_header | [neo.fs.v2.session.RequestMetaHeader](#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](#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. |
@ -73,14 +80,14 @@ Get NodeInfo from the particular node directly
<a name="neo.fs.v2.netmap.LocalNodeInfoRequest.Body"></a>
### Message LocalNodeInfoRequest.Body
Request body
LocalNodeInfo request body is empty.
<a name="neo.fs.v2.netmap.LocalNodeInfoResponse"></a>
### Message LocalNodeInfoResponse
Local nod Info, including API Version in use
Local Node Info, including API Version in use
| Field | Type | Label | Description |
@ -93,13 +100,13 @@ Local nod Info, including API Version in use
<a name="neo.fs.v2.netmap.LocalNodeInfoResponse.Body"></a>
### Message LocalNodeInfoResponse.Body
Response body
Local Node Info, including API Version in use.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | API version in use |
| node_info | [NodeInfo](#neo.fs.v2.netmap.NodeInfo) | | NodeInfo from node itself |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Latest NeoFS API version in use |
| node_info | [NodeInfo](#neo.fs.v2.netmap.NodeInfo) | | NodeInfo structure with recent information from node itself |
<!-- end messages -->
@ -119,12 +126,13 @@ Response body
<a name="neo.fs.v2.netmap.Filter"></a>
### Message Filter
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](#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 |
| name | [string](#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](#string) | | Key to filter |
| op | [Operation](#neo.fs.v2.netmap.Operation) | | Filtering operation |
| value | [string](#string) | | Value to match |
@ -148,26 +156,63 @@ NeoFS node description
<a name="neo.fs.v2.netmap.NodeInfo.Attribute"></a>
### Message NodeInfo.Attribute
Attributes of the NeoFS node.
Administrator-defined Attributes of the NeoFS Storage Node.
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](https://www.unece.org/cefact/codesfortrade/codes_index.html)
format approximated to the nearest point defined in standard.
* Country \
Country code in
[ISO 3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
format. Calculated automatically from `Locode` attribute
* Region \
Country's administative subdivision where node is located. Calculated
automatically from `Locode` attribute based on `SubDiv` field. Presented
in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format.
* City \
City, town, village or rural area name where node is located written
without diacritics . Calculated automatically from `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](#string) | | Key of the node attribute. |
| value | [string](#string) | | Value of the node attribute. |
| parents | [string](#string) | repeated | Parent keys, if any Example: For City it can be Region or Country |
| parents | [string](#string) | repeated | Parent keys, if any. For example for `City` it could be `Region` and `Country`. |
<a name="neo.fs.v2.netmap.PlacementPolicy"></a>
### Message PlacementPolicy
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.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| replicas | [Replica](#neo.fs.v2.netmap.Replica) | repeated | Rules to set number of object replicas and place each one into a particular bucket |
| container_backup_factor | [uint32](#uint32) | | Container backup factor controls how deep NeoFS will search for nodes alternatives to include into container. |
| replicas | [Replica](#neo.fs.v2.netmap.Replica) | repeated | Rules to set number of object replicas and place each one into a named bucket |
| container_backup_factor | [uint32](#uint32) | | Container backup factor controls how deep NeoFS will search for nodes alternatives to include into container's nodes subset |
| selectors | [Selector](#neo.fs.v2.netmap.Selector) | repeated | Set of Selectors to form the container's nodes subset |
| filters | [Filter](#neo.fs.v2.netmap.Filter) | repeated | List of named filters to reference in selectors |
@ -175,25 +220,28 @@ Set of rules to select a subset of nodes able to store container's objects
<a name="neo.fs.v2.netmap.Replica"></a>
### Message Replica
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.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| count | [uint32](#uint32) | | How many object replicas to put |
| selector | [string](#string) | | Named selector bucket to put in |
| selector | [string](#string) | | Named selector bucket to put replicas |
<a name="neo.fs.v2.netmap.Selector"></a>
### Message Selector
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](#string) | | Selector name to reference in object placement section |
| count | [uint32](#uint32) | | How many nodes to select from bucket |
| count | [uint32](#uint32) | | How many nodes to select from the bucket |
| clause | [Clause](#neo.fs.v2.netmap.Clause) | | Selector modifier showing how to form a bucket |
| attribute | [string](#string) | | Attribute bucket to select from |
| filter | [string](#string) | | Filter reference to select from |
@ -204,13 +252,13 @@ Selector
<a name="neo.fs.v2.netmap.Clause"></a>
### Clause
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.
| Name | Number | Description |
| ---- | ------ | ----------- |
| CLAUSE_UNSPECIFIED | 0 | No modifier defined |
| 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 |