diff --git a/.github/markdown.tmpl b/.github/markdown.tmpl new file mode 100644 index 0000000..f945c13 --- /dev/null +++ b/.github/markdown.tmpl @@ -0,0 +1,83 @@ +# Protocol Documentation + + +## Table of Contents +{{range .Files}} +{{$file_name := .Name}}- [{{.Name}}](#{{.Name}}) +{{if .Services}} - Services + {{range .Services}}- [{{.Name}}](#{{.FullName}}) + {{end}}{{end}} +{{if .Messages}} - Messages + {{range .Messages}}- [{{.LongName}}](#{{.FullName}}) + {{end}}{{end}} +{{end}} +- [Scalar Value Types](#scalar-value-types) + +{{range .Files}} +{{$file_name := .Name}} + +
+ +## {{.Name}} +{{.Description}} + +{{range .Services}} + + + +### Service "{{.FullName}}" +{{.Description}} + +``` +{{range .Methods -}} + rpc {{.Name}}({{if .RequestStreaming}}stream {{end}}{{.RequestLongType}}) returns ({{if .ResponseStreaming}}stream {{end}}{{.ResponseLongType}}); +{{end}} +``` + +{{range .Methods -}} +#### Method {{.Name}} + +{{.Description}} + +| Name | Input | Output | +| ---- | ----- | ------ | +| {{.Name}} | [{{.RequestLongType}}](#{{.RequestFullType}}) | [{{.ResponseLongType}}](#{{.ResponseFullType}}) | +{{end}}{{end}} + +{{range .Messages}} + + +### Message {{.LongName}} +{{.Description}} + +{{if .HasFields}} +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +{{range .Fields -}} + | {{.Name}} | [{{.LongType}}](#{{.FullType}}) | {{.Label}} | {{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} | +{{end}}{{end}} +{{end}} + +{{range .Enums}} + + +### {{.LongName}} +{{.Description}} + +| Name | Number | Description | +| ---- | ------ | ----------- | +{{range .Values -}} + | {{.Name}} | {{.Number}} | {{nobr .Description}} | +{{end}} + +{{end}} + +{{end}} + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +{{range .Scalars -}} + | {{.ProtoType}} | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} | +{{end}} diff --git a/Makefile b/Makefile index c17477a..64b0939 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,26 @@ +B=\033[0;1m +G=\033[0;92m +R=\033[0m + +# Reformat code +format: + @[ ! -z `which goimports` ] || (echo "install goimports" && exit 2) + @for f in `find . -type f -name '*.go' -not -path './vendor/*' -not -name '*.pb.go' -prune`; do \ + echo "${B}${G}⇒ Processing $$f ${R}"; \ + goimports -w $$f; \ + done + +# Regenerate documentation for protot files: +docgen: + @for f in `find . -type f -name '*.proto' -not -path './vendor/*' -exec dirname {} \; | sort -u `; do \ + echo "${B}${G}⇒ Documentation for $$(basename $$f) ${R}"; \ + protoc \ + --doc_opt=.github/markdown.tmpl,$${f}.md \ + --proto_path=.:./vendor:/usr/local/include \ + --doc_out=docs/ $${f}/*.proto; \ + done + +# Regenerate proto files: protoc: @go mod tidy -v @go mod vendor @@ -6,7 +29,9 @@ protoc: # Install specific version for protobuf lib @go list -f '{{.Path}}/...@{{.Version}}' -m github.com/golang/protobuf | xargs go get -v # Protoc generate - @find . -type f -name '*.proto' -not -path './vendor/*' \ - -exec protoc \ - --proto_path=.:./vendor \ - --gofast_out=plugins=grpc,paths=source_relative:. '{}' \; + @for f in `find . -type f -name '*.proto' -not -path './vendor/*'`; do \ + echo "${B}${G}⇒ Processing $$f ${R}"; \ + protoc \ + --proto_path=.:./vendor:/usr/local/include \ + --gofast_out=plugins=grpc,paths=source_relative:. $$f; \ + done diff --git a/README.md b/README.md index 9247a10..a6662c3 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/accounting/service.pb.go b/accounting/service.pb.go index 8708db3..ea86a8e 100644 Binary files a/accounting/service.pb.go and b/accounting/service.pb.go differ diff --git a/accounting/service.proto b/accounting/service.proto index b75bf9c..f975c23 100644 --- a/accounting/service.proto +++ b/accounting/service.proto @@ -8,16 +8,24 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; +// Accounting is a service that provides access for accounting balance +// information service Accounting { + // Balance returns current balance status of the NeoFS user rpc Balance(BalanceRequest) returns (BalanceResponse); } message BalanceRequest { + // OwnerID is a wallet address bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 2; } message BalanceResponse { + // Balance contains current account balance state decimal.Decimal Balance = 1; + // LockAccounts contains information about locked funds. Locked funds appear + // when user pays for storage or withdraw assets. repeated Account LockAccounts = 2; } diff --git a/accounting/types.pb.go b/accounting/types.pb.go index cb4b0c8..dd020ec 100644 Binary files a/accounting/types.pb.go and b/accounting/types.pb.go differ diff --git a/accounting/types.proto b/accounting/types.proto index 1b4e783..ac512b9 100644 --- a/accounting/types.proto +++ b/accounting/types.proto @@ -7,61 +7,63 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; -// Snapshot accounting messages message Account { + // OwnerID is a wallet address bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // Address is identifier of accounting record string Address = 2; + // ParentAddress is identifier of parent accounting record string ParentAddress = 3; + // ActiveFunds is amount of active (non locked) funds for account decimal.Decimal ActiveFunds = 4; + // Lifetime is time until account is valid (used for lock accounts) Lifetime Lifetime = 5 [(gogoproto.nullable) = false]; + // LockTarget is the purpose of lock funds (it might be withdraw or payment for storage) LockTarget LockTarget = 6; + // LockAccounts contains child accounts with locked funds repeated Account LockAccounts = 7; } +// LockTarget must be one of two options message LockTarget { oneof Target { + // WithdrawTarget used when user requested withdraw WithdrawTarget WithdrawTarget = 1; + // ContainerCreateTarget used when user requested creation of container ContainerCreateTarget ContainerCreateTarget = 2; } } -// Snapshot balance messages message Balances { + // Accounts contains multiple account snapshots repeated Account Accounts = 1 [(gogoproto.nullable) = false]; } -// PayIn / PayOut messages message PayIO { + // BlockID contains id of the NEO block where withdraw or deposit + // call was invoked uint64 BlockID = 1; + // Transactions contains all transactions that founded in block + // and used for PayIO repeated Tx Transactions = 2 [(gogoproto.nullable) = false]; } -// Clearing messages -message Clearing { - repeated Tx Transactions = 1 [(gogoproto.nullable) = false]; -} - -// Clearing messages -message Withdraw { - string ID = 1; - uint64 Epoch = 2; - Tx Transaction = 3; -} - -// Lifetime of locks message Lifetime { + // Unit can be Unlimited, based on NeoFS epoch or Neo block enum Unit { Unlimited = 0; NeoFSEpoch = 1; NeoBlock = 2; } + // Unit describes how lifetime is measured in account Unit unit = 1 [(gogoproto.customname) = "Unit"]; + // Value describes how long lifetime will be valid int64 Value = 2; } -// Transaction messages message Tx { + // Type can be withdrawal, payIO or inner enum Type { Unknown = 0; Withdraw = 1; @@ -69,38 +71,54 @@ message Tx { Inner = 3; } + // Type describes target of transaction Type type = 1 [(gogoproto.customname) = "Type"]; + // From describes sender of funds string From = 2; + // To describes receiver of funds string To = 3; + // Amount describes amount of funds decimal.Decimal Amount = 4; - bytes PublicKeys = 5; // of sender + // PublicKeys contains public key of sender + bytes PublicKeys = 5; } message Settlement { message Receiver { + // To is the address of funds recipient string To = 1; + // Amount is the amount of funds that will be sent decimal.Decimal Amount = 2; } message Container { + // CID is container identifier bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; + // SGIDs is a set of storage groups that successfully passed the audit repeated bytes SGIDs = 2 [(gogoproto.customtype) = "SGID", (gogoproto.nullable) = false]; } message Tx { + // From is the address of the sender of funds string From = 1; + // Container that successfully had passed the audit Container Container = 2 [(gogoproto.nullable) = false]; + // Receivers is a set of addresses of funds recipients repeated Receiver Receivers = 3 [(gogoproto.nullable) = false]; } + // Epoch contains an epoch when settlement was accepted uint64 Epoch = 1; + // Transactions is a set of transactions repeated Tx Transactions = 2; } message ContainerCreateTarget { + // CID is container identifier bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; } message WithdrawTarget { + // Cheque is a string representation of cheque id string Cheque = 1; } diff --git a/accounting/withdraw.pb.go b/accounting/withdraw.pb.go index 967a2ce..b50bc1c 100644 Binary files a/accounting/withdraw.pb.go and b/accounting/withdraw.pb.go differ diff --git a/accounting/withdraw.proto b/accounting/withdraw.proto index c099ef7..33ce402 100644 --- a/accounting/withdraw.proto +++ b/accounting/withdraw.proto @@ -7,55 +7,88 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; +// Withdraw is a service that provides withdraw assets operations from the NeoFS service Withdraw { + // Get returns cheque if it was signed by inner ring nodes rpc Get(GetRequest) returns (GetResponse); + // Put ask inner ring nodes to sign a cheque for withdraw invoke rpc Put(PutRequest) returns (PutResponse); + // List shows all user's checks rpc List(ListRequest) returns (ListResponse); + // Delete allows user to remove unused cheque rpc Delete(DeleteRequest) returns (DeleteResponse); } message Item { + // ID is a cheque identifier bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; + // OwnerID is a wallet address bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // Amount of funds decimal.Decimal Amount = 3; + // Height is the neo blockchain height until the cheque is valid uint64 Height = 4; + // Payload contains cheque representation in bytes bytes Payload = 5; } message GetRequest { + // ID is cheque identifier bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; + // OwnerID is a wallet address bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 3; } + message GetResponse { + // Item is cheque with meta information Item Withdraw = 1; } message PutRequest { + // OwnerID is a wallet address bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // Amount of funds decimal.Decimal Amount = 2; + // Height is the neo blockchain height until the cheque is valid uint64 Height = 3; + // MessageID is a nonce for uniq request (UUIDv4) bytes MessageID = 4 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false]; + // Signature is a signature of the sent request bytes Signature = 5; + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 6; } message PutResponse { + // ID is cheque identifier bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; } message ListRequest { + // OwnerID is a wallet address bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 2; } + message ListResponse { + // Item is a set of cheques with meta information repeated Item Items = 1; } message DeleteRequest { + // ID is cheque identifier bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; + // OwnerID is a wallet address bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // MessageID is a nonce for uniq request (UUIDv4) bytes MessageID = 3 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false]; + // Signature is a signature of the sent request bytes Signature = 4; + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 5; } + +// DeleteResponse is empty message DeleteResponse {} diff --git a/bootstrap/service.pb.go b/bootstrap/service.pb.go index 2fcdb4d..14f8e9e 100644 Binary files a/bootstrap/service.pb.go and b/bootstrap/service.pb.go differ diff --git a/bootstrap/service.proto b/bootstrap/service.proto index 3c9dced..a0f82dc 100644 --- a/bootstrap/service.proto +++ b/bootstrap/service.proto @@ -7,14 +7,19 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; -// The Bootstrap service definition. +// 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. service Bootstrap { + // Process is method that allows to register node in the network and receive actual netmap rpc Process(Request) returns (bootstrap.SpreadMap); } -// Request message to communicate between DHT nodes message Request { + // Type is NodeType, can be InnerRingNode (type=1) or StorageNode (type=2) int32 type = 1 [(gogoproto.customname) = "Type" , (gogoproto.nullable) = false, (gogoproto.customtype) = "NodeType"]; + // Info contains information about node bootstrap.NodeInfo info = 2 [(gogoproto.nullable) = false]; + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 3; } diff --git a/bootstrap/types.pb.go b/bootstrap/types.pb.go index a90de05..f279919 100644 Binary files a/bootstrap/types.pb.go and b/bootstrap/types.pb.go differ diff --git a/bootstrap/types.proto b/bootstrap/types.proto index 4d6e458..5a566da 100644 --- a/bootstrap/types.proto +++ b/bootstrap/types.proto @@ -10,13 +10,19 @@ option (gogoproto.stringer_all) = false; option (gogoproto.goproto_stringer_all) = false; message SpreadMap { + // Epoch is current epoch for netmap uint64 Epoch = 1; + // NetMap is a set of NodeInfos repeated NodeInfo NetMap = 2 [(gogoproto.nullable) = false]; } message NodeInfo { + // Address is a node [multi-address](https://github.com/multiformats/multiaddr) string Address = 1 [(gogoproto.jsontag) = "address"]; + // PubKey is a compressed public key representation in bytes bytes PubKey = 2 [(gogoproto.jsontag) = "pubkey,omitempty"]; + // Options is set of node optional information, such as storage capacity, node location, price and etc repeated string Options = 3 [(gogoproto.jsontag) = "options,omitempty"]; + // Status is bitmap status of the node uint64 Status = 4 [(gogoproto.jsontag) = "status", (gogoproto.nullable) = false, (gogoproto.customtype) = "NodeStatus"]; } diff --git a/container/service.pb.go b/container/service.pb.go index bc2e831..9cc6991 100644 Binary files a/container/service.pb.go and b/container/service.pb.go differ diff --git a/container/service.proto b/container/service.proto index a3b72ca..72c0899 100644 --- a/container/service.proto +++ b/container/service.proto @@ -8,61 +8,87 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; +// Container service provides API for manipulating with the container. service Service { - // Create container + // 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. rpc Put(PutRequest) returns (PutResponse); - // Delete container ... discuss implementation later + // Delete container removes it from the inner ring container storage. It + // also asynchronous process done by consensus. rpc Delete(DeleteRequest) returns (DeleteResponse); - // Get container + // Get container returns container instance rpc Get(GetRequest) returns (GetResponse); + // List returns all user's containers rpc List(ListRequest) returns (ListResponse); } -// NewRequest message to create new container message PutRequest { + // MessageID is a nonce for uniq container id calculation bytes MessageID = 1 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false]; - uint64 Capacity = 2; // not actual size in megabytes, but probability of storage availability + + // Capacity defines amount of data that can be stored in the container (doesn't used for now). + uint64 Capacity = 2; + + // OwnerID is a wallet address bytes OwnerID = 3 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + + // Rules define storage policy for the object inside the container. netmap.PlacementRule rules = 4 [(gogoproto.nullable) = false]; + + // Signature of the user (owner id) bytes Signature = 5; + + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 6; } -// PutResponse message to respond about container uuid message PutResponse { + // CID (container id) is a SHA256 hash of the container structure bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; } message DeleteRequest { + // CID (container id) is a SHA256 hash of the container structure bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; + + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 2; + + // Signature of the container owner bytes Signature = 3; } +// DeleteResponse is empty because delete operation is asynchronous and done +// via consensus in inner ring nodes message DeleteResponse { } -// GetRequest message to fetch container placement rules message GetRequest { + // CID (container id) is a SHA256 hash of the container structure bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; + + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 2; } -// GetResponse message with container structure message GetResponse { + // Container is a structure that contains placement rules and owner id container.Container Container = 1; } -// ListRequest message to list containers for user message ListRequest { + // OwnerID is a wallet address bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 2; } -// ListResponse message to respond about all user containers message ListResponse { + // CID (container id) is list of SHA256 hashes of the container structures repeated bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; } diff --git a/container/types.proto b/container/types.proto index b05001f..efcaee8 100644 --- a/container/types.proto +++ b/container/types.proto @@ -9,8 +9,8 @@ option (gogoproto.stable_marshaler_all) = true; // The Container service definition. message Container { - bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; - bytes Salt = 2 [(gogoproto.customtype) = "UUID", (gogoproto.nullable) = false]; - uint64 Capacity = 3; - netmap.PlacementRule Rules = 4 [(gogoproto.nullable) = false]; + bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; // OwnerID is a wallet address. + bytes Salt = 2 [(gogoproto.customtype) = "UUID", (gogoproto.nullable) = false]; // Salt is a nonce for unique container id calculation. + uint64 Capacity = 3; // Capacity defines amount of data that can be stored in the container (doesn't used for now). + netmap.PlacementRule Rules = 4 [(gogoproto.nullable) = false]; // Rules define storage policy for the object inside the container. } diff --git a/decimal/decimal.pb.go b/decimal/decimal.pb.go index e125af4..d2bed7d 100644 Binary files a/decimal/decimal.pb.go and b/decimal/decimal.pb.go differ diff --git a/decimal/decimal.proto b/decimal/decimal.proto index 31bb963..42cf2df 100644 --- a/decimal/decimal.proto +++ b/decimal/decimal.proto @@ -6,9 +6,12 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; +// Decimal is a structure used for representation of assets amount message Decimal { option (gogoproto.goproto_stringer) = false; + // Value is value number int64 Value = 1; + // Precision is precision number uint32 Precision = 2; } diff --git a/docs/.gitkeep b/docs/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/accounting.md b/docs/accounting.md new file mode 100644 index 0000000..f08bd52 --- /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 0000000..dfada2c --- /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 0000000..5ff0d89 --- /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 0000000..62acb86 --- /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 0000000..5ba1845 --- /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 0000000..9deb2c1 --- /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 0000000..c3051ab --- /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 0000000..8ea703e --- /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 0000000..6d240c1 --- /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 | + diff --git a/object/service.pb.go b/object/service.pb.go index aede5cd..8301ebb 100644 Binary files a/object/service.pb.go and b/object/service.pb.go differ diff --git a/object/service.proto b/object/service.proto index 0a03383..6f13d55 100644 --- a/object/service.proto +++ b/object/service.proto @@ -9,111 +9,132 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; +// Object service provides API for manipulating with the object. service Service { - // Get the object from a container + + // 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. rpc Get(GetRequest) returns (stream GetResponse); - // Put the object into a container + // 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. rpc Put(stream PutRequest) returns (PutResponse); // Delete the object from a container rpc Delete(DeleteRequest) returns (DeleteResponse); - // Get MetaInfo + // 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. rpc Head(HeadRequest) returns (HeadResponse); - // Search by MetaInfo + // Search objects in container. Version of query language format SHOULD BE + // set to 1. Search query represented in serialized format (see query + // package). rpc Search(SearchRequest) returns (SearchResponse); - // Get ranges of object payload + // GetRange of data payload. Ranges are set of pairs (offset, length). + // Fragments order in response corresponds to ranges order in request. rpc GetRange(GetRangeRequest) returns (GetRangeResponse); - // Get hashes of object ranges + // 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. rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse); } message GetRequest { - uint64 Epoch = 1; - refs.Address Address = 2 [(gogoproto.nullable) = false]; - uint32 TTL = 3; + uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value + refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id) + uint32 TTL = 3; // TTL must be larger than zero, it decreased in every neofs-node } message GetResponse { oneof R { - Object object = 1; - bytes Chunk = 2; + Object object = 1; // Object header and some payload + bytes Chunk = 2; // Chunk of remaining payload } } message PutRequest { message PutHeader { - uint64 Epoch = 1; - Object Object = 2; - uint32 TTL = 3; - session.Token Token = 4; + uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value + Object Object = 2; // Object with at least container id and owner id fields + uint32 TTL = 3; // TTL must be larger than zero, it decreased in every neofs-node + session.Token Token = 4; // Token with session public key and user's signature } oneof R { - PutHeader Header = 1; - bytes Chunk = 2; + PutHeader Header = 1; // Header should be the first message in the stream + bytes Chunk = 2; // Chunk should be a remaining message in stream should be chunks } } message PutResponse { - refs.Address Address = 1 [(gogoproto.nullable) = false]; + refs.Address Address = 1 [(gogoproto.nullable) = false]; // Address of object (container id + object id) } message DeleteRequest { - uint64 Epoch = 1; - refs.Address Address = 2 [(gogoproto.nullable) = false]; - bytes OwnerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "OwnerID"]; - uint32 TTL = 4; - session.Token Token = 5; + uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value + refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id) + bytes OwnerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "OwnerID"]; // OwnerID is a wallet address + uint32 TTL = 4; // TTL must be larger than zero, it decreased in every neofs-node + session.Token Token = 5; // Token with session public key and user's signature } + +// DeleteResponse is empty because we cannot guarantee permanent object removal +// in distributed system. message DeleteResponse {} -// HeadRequest.FullHeader == true, for fetch all headers message HeadRequest { - uint64 Epoch = 1; - refs.Address Address = 2 [(gogoproto.nullable) = false, (gogoproto.customtype) = "Address"]; - bool FullHeaders = 3; - uint32 TTL = 4; + uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value + refs.Address Address = 2 [(gogoproto.nullable) = false, (gogoproto.customtype) = "Address"]; // Address of object (container id + object id) + bool FullHeaders = 3; // FullHeaders can be set true for extended headers in the object + uint32 TTL = 4; // TTL must be larger than zero, it decreased in every neofs-node } message HeadResponse { - Object Object = 1; + Object Object = 1; // Object without payload } message SearchRequest { - uint64 Epoch = 1; - uint32 Version = 2; - bytes ContainerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "CID"]; - bytes Query = 4; - uint32 TTL = 5; + uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value + uint32 Version = 2; // Version of search query format + bytes ContainerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "CID"]; // ContainerID for searching the object + bytes Query = 4; // Query in the binary serialized format + uint32 TTL = 5; // TTL must be larger than zero, it decreased in every neofs-node } message SearchResponse { - repeated refs.Address Addresses = 1 [(gogoproto.nullable) = false]; + repeated refs.Address Addresses = 1 [(gogoproto.nullable) = false]; // Addresses of found objects } message GetRangeRequest { - uint64 Epoch = 1; - refs.Address Address = 2 [(gogoproto.nullable) = false]; - repeated Range Ranges = 3 [(gogoproto.nullable) = false]; - uint32 TTL = 4; + uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value + refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id) + repeated Range Ranges = 3 [(gogoproto.nullable) = false]; // Ranges of object's payload to return + uint32 TTL = 4; // TTL must be larger than zero, it decreased in every neofs-node } message GetRangeResponse { - repeated bytes Fragments = 1; + repeated bytes Fragments = 1; // Fragments of object's payload } message GetRangeHashRequest { - uint64 Epoch = 1; - refs.Address Address = 2 [(gogoproto.nullable) = false]; - repeated Range Ranges = 3 [(gogoproto.nullable) = false]; - bytes Salt = 4; - uint32 TTL = 5; + uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value + refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id) + repeated Range Ranges = 3 [(gogoproto.nullable) = false]; // Ranges of object's payload to calculate homomorphic hash + bytes Salt = 4; // Salt is used to XOR object's payload ranges before hashing, it can be nil + uint32 TTL = 5; // TTL must be larger than zero, it decreased in every neofs-node } message GetRangeHashResponse { - repeated bytes Hashes = 1 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false]; + repeated bytes Hashes = 1 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false]; // Homomorphic hashes of all ranges } diff --git a/object/types.proto b/object/types.proto index a7cbd8c..30e468e 100644 --- a/object/types.proto +++ b/object/types.proto @@ -9,99 +9,97 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; message Range { - uint64 Offset = 1; - uint64 Length = 2; + uint64 Offset = 1; // Offset of the data range + uint64 Length = 2; // Length of the data range } message UserHeader { - string Key = 1; - string Value = 2; + string Key = 1; // Key of the user's header + string Value = 2; // Value of the user's header } message Header { oneof Value { - Link Link = 1; - refs.Address Redirect = 2; - UserHeader UserHeader = 3; - Transform Transform = 4; - Tombstone Tombstone = 5; - // session-related info: session.VerificationHeader - session.VerificationHeader Verify = 6; - // integrity-related info - bytes HomoHash = 7 [(gogoproto.customtype) = "Hash"]; - bytes PayloadChecksum = 8; - IntegrityHeader Integrity = 9; - StorageGroup StorageGroup = 10; + Link Link = 1; // Link to other objects + refs.Address Redirect = 2; // RedirectNot used yet + UserHeader UserHeader = 3; // UserHeader defined by user + Transform Transform = 4; // Transform defines transform operation (e.g. payload split) + Tombstone Tombstone = 5; // Tombstone header that set up in deleted objects + session.VerificationHeader Verify = 6; // Verify header that contains session public key and user's signature + bytes HomoHash = 7 [(gogoproto.customtype) = "Hash"]; // Homomorphic hash of original object payload + bytes PayloadChecksum = 8; // PayloadChecksum of actual object's payload + IntegrityHeader Integrity = 9; // Integrity header with checksum of all above headers in the object + StorageGroup StorageGroup = 10; // StorageGroup contains meta information for the data audit } } message Tombstone { - uint64 Epoch = 1; + uint64 Epoch = 1; // Epoch when tombstone was created } message SystemHeader { - uint64 Version = 1; - uint64 PayloadLength = 2; + uint64 Version = 1; // Version of the object structure + uint64 PayloadLength = 2; // Object payload length - bytes ID = 3 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false]; - bytes OwnerID = 4 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; - bytes CID = 5 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; - CreationPoint CreatedAt = 6 [(gogoproto.nullable) = false]; + bytes ID = 3 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false]; // ObjectID is a UUID + bytes OwnerID = 4 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; // OwnerID is a wallet address + bytes CID = 5 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; // ContainerID is a SHA256 hash of the container structure + CreationPoint CreatedAt = 6 [(gogoproto.nullable) = false]; // Timestamp of object creation } message CreationPoint { - int64 UnixTime = 1; - uint64 Epoch = 2; + int64 UnixTime = 1; // Date of creation in unixtime format + uint64 Epoch = 2; // Date of creation in NeoFS epochs } message IntegrityHeader { - bytes HeadersChecksum = 1; - bytes ChecksumSignature = 2; + bytes HeadersChecksum = 1; // Checksum of all above headers in the object + bytes ChecksumSignature = 2; // User's signature of checksum to verify if it is correct } message Link { enum Type { Unknown = 0; - Parent = 1; - Previous = 2; - Next = 3; - Child = 4; - StorageGroup = 5; + 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 } - Type type = 1; - bytes ID = 2 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false]; + Type type = 1; // Link type + bytes ID = 2 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false]; // Object id } message Transform { enum Type { Unknown = 0; - Split = 1; - Sign = 2; - Mould = 3; + 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 } - Type type = 1; + Type type = 1; // Type of object transformation } message Object { - SystemHeader SystemHeader = 1 [(gogoproto.nullable) = false]; - repeated Header Headers = 2 [(gogoproto.nullable) = false]; - bytes Payload = 3; + SystemHeader SystemHeader = 1 [(gogoproto.nullable) = false]; // System header + repeated Header Headers = 2 [(gogoproto.nullable) = false]; // Extended headers + bytes Payload = 3; // Object's payload } message StorageGroup { - uint64 ValidationDataSize = 1; - bytes ValidationHash = 2 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false]; + uint64 ValidationDataSize = 1; // Size of the all object's payloads included into storage group + bytes ValidationHash = 2 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false]; // Homomorphic hash of all object's payloads included into storage group message Lifetime { enum Unit { - Unlimited = 0; - NeoFSEpoch = 1; - UnixTime = 2; + 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 } - Unit unit = 1 [(gogoproto.customname) = "Unit"]; - int64 Value = 2; + Unit unit = 1 [(gogoproto.customname) = "Unit"]; // Lifetime type + int64 Value = 2; // Lifetime value } - Lifetime lifetime = 3 [(gogoproto.customname) = "Lifetime"]; + Lifetime lifetime = 3 [(gogoproto.customname) = "Lifetime"]; // Time until storage group is valid } diff --git a/query/types.pb.go b/query/types.pb.go index 51f682e..8fa3dbe 100644 Binary files a/query/types.pb.go and b/query/types.pb.go differ diff --git a/query/types.proto b/query/types.proto index 5f46072..884a6bd 100644 --- a/query/types.proto +++ b/query/types.proto @@ -9,17 +9,23 @@ option (gogoproto.stable_marshaler_all) = true; message Filter { option (gogoproto.goproto_stringer) = false; + // Type can be Exact or Regex enum Type { Exact = 0; Regex = 1; } + + // Type of filter Type type = 1 [(gogoproto.customname) = "Type"]; + // Name of field that should be filtered string Name = 2; + // Value that should be used for filter string Value = 3; } message Query { option (gogoproto.goproto_stringer) = false; + // Filters is set of filters, should not be empty repeated Filter Filters = 1 [(gogoproto.nullable) = false]; } diff --git a/refs/types.pb.go b/refs/types.pb.go index 33f7578..87f3fce 100644 Binary files a/refs/types.pb.go and b/refs/types.pb.go differ diff --git a/refs/types.proto b/refs/types.proto index e607f34..15355ae 100644 --- a/refs/types.proto +++ b/refs/types.proto @@ -9,7 +9,10 @@ option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stringer_all) = false; option (gogoproto.goproto_stringer_all) = false; +// Address of object (container id + object id) message Address { - bytes ObjectID = 1[(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false]; // UUID - bytes CID = 2[(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; // sha256 + // ObjectID is an object identifier + bytes ObjectID = 1[(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false]; + // CID is container identifier + bytes CID = 2[(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; } diff --git a/session/service.pb.go b/session/service.pb.go index da85708..4961b0d 100644 Binary files a/session/service.pb.go and b/session/service.pb.go differ diff --git a/session/service.proto b/session/service.proto index ee56a22..484425b 100644 --- a/session/service.proto +++ b/session/service.proto @@ -7,21 +7,41 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; + service 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 + + // - First client stream message SHOULD BE type of `CreateRequest_Init`. + // - First server stream message SHOULD BE type of `CreateResponse_Unsigned`. + // - Second client stream message SHOULD BE type of `CreateRequest_Signed`. + // - Second server stream message SHOULD BE type of `CreateResponse_Result`. + rpc Create (stream CreateRequest) returns (stream CreateResponse); } message CreateRequest { + // Message should be one of oneof Message { + // Message to init session opening. Carry: + // owner of manipulation object; + // ID of manipulation object; + // token lifetime bounds. session.Token Init = 1; + // Signed Init message response (Unsigned) from server with user private key session.Token Signed = 2; } } message CreateResponse { oneof Message { + // Unsigned token with token ID and session public key generated on server side session.Token Unsigned = 1; + // Resulting token which can be used for object placing through an trusted intermediary session.Token Result = 2; } } diff --git a/session/types.pb.go b/session/types.pb.go index ce0e0a4..d39961e 100644 Binary files a/session/types.pb.go and b/session/types.pb.go differ diff --git a/session/types.proto b/session/types.proto index 8989040..bf804bf 100644 --- a/session/types.proto +++ b/session/types.proto @@ -7,16 +7,26 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; message VerificationHeader { + // Session public key bytes PublicKey = 1; + // Session public key signature. Signed by trusted side bytes KeySignature = 2; } +// User token granting rights for object manipulation message Token { + // Header carries verification data of session key VerificationHeader Header = 1 [(gogoproto.nullable) = false]; + // Owner of manipulation object bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // Initial epoch of token lifetime uint64 FirstEpoch = 3; + // Last epoch of token lifetime uint64 LastEpoch = 4; + // ID of manipulation object repeated bytes ObjectID = 5 [(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false]; + // Token signature. Signed by owner of manipulation object bytes Signature = 6; + // Token ID (UUID) bytes ID = 7 [(gogoproto.customtype) = "TokenID", (gogoproto.nullable) = false]; } diff --git a/state/service.pb.go b/state/service.pb.go index f71dad6..a368410 100644 Binary files a/state/service.pb.go and b/state/service.pb.go differ diff --git a/state/service.proto b/state/service.proto index d0e59b4..3c85d86 100644 --- a/state/service.proto +++ b/state/service.proto @@ -7,10 +7,14 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; -// The Status service definition. +// Status service provides node's healthcheck and status info service Status { + // Netmap request allows to receive current [bootstrap.SpreadMap](bootstrap.md#bootstrap.SpreadMap) rpc Netmap(NetmapRequest) returns (bootstrap.SpreadMap); + // Metrics request allows to receive metrics in prometheus format rpc Metrics(MetricsRequest) returns (MetricsResponse); + // HealthCheck request allows to check health status of the node. + // If node unhealthy field Status would contains detailed info. rpc HealthCheck(HealthRequest) returns (HealthResponse); } @@ -32,6 +36,8 @@ message HealthRequest {} // HealthResponse message with current state message HealthResponse { + // Healthy is true when node alive and healthy bool Healthy = 1; + // Status contains detailed information about health status string Status = 2; }