TrueCloudLab/frostfs-api
34
1
Fork 18
Code Issues 14 Pull requests 3 Releases Activity Actions

[#50] *: Regenerate docs
All checks were successful
Formatters / Run fmt (pull_request) Successful in 22s
Details
DCO action / DCO (pull_request) Successful in 40s
Details
Pre-commit hooks / Pre-commit (pull_request) Successful in 41s
Details

Browse source 
Signed-off-by: Aleksey Savchuk <a.savchuk@yadro.com>
This commit is contained in:
Aleksey Savchuk 2024-09-05 16:27:53 +03:00
parent 5602b8fa2a
commit 2a46a9ea0a
No known key found for this signature in database
10 changed files with 118 additions and 301 deletions
Download patch file Download diff file Expand all files Collapse all files

80
proto-docs/netmap.md
View file

@ -55,7 +55,7 @@
`NetmapService` provides methods to work with `Network Map` and the
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.
from other FrostFS nodes.
```
rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
@ -83,7 +83,7 @@ information about the server has been successfully read;
| LocalNodeInfo | [LocalNodeInfoRequest](#neo.fs.v2.netmap.LocalNodeInfoRequest) | [LocalNodeInfoResponse](#neo.fs.v2.netmap.LocalNodeInfoResponse) |
#### Method NetworkInfo
Read recent information about the NeoFS network.
Read recent information about the FrostFS network.
Statuses:
- **OK** (0, SECTION_SUCCESS):
@ -95,7 +95,7 @@ information about the current network state has been successfully read;
| NetworkInfo | [NetworkInfoRequest](#neo.fs.v2.netmap.NetworkInfoRequest) | [NetworkInfoResponse](#neo.fs.v2.netmap.NetworkInfoResponse) |
#### Method NetmapSnapshot
Returns network map snapshot of the current NeoFS epoch.
Returns network map snapshot of the current FrostFS epoch.
Statuses:
- **OK** (0, SECTION_SUCCESS):
@ -149,7 +149,7 @@ Local Node Info, including API Version in use.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Latest NeoFS API version in use |
| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Latest FrostFS API version in use |
| node_info | [NodeInfo](#neo.fs.v2.netmap.NodeInfo) | | NodeInfo structure with recent information from node itself |
@ -287,7 +287,7 @@ Network map structure
<a name="neo.fs.v2.netmap.NetworkConfig"></a>
### Message NetworkConfig
NeoFS network configuration
FrostFS network configuration
| Field | Type | Label | Description |
@ -315,7 +315,7 @@ System parameters:
Fee paid for container creation by the container owner.
Value: little-endian integer. Default: 0.
- **EpochDuration** \
NeoFS epoch duration measured in Sidechain blocks.
FrostFS epoch duration measured in Sidechain blocks.
Value: little-endian integer. Default: 0.
- **HomomorphicHashingDisabled** \
Flag of disabling the homomorphic hashing of objects' payload.
@ -327,8 +327,39 @@ System parameters:
Flag allowing setting the MAINTENANCE state to storage nodes.
Value: true if any byte != 0. Default: false.
- **MaxObjectSize** \
Maximum size of physically stored NeoFS object measured in bytes.
Maximum size of physically stored FrostFS object measured in bytes.
Value: little-endian integer. Default: 0.
This value refers to the maximum size of a **physically** stored object
in FrostFS. However, from a user's perspective, the **logical** size of a
stored object can be significantly larger. The relationship between the
physical and logical object sizes is governed by the following formula
```math
\mathrm{Stored\ Object\ Size} \le
\frac{
\left(\mathrm{Max\ Object\ Size}\right)^2
}{
\mathrm{Object\ ID\ Size}
}
```
This arises from the fact that a tombstone, also being an object, stores
the IDs of inhumed objects and cannot be divided into smaller objects,
thus having an upper limit for its size.
For example, if:
* Max Object Size Size = 64 MiB;
* Object ID Size = 32 B;
then:
```math
\mathrm{Stored\ Object\ Size} \le
\frac{\left(64\ \mathrm{MiB}\right)^2}{32\ \mathrm{B}} =
\frac{2^{52}}{2^5}\ \mathrm{B} =
2^{47}\ \mathrm{B} =
128\ \mathrm{TiB}
```
- **WithdrawFee** \
Fee paid for withdrawal of funds paid by the account owner.
Value: little-endian integer. Default: 0.
@ -349,45 +380,45 @@ System parameters:
<a name="neo.fs.v2.netmap.NetworkInfo"></a>
### Message NetworkInfo
Information about NeoFS network
Information about FrostFS network
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| current_epoch | [uint64](#uint64) | | Number of the current epoch in the NeoFS network |
| magic_number | [uint64](#uint64) | | Magic number of the sidechain of the NeoFS network |
| ms_per_block | [int64](#int64) | | MillisecondsPerBlock network parameter of the sidechain of the NeoFS network |
| network_config | [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig) | | NeoFS network configuration |
| current_epoch | [uint64](#uint64) | | Number of the current epoch in the FrostFS network |
| magic_number | [uint64](#uint64) | | Magic number of the sidechain of the FrostFS network |
| ms_per_block | [int64](#int64) | | MillisecondsPerBlock network parameter of the sidechain of the FrostFS network |
| network_config | [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig) | | FrostFS network configuration |
<a name="neo.fs.v2.netmap.NodeInfo"></a>
### Message NodeInfo
NeoFS node description
FrostFS node description
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| public_key | [bytes](#bytes) | | Public key of the NeoFS node in a binary format |
| public_key | [bytes](#bytes) | | Public key of the FrostFS node in a binary format |
| addresses | [string](#string) | repeated | Ways to connect to a node |
| attributes | [NodeInfo.Attribute](#neo.fs.v2.netmap.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](#neo.fs.v2.netmap.NodeInfo.State) | | Carries state of the NeoFS node |
| attributes | [NodeInfo.Attribute](#neo.fs.v2.netmap.NodeInfo.Attribute) | repeated | Carries list of the FrostFS 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](#neo.fs.v2.netmap.NodeInfo.State) | | Carries state of the FrostFS node |
<a name="neo.fs.v2.netmap.NodeInfo.Attribute"></a>
### Message NodeInfo.Attribute
Administrator-defined Attributes of the NeoFS Storage Node.
Administrator-defined Attributes of the FrostFS Storage Node.
`Attribute` is a Key-Value metadata pair. Key name must be a valid UTF-8
string. Value can't be empty.
Attributes can be constructed into a chain of attributes: any attribute can
have a parent attribute and a child attribute (except the first and the
last one). A string representation of the chain of attributes in NeoFS
last one). A string representation of the chain of attributes in FrostFS
Storage Node configuration uses ":" and "/" symbols, e.g.:
`NEOFS_NODE_ATTRIBUTE_1=key1:val1/key2:val2`
`FrostFS_NODE_ATTRIBUTE_1=key1:val1/key2:val2`
Therefore the string attribute representation in the Node configuration
must use "\:", "\/" and "\\" escaped symbols if any of them appears in an
@ -434,8 +465,8 @@ explicitly set:
[ISO 3166-2](https://en.wikipedia.org/wiki/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
Node's continent name according to the [Seven-Continent
model](https://en.wikipedia.org/wiki/Continent#Number). Calculated
automatically from `UN-LOCODE` attribute.
* ExternalAddr
Node's preferred way for communications with external clients.
@ -443,7 +474,7 @@ explicitly set:
Must contain a comma-separated list of multi-addresses.
For detailed description of each well-known attribute please see the
corresponding section in NeoFS Technical Specification.
corresponding section in FrostFS Technical Specification.
| Field | Type | Label | Description |
@ -464,7 +495,7 @@ 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 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 |
| container_backup_factor | [uint32](#uint32) | | Container backup factor controls how deep FrostFS 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 |
| unique | [bool](#bool) | | Unique flag defines non-overlapping application for replicas |
@ -522,7 +553,7 @@ hash distance.
<a name="neo.fs.v2.netmap.NodeInfo.State"></a>
### NodeInfo.State
Represents the enumeration of various states of the NeoFS node.
Represents the enumeration of various states of the FrostFS node.
| Name | Number | Description |
| ---- | ------ | ----------- |
@ -550,6 +581,7 @@ Operations on filters
| OR | 7 | Logical OR |
| AND | 8 | Logical AND |
| NOT | 9 | Logical negation |
| LIKE | 10 | Matches pattern |
<!-- end enums -->