From 0aa2d69dbd55afbd3e7e83758c45297958e46a3b Mon Sep 17 00:00:00 2001 From: Evgeniy Kulikov Date: Thu, 21 Nov 2019 15:28:15 +0300 Subject: [PATCH] docs: regenerate proto documentation --- docs/accounting.md | 15 +++-- docs/bootstrap.md | 3 +- docs/container.md | 12 ++-- docs/object.md | 30 ++++----- docs/service.md | 157 +++++++++++++++++++++++++++++++++++++++++++++ docs/session.md | 2 + docs/state.md | 15 +++++ 7 files changed, 209 insertions(+), 25 deletions(-) create mode 100644 docs/service.md diff --git a/docs/accounting.md b/docs/accounting.md index b4317ae..268a187 100644 --- a/docs/accounting.md +++ b/docs/accounting.md @@ -87,7 +87,8 @@ Balance returns current balance status of the NeoFS user | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | @@ -362,7 +363,8 @@ Delete allows user to remove unused cheque | OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | | MessageID | [bytes](#bytes) | | MessageID is a nonce for uniq request (UUIDv4) | | Signature | [bytes](#bytes) | | Signature is a signature of the sent request | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | @@ -382,7 +384,8 @@ DeleteResponse is empty | ----- | ---- | ----- | ----------- | | ID | [bytes](#bytes) | | ID is cheque identifier | | OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | @@ -420,7 +423,8 @@ DeleteResponse is empty | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | @@ -447,7 +451,8 @@ DeleteResponse is empty | Height | [uint64](#uint64) | | Height is the neo blockchain height until the cheque is valid | | MessageID | [bytes](#bytes) | | MessageID is a nonce for uniq request (UUIDv4) | | Signature | [bytes](#bytes) | | Signature is a signature of the sent request | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | diff --git a/docs/bootstrap.md b/docs/bootstrap.md index 19967bf..737e085 100644 --- a/docs/bootstrap.md +++ b/docs/bootstrap.md @@ -62,7 +62,8 @@ Process is method that allows to register node in the network and receive actual | ----- | ---- | ----- | ----------- | | type | [int32](#int32) | | Type is NodeType, can be InnerRingNode (type=1) or StorageNode (type=2) | | info | [NodeInfo](#bootstrap.NodeInfo) | | Info contains information about node | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | diff --git a/docs/container.md b/docs/container.md index 4f98a47..bc559ce 100644 --- a/docs/container.md +++ b/docs/container.md @@ -92,8 +92,9 @@ List returns all user's containers | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | CID | [bytes](#bytes) | | CID (container id) is a SHA256 hash of the container structure | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | | Signature | [bytes](#bytes) | | Signature of the container owner | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | @@ -113,7 +114,8 @@ via consensus in inner ring nodes | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | CID | [bytes](#bytes) | | CID (container id) is a SHA256 hash of the container structure | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | @@ -136,7 +138,8 @@ via consensus in inner ring nodes | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | @@ -163,7 +166,8 @@ via consensus in inner ring nodes | OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | | rules | [netmap.PlacementRule](#netmap.PlacementRule) | | Rules define storage policy for the object inside the container. | | Signature | [bytes](#bytes) | | Signature of the user (owner id) | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | diff --git a/docs/object.md b/docs/object.md index 03e41c8..8407733 100644 --- a/docs/object.md +++ b/docs/object.md @@ -147,11 +147,11 @@ calculated for XORed data. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value Deprecated: will be replaced with RequestMetaHeader (see develop branch) | | Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) | | OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | | Token | [session.Token](#session.Token) | | Token with session public key and user's signature | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | @@ -170,11 +170,11 @@ in distributed system. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value Deprecated: will be replaced with RequestMetaHeader (see develop branch) | | Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) | | Ranges | [Range](#object.Range) | repeated | Ranges of object's payload to calculate homomorphic hash | | Salt | [bytes](#bytes) | | Salt is used to XOR object's payload ranges before hashing, it can be nil | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | @@ -196,10 +196,10 @@ in distributed system. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value Deprecated: will be replaced with RequestMetaHeader (see develop branch) | | Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) | | Ranges | [Range](#object.Range) | repeated | Ranges of object's payload to return | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | @@ -221,9 +221,9 @@ in distributed system. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value Deprecated: will be replaced with RequestMetaHeader (see develop branch) | | Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | @@ -246,10 +246,10 @@ in distributed system. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| Epoch | [uint64](#uint64) | | Epoch should be empty on user side, node sets epoch to the actual value Deprecated: will be replaced with RequestMetaHeader (see develop branch) | | Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) | | FullHeaders | [bool](#bool) | | FullHeaders can be set true for extended headers in the object | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | @@ -273,6 +273,8 @@ in distributed system. | ----- | ---- | ----- | ----------- | | Header | [PutRequest.PutHeader](#object.PutRequest.PutHeader) | | Header should be the first message in the stream | | Chunk | [bytes](#bytes) | | Chunk should be a remaining message in stream should be chunks | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | @@ -283,9 +285,7 @@ in distributed system. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value Deprecated: will be replaced with RequestMetaHeader (see develop branch) | | Object | [Object](#object.Object) | | Object with at least container id and owner id fields | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | | Token | [session.Token](#session.Token) | | Token with session public key and user's signature | @@ -308,11 +308,11 @@ in distributed system. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value Deprecated: will be replaced with RequestMetaHeader (see develop branch) | -| Version | [uint32](#uint32) | | Version of search query format | | ContainerID | [bytes](#bytes) | | ContainerID for searching the object | | Query | [bytes](#bytes) | | Query in the binary serialized format | -| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node Deprecated: will be replaced with RequestMetaHeader (see develop branch) | +| QueryVersion | [uint32](#uint32) | | QueryVersion is a version of search query format | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | diff --git a/docs/service.md b/docs/service.md new file mode 100644 index 0000000..454fab4 --- /dev/null +++ b/docs/service.md @@ -0,0 +1,157 @@ +# Protocol Documentation + + +## Table of Contents + +- [service/meta.proto](#service/meta.proto) + + - Messages + - [RequestMetaHeader](#service.RequestMetaHeader) + + +- [service/verify.proto](#service/verify.proto) + + - Messages + - [RequestVerificationHeader](#service.RequestVerificationHeader) + - [RequestVerificationHeader.Sign](#service.RequestVerificationHeader.Sign) + - [RequestVerificationHeader.Signature](#service.RequestVerificationHeader.Signature) + + +- [service/verify_test.proto](#service/verify_test.proto) + + - Messages + - [TestRequest](#service.TestRequest) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

+ +## service/meta.proto + + + + + + + +### Message RequestMetaHeader +RequestMetaHeader contains information about request meta headers +(should be embedded into message) + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every NeoFS Node | +| Epoch | [uint64](#uint64) | | Epoch for user can be empty, because node sets epoch to the actual value | +| Version | [uint32](#uint32) | | Version defines protocol version TODO: not used for now, should be implemented in future | + + + + + + + + +

Top

+ +## service/verify.proto + + + + + + + +### Message RequestVerificationHeader +RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request +(should be embedded into message). + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Signatures | [RequestVerificationHeader.Signature](#service.RequestVerificationHeader.Signature) | repeated | Signatures is a set of signatures of every passed NeoFS Node | + + + + +### Message RequestVerificationHeader.Sign + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Sign | [bytes](#bytes) | | Sign is signature of the request or session key. | +| Peer | [bytes](#bytes) | | Peer is compressed public key used for signature. | + + + + +### Message RequestVerificationHeader.Signature + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Sign | [RequestVerificationHeader.Sign](#service.RequestVerificationHeader.Sign) | | Sign is a signature and public key of the request. | +| Origin | [RequestVerificationHeader.Sign](#service.RequestVerificationHeader.Sign) | | Origin used for requests, when trusted node changes it and re-sign with session key. If session key used for signature request, then Origin should contain public key of user and signed session key. | + + + + + + + + +

Top

+ +## service/verify_test.proto + + + + + + + +### Message TestRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| IntField | [int32](#int32) | | | +| StringField | [string](#string) | | | +| BytesField | [bytes](#bytes) | | | +| CustomField | [bytes](#bytes) | | | +| Meta | [RequestMetaHeader](#service.RequestMetaHeader) | | | +| Header | [RequestVerificationHeader](#service.RequestVerificationHeader) | | | + + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| 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 | +| 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 | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/docs/session.md b/docs/session.md index cf4a1fd..e8633d3 100644 --- a/docs/session.md +++ b/docs/session.md @@ -70,6 +70,8 @@ session key. Session is established during 4-step handshake in one gRPC stream | ----- | ---- | ----- | ----------- | | Init | [Token](#session.Token) | | Init is a message to initialize session opening. Carry: owner of manipulation object; ID of manipulation object; token lifetime bounds. | | Signed | [Token](#session.Token) | | Signed Init message response (Unsigned) from server with user private key | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | diff --git a/docs/state.md b/docs/state.md index 6d240c1..e678be3 100644 --- a/docs/state.md +++ b/docs/state.md @@ -70,6 +70,11 @@ If node unhealthy field Status would contains detailed info. HealthRequest message to check current state +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | + @@ -89,6 +94,11 @@ HealthResponse message with current state MetricsRequest message to request node metrics +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | + @@ -109,6 +119,11 @@ from github.com/prometheus/client_model/metrics.proto NetmapRequest message to request current node netmap +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | +| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | +