diff --git a/README.md b/README.md index 9247a10f..a6662c35 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ Repository contains 13 packages that implement NeoFS core structures. These packages mostly contain protobuf files with service and structure definitions or NeoFS core types with complemented functions. +There is a auto-generated documentation for protobuf files in [docs](docs). + ### Accounting Accounting package defines services and structures for accounting operations: @@ -17,11 +19,22 @@ with inner ring signatures, which approve that user can withdraw requested amount of assets. NeoFS smart contract takes binary formatted `cheque` as a parameter in withdraw call. +#### API +Accounting package defines: +- [Accounting service](docs/accounting.md#accounting.Accounting) +- [Withdraw service](docs/accounting.md#accounting.Withdraw) + + ### Bootstrap Bootstrap package defines bootstrap service which is used by storage nodes to connect to the storage network. +#### API +Bootstrap package defines: +- [Bootstrap service](docs/bootstrap.md#bootstrap.Bootstrap) + + ### Chain Chain package contains util functions for operations with NEO Blockchain types: @@ -33,6 +46,10 @@ Container package defines service and structures for operations with containers. Objects in NeoFS are stored in containers. Container defines storage policy for the objects. +#### API +Bootstrap package defines: +- [Container service](docs/container.md#container.Service) + ### Decimal Decimal defines custom decimal implementation which is used in accounting @@ -53,6 +70,10 @@ Object package defines service and structures for object operations. Object is a core storage structure in NeoFS. Package contains detailed information about object internal structure. +#### API +Object package defines: +- [Object service](docs/object.md#object.Service) + ### Query Query package defines structure for object search requests. @@ -72,10 +93,18 @@ Session package defines service and structures for session obtain. Object operations require an established session with pair of session keys signed by owner of the object. +#### API +Session package defines: +- [Session service](docs/session.md#session.Session) + ### State State package defines service and structures for metrics gathering. +#### API +State package defines: +- [Status service](docs/state.md#state.Status) + ## How to use NeoFS-proto packages contain godoc documentation. Examples of using most of diff --git a/docs/accounting.md b/docs/accounting.md new file mode 100644 index 00000000..f08bd52d --- /dev/null +++ b/docs/accounting.md @@ -0,0 +1,488 @@ +# Protocol Documentation + + +## Table of Contents + +- [accounting/service.proto](#accounting/service.proto) + - Services + - [Accounting](#accounting.Accounting) + + - Messages + - [BalanceRequest](#accounting.BalanceRequest) + - [BalanceResponse](#accounting.BalanceResponse) + + +- [accounting/types.proto](#accounting/types.proto) + + - Messages + - [Account](#accounting.Account) + - [Balances](#accounting.Balances) + - [ContainerCreateTarget](#accounting.ContainerCreateTarget) + - [Lifetime](#accounting.Lifetime) + - [LockTarget](#accounting.LockTarget) + - [PayIO](#accounting.PayIO) + - [Settlement](#accounting.Settlement) + - [Settlement.Container](#accounting.Settlement.Container) + - [Settlement.Receiver](#accounting.Settlement.Receiver) + - [Settlement.Tx](#accounting.Settlement.Tx) + - [Tx](#accounting.Tx) + - [WithdrawTarget](#accounting.WithdrawTarget) + + +- [accounting/withdraw.proto](#accounting/withdraw.proto) + - Services + - [Withdraw](#accounting.Withdraw) + + - Messages + - [DeleteRequest](#accounting.DeleteRequest) + - [DeleteResponse](#accounting.DeleteResponse) + - [GetRequest](#accounting.GetRequest) + - [GetResponse](#accounting.GetResponse) + - [Item](#accounting.Item) + - [ListRequest](#accounting.ListRequest) + - [ListResponse](#accounting.ListResponse) + - [PutRequest](#accounting.PutRequest) + - [PutResponse](#accounting.PutResponse) + + +- [Scalar Value Types](#scalar-value-types) + + + + +
+ +## accounting/service.proto + + + + + + +### Service "accounting.Accounting" +Accounting is a service that provides access for accounting balance +information + +``` +rpc Balance(BalanceRequest) returns (BalanceResponse); + +``` + +#### Method Balance + +Balance returns current balance status of the NeoFS user + +| Name | Input | Output | +| ---- | ----- | ------ | +| Balance | [BalanceRequest](#accounting.BalanceRequest) | [BalanceResponse](#accounting.BalanceResponse) | + + + + + +### Message BalanceRequest + + + +| 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 | + + + + +### Message BalanceResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Balance | [decimal.Decimal](#decimal.Decimal) | | Balance contains current account balance state | +| LockAccounts | [Account](#accounting.Account) | repeated | LockAccounts contains information about locked funds. Locked funds appear when user pays for storage or withdraw assets. | + + + + + + + + + + +## accounting/types.proto + + + + + + + +### Message Account + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | +| Address | [string](#string) | | Address is identifier of accounting record | +| ParentAddress | [string](#string) | | ParentAddress is identifier of parent accounting record | +| ActiveFunds | [decimal.Decimal](#decimal.Decimal) | | ActiveFunds is amount of active (non locked) funds for account | +| Lifetime | [Lifetime](#accounting.Lifetime) | | Lifetime is time until account is valid (used for lock accounts) | +| LockTarget | [LockTarget](#accounting.LockTarget) | | LockTarget is the purpose of lock funds (it might be withdraw or payment for storage) | +| LockAccounts | [Account](#accounting.Account) | repeated | LockAccounts contains child accounts with locked funds | + + + + +### Message Balances + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Accounts | [Account](#accounting.Account) | repeated | Accounts contains multiple account snapshots | + + + + +### Message ContainerCreateTarget + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| CID | [bytes](#bytes) | | CID is container identifier | + + + + +### Message Lifetime + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| unit | [Lifetime.Unit](#accounting.Lifetime.Unit) | | Unit describes how lifetime is measured in account | +| Value | [int64](#int64) | | Value describes how long lifetime will be valid | + + + + +### Message LockTarget +LockTarget must be one of two options + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| WithdrawTarget | [WithdrawTarget](#accounting.WithdrawTarget) | | WithdrawTarget used when user requested withdraw | +| ContainerCreateTarget | [ContainerCreateTarget](#accounting.ContainerCreateTarget) | | ContainerCreateTarget used when user requested creation of container | + + + + +### Message PayIO + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| BlockID | [uint64](#uint64) | | BlockID contains id of the NEO block where withdraw or deposit call was invoked | +| Transactions | [Tx](#accounting.Tx) | repeated | Transactions contains all transactions that founded in block and used for PayIO | + + + + +### Message Settlement + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Epoch | [uint64](#uint64) | | Epoch contains an epoch when settlement was accepted | +| Transactions | [Settlement.Tx](#accounting.Settlement.Tx) | repeated | Transactions is a set of transactions | + + + + +### Message Settlement.Container + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| CID | [bytes](#bytes) | | CID is container identifier | +| SGIDs | [bytes](#bytes) | repeated | SGIDs is a set of storage groups that successfully passed the audit | + + + + +### Message Settlement.Receiver + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| To | [string](#string) | | To is the address of funds recipient | +| Amount | [decimal.Decimal](#decimal.Decimal) | | Amount is the amount of funds that will be sent | + + + + +### Message Settlement.Tx + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| From | [string](#string) | | From is the address of the sender of funds | +| Container | [Settlement.Container](#accounting.Settlement.Container) | | Container that successfully had passed the audit | +| Receivers | [Settlement.Receiver](#accounting.Settlement.Receiver) | repeated | Receivers is a set of addresses of funds recipients | + + + + +### Message Tx + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| type | [Tx.Type](#accounting.Tx.Type) | | Type describes target of transaction | +| From | [string](#string) | | From describes sender of funds | +| To | [string](#string) | | To describes receiver of funds | +| Amount | [decimal.Decimal](#decimal.Decimal) | | Amount describes amount of funds | +| PublicKeys | [bytes](#bytes) | | PublicKeys contains public key of sender | + + + + +### Message WithdrawTarget + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Cheque | [string](#string) | | Cheque is a string representation of cheque id | + + + + + + +### Lifetime.Unit +Unit can be Unlimited, based on NeoFS epoch or Neo block + +| Name | Number | Description | +| ---- | ------ | ----------- | +| Unlimited | 0 | | +| NeoFSEpoch | 1 | | +| NeoBlock | 2 | | + + + + + +### Tx.Type +Type can be withdrawal, payIO or inner + +| Name | Number | Description | +| ---- | ------ | ----------- | +| Unknown | 0 | | +| Withdraw | 1 | | +| PayIO | 2 | | +| Inner | 3 | | + + + + + + + + + +## accounting/withdraw.proto + + + + + + +### Service "accounting.Withdraw" +Withdraw is a service that provides withdraw assets operations from the NeoFS + +``` +rpc Get(GetRequest) returns (GetResponse); +rpc Put(PutRequest) returns (PutResponse); +rpc List(ListRequest) returns (ListResponse); +rpc Delete(DeleteRequest) returns (DeleteResponse); + +``` + +#### Method Get + +Get returns cheque if it was signed by inner ring nodes + +| Name | Input | Output | +| ---- | ----- | ------ | +| Get | [GetRequest](#accounting.GetRequest) | [GetResponse](#accounting.GetResponse) | +#### Method Put + +Put ask inner ring nodes to sign a cheque for withdraw invoke + +| Name | Input | Output | +| ---- | ----- | ------ | +| Put | [PutRequest](#accounting.PutRequest) | [PutResponse](#accounting.PutResponse) | +#### Method List + +List shows all user's checks + +| Name | Input | Output | +| ---- | ----- | ------ | +| List | [ListRequest](#accounting.ListRequest) | [ListResponse](#accounting.ListResponse) | +#### Method Delete + +Delete allows user to remove unused cheque + +| Name | Input | Output | +| ---- | ----- | ------ | +| Delete | [DeleteRequest](#accounting.DeleteRequest) | [DeleteResponse](#accounting.DeleteResponse) | + + + + + +### Message DeleteRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ID | [bytes](#bytes) | | ID is cheque identifier | +| 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 | + + + + +### Message DeleteResponse +DeleteResponse is empty + + + + + +### Message GetRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| 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 | + + + + +### Message GetResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Withdraw | [Item](#accounting.Item) | | Item is cheque with meta information | + + + + +### Message Item + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ID | [bytes](#bytes) | | ID is a cheque identifier | +| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | +| Amount | [decimal.Decimal](#decimal.Decimal) | | Amount of funds | +| Height | [uint64](#uint64) | | Height is the neo blockchain height until the cheque is valid | +| Payload | [bytes](#bytes) | | Payload contains cheque representation in bytes | + + + + +### Message ListRequest + + + +| 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 | + + + + +### Message ListResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Items | [Item](#accounting.Item) | repeated | Item is a set of cheques with meta information | + + + + +### Message PutRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | +| Amount | [decimal.Decimal](#decimal.Decimal) | | Amount of funds | +| 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 | + + + + +### Message PutResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ID | [bytes](#bytes) | | ID is cheque identifier | + + + + + + + +## 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/bootstrap.md b/docs/bootstrap.md new file mode 100644 index 00000000..dfada2c6 --- /dev/null +++ b/docs/bootstrap.md @@ -0,0 +1,132 @@ +# Protocol Documentation + + +## Table of Contents + +- [bootstrap/service.proto](#bootstrap/service.proto) + - Services + - [Bootstrap](#bootstrap.Bootstrap) + + - Messages + - [Request](#bootstrap.Request) + + +- [bootstrap/types.proto](#bootstrap/types.proto) + + - Messages + - [NodeInfo](#bootstrap.NodeInfo) + - [SpreadMap](#bootstrap.SpreadMap) + + +- [Scalar Value Types](#scalar-value-types) + + + + + + +## bootstrap/service.proto + + + + + + +### Service "bootstrap.Bootstrap" +Bootstrap service allows neofs-node to connect to the network. Node should +perform at least one bootstrap request in the epoch to stay in the network +for the next epoch. + +``` +rpc Process(Request) returns (SpreadMap); + +``` + +#### Method Process + +Process is method that allows to register node in the network and receive actual netmap + +| Name | Input | Output | +| ---- | ----- | ------ | +| Process | [Request](#bootstrap.Request) | [SpreadMap](#bootstrap.SpreadMap) | + + + + + +### Message Request + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| 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 | + + + + + + + + + + +## bootstrap/types.proto + + + + + + + +### Message NodeInfo + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Address | [string](#string) | | Address is a node [multi-address](https://github.com/multiformats/multiaddr) | +| PubKey | [bytes](#bytes) | | PubKey is a compressed public key representation in bytes | +| Options | [string](#string) | repeated | Options is set of node optional information, such as storage capacity, node location, price and etc | +| Status | [uint64](#uint64) | | Status is bitmap status of the node | + + + + +### Message SpreadMap + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Epoch | [uint64](#uint64) | | Epoch is current epoch for netmap | +| NetMap | [NodeInfo](#bootstrap.NodeInfo) | repeated | NetMap is a set of NodeInfos | + + + + + + + +## 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/container.md b/docs/container.md new file mode 100644 index 00000000..5ff0d891 --- /dev/null +++ b/docs/container.md @@ -0,0 +1,232 @@ +# Protocol Documentation + + +## Table of Contents + +- [container/service.proto](#container/service.proto) + - Services + - [Service](#container.Service) + + - Messages + - [DeleteRequest](#container.DeleteRequest) + - [DeleteResponse](#container.DeleteResponse) + - [GetRequest](#container.GetRequest) + - [GetResponse](#container.GetResponse) + - [ListRequest](#container.ListRequest) + - [ListResponse](#container.ListResponse) + - [PutRequest](#container.PutRequest) + - [PutResponse](#container.PutResponse) + + +- [container/types.proto](#container/types.proto) + + - Messages + - [Container](#container.Container) + + +- [Scalar Value Types](#scalar-value-types) + + + + + + +## container/service.proto + + + + + + +### Service "container.Service" +Container service provides API for manipulating with the container. + +``` +rpc Put(PutRequest) returns (PutResponse); +rpc Delete(DeleteRequest) returns (DeleteResponse); +rpc Get(GetRequest) returns (GetResponse); +rpc List(ListRequest) returns (ListResponse); + +``` + +#### Method Put + +Put request proposes container to the inner ring nodes. They will +accept new container if user has enough deposit. All containers +are accepted by the consensus, therefore it is asynchronous process. + +| Name | Input | Output | +| ---- | ----- | ------ | +| Put | [PutRequest](#container.PutRequest) | [PutResponse](#container.PutResponse) | +#### Method Delete + +Delete container removes it from the inner ring container storage. It +also asynchronous process done by consensus. + +| Name | Input | Output | +| ---- | ----- | ------ | +| Delete | [DeleteRequest](#container.DeleteRequest) | [DeleteResponse](#container.DeleteResponse) | +#### Method Get + +Get container returns container instance + +| Name | Input | Output | +| ---- | ----- | ------ | +| Get | [GetRequest](#container.GetRequest) | [GetResponse](#container.GetResponse) | +#### Method List + +List returns all user's containers + +| Name | Input | Output | +| ---- | ----- | ------ | +| List | [ListRequest](#container.ListRequest) | [ListResponse](#container.ListResponse) | + + + + + +### Message DeleteRequest + + + +| 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 | +| Signature | [bytes](#bytes) | | Signature of the container owner | + + + + +### Message DeleteResponse +DeleteResponse is empty because delete operation is asynchronous and done +via consensus in inner ring nodes + + + + + +### Message GetRequest + + + +| 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 | + + + + +### Message GetResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Container | [Container](#container.Container) | | Container is a structure that contains placement rules and owner id | + + + + +### Message ListRequest + + + +| 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 | + + + + +### Message ListResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| CID | [bytes](#bytes) | repeated | CID (container id) is list of SHA256 hashes of the container structures | + + + + +### Message PutRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| MessageID | [bytes](#bytes) | | MessageID is a nonce for uniq container id calculation | +| Capacity | [uint64](#uint64) | | Capacity defines amount of data that can be stored in the container (doesn't used for now). | +| 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 | + + + + +### Message PutResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| CID | [bytes](#bytes) | | CID (container id) is a SHA256 hash of the container structure | + + + + + + + + + + +## container/types.proto + + + + + + + +### Message Container +The Container service definition. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address. | +| Salt | [bytes](#bytes) | | Salt is a nonce for unique container id calculation. | +| Capacity | [uint64](#uint64) | | Capacity defines amount of data that can be stored in the container (doesn't used for now). | +| Rules | [netmap.PlacementRule](#netmap.PlacementRule) | | Rules define storage policy for the object inside the container. | + + + + + + + +## 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/decimal.md b/docs/decimal.md new file mode 100644 index 00000000..62acb863 --- /dev/null +++ b/docs/decimal.md @@ -0,0 +1,61 @@ +# Protocol Documentation + + +## Table of Contents + +- [decimal/decimal.proto](#decimal/decimal.proto) + + - Messages + - [Decimal](#decimal.Decimal) + + +- [Scalar Value Types](#scalar-value-types) + + + + + + +## decimal/decimal.proto + + + + + + + +### Message Decimal +Decimal is a structure used for representation of assets amount + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Value | [int64](#int64) | | Value is value number | +| Precision | [uint32](#uint32) | | Precision is precision number | + + + + + + + +## 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/object.md b/docs/object.md new file mode 100644 index 00000000..5ba1845b --- /dev/null +++ b/docs/object.md @@ -0,0 +1,566 @@ +# Protocol Documentation + + +## Table of Contents + +- [object/service.proto](#object/service.proto) + - Services + - [Service](#object.Service) + + - Messages + - [DeleteRequest](#object.DeleteRequest) + - [DeleteResponse](#object.DeleteResponse) + - [GetRangeHashRequest](#object.GetRangeHashRequest) + - [GetRangeHashResponse](#object.GetRangeHashResponse) + - [GetRangeRequest](#object.GetRangeRequest) + - [GetRangeResponse](#object.GetRangeResponse) + - [GetRequest](#object.GetRequest) + - [GetResponse](#object.GetResponse) + - [HeadRequest](#object.HeadRequest) + - [HeadResponse](#object.HeadResponse) + - [PutRequest](#object.PutRequest) + - [PutRequest.PutHeader](#object.PutRequest.PutHeader) + - [PutResponse](#object.PutResponse) + - [SearchRequest](#object.SearchRequest) + - [SearchResponse](#object.SearchResponse) + + +- [object/types.proto](#object/types.proto) + + - Messages + - [CreationPoint](#object.CreationPoint) + - [Header](#object.Header) + - [IntegrityHeader](#object.IntegrityHeader) + - [Link](#object.Link) + - [Object](#object.Object) + - [Range](#object.Range) + - [StorageGroup](#object.StorageGroup) + - [StorageGroup.Lifetime](#object.StorageGroup.Lifetime) + - [SystemHeader](#object.SystemHeader) + - [Tombstone](#object.Tombstone) + - [Transform](#object.Transform) + - [UserHeader](#object.UserHeader) + + +- [Scalar Value Types](#scalar-value-types) + + + + + + +## object/service.proto + + + + + + +### Service "object.Service" +Object service provides API for manipulating with the object. + +``` +rpc Get(GetRequest) returns (stream GetResponse); +rpc Put(stream PutRequest) returns (PutResponse); +rpc Delete(DeleteRequest) returns (DeleteResponse); +rpc Head(HeadRequest) returns (HeadResponse); +rpc Search(SearchRequest) returns (SearchResponse); +rpc GetRange(GetRangeRequest) returns (GetRangeResponse); +rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse); + +``` + +#### Method Get + +Get the object from container. Response uses gRPC stream. First response +message carry object of requested address. Chunk messages are parts of +the object's payload if it is needed. All messages except first carry +chunks. Requested object can be restored by concatenation of object +message payload and all chunks keeping receiving order. + +| Name | Input | Output | +| ---- | ----- | ------ | +| Get | [GetRequest](#object.GetRequest) | [GetResponse](#object.GetResponse) | +#### Method Put + +Put the object into container. Request uses gRPC stream. First message +SHOULD BE type of PutHeader. Container id and Owner id of object SHOULD +BE set. Session token SHOULD BE obtained before put operation (see +session package). Chunk messages considered by server as part of object +payload. All messages except first SHOULD BE chunks. Chunk messages +SHOULD BE sent in direct order of fragmentation. + +| Name | Input | Output | +| ---- | ----- | ------ | +| Put | [PutRequest](#object.PutRequest) | [PutResponse](#object.PutResponse) | +#### Method Delete + +Delete the object from a container + +| Name | Input | Output | +| ---- | ----- | ------ | +| Delete | [DeleteRequest](#object.DeleteRequest) | [DeleteResponse](#object.DeleteResponse) | +#### Method Head + +Head returns the object without data payload. Object in the +response has system header only. If full headers flag is set, extended +headers are also present. + +| Name | Input | Output | +| ---- | ----- | ------ | +| Head | [HeadRequest](#object.HeadRequest) | [HeadResponse](#object.HeadResponse) | +#### Method Search + +Search objects in container. Version of query language format SHOULD BE +set to 1. Search query represented in serialized format (see query +package). + +| Name | Input | Output | +| ---- | ----- | ------ | +| Search | [SearchRequest](#object.SearchRequest) | [SearchResponse](#object.SearchResponse) | +#### Method GetRange + +GetRange of data payload. Ranges are set of pairs (offset, length). +Fragments order in response corresponds to ranges order in request. + +| Name | Input | Output | +| ---- | ----- | ------ | +| GetRange | [GetRangeRequest](#object.GetRangeRequest) | [GetRangeResponse](#object.GetRangeResponse) | +#### Method GetRangeHash + +GetRangeHash returns homomorphic hash of object payload range after XOR +operation. Ranges are set of pairs (offset, length). Hashes order in +response corresponds to ranges order in request. Homomorphic hash is +calculated for XORed data. + +| Name | Input | Output | +| ---- | ----- | ------ | +| GetRangeHash | [GetRangeHashRequest](#object.GetRangeHashRequest) | [GetRangeHashResponse](#object.GetRangeHashResponse) | + + + + + +### Message DeleteRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value | +| 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 | +| Token | [session.Token](#session.Token) | | Token with session public key and user's signature | + + + + +### Message DeleteResponse +DeleteResponse is empty because we cannot guarantee permanent object removal +in distributed system. + + + + + +### Message GetRangeHashRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value | +| 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 | + + + + +### Message GetRangeHashResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Hashes | [bytes](#bytes) | repeated | Homomorphic hashes of all ranges | + + + + +### Message GetRangeRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value | +| 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 | + + + + +### Message GetRangeResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Fragments | [bytes](#bytes) | repeated | Fragments of object's payload | + + + + +### Message GetRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value | +| 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 | + + + + +### Message GetResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| object | [Object](#object.Object) | | Object header and some payload | +| Chunk | [bytes](#bytes) | | Chunk of remaining payload | + + + + +### Message HeadRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value | +| 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 | + + + + +### Message HeadResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Object | [Object](#object.Object) | | Object without payload | + + + + +### Message PutRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| 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 | + + + + +### Message PutRequest.PutHeader + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value | +| 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 | +| Token | [session.Token](#session.Token) | | Token with session public key and user's signature | + + + + +### Message PutResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) | + + + + +### Message SearchRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value | +| 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 | + + + + +### Message SearchResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Addresses | [refs.Address](#refs.Address) | repeated | Addresses of found objects | + + + + + + + + + + +## object/types.proto + + + + + + + +### Message CreationPoint + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| UnixTime | [int64](#int64) | | Date of creation in unixtime format | +| Epoch | [uint64](#uint64) | | Date of creation in NeoFS epochs | + + + + +### Message Header + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Link | [Link](#object.Link) | | Link to other objects | +| Redirect | [refs.Address](#refs.Address) | | RedirectNot used yet | +| UserHeader | [UserHeader](#object.UserHeader) | | UserHeader defined by user | +| Transform | [Transform](#object.Transform) | | Transform defines transform operation (e.g. payload split) | +| Tombstone | [Tombstone](#object.Tombstone) | | Tombstone header that set up in deleted objects | +| Verify | [session.VerificationHeader](#session.VerificationHeader) | | Verify header that contains session public key and user's signature | +| HomoHash | [bytes](#bytes) | | Homomorphic hash of original object payload | +| PayloadChecksum | [bytes](#bytes) | | PayloadChecksum of actual object's payload | +| Integrity | [IntegrityHeader](#object.IntegrityHeader) | | Integrity header with checksum of all above headers in the object | +| StorageGroup | [StorageGroup](#object.StorageGroup) | | StorageGroup contains meta information for the data audit | + + + + +### Message IntegrityHeader + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| HeadersChecksum | [bytes](#bytes) | | Checksum of all above headers in the object | +| ChecksumSignature | [bytes](#bytes) | | User's signature of checksum to verify if it is correct | + + + + +### Message Link + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| type | [Link.Type](#object.Link.Type) | | Link type | +| ID | [bytes](#bytes) | | Object id | + + + + +### Message Object + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| SystemHeader | [SystemHeader](#object.SystemHeader) | | System header | +| Headers | [Header](#object.Header) | repeated | Extended headers | +| Payload | [bytes](#bytes) | | Object's payload | + + + + +### Message Range + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Offset | [uint64](#uint64) | | Offset of the data range | +| Length | [uint64](#uint64) | | Length of the data range | + + + + +### Message StorageGroup + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ValidationDataSize | [uint64](#uint64) | | Size of the all object's payloads included into storage group | +| ValidationHash | [bytes](#bytes) | | Homomorphic hash of all object's payloads included into storage group | +| lifetime | [StorageGroup.Lifetime](#object.StorageGroup.Lifetime) | | Time until storage group is valid | + + + + +### Message StorageGroup.Lifetime + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| unit | [StorageGroup.Lifetime.Unit](#object.StorageGroup.Lifetime.Unit) | | Lifetime type | +| Value | [int64](#int64) | | Lifetime value | + + + + +### Message SystemHeader + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Version | [uint64](#uint64) | | Version of the object structure | +| PayloadLength | [uint64](#uint64) | | Object payload length | +| ID | [bytes](#bytes) | | ObjectID is a UUID | +| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | +| CID | [bytes](#bytes) | | ContainerID is a SHA256 hash of the container structure | +| CreatedAt | [CreationPoint](#object.CreationPoint) | | Timestamp of object creation | + + + + +### Message Tombstone + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Epoch | [uint64](#uint64) | | Epoch when tombstone was created | + + + + +### Message Transform + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| type | [Transform.Type](#object.Transform.Type) | | Type of object transformation | + + + + +### Message UserHeader + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Key | [string](#string) | | Key of the user's header | +| Value | [string](#string) | | Value of the user's header | + + + + + + +### Link.Type + + +| Name | Number | Description | +| ---- | ------ | ----------- | +| Unknown | 0 | | +| Parent | 1 | Parent object created during object transformation | +| Previous | 2 | Previous object in the linked list created during object transformation | +| Next | 3 | Next object in the linked list created during object transformation | +| Child | 4 | Child object created during object transformation | +| StorageGroup | 5 | Object that included into this storage group | + + + + + +### StorageGroup.Lifetime.Unit + + +| Name | Number | Description | +| ---- | ------ | ----------- | +| Unlimited | 0 | Storage group always valid | +| NeoFSEpoch | 1 | Storage group is valid until lifetime NeoFS epoch | +| UnixTime | 2 | Storage group is valid until lifetime unix timestamp | + + + + + +### Transform.Type + + +| Name | Number | Description | +| ---- | ------ | ----------- | +| Unknown | 0 | | +| Split | 1 | Object created after payload split | +| Sign | 2 | Object created after re-signing (doesn't used) | +| Mould | 3 | Object created after filling missing headers in the object | + + + + + + +## 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/query.md b/docs/query.md new file mode 100644 index 00000000..9deb2c19 --- /dev/null +++ b/docs/query.md @@ -0,0 +1,86 @@ +# Protocol Documentation + + +## Table of Contents + +- [query/types.proto](#query/types.proto) + + - Messages + - [Filter](#query.Filter) + - [Query](#query.Query) + + +- [Scalar Value Types](#scalar-value-types) + + + + + + +## query/types.proto + + + + + + + +### Message Filter + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| type | [Filter.Type](#query.Filter.Type) | | Type of filter | +| Name | [string](#string) | | Name of field that should be filtered | +| Value | [string](#string) | | Value that should be used for filter | + + + + +### Message Query + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Filters | [Filter](#query.Filter) | repeated | Filters is set of filters, should not be empty | + + + + + + +### Filter.Type +Type can be Exact or Regex + +| Name | Number | Description | +| ---- | ------ | ----------- | +| Exact | 0 | | +| Regex | 1 | | + + + + + + +## 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/refs.md b/docs/refs.md new file mode 100644 index 00000000..c3051ab2 --- /dev/null +++ b/docs/refs.md @@ -0,0 +1,61 @@ +# Protocol Documentation + + +## Table of Contents + +- [refs/types.proto](#refs/types.proto) + + - Messages + - [Address](#refs.Address) + + +- [Scalar Value Types](#scalar-value-types) + + + + + + +## refs/types.proto + + + + + + + +### Message Address +Address of object (container id + object id) + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ObjectID | [bytes](#bytes) | | ObjectID is an object identifier | +| CID | [bytes](#bytes) | | CID is container identifier | + + + + + + + +## 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 new file mode 100644 index 00000000..8ea703e9 --- /dev/null +++ b/docs/session.md @@ -0,0 +1,149 @@ +# Protocol Documentation + + +## Table of Contents + +- [session/service.proto](#session/service.proto) + - Services + - [Session](#session.Session) + + - Messages + - [CreateRequest](#session.CreateRequest) + - [CreateResponse](#session.CreateResponse) + + +- [session/types.proto](#session/types.proto) + + - Messages + - [Token](#session.Token) + - [VerificationHeader](#session.VerificationHeader) + + +- [Scalar Value Types](#scalar-value-types) + + + + + + +## session/service.proto + + + + + + +### Service "session.Session" +Open a trusted session to manipulate an object. In order to put or +delete object client have to obtain session token with trusted node. +Trusted node will modify client's object (add missing headers, checksums, +homomorphic hash) and sign id with session key. Session is established +during 4-step handshake in one gRPC stream + +``` +rpc Create(stream CreateRequest) returns (stream CreateResponse); + +``` + +#### Method Create + + + +| Name | Input | Output | +| ---- | ----- | ------ | +| Create | [CreateRequest](#session.CreateRequest) | [CreateResponse](#session.CreateResponse) | + + + + + +### Message CreateRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Init | [Token](#session.Token) | | Message to init 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 | + + + + +### Message CreateResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Unsigned | [Token](#session.Token) | | Unsigned token with token ID and session public key generated on server side | +| Result | [Token](#session.Token) | | Resulting token which can be used for object placing through an trusted intermediary | + + + + + + + + + + +## session/types.proto + + + + + + + +### Message Token +User token granting rights for object manipulation + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Header | [VerificationHeader](#session.VerificationHeader) | | Header carries verification data of session key | +| OwnerID | [bytes](#bytes) | | Owner of manipulation object | +| FirstEpoch | [uint64](#uint64) | | Initial epoch of token lifetime | +| LastEpoch | [uint64](#uint64) | | Last epoch of token lifetime | +| ObjectID | [bytes](#bytes) | repeated | ID of manipulation object | +| Signature | [bytes](#bytes) | | Token signature. Signed by owner of manipulation object | +| ID | [bytes](#bytes) | | Token ID (UUID) | + + + + +### Message VerificationHeader + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| PublicKey | [bytes](#bytes) | | Session public key | +| KeySignature | [bytes](#bytes) | | Session public key signature. Signed by trusted side | + + + + + + + +## 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/state.md b/docs/state.md new file mode 100644 index 00000000..6d240c1d --- /dev/null +++ b/docs/state.md @@ -0,0 +1,137 @@ +# Protocol Documentation + + +## Table of Contents + +- [state/service.proto](#state/service.proto) + - Services + - [Status](#state.Status) + + - Messages + - [HealthRequest](#state.HealthRequest) + - [HealthResponse](#state.HealthResponse) + - [MetricsRequest](#state.MetricsRequest) + - [MetricsResponse](#state.MetricsResponse) + - [NetmapRequest](#state.NetmapRequest) + + +- [Scalar Value Types](#scalar-value-types) + + + + + + +## state/service.proto + + + + + + +### Service "state.Status" +Status service provides node's healthcheck and status info + +``` +rpc Netmap(NetmapRequest) returns (.bootstrap.SpreadMap); +rpc Metrics(MetricsRequest) returns (MetricsResponse); +rpc HealthCheck(HealthRequest) returns (HealthResponse); + +``` + +#### Method Netmap + +Netmap request allows to receive current [bootstrap.SpreadMap](bootstrap.md#bootstrap.SpreadMap) + +| Name | Input | Output | +| ---- | ----- | ------ | +| Netmap | [NetmapRequest](#state.NetmapRequest) | [.bootstrap.SpreadMap](#bootstrap.SpreadMap) | +#### Method Metrics + +Metrics request allows to receive metrics in prometheus format + +| Name | Input | Output | +| ---- | ----- | ------ | +| Metrics | [MetricsRequest](#state.MetricsRequest) | [MetricsResponse](#state.MetricsResponse) | +#### Method HealthCheck + +HealthCheck request allows to check health status of the node. +If node unhealthy field Status would contains detailed info. + +| Name | Input | Output | +| ---- | ----- | ------ | +| HealthCheck | [HealthRequest](#state.HealthRequest) | [HealthResponse](#state.HealthResponse) | + + + + + +### Message HealthRequest +HealthRequest message to check current state + + + + + +### Message HealthResponse +HealthResponse message with current state + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Healthy | [bool](#bool) | | Healthy is true when node alive and healthy | +| Status | [string](#string) | | Status contains detailed information about health status | + + + + +### Message MetricsRequest +MetricsRequest message to request node metrics + + + + + +### Message MetricsResponse +MetricsResponse contains [][]byte, +every []byte is marshaled MetricFamily proto message +from github.com/prometheus/client_model/metrics.proto + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Metrics | [bytes](#bytes) | repeated | | + + + + +### Message NetmapRequest +NetmapRequest message to request current node netmap + + + + + + + + +## 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 | +