*: Re-generate protobuf docs

Signed-off-by: Leonard Lyubich <leonard@nspcc.ru>
2022-09-23 18:57:44 +04:00 · 2022-09-23 18:57:44 +04:00 · ae38b06f9b
commit ae38b06f9b
parent 35a012b0fe
5 changed files with 167 additions and 27 deletions
--- 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
--- 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) |
 <!-- end services -->


@ -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 |


+<a name="neo.fs.v2.netmap.NetmapSnapshotRequest"></a>
+
+### 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. |
+
+
+<a name="neo.fs.v2.netmap.NetmapSnapshotRequest.Body"></a>
+
+### Message NetmapSnapshotRequest.Body
+Get netmap snapshot request body.
+
+
+
+<a name="neo.fs.v2.netmap.NetmapSnapshotResponse"></a>
+
+### 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. |
+
+
+<a name="neo.fs.v2.netmap.NetmapSnapshotResponse.Body"></a>
+
+### 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. |
+
+
 <a name="neo.fs.v2.netmap.NetworkInfoRequest"></a>

 ### 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. |


+<a name="neo.fs.v2.netmap.Netmap"></a>
+
+### 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. |
+
+
 <a name="neo.fs.v2.netmap.NetworkConfig"></a>

 ### Message NetworkConfig
@ -223,7 +297,47 @@ NeoFS network configuration
 <a name="neo.fs.v2.netmap.NetworkConfig.Parameter"></a>

 ### 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 |



--- 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 \
--- 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. |
+
+
+<a name="neo.fs.v2.session.ObjectSessionContext.Target"></a>
+
+### 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. |


 <a name="neo.fs.v2.session.RequestMetaHeader"></a>
--- 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. |