From ae38b06f9b5e3889d4cb43b9251bf8ed11c74552 Mon Sep 17 00:00:00 2001 From: Leonard Lyubich Date: Fri, 23 Sep 2022 18:57:44 +0400 Subject: [PATCH] *: Re-generate protobuf docs Signed-off-by: Leonard Lyubich --- proto-docs/acl.md | 2 +- proto-docs/netmap.md | 121 +++++++++++++++++++++++++++++++++++++++++- proto-docs/object.md | 55 ++++++++++--------- proto-docs/session.md | 15 +++++- proto-docs/status.md | 1 + 5 files changed, 167 insertions(+), 27 deletions(-) diff --git a/proto-docs/acl.md b/proto-docs/acl.md index 80416c5..09762a1 100644 --- a/proto-docs/acl.md +++ b/proto-docs/acl.md @@ -118,7 +118,7 @@ prefix to the name. Here is the list of fields available via this prefix: * $Object:homomorphicHash \ homomorphic_hash -Please note, that if request or response does not have object's headers or +Please note, that if request or response does not have object's headers of full object (Range, RangeHash, Search, Delete), it will not be possible to filter by object header fields or user attributes. From the well-known list only `$Object:objectID` and `$Object:containerID` will be available, as diff --git a/proto-docs/netmap.md b/proto-docs/netmap.md index c029442..2c7545d 100644 --- a/proto-docs/netmap.md +++ b/proto-docs/netmap.md @@ -12,6 +12,10 @@ - [LocalNodeInfoRequest.Body](#neo.fs.v2.netmap.LocalNodeInfoRequest.Body) - [LocalNodeInfoResponse](#neo.fs.v2.netmap.LocalNodeInfoResponse) - [LocalNodeInfoResponse.Body](#neo.fs.v2.netmap.LocalNodeInfoResponse.Body) + - [NetmapSnapshotRequest](#neo.fs.v2.netmap.NetmapSnapshotRequest) + - [NetmapSnapshotRequest.Body](#neo.fs.v2.netmap.NetmapSnapshotRequest.Body) + - [NetmapSnapshotResponse](#neo.fs.v2.netmap.NetmapSnapshotResponse) + - [NetmapSnapshotResponse.Body](#neo.fs.v2.netmap.NetmapSnapshotResponse.Body) - [NetworkInfoRequest](#neo.fs.v2.netmap.NetworkInfoRequest) - [NetworkInfoRequest.Body](#neo.fs.v2.netmap.NetworkInfoRequest.Body) - [NetworkInfoResponse](#neo.fs.v2.netmap.NetworkInfoResponse) @@ -22,6 +26,7 @@ - Messages - [Filter](#neo.fs.v2.netmap.Filter) + - [Netmap](#neo.fs.v2.netmap.Netmap) - [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig) - [NetworkConfig.Parameter](#neo.fs.v2.netmap.NetworkConfig.Parameter) - [NetworkInfo](#neo.fs.v2.netmap.NetworkInfo) @@ -55,6 +60,7 @@ NeoFS nodes. ``` rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse); rpc NetworkInfo(NetworkInfoRequest) returns (NetworkInfoResponse); +rpc NetmapSnapshot(NetmapSnapshotRequest) returns (NetmapSnapshotResponse); ``` @@ -86,6 +92,18 @@ information about the current network state has been successfully read; | Name | Input | Output | | ---- | ----- | ------ | | NetworkInfo | [NetworkInfoRequest](#neo.fs.v2.netmap.NetworkInfoRequest) | [NetworkInfoResponse](#neo.fs.v2.netmap.NetworkInfoResponse) | +#### Method NetmapSnapshot + +Returns network map snapshot of the current NeoFS epoch. + +Statuses: +- **OK** (0, SECTION_SUCCESS): +information about the current network map has been successfully read; +- Common failures (SECTION_FAILURE_COMMON). + +| Name | Input | Output | +| ---- | ----- | ------ | +| NetmapSnapshot | [NetmapSnapshotRequest](#neo.fs.v2.netmap.NetmapSnapshotRequest) | [NetmapSnapshotResponse](#neo.fs.v2.netmap.NetmapSnapshotResponse) | @@ -134,6 +152,50 @@ Local Node Info, including API Version in use. | node_info | [NodeInfo](#neo.fs.v2.netmap.NodeInfo) | | NodeInfo structure with recent information from node itself | + + +### Message NetmapSnapshotRequest +Get netmap snapshot request + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [NetmapSnapshotRequest.Body](#neo.fs.v2.netmap.NetmapSnapshotRequest.Body) | | Body of get netmap snapshot 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. | + + + + +### Message NetmapSnapshotRequest.Body +Get netmap snapshot request body. + + + + + +### Message NetmapSnapshotResponse +Response with current netmap snapshot + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [NetmapSnapshotResponse.Body](#neo.fs.v2.netmap.NetmapSnapshotResponse.Body) | | Body of get netmap snapshot 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 response 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. | + + + + +### Message NetmapSnapshotResponse.Body +Get netmap snapshot response body + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| netmap | [Netmap](#neo.fs.v2.netmap.Netmap) | | Structure of the requested network map. | + + ### Message NetworkInfoRequest @@ -209,6 +271,18 @@ results that will satisfy filter's conditions. | filters | [Filter](#neo.fs.v2.netmap.Filter) | repeated | List of inner filters. Top level operation will be applied to the whole list. | + + +### Message Netmap +Network map structure + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| epoch | [uint64](#uint64) | | Network map revision number. | +| nodes | [NodeInfo](#neo.fs.v2.netmap.NodeInfo) | repeated | Nodes presented in network. | + + ### Message NetworkConfig @@ -223,7 +297,47 @@ NeoFS network configuration ### Message NetworkConfig.Parameter -Single configuration parameter +Single configuration parameter. Key MUST be network-unique. + +System parameters: +- **AuditFee** \ + Fee paid by the storage group owner to the Inner Ring member. + Value: little-endian integer. Default: 0. +- **BasicIncomeRate** \ + Cost of storing one gigabyte of data for a period of one epoch. Paid by + container owner to container nodes. + Value: little-endian integer. Default: 0. +- **ContainerAliasFee** \ + Fee paid for named container's creation by the container owner. + Value: little-endian integer. Default: 0. +- **ContainerFee** \ + Fee paid for container creation by the container owner. + Value: little-endian integer. Default: 0. +- **EigenTrustAlpha** \ + Alpha parameter of EigenTrust algorithm used in the Reputation system. + Value: decimal floating-point number in UTF-8 string representation. + Default: 0. +- **EigenTrustIterations** \ + Number of EigenTrust algorithm iterations to pass in the Reputation system. + Value: little-endian integer. Default: 0. +- **EpochDuration** \ + NeoFS epoch duration measured in Sidechain blocks. + Value: little-endian integer. Default: 0. +- **HomomorphicHashingDisabled** \ + Flag of disabling the homomorphic hashing of objects' payload. + Value: true if any byte != 0. Default: false. +- **InnerRingCandidateFee** \ + Fee for entrance to the Inner Ring paid by the candidate. + Value: little-endian integer. Default: 0. +- **MaintenanceModeAllowed** \ + 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. + Value: little-endian integer. Default: 0. +- **WithdrawFee** \ + Fee paid for withdrawal of funds paid by the account owner. + Value: little-endian integer. Default: 0. | Field | Type | Label | Description | @@ -330,6 +444,10 @@ explicitly set: 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. + Clients SHOULD use these addresses if possible. + 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. @@ -416,6 +534,7 @@ Represents the enumeration of various states of the NeoFS node. | UNSPECIFIED | 0 | Unknown state | | ONLINE | 1 | Active state in the network | | OFFLINE | 2 | Network unavailable state | +| MAINTENANCE | 3 | Maintenance state | diff --git a/proto-docs/object.md b/proto-docs/object.md index 025f41f..e22f6c0 100644 --- a/proto-docs/object.md +++ b/proto-docs/object.md @@ -107,16 +107,16 @@ Statuses: - **OK** (0, SECTION_SUCCESS): \ object has been successfully read; - Common failures (SECTION_FAILURE_COMMON); -- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - object container not found; - **ACCESS_DENIED** (2048, SECTION_OBJECT): \ read access to the object is denied; - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \ object not found in container; -- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - provided session token has expired; - **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \ - the requested object has been marked as deleted. + the requested object has been marked as deleted; +- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ + object container not found; +- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ + provided session token has expired. | Name | Input | Output | | ---- | ----- | ------ | @@ -141,6 +141,8 @@ Statuses: - **OK** (0, SECTION_SUCCESS): \ object has been successfully saved in the container; - Common failures (SECTION_FAILURE_COMMON); +- **ACCESS_DENIED** (2048, SECTION_OBJECT): \ + write access to the container is denied; - **LOCKED** (2050, SECTION_OBJECT): \ placement of an object of type TOMBSTONE that includes at least one locked object is prohibited; @@ -149,8 +151,6 @@ Statuses: type other than REGULAR is prohibited; - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ object storage container not found; -- **ACCESS_DENIED** (2048, SECTION_OBJECT): \ - write access to the container is denied; - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \ (for trusted object preparation) session private key does not exist or has been deleted; @@ -176,12 +176,12 @@ Statuses: - **OK** (0, SECTION_SUCCESS): \ object has been successfully marked to be removed from the container; - Common failures (SECTION_FAILURE_COMMON); +- **ACCESS_DENIED** (2048, SECTION_OBJECT): \ + delete access to the object is denied; - **LOCKED** (2050, SECTION_OBJECT): \ deleting a locked object is prohibited; - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ object container not found; -- **ACCESS_DENIED** (2048, SECTION_OBJECT): \ - delete access to the object is denied; - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ provided session token has expired. @@ -205,16 +205,16 @@ Statuses: - **OK** (0, SECTION_SUCCESS): \ object header has been successfully read; - Common failures (SECTION_FAILURE_COMMON); -- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - object container not found; - **ACCESS_DENIED** (2048, SECTION_OBJECT): \ access to operation HEAD of the object is denied; - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \ object not found in container; -- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - provided session token has expired; - **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \ - the requested object has been marked as deleted. + the requested object has been marked as deleted; +- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ + object container not found; +- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ + provided session token has expired. | Name | Input | Output | | ---- | ----- | ------ | @@ -236,10 +236,10 @@ Statuses: - **OK** (0, SECTION_SUCCESS): \ objects have been successfully selected; - Common failures (SECTION_FAILURE_COMMON); -- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - search container not found; - **ACCESS_DENIED** (2048, SECTION_OBJECT): \ access to operation SEARCH of the object is denied; +- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ + search container not found; - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ provided session token has expired. @@ -267,18 +267,18 @@ Statuses: - **OK** (0, SECTION_SUCCESS): \ data range of the object payload has been successfully read; - Common failures (SECTION_FAILURE_COMMON); -- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - object container not found; - **ACCESS_DENIED** (2048, SECTION_OBJECT): \ access to operation RANGE of the object is denied; - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \ object not found in container; -- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - provided session token has expired; - **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \ the requested object has been marked as deleted. - **OUT_OF_RANGE** (2053, SECTION_OBJECT): \ - the requested range is out of bounds. + the requested range is out of bounds; +- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ + object container not found; +- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ + provided session token has expired. | Name | Input | Output | | ---- | ----- | ------ | @@ -304,14 +304,14 @@ Statuses: - **OK** (0, SECTION_SUCCESS): \ data range of the object payload has been successfully hashed; - Common failures (SECTION_FAILURE_COMMON); -- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - object container not found; - **ACCESS_DENIED** (2048, SECTION_OBJECT): \ access to operation RANGEHASH of the object is denied; - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \ object not found in container; - **OUT_OF_RANGE** (2053, SECTION_OBJECT): \ - the requested range is out of bounds. + the requested range is out of bounds; +- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ + object container not found; - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ provided session token has expired. @@ -869,6 +869,13 @@ And some well-known attributes used by applications only: Human-friendly name * FileName \ File name to be associated with the object on saving +* FilePath \ + Full path to be associated with the object on saving. Should start with a + '/' and use '/' as a delimiting symbol. Trailing '/' should be + interpreted as a virtual directory marker. If an object has conflicting + FilePath and FileName, FilePath should have higher priority, because it + is used to construct the directory tree. FilePath with trailing '/' and + non-empty FileName attribute should not be used together. * Timestamp \ User-defined local time of object creation in Unix Timestamp format * Content-Type \ diff --git a/proto-docs/session.md b/proto-docs/session.md index 40a48e2..2cdfd1e 100644 --- a/proto-docs/session.md +++ b/proto-docs/session.md @@ -19,6 +19,7 @@ - Messages - [ContainerSessionContext](#neo.fs.v2.session.ContainerSessionContext) - [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext) + - [ObjectSessionContext.Target](#neo.fs.v2.session.ObjectSessionContext.Target) - [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) - [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) - [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) @@ -155,7 +156,19 @@ Context information for Session Tokens related to ObjectService requests | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | verb | [ObjectSessionContext.Verb](#neo.fs.v2.session.ObjectSessionContext.Verb) | | Type of request for which the token is issued | -| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | Related Object address | +| target | [ObjectSessionContext.Target](#neo.fs.v2.session.ObjectSessionContext.Target) | | Object session target. MUST be correctly formed and set. If `objects` field is not empty, then the session applies only to these elements, otherwise, to all objects from the specified container. | + + + + +### Message ObjectSessionContext.Target +Carries objects involved in the object session. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| container | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Indicates which container the session is spread to. Field MUST be set and correct. | +| objects | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Indicates which objects the session is spread to. Objects are expected to be stored in the NeoFS container referenced by `container` field. Each element MUST have correct format. | diff --git a/proto-docs/status.md b/proto-docs/status.md index 246292e..b426326 100644 --- a/proto-docs/status.md +++ b/proto-docs/status.md @@ -89,6 +89,7 @@ Section of failed statuses independent of the operation. | INTERNAL | 0 | [**1024**] Internal server error, default failure. Not detailed. If the server cannot match failed outcome to the code, it should use this code. | | WRONG_MAGIC_NUMBER | 1 | [**1025**] Wrong magic of the NeoFS network. Details: - [**0**] Magic number of the served NeoFS network (big-endian 64-bit unsigned integer). | | SIGNATURE_VERIFICATION_FAIL | 2 | [**1026**] Signature verification failure. | +| NODE_UNDER_MAINTENANCE | 3 | [**1027**] Node is under maintenance. |