aarifullin/frostfs-api-go
1
0
Fork 0
forked from TrueCloudLab/frostfs-api-go
Code Pull requests Activity

docs: generate documentation for proto files

Browse source
This commit is contained in:
alexvanin 2019-11-20 21:42:03 +03:00
parent 0af63c42cc
commit c7a5c19ef5
10 changed files with 1941 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
README.md
View file

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

488
docs/accounting.md Normal file
View file

@ -0,0 +1,488 @@
# Protocol Documentation
<a name="top"></a>
## 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)
<a name="accounting/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## accounting/service.proto
<a name="accounting.Accounting"></a>
### 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) |
<!-- end services -->
<a name="accounting.BalanceRequest"></a>
### 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 |
<a name="accounting.BalanceResponse"></a>
### 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. |
<!-- end messages -->
<!-- end enums -->
<a name="accounting/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## accounting/types.proto
<!-- end services -->
<a name="accounting.Account"></a>
### 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 |
<a name="accounting.Balances"></a>
### Message Balances
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Accounts | [Account](#accounting.Account) | repeated | Accounts contains multiple account snapshots |
<a name="accounting.ContainerCreateTarget"></a>
### Message ContainerCreateTarget
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| CID | [bytes](#bytes) | | CID is container identifier |
<a name="accounting.Lifetime"></a>
### 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 |
<a name="accounting.LockTarget"></a>
### 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 |
<a name="accounting.PayIO"></a>
### 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 |
<a name="accounting.Settlement"></a>
### 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 |
<a name="accounting.Settlement.Container"></a>
### 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 |
<a name="accounting.Settlement.Receiver"></a>
### 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 |
<a name="accounting.Settlement.Tx"></a>
### 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 |
<a name="accounting.Tx"></a>
### 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 |
<a name="accounting.WithdrawTarget"></a>
### Message WithdrawTarget
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Cheque | [string](#string) | | Cheque is a string representation of cheque id |
<!-- end messages -->
<a name="accounting.Lifetime.Unit"></a>
### Lifetime.Unit
Unit can be Unlimited, based on NeoFS epoch or Neo block
| Name | Number | Description |
| ---- | ------ | ----------- |
| Unlimited | 0 | |
| NeoFSEpoch | 1 | |
| NeoBlock | 2 | |
<a name="accounting.Tx.Type"></a>
### Tx.Type
Type can be withdrawal, payIO or inner
| Name | Number | Description |
| ---- | ------ | ----------- |
| Unknown | 0 | |
| Withdraw | 1 | |
| PayIO | 2 | |
| Inner | 3 | |
<!-- end enums -->
<a name="accounting/withdraw.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## accounting/withdraw.proto
<a name="accounting.Withdraw"></a>
### 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) |
<!-- end services -->
<a name="accounting.DeleteRequest"></a>
### 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 |
<a name="accounting.DeleteResponse"></a>
### Message DeleteResponse
DeleteResponse is empty
<a name="accounting.GetRequest"></a>
### 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 |
<a name="accounting.GetResponse"></a>
### Message GetResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Withdraw | [Item](#accounting.Item) | | Item is cheque with meta information |
<a name="accounting.Item"></a>
### 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 |
<a name="accounting.ListRequest"></a>
### 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 |
<a name="accounting.ListResponse"></a>
### Message ListResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Items | [Item](#accounting.Item) | repeated | Item is a set of cheques with meta information |
<a name="accounting.PutRequest"></a>
### 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 |
<a name="accounting.PutResponse"></a>
### Message PutResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ID | [bytes](#bytes) | | ID is cheque identifier |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

132
docs/bootstrap.md Normal file
View file

@ -0,0 +1,132 @@
# Protocol Documentation
<a name="top"></a>
## 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)
<a name="bootstrap/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## bootstrap/service.proto
<a name="bootstrap.Bootstrap"></a>
### 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) |
<!-- end services -->
<a name="bootstrap.Request"></a>
### 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 |
<!-- end messages -->
<!-- end enums -->
<a name="bootstrap/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## bootstrap/types.proto
<!-- end services -->
<a name="bootstrap.NodeInfo"></a>
### 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 |
<a name="bootstrap.SpreadMap"></a>
### 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 |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

232
docs/container.md Normal file
View file

@ -0,0 +1,232 @@
# Protocol Documentation
<a name="top"></a>
## 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)
<a name="container/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## container/service.proto
<a name="container.Service"></a>
### 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) |
<!-- end services -->
<a name="container.DeleteRequest"></a>
### 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 |
<a name="container.DeleteResponse"></a>
### Message DeleteResponse
DeleteResponse is empty because delete operation is asynchronous and done
via consensus in inner ring nodes
<a name="container.GetRequest"></a>
### 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 |
<a name="container.GetResponse"></a>
### Message GetResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Container | [Container](#container.Container) | | Container is a structure that contains placement rules and owner id |
<a name="container.ListRequest"></a>
### 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 |
<a name="container.ListResponse"></a>
### Message ListResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| CID | [bytes](#bytes) | repeated | CID (container id) is list of SHA256 hashes of the container structures |
<a name="container.PutRequest"></a>
### 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 |
<a name="container.PutResponse"></a>
### Message PutResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| CID | [bytes](#bytes) | | CID (container id) is a SHA256 hash of the container structure |
<!-- end messages -->
<!-- end enums -->
<a name="container/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## container/types.proto
<!-- end services -->
<a name="container.Container"></a>
### 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. |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

61
docs/decimal.md Normal file
View file

@ -0,0 +1,61 @@
# Protocol Documentation
<a name="top"></a>
## Table of Contents
- [decimal/decimal.proto](#decimal/decimal.proto)
- Messages
- [Decimal](#decimal.Decimal)
- [Scalar Value Types](#scalar-value-types)
<a name="decimal/decimal.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## decimal/decimal.proto
<!-- end services -->
<a name="decimal.Decimal"></a>
### 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 |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

566
docs/object.md Normal file
View file

@ -0,0 +1,566 @@
# Protocol Documentation
<a name="top"></a>
## 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)
<a name="object/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## object/service.proto
<a name="object.Service"></a>
### 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) |
<!-- end services -->
<a name="object.DeleteRequest"></a>
### 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 |
<a name="object.DeleteResponse"></a>
### Message DeleteResponse
DeleteResponse is empty because we cannot guarantee permanent object removal
in distributed system.
<a name="object.GetRangeHashRequest"></a>
### 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 |
<a name="object.GetRangeHashResponse"></a>
### Message GetRangeHashResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Hashes | [bytes](#bytes) | repeated | Homomorphic hashes of all ranges |
<a name="object.GetRangeRequest"></a>
### 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 |
<a name="object.GetRangeResponse"></a>
### Message GetRangeResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Fragments | [bytes](#bytes) | repeated | Fragments of object's payload |
<a name="object.GetRequest"></a>
### 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 |
<a name="object.GetResponse"></a>
### Message GetResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| object | [Object](#object.Object) | | Object header and some payload |
| Chunk | [bytes](#bytes) | | Chunk of remaining payload |
<a name="object.HeadRequest"></a>
### 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 |
<a name="object.HeadResponse"></a>
### Message HeadResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Object | [Object](#object.Object) | | Object without payload |
<a name="object.PutRequest"></a>
### 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 |
<a name="object.PutRequest.PutHeader"></a>
### 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 |
<a name="object.PutResponse"></a>
### Message PutResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) |
<a name="object.SearchRequest"></a>
### 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 |
<a name="object.SearchResponse"></a>
### Message SearchResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Addresses | [refs.Address](#refs.Address) | repeated | Addresses of found objects |
<!-- end messages -->
<!-- end enums -->
<a name="object/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## object/types.proto
<!-- end services -->
<a name="object.CreationPoint"></a>
### Message CreationPoint
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| UnixTime | [int64](#int64) | | Date of creation in unixtime format |
| Epoch | [uint64](#uint64) | | Date of creation in NeoFS epochs |
<a name="object.Header"></a>
### 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 |
<a name="object.IntegrityHeader"></a>
### 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 |
<a name="object.Link"></a>
### Message Link
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| type | [Link.Type](#object.Link.Type) | | Link type |
| ID | [bytes](#bytes) | | Object id |
<a name="object.Object"></a>
### 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 |
<a name="object.Range"></a>
### Message Range
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Offset | [uint64](#uint64) | | Offset of the data range |
| Length | [uint64](#uint64) | | Length of the data range |
<a name="object.StorageGroup"></a>
### 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 |
<a name="object.StorageGroup.Lifetime"></a>
### Message StorageGroup.Lifetime
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| unit | [StorageGroup.Lifetime.Unit](#object.StorageGroup.Lifetime.Unit) | | Lifetime type |
| Value | [int64](#int64) | | Lifetime value |
<a name="object.SystemHeader"></a>
### 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 |
<a name="object.Tombstone"></a>
### Message Tombstone
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Epoch | [uint64](#uint64) | | Epoch when tombstone was created |
<a name="object.Transform"></a>
### Message Transform
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| type | [Transform.Type](#object.Transform.Type) | | Type of object transformation |
<a name="object.UserHeader"></a>
### Message UserHeader
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Key | [string](#string) | | Key of the user's header |
| Value | [string](#string) | | Value of the user's header |
<!-- end messages -->
<a name="object.Link.Type"></a>
### 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 |
<a name="object.StorageGroup.Lifetime.Unit"></a>
### 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 |
<a name="object.Transform.Type"></a>
### 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 |
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

86
docs/query.md Normal file
View file

@ -0,0 +1,86 @@
# Protocol Documentation
<a name="top"></a>
## Table of Contents
- [query/types.proto](#query/types.proto)
- Messages
- [Filter](#query.Filter)
- [Query](#query.Query)
- [Scalar Value Types](#scalar-value-types)
<a name="query/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## query/types.proto
<!-- end services -->
<a name="query.Filter"></a>
### 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 |
<a name="query.Query"></a>
### Message Query
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Filters | [Filter](#query.Filter) | repeated | Filters is set of filters, should not be empty |
<!-- end messages -->
<a name="query.Filter.Type"></a>
### Filter.Type
Type can be Exact or Regex
| Name | Number | Description |
| ---- | ------ | ----------- |
| Exact | 0 | |
| Regex | 1 | |
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

61
docs/refs.md Normal file
View file

@ -0,0 +1,61 @@
# Protocol Documentation
<a name="top"></a>
## Table of Contents
- [refs/types.proto](#refs/types.proto)
- Messages
- [Address](#refs.Address)
- [Scalar Value Types](#scalar-value-types)
<a name="refs/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## refs/types.proto
<!-- end services -->
<a name="refs.Address"></a>
### 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 |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

149
docs/session.md Normal file
View file

@ -0,0 +1,149 @@
# Protocol Documentation
<a name="top"></a>
## 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)
<a name="session/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## session/service.proto
<a name="session.Session"></a>
### 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) |
<!-- end services -->
<a name="session.CreateRequest"></a>
### 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 |
<a name="session.CreateResponse"></a>
### 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 |
<!-- end messages -->
<!-- end enums -->
<a name="session/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## session/types.proto
<!-- end services -->
<a name="session.Token"></a>
### 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) |
<a name="session.VerificationHeader"></a>
### Message VerificationHeader
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| PublicKey | [bytes](#bytes) | | Session public key |
| KeySignature | [bytes](#bytes) | | Session public key signature. Signed by trusted side |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

137
docs/state.md Normal file
View file

@ -0,0 +1,137 @@
# Protocol Documentation
<a name="top"></a>
## 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)
<a name="state/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## state/service.proto
<a name="state.Status"></a>
### 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) |
<!-- end services -->
<a name="state.HealthRequest"></a>
### Message HealthRequest
HealthRequest message to check current state
<a name="state.HealthResponse"></a>
### 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 |
<a name="state.MetricsRequest"></a>
### Message MetricsRequest
MetricsRequest message to request node metrics
<a name="state.MetricsResponse"></a>
### 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 | |
<a name="state.NetmapRequest"></a>
### Message NetmapRequest
NetmapRequest message to request current node netmap
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |