TrueCloudLab/frostfs-api
28
0
Fork 17
Code Issues 11 Pull requests 1 Releases Activity Actions

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

Browse source 
Signed-off-by: Aleksey Savchuk <a.savchuk@yadro.com>
This commit is contained in:
Aleksey Savchuk 2024-09-05 14:23:18 +03:00
parent 29a1940e5a
commit 56bdadd74d
No known key found for this signature in database
5 changed files with 55 additions and 239 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
proto-docs/acl.md
View file

@ -71,11 +71,12 @@ Deprecated: eACL tables are no longer relevant - `APEOverrides` should be used i
### Message BearerToken.Body.APEOverride
APEOverride is the list of APE chains defined for a target.
These chains are meant to serve as overrides to the already defined (or even undefined)
APE chains for the target (see contract `Policy`).
These chains are meant to serve as overrides to the already defined (or
even undefined) APE chains for the target (see contract `Policy`).
The server-side processing of the bearer token with set APE overrides must verify if a client is permitted
to override chains for the target, preventing unauthorized access through the APE mechanism.
The server-side processing of the bearer token with set APE overrides
must verify if a client is permitted to override chains for the target,
preventing unauthorized access through the APE mechanism.
| Field | Type | Label | Description |

4
proto-docs/ape.md
View file

@ -72,8 +72,8 @@ TargetType is a type target to which a rule chain is defined.
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> 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 |
| <a name="int64" /> 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 |
| <a name="int32" /> 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 |
| <a name="int64" /> 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 |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |

221
proto-docs/container.md
View file

@ -8,19 +8,10 @@
- [ContainerService](#neo.fs.v2.container.ContainerService)
- Messages
- [AnnounceUsedSpaceRequest](#neo.fs.v2.container.AnnounceUsedSpaceRequest)
- [AnnounceUsedSpaceRequest.Body](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body)
- [AnnounceUsedSpaceRequest.Body.Announcement](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement)
- [AnnounceUsedSpaceResponse](#neo.fs.v2.container.AnnounceUsedSpaceResponse)
- [AnnounceUsedSpaceResponse.Body](#neo.fs.v2.container.AnnounceUsedSpaceResponse.Body)
- [DeleteRequest](#neo.fs.v2.container.DeleteRequest)
- [DeleteRequest.Body](#neo.fs.v2.container.DeleteRequest.Body)
- [DeleteResponse](#neo.fs.v2.container.DeleteResponse)
- [DeleteResponse.Body](#neo.fs.v2.container.DeleteResponse.Body)
- [GetExtendedACLRequest](#neo.fs.v2.container.GetExtendedACLRequest)
- [GetExtendedACLRequest.Body](#neo.fs.v2.container.GetExtendedACLRequest.Body)
- [GetExtendedACLResponse](#neo.fs.v2.container.GetExtendedACLResponse)
- [GetExtendedACLResponse.Body](#neo.fs.v2.container.GetExtendedACLResponse.Body)
- [GetRequest](#neo.fs.v2.container.GetRequest)
- [GetRequest.Body](#neo.fs.v2.container.GetRequest.Body)
- [GetResponse](#neo.fs.v2.container.GetResponse)
@ -33,10 +24,6 @@
- [PutRequest.Body](#neo.fs.v2.container.PutRequest.Body)
- [PutResponse](#neo.fs.v2.container.PutResponse)
- [PutResponse.Body](#neo.fs.v2.container.PutResponse.Body)
- [SetExtendedACLRequest](#neo.fs.v2.container.SetExtendedACLRequest)
- [SetExtendedACLRequest.Body](#neo.fs.v2.container.SetExtendedACLRequest.Body)
- [SetExtendedACLResponse](#neo.fs.v2.container.SetExtendedACLResponse)
- [SetExtendedACLResponse.Body](#neo.fs.v2.container.SetExtendedACLResponse.Body)
- [container/types.proto](#container/types.proto)
@ -71,9 +58,6 @@ rpc Put(PutRequest) returns (PutResponse);
rpc Delete(DeleteRequest) returns (DeleteResponse);
rpc Get(GetRequest) returns (GetResponse);
rpc List(ListRequest) returns (ListResponse);
rpc SetExtendedACL(SetExtendedACLRequest) returns (SetExtendedACLResponse);
rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse);
rpc AnnounceUsedSpace(AnnounceUsedSpaceRequest) returns (AnnounceUsedSpaceResponse);
```
@ -141,114 +125,9 @@ Statuses:
| Name | Input | Output |
| ---- | ----- | ------ |
| List | [ListRequest](#neo.fs.v2.container.ListRequest) | [ListResponse](#neo.fs.v2.container.ListResponse) |
#### Method SetExtendedACL
Invokes 'SetEACL' method of 'Container` smart contract and returns response
immediately. After one more block in sidechain, changes in an Extended ACL
are added into smart contract storage.
Statuses:
- **OK** (0, SECTION_SUCCESS): \
request to save container eACL has been sent to the sidechain;
- Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
set container eACL access denied.
| Name | Input | Output |
| ---- | ----- | ------ |
| SetExtendedACL | [SetExtendedACLRequest](#neo.fs.v2.container.SetExtendedACLRequest) | [SetExtendedACLResponse](#neo.fs.v2.container.SetExtendedACLResponse) |
#### Method GetExtendedACL
Returns Extended ACL table and signature from `Container` smart contract
storage.
Statuses:
- **OK** (0, SECTION_SUCCESS): \
container eACL has been successfully read;
- Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
container not found;
- **EACL_NOT_FOUND** (3073, SECTION_CONTAINER): \
eACL table not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container eACL is denied.
| Name | Input | Output |
| ---- | ----- | ------ |
| GetExtendedACL | [GetExtendedACLRequest](#neo.fs.v2.container.GetExtendedACLRequest) | [GetExtendedACLResponse](#neo.fs.v2.container.GetExtendedACLResponse) |
#### Method AnnounceUsedSpace
Announces the space values used by the container for P2P synchronization.
Statuses:
- **OK** (0, SECTION_SUCCESS): \
estimation of used space has been successfully announced;
- Common failures (SECTION_FAILURE_COMMON).
| Name | Input | Output |
| ---- | ----- | ------ |
| AnnounceUsedSpace | [AnnounceUsedSpaceRequest](#neo.fs.v2.container.AnnounceUsedSpaceRequest) | [AnnounceUsedSpaceResponse](#neo.fs.v2.container.AnnounceUsedSpaceResponse) |
<!-- end services -->
<a name="neo.fs.v2.container.AnnounceUsedSpaceRequest"></a>
### Message AnnounceUsedSpaceRequest
Announce container used space
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [AnnounceUsedSpaceRequest.Body](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body) | | Body of announce used space 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. |
<a name="neo.fs.v2.container.AnnounceUsedSpaceRequest.Body"></a>
### Message AnnounceUsedSpaceRequest.Body
Container used space announcement body.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| announcements | [AnnounceUsedSpaceRequest.Body.Announcement](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement) | repeated | List of announcements. If nodes share several containers, announcements are transferred in a batch. |
<a name="neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement"></a>
### Message AnnounceUsedSpaceRequest.Body.Announcement
Announcement contains used space information for a single container.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| epoch | [uint64](#uint64) | | Epoch number for which the container size estimation was produced. |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container. |
| used_space | [uint64](#uint64) | | Used space is a sum of object payload sizes of a specified container, stored in the node. It must not include inhumed objects. |
<a name="neo.fs.v2.container.AnnounceUsedSpaceResponse"></a>
### Message AnnounceUsedSpaceResponse
Announce container used space
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [AnnounceUsedSpaceResponse.Body](#neo.fs.v2.container.AnnounceUsedSpaceResponse.Body) | | Body of announce used space response message. |
| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#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. |
<a name="neo.fs.v2.container.AnnounceUsedSpaceResponse.Body"></a>
### Message AnnounceUsedSpaceResponse.Body
`AnnounceUsedSpaceResponse` has an empty body because announcements are
one way communication.
<a name="neo.fs.v2.container.DeleteRequest"></a>
### Message DeleteRequest
@ -298,58 +177,6 @@ and done via consensus in Inner Ring nodes.
<a name="neo.fs.v2.container.GetExtendedACLRequest"></a>
### Message GetExtendedACLRequest
Get Extended ACL
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [GetExtendedACLRequest.Body](#neo.fs.v2.container.GetExtendedACLRequest.Body) | | Body of get extended acl 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. |
<a name="neo.fs.v2.container.GetExtendedACLRequest.Body"></a>
### Message GetExtendedACLRequest.Body
Get Extended ACL request body
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container having Extended ACL |
<a name="neo.fs.v2.container.GetExtendedACLResponse"></a>
### Message GetExtendedACLResponse
Get Extended ACL
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [GetExtendedACLResponse.Body](#neo.fs.v2.container.GetExtendedACLResponse.Body) | | Body of get extended acl response message. |
| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#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. |
<a name="neo.fs.v2.container.GetExtendedACLResponse.Body"></a>
### Message GetExtendedACLResponse.Body
Get Extended ACL Response body can be empty if the requested container does
not have Extended ACL Table attached or Extended ACL has not been allowed
at the time of container creation.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) | | Extended ACL requested, if available |
| signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of stable-marshalled Extended ACL according to RFC-6979. |
| session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) | | Session token if Extended ACL was set within a session |
<a name="neo.fs.v2.container.GetRequest"></a>
### Message GetRequest
@ -504,54 +331,6 @@ returned here to make sure everything has been done as expected.
| ----- | ---- | ----- | ----------- |
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Unique identifier of the newly created container |
<a name="neo.fs.v2.container.SetExtendedACLRequest"></a>
### Message SetExtendedACLRequest
Set Extended ACL
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [SetExtendedACLRequest.Body](#neo.fs.v2.container.SetExtendedACLRequest.Body) | | Body of set extended acl 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. |
<a name="neo.fs.v2.container.SetExtendedACLRequest.Body"></a>
### Message SetExtendedACLRequest.Body
Set Extended ACL request body does not have separate `ContainerID`
reference. It will be taken from `EACLTable.container_id` field.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) | | Extended ACL table to set for the container |
| signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of stable-marshalled Extended ACL table according to RFC-6979. |
<a name="neo.fs.v2.container.SetExtendedACLResponse"></a>
### Message SetExtendedACLResponse
Set Extended ACL
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [SetExtendedACLResponse.Body](#neo.fs.v2.container.SetExtendedACLResponse.Body) | | Body of set extended acl response message. |
| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#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. |
<a name="neo.fs.v2.container.SetExtendedACLResponse.Body"></a>
### Message SetExtendedACLResponse.Body
`SetExtendedACLResponse` has an empty body because the operation is
asynchronous and the update should be reflected in `Container` smart
contract's storage after next block is issued in sidechain.
<!-- end messages -->
<!-- end enums -->

36
proto-docs/netmap.md
View file

@ -329,6 +329,37 @@ System parameters:
- **MaxObjectSize** \
Maximum size of physically stored NeoFS object measured in bytes.
Value: little-endian integer. Default: 0.
This value refers to the maximum size of a **physically** stored object
in NeoFS. 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 fragments,
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.
@ -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.
@ -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 -->

24
proto-docs/object.md
View file

@ -404,16 +404,20 @@ been deleted;
#### Method Patch
Patch the object. Request uses gRPC stream. First message must set
the address of the object that is going to get patched. If the object's attributes
are patched, then these attrubutes must be set only within the first stream message.
the address of the object that is going to get patched. If the object's
attributes are patched, then these attrubutes must be set only within the
first stream message.
If the patch request is performed by NOT the object's owner but if the actor has the permission
to perform the patch, then `OwnerID` of the object is changed. In this case the object's owner
loses the object's ownership after the patch request is successfully done.
If the patch request is performed by NOT the object's owner but if the
actor has the permission to perform the patch, then `OwnerID` of the object
is changed. In this case the object's owner loses the object's ownership
after the patch request is successfully done.
As objects are content-addressable the patching causes new object ID generation for the patched object.
This object id is set witihn `PatchResponse`. But the object id may remain unchanged in such cases:
1. The chunk of the applying patch contains the same value as the object's payload within the same range;
As objects are content-addressable the patching causes new object ID
generation for the patched object. This object id is set witihn
`PatchResponse`. But the object id may remain unchanged in such cases:
1. The chunk of the applying patch contains the same value as the object's
payload within the same range;
2. The patch that reverts the changes applied by preceding patch;
3. The application of the same patches for the object a few times.
@ -996,8 +1000,8 @@ prefix to the name. Here is the list of fields available via this prefix:
* $Object:split.splitID \
16 byte UUIDv4 used to identify the split object hierarchy parts
* $Object:ec.parent \
If the object is stored according to EC policy, then ec_parent attribute
is set to return an id list of all related EC chunks.
If the object is stored according to EC policy, then ec_parent
attribute is set to return an id list of all related EC chunks.
There are some well-known filter aliases to match objects by certain
properties: