From 04a5b80550190b46167d1dedae070d4ffcaeac2a Mon Sep 17 00:00:00 2001 From: Evgeniy Kulikov Date: Wed, 20 Nov 2019 16:40:06 +0300 Subject: [PATCH 01/12] docs: prepare template and gen make command - add markdown simple template - add Makefile `docgen` command --- .github/markdown.tmpl | 83 +++++++++++++++++++++++++++++++++++++++++++ Makefile | 33 ++++++++++++++--- docs/.gitkeep | 0 3 files changed, 112 insertions(+), 4 deletions(-) create mode 100644 .github/markdown.tmpl create mode 100644 docs/.gitkeep diff --git a/.github/markdown.tmpl b/.github/markdown.tmpl new file mode 100644 index 00000000..f945c137 --- /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}} + +

Top

+ +## {{.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 c17477a8..64b09397 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/docs/.gitkeep b/docs/.gitkeep new file mode 100644 index 00000000..e69de29b From 5befe14968a3b5eff2db684299830748a2b1ac36 Mon Sep 17 00:00:00 2001 From: Evgeniy Kulikov Date: Wed, 20 Nov 2019 18:57:51 +0300 Subject: [PATCH 02/12] docs: add accounting proto documentation --- accounting/service.proto | 8 ++++++ accounting/types.proto | 54 ++++++++++++++++++++++++++------------- accounting/withdraw.proto | 33 ++++++++++++++++++++++++ 3 files changed, 77 insertions(+), 18 deletions(-) diff --git a/accounting/service.proto b/accounting/service.proto index b75bf9c9..f975c232 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.proto b/accounting/types.proto index 1b4e7838..ac512b91 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.proto b/accounting/withdraw.proto index c099ef7c..33ce402f 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 {} From 5aaea793da22bee51f79debbc3a4caae86ccae5b Mon Sep 17 00:00:00 2001 From: alexvanin Date: Wed, 20 Nov 2019 18:50:10 +0300 Subject: [PATCH 03/12] docs: add object proto documentation --- object/service.proto | 113 +++++++++++++++++++++++++------------------ object/types.proto | 96 ++++++++++++++++++------------------ 2 files changed, 114 insertions(+), 95 deletions(-) diff --git a/object/service.proto b/object/service.proto index 0a033838..6f13d55c 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 a7cbd8c7..30e468ec 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 } From 1383aabfa55309023c423222978b77cd44c6022e Mon Sep 17 00:00:00 2001 From: Evgeniy Kulikov Date: Wed, 20 Nov 2019 19:07:48 +0300 Subject: [PATCH 04/12] docs: add decimal proto documentation --- decimal/decimal.proto | 3 +++ 1 file changed, 3 insertions(+) diff --git a/decimal/decimal.proto b/decimal/decimal.proto index 31bb9636..42cf2df4 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; } From 811bcbd14fa110335bd2c62bba186bd7c0d09c16 Mon Sep 17 00:00:00 2001 From: Evgeniy Kulikov Date: Wed, 20 Nov 2019 19:11:46 +0300 Subject: [PATCH 05/12] docs: add refs proto documentation --- refs/types.proto | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/refs/types.proto b/refs/types.proto index e607f349..15355ae0 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]; } From 84ac6f55a3be265db8d8cccb709f5a328f4ab401 Mon Sep 17 00:00:00 2001 From: Evgeniy Kulikov Date: Wed, 20 Nov 2019 19:21:45 +0300 Subject: [PATCH 06/12] docs: add bootstrap proto documentation --- bootstrap/service.proto | 9 +++++++-- bootstrap/types.proto | 6 ++++++ 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/bootstrap/service.proto b/bootstrap/service.proto index 3c9dcedc..a0f82dca 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.proto b/bootstrap/types.proto index 4d6e458b..5a566dae 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"]; } From 6c0ee948e660c80cb7bf24818acce38eaed66f2f Mon Sep 17 00:00:00 2001 From: Evgeniy Kulikov Date: Wed, 20 Nov 2019 19:25:53 +0300 Subject: [PATCH 07/12] docs: add query proto documentation --- query/types.proto | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/query/types.proto b/query/types.proto index 5f460724..884a6bd1 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]; } From 6050ab755c8f05e285dfd4b5b90aab95f837257f Mon Sep 17 00:00:00 2001 From: Evgeniy Kulikov Date: Wed, 20 Nov 2019 19:33:10 +0300 Subject: [PATCH 08/12] docs: add state proto documentation --- state/service.proto | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/state/service.proto b/state/service.proto index d0e59b4f..3c85d860 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; } From 04f1cbca48f7c95aacc96e565e424b31760af598 Mon Sep 17 00:00:00 2001 From: Leonard Lyubich Date: Wed, 20 Nov 2019 19:46:30 +0300 Subject: [PATCH 09/12] docs: add session proto documentation --- session/service.proto | 20 ++++++++++++++++++++ session/types.proto | 10 ++++++++++ 2 files changed, 30 insertions(+) diff --git a/session/service.proto b/session/service.proto index ee56a220..484425bc 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.proto b/session/types.proto index 8989040d..bf804bf4 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]; } From ad86acf62f40677c7b3a5fac969b032e00cf9e06 Mon Sep 17 00:00:00 2001 From: alexvanin Date: Wed, 20 Nov 2019 20:16:24 +0300 Subject: [PATCH 10/12] docs: add container proto documentation --- container/service.proto | 46 ++++++++++++++++++++++++++++++++--------- container/types.proto | 8 +++---- 2 files changed, 40 insertions(+), 14 deletions(-) diff --git a/container/service.proto b/container/service.proto index a3b72ca8..72c08993 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 b05001fb..efcaee82 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. } From 0af63c42ccf04fd9b3f919512c2ae522f0747c03 Mon Sep 17 00:00:00 2001 From: alexvanin Date: Wed, 20 Nov 2019 21:18:44 +0300 Subject: [PATCH 11/12] docs: regenerate proto files --- accounting/service.pb.go | Bin 18543 -> 18893 bytes accounting/types.pb.go | Bin 93344 -> 83674 bytes accounting/withdraw.pb.go | Bin 65250 -> 66389 bytes bootstrap/service.pb.go | Bin 12895 -> 13179 bytes bootstrap/types.pb.go | Bin 17190 -> 17479 bytes container/service.pb.go | Bin 53662 -> 54848 bytes decimal/decimal.pb.go | Bin 8464 -> 8573 bytes object/service.pb.go | Bin 109487 -> 112198 bytes query/types.pb.go | Bin 15126 -> 15260 bytes refs/types.pb.go | Bin 9127 -> 9232 bytes session/service.pb.go | Bin 22812 -> 22845 bytes session/types.pb.go | Bin 21017 -> 21236 bytes state/service.pb.go | Bin 29226 -> 29918 bytes 13 files changed, 0 insertions(+), 0 deletions(-) diff --git a/accounting/service.pb.go b/accounting/service.pb.go index 8708db374c6f37037fb8c01da66378b96ebd223f..ea86a8ea5b39319dff0db38b128e077209a9233a 100644 GIT binary patch delta 478 zcmbu5u}T9$5Qd4lB6p3oU|_J6m^7(O6%j!Q5iyPBWN$86yzIuA-5jwItSp6Xd<-G@ z7&g9uk6>x*5)(*oH8br0e>4AnztlcL?d`SR>2%<#GQ^kXpal>rEK72LdCnw~rQ63% z4UM!JKI`3n^o>RXn0aw9CMc07#NeiA;DOk-Ks(4uF`-Zn+5jzxmte>ia$;;wt0ehK zP9x?FOEii=S>sR}0p*#=#2b{dKGyL@APya6=|&%Z8n=(pKCtSp|EG-BEkm2a@(i7} z25@Y>gEH#kC51P+wAZff1UR1)a+XF~H6;UHVw5>91tJ8*S;h%LY%A@iIb#JVLQdLY zm>z{idLN#WW? delta 121 zcmX>*neqJu#tk!=W&O+ZQj0uY6i@(6aPo2Hz|GMtcUeT75_1ysl2cJsO)lb$ob1D; qzzPXU}<` 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 delta 7518 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 delta 151 zcmeyJc0Xl<3v;}_zCuuHVQFe{i9&8_adBdLszOP=LUMj?ZfRa-a$-rULQ-l;d1`8& zf{RCpLSBAKYB5(yWkD)jS8+*EX>y4|H5X?HNEi)FUdZEH?eYVFDdt%?{8*5-a6m!ov+{Sd6vP*8d-w!AcJ$L2`~b4<3J2C%_|tnZv{sc&q2eudjAKcb}LvEDDF-w=B(LnAV{pbt>Ay?6@Sd zevoAgMPc$LN=bO( zk;4Y$)dVS{L21aBgg#9+(&?;uukzl_EBoEsh7~(+_KL+#ghj>jwi}cB-~-=Ic<^ML zSRhDYg;cccLljj;#>_rgrzC>V1t7^Z*@jGK?K1FeoguUO=?#y#!y{J>u|lqzFJS)& O@R6y+=)K-g4hH|mK%y`J delta 163 zcmX@!!MLoAal>sUdDnvcRWDWb zrg>%&T@Eg5ts>$s3*qe)#6J+!pWsh$=OTiqUVj?KB#`LBMKj$~_ue}9+;dNT`Ay}g zdzJ5QRR%6knLfzeKHtvRIBFf#6eI;CGkkl(9(So669gu;_l}3FYar2{Y?%3a}?R1cNaIize3{wIz zi7pYL^Uw@bY(D9z`&;z z(d*6S-KXZFQ4d@OiM+8skx2Ws<7PAOs+^DitVYG1GnLw11Yc&Thxd6x9Cn0FJvP?d7xo0>#fnZXf#xt)t@Ib6-{b^VEDFU2e@iBRI-TDM82B`SGcx zG!YRG8J=Lu-3vrb_oG;%AF9_%GIpdr-nb?UJl5*twtTmB{n>O|JZNoJy$SK2%b5)%~gt#Ki^OgAqt29mLE&xfCe zVaFWoD7+erdI$6fM%(u9T+#>|>O-`FxSr9&hdY>e7oGq(Zkw*UF@nVEW9yc?6fn*3 zwEg`{t_kX3w`!3w__Pyv&3vbGa}`|$CC$R{DwLcoEo7j1#Q3k@YZl*k;@baiBJJ(H Z|7ap#Y#%&wBEN6H)q0|d6suR<(O=n=7;69k delta 954 zcma)5O=#0l90!xMv@7EJ;pY0We!=ndLJbLlyMLg~#_|m#AZFex2B)`1hM}F`B4iBWguJr1OR4A3; z9_cj57AKTJi%_aRCcqppT%t1qHtB%j*i1KV;-V>~FW38P?kqvz8UyitehT*|BlugY zUa9GA-7wj9fB?Wvn_aC8L4etK4&TUy`L&L)8@2!#2XQYxizTI!Y;cRvVJ*Pd6Djw zXAMHzj!j9hLbr!CL4V|McG4nnZZ@NAyG?u|s?!PV=2PBL?5^xT;8CnD;+3%+FM2z1 zRq@VGUy`p0n`I(w#x`n$Fk>^I-nMjuw1~~X^-IBOCOs;Px$v%cHn%U8j#Wp(cT5(P zq|D_8<1WDiHRGL|dn;cTM9rk9<*@{O5{JTu;{vC|?fdbU(u*BhT@n?;liAHdC<$-_uu{Pr+Zfz>3i+|OU b_^qz~zxbck`*Jk0OweaO)h>FUHFx(fh0QU@ diff --git a/decimal/decimal.pb.go b/decimal/decimal.pb.go index e125af418fc17747c33a36b99d2c1002d42b8d3a..d2bed7d3b89eda3e3210c815c09b7209451ac6b8 100644 GIT binary patch delta 158 zcmbQ>^w(*_0VXGXeFc})B88&Vf}+&o z)Vz|!lFa-(h5R&y#Ny)A5}@kb{L;LV$@`fkRDs5XCFYc-f($7GGxADvlTwSgIHAIM jC1xg*zc9Hf096JQ0c|V>nFUl0G#ko+=-6z|d{Y(x2+ui( delta 71 zcmezCG{I@Z0Vbo8%7Rn{m(=9U+{7G(;*z4$b>&4S2O8s zN;5l&Ob;c9;KGedQ5eCMTm1=c{0VOS2cGxpqtnrZEQA3Ky{WExb?&+6oO`>!|LycI zf1Lhdyd}4`XooX)JYidCWtpTU&I`AoDMzBjjeVv_D5V|EN@0X@%v7++g<|DMPj7JK z$Z)RrL^c4PR1{0=jGUH^W3mhDI3FIrxAo$wXbm=ioU^rJ=II!-=ql?3hdwSDRbmoxj5q9%w$oD0yB9181J1%YOFF3n zmP@%sIB)T2k!cZ=Oh`JffMSk09@6VswgTas5f_eaVJ2 z*Od*L(EWsMwG4%?jm96myF+ihNp4XiLv!< z-Ziq<*#u+ID-wn|%!I;Xz*xf0T)36ht&a{7pqG6hgo)DjCBtoD*av*rCq*W2;aiKc zX`jcQ2^9iPpM$|h0IFZQ{apRZr=x0u@*%V9GKSmD;6nzVheBX*X;UXj&?RFvbLj;% zj?i9dUBi9|PJ&XedZbNr9m73M*nl(as_xw5I2b0)EBMWwq`tU3({LIIoA$P+I>*Np zsf@gh=_;U|^9?YG#34x^jwgXvKNwgqOIXdaJ{>(qG^?JE{=cIS}Q~mZ^t+GE4pRS)c Ty7Yfv=?C%APw~-XSI_+gb0|v& delta 364 zcmX^1hHd?IwhjLJlLI1HH}BI|V6o8GSMW$pObJRYEKMyg(Q_-!$pP_Gixg~a6-tUq zQ*{*5@{1JGQcIFE6cTfC6f(fF#hdRMw|GyMZRVZ4p`lbDQ6V`$uOu-uFSUq^GoZ9& zvO%-hI z?6LWG`xYLs6aP(h;zn}fed%#5{$hR0Y?H#N-l%{33;*)b!Mf%{!USF^a>K9F9A6rHMgLoaln9eeagj5!!DxiVMdsxyG{1S69BovBEiZb)k!OACxvpP*a#40!W dE^7*tg2H46Htoq-+`5}5v9YpjKE-v(0095Y9Vh?* diff --git a/refs/types.pb.go b/refs/types.pb.go index 33f7578a684f5afeae4c69681a6ab90e0173119d..87f3fcede248ce3edcab87de6efcbef50939296b 100644 GIT binary patch delta 175 zcmZ4PKEY$d4yJm2eFevql%mw)Vuk!Ph5V$f)Z`KcjpY2ilElos)FOq<6a{UVaAt}o zS4m|-DqKf#Nl__Kc{LX&&=`NPUQZW=%wmPaJcORqypqhc%+w+-PPhs SW@m^#WP4%yHrp|0DgXf2JUkZw delta 60 zcmbQ>vD|&b4kqoA%7Rn{$CQ+!)Z$`=;*z4$8cXtkmQZPZtFwFjY5Qa&D=-pXF1?%b5#whp!Vi`YTrR z8cm_yaZ^dvXVKZ6s0D!`BQoK19U8i%KDa4Jo(QQ+fj%7`m9A&DHQW-EgN%EWLC6V{ z$U@*4cBOzI<`BCV)RWLB3r1qqq=9c#~c}$6~S&wjzRKO+W7@(I+z$cPG9Do>~ zk^3J3YN5QOEMtE|kEmZUJwfY!&mZqJjl64DM=HCjm~oalwi!w!5zs;Gbu)P6KEi-X z>{HV?L@wk(-c69noh|id)HgNh5Fw{yS@#chZk}Y6b}-dp{v9o7ck1I(J)2EOQ_cLP u6LX0Fy*kS)kM29=n&mA14Ai?;TP?e~rfw`ykCv}qNQ!5n|6eiDLR-U|vlY6oXv;O8D<~CN%lFEWqg^>L0 z)I5dalA_Y&5`}6mPLI^Yl++@idL%G;I;X#?e|cVNk*5oiFp!BZIC(j<{A6P;6Lq)D zqT&+Qg8bwRBn_pRc_n5hNCFCz=WzL}`y^s2RluTFhTB)&KPf9UxdhD_(Xr^llV@>< zs0U}J=Ovbu7NsKF7#*8bS%M-m*^0+!@+=-X4w$mZ+j!DAVH}0Y(!AR2P~Kz*7F{+7 KdvgwNhbsVgm|6n> diff --git a/state/service.pb.go b/state/service.pb.go index f71dad6b1b621a96ecd7c3d509b4dc6c33cde821..a3684101176dc7672a7ab3b85e33ed22fec9b65c 100644 GIT binary patch delta 764 zcmd6jp-uxq5Qfu$xhhokB$zg#?E`>m3W17ZDhVXp-8pW<-R`kFOM}8AIf=nwP$Yey zDhw}xBn)@g)-)Irg4xMT{{8=%@8zwrcyGK8S_l0;oS;Z4xdrWkTtJv5Xuw#7AX0t9 zuThXxnr5^VPpwUhi`HnL4JITgc#zhR(8hy8t|=PD}qoSXL{vf!tZ{66EWuOCH*ncPnJW1m)ERBU#QXWc8_FV_=^WYp>j6 y6jzLcso6rTF;z>LGaIF^6Imlxy! delta 94 zcmccjl5y1&#tn{QvL304IVBmD3Me2cKR*W~Fu7LDb2GE}7lFz8hBA`{v{)wBXt=Zc mrj`_CCKpfsrzJI6UDIXrd(D|Fli%vOPcGMY-Rxj6&jkRMh#!vt From c7a5c19ef5359005b8ac1e1138f42e70ef9a51ab Mon Sep 17 00:00:00 2001 From: alexvanin Date: Wed, 20 Nov 2019 21:42:03 +0300 Subject: [PATCH 12/12] docs: generate documentation for proto files --- README.md | 29 +++ docs/accounting.md | 488 ++++++++++++++++++++++++++++++++++++++ docs/bootstrap.md | 132 +++++++++++ docs/container.md | 232 +++++++++++++++++++ docs/decimal.md | 61 +++++ docs/object.md | 566 +++++++++++++++++++++++++++++++++++++++++++++ docs/query.md | 86 +++++++ docs/refs.md | 61 +++++ docs/session.md | 149 ++++++++++++ docs/state.md | 137 +++++++++++ 10 files changed, 1941 insertions(+) create mode 100644 docs/accounting.md create mode 100644 docs/bootstrap.md create mode 100644 docs/container.md create mode 100644 docs/decimal.md create mode 100644 docs/object.md create mode 100644 docs/query.md create mode 100644 docs/refs.md create mode 100644 docs/session.md create mode 100644 docs/state.md diff --git a/README.md b/README.md index 9247a10f..a6662c35 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ Repository contains 13 packages that implement NeoFS core structures. These packages mostly contain protobuf files with service and structure definitions or NeoFS core types with complemented functions. +There is a auto-generated documentation for protobuf files in [docs](docs). + ### Accounting Accounting package defines services and structures for accounting operations: @@ -17,11 +19,22 @@ with inner ring signatures, which approve that user can withdraw requested amount of assets. NeoFS smart contract takes binary formatted `cheque` as a parameter in withdraw call. +#### API +Accounting package defines: +- [Accounting service](docs/accounting.md#accounting.Accounting) +- [Withdraw service](docs/accounting.md#accounting.Withdraw) + + ### Bootstrap Bootstrap package defines bootstrap service which is used by storage nodes to connect to the storage network. +#### API +Bootstrap package defines: +- [Bootstrap service](docs/bootstrap.md#bootstrap.Bootstrap) + + ### Chain Chain package contains util functions for operations with NEO Blockchain types: @@ -33,6 +46,10 @@ Container package defines service and structures for operations with containers. Objects in NeoFS are stored in containers. Container defines storage policy for the objects. +#### API +Bootstrap package defines: +- [Container service](docs/container.md#container.Service) + ### Decimal Decimal defines custom decimal implementation which is used in accounting @@ -53,6 +70,10 @@ Object package defines service and structures for object operations. Object is a core storage structure in NeoFS. Package contains detailed information about object internal structure. +#### API +Object package defines: +- [Object service](docs/object.md#object.Service) + ### Query Query package defines structure for object search requests. @@ -72,10 +93,18 @@ Session package defines service and structures for session obtain. Object operations require an established session with pair of session keys signed by owner of the object. +#### API +Session package defines: +- [Session service](docs/session.md#session.Session) + ### State State package defines service and structures for metrics gathering. +#### API +State package defines: +- [Status service](docs/state.md#state.Status) + ## How to use NeoFS-proto packages contain godoc documentation. Examples of using most of diff --git a/docs/accounting.md b/docs/accounting.md new file mode 100644 index 00000000..f08bd52d --- /dev/null +++ b/docs/accounting.md @@ -0,0 +1,488 @@ +# Protocol Documentation + + +## Table of Contents + +- [accounting/service.proto](#accounting/service.proto) + - Services + - [Accounting](#accounting.Accounting) + + - Messages + - [BalanceRequest](#accounting.BalanceRequest) + - [BalanceResponse](#accounting.BalanceResponse) + + +- [accounting/types.proto](#accounting/types.proto) + + - Messages + - [Account](#accounting.Account) + - [Balances](#accounting.Balances) + - [ContainerCreateTarget](#accounting.ContainerCreateTarget) + - [Lifetime](#accounting.Lifetime) + - [LockTarget](#accounting.LockTarget) + - [PayIO](#accounting.PayIO) + - [Settlement](#accounting.Settlement) + - [Settlement.Container](#accounting.Settlement.Container) + - [Settlement.Receiver](#accounting.Settlement.Receiver) + - [Settlement.Tx](#accounting.Settlement.Tx) + - [Tx](#accounting.Tx) + - [WithdrawTarget](#accounting.WithdrawTarget) + + +- [accounting/withdraw.proto](#accounting/withdraw.proto) + - Services + - [Withdraw](#accounting.Withdraw) + + - Messages + - [DeleteRequest](#accounting.DeleteRequest) + - [DeleteResponse](#accounting.DeleteResponse) + - [GetRequest](#accounting.GetRequest) + - [GetResponse](#accounting.GetResponse) + - [Item](#accounting.Item) + - [ListRequest](#accounting.ListRequest) + - [ListResponse](#accounting.ListResponse) + - [PutRequest](#accounting.PutRequest) + - [PutResponse](#accounting.PutResponse) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

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

Top

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

Top

+ +## accounting/withdraw.proto + + + + + + +### Service "accounting.Withdraw" +Withdraw is a service that provides withdraw assets operations from the NeoFS + +``` +rpc Get(GetRequest) returns (GetResponse); +rpc Put(PutRequest) returns (PutResponse); +rpc List(ListRequest) returns (ListResponse); +rpc Delete(DeleteRequest) returns (DeleteResponse); + +``` + +#### Method Get + +Get returns cheque if it was signed by inner ring nodes + +| Name | Input | Output | +| ---- | ----- | ------ | +| Get | [GetRequest](#accounting.GetRequest) | [GetResponse](#accounting.GetResponse) | +#### Method Put + +Put ask inner ring nodes to sign a cheque for withdraw invoke + +| Name | Input | Output | +| ---- | ----- | ------ | +| Put | [PutRequest](#accounting.PutRequest) | [PutResponse](#accounting.PutResponse) | +#### Method List + +List shows all user's checks + +| Name | Input | Output | +| ---- | ----- | ------ | +| List | [ListRequest](#accounting.ListRequest) | [ListResponse](#accounting.ListResponse) | +#### Method Delete + +Delete allows user to remove unused cheque + +| Name | Input | Output | +| ---- | ----- | ------ | +| Delete | [DeleteRequest](#accounting.DeleteRequest) | [DeleteResponse](#accounting.DeleteResponse) | + + + + + +### Message DeleteRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ID | [bytes](#bytes) | | ID is cheque identifier | +| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | +| MessageID | [bytes](#bytes) | | MessageID is a nonce for uniq request (UUIDv4) | +| Signature | [bytes](#bytes) | | Signature is a signature of the sent request | +| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node | + + + + +### Message DeleteResponse +DeleteResponse is empty + + + + + +### Message GetRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ID | [bytes](#bytes) | | ID is cheque identifier | +| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | +| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node | + + + + +### Message GetResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Withdraw | [Item](#accounting.Item) | | Item is cheque with meta information | + + + + +### Message Item + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ID | [bytes](#bytes) | | ID is a cheque identifier | +| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | +| Amount | [decimal.Decimal](#decimal.Decimal) | | Amount of funds | +| Height | [uint64](#uint64) | | Height is the neo blockchain height until the cheque is valid | +| Payload | [bytes](#bytes) | | Payload contains cheque representation in bytes | + + + + +### Message ListRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | +| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node | + + + + +### Message ListResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Items | [Item](#accounting.Item) | repeated | Item is a set of cheques with meta information | + + + + +### Message PutRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | +| Amount | [decimal.Decimal](#decimal.Decimal) | | Amount of funds | +| Height | [uint64](#uint64) | | Height is the neo blockchain height until the cheque is valid | +| MessageID | [bytes](#bytes) | | MessageID is a nonce for uniq request (UUIDv4) | +| Signature | [bytes](#bytes) | | Signature is a signature of the sent request | +| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node | + + + + +### Message PutResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ID | [bytes](#bytes) | | ID is cheque identifier | + + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/docs/bootstrap.md b/docs/bootstrap.md new file mode 100644 index 00000000..dfada2c6 --- /dev/null +++ b/docs/bootstrap.md @@ -0,0 +1,132 @@ +# Protocol Documentation + + +## Table of Contents + +- [bootstrap/service.proto](#bootstrap/service.proto) + - Services + - [Bootstrap](#bootstrap.Bootstrap) + + - Messages + - [Request](#bootstrap.Request) + + +- [bootstrap/types.proto](#bootstrap/types.proto) + + - Messages + - [NodeInfo](#bootstrap.NodeInfo) + - [SpreadMap](#bootstrap.SpreadMap) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

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

Top

+ +## bootstrap/types.proto + + + + + + + +### Message NodeInfo + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Address | [string](#string) | | Address is a node [multi-address](https://github.com/multiformats/multiaddr) | +| PubKey | [bytes](#bytes) | | PubKey is a compressed public key representation in bytes | +| Options | [string](#string) | repeated | Options is set of node optional information, such as storage capacity, node location, price and etc | +| Status | [uint64](#uint64) | | Status is bitmap status of the node | + + + + +### Message SpreadMap + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Epoch | [uint64](#uint64) | | Epoch is current epoch for netmap | +| NetMap | [NodeInfo](#bootstrap.NodeInfo) | repeated | NetMap is a set of NodeInfos | + + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/docs/container.md b/docs/container.md new file mode 100644 index 00000000..5ff0d891 --- /dev/null +++ b/docs/container.md @@ -0,0 +1,232 @@ +# Protocol Documentation + + +## Table of Contents + +- [container/service.proto](#container/service.proto) + - Services + - [Service](#container.Service) + + - Messages + - [DeleteRequest](#container.DeleteRequest) + - [DeleteResponse](#container.DeleteResponse) + - [GetRequest](#container.GetRequest) + - [GetResponse](#container.GetResponse) + - [ListRequest](#container.ListRequest) + - [ListResponse](#container.ListResponse) + - [PutRequest](#container.PutRequest) + - [PutResponse](#container.PutResponse) + + +- [container/types.proto](#container/types.proto) + + - Messages + - [Container](#container.Container) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

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

Top

+ +## container/types.proto + + + + + + + +### Message Container +The Container service definition. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address. | +| Salt | [bytes](#bytes) | | Salt is a nonce for unique container id calculation. | +| Capacity | [uint64](#uint64) | | Capacity defines amount of data that can be stored in the container (doesn't used for now). | +| Rules | [netmap.PlacementRule](#netmap.PlacementRule) | | Rules define storage policy for the object inside the container. | + + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/docs/decimal.md b/docs/decimal.md new file mode 100644 index 00000000..62acb863 --- /dev/null +++ b/docs/decimal.md @@ -0,0 +1,61 @@ +# Protocol Documentation + + +## Table of Contents + +- [decimal/decimal.proto](#decimal/decimal.proto) + + - Messages + - [Decimal](#decimal.Decimal) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

+ +## decimal/decimal.proto + + + + + + + +### Message Decimal +Decimal is a structure used for representation of assets amount + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Value | [int64](#int64) | | Value is value number | +| Precision | [uint32](#uint32) | | Precision is precision number | + + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/docs/object.md b/docs/object.md new file mode 100644 index 00000000..5ba1845b --- /dev/null +++ b/docs/object.md @@ -0,0 +1,566 @@ +# Protocol Documentation + + +## Table of Contents + +- [object/service.proto](#object/service.proto) + - Services + - [Service](#object.Service) + + - Messages + - [DeleteRequest](#object.DeleteRequest) + - [DeleteResponse](#object.DeleteResponse) + - [GetRangeHashRequest](#object.GetRangeHashRequest) + - [GetRangeHashResponse](#object.GetRangeHashResponse) + - [GetRangeRequest](#object.GetRangeRequest) + - [GetRangeResponse](#object.GetRangeResponse) + - [GetRequest](#object.GetRequest) + - [GetResponse](#object.GetResponse) + - [HeadRequest](#object.HeadRequest) + - [HeadResponse](#object.HeadResponse) + - [PutRequest](#object.PutRequest) + - [PutRequest.PutHeader](#object.PutRequest.PutHeader) + - [PutResponse](#object.PutResponse) + - [SearchRequest](#object.SearchRequest) + - [SearchResponse](#object.SearchResponse) + + +- [object/types.proto](#object/types.proto) + + - Messages + - [CreationPoint](#object.CreationPoint) + - [Header](#object.Header) + - [IntegrityHeader](#object.IntegrityHeader) + - [Link](#object.Link) + - [Object](#object.Object) + - [Range](#object.Range) + - [StorageGroup](#object.StorageGroup) + - [StorageGroup.Lifetime](#object.StorageGroup.Lifetime) + - [SystemHeader](#object.SystemHeader) + - [Tombstone](#object.Tombstone) + - [Transform](#object.Transform) + - [UserHeader](#object.UserHeader) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

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

Top

+ +## object/types.proto + + + + + + + +### Message CreationPoint + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| UnixTime | [int64](#int64) | | Date of creation in unixtime format | +| Epoch | [uint64](#uint64) | | Date of creation in NeoFS epochs | + + + + +### Message Header + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Link | [Link](#object.Link) | | Link to other objects | +| Redirect | [refs.Address](#refs.Address) | | RedirectNot used yet | +| UserHeader | [UserHeader](#object.UserHeader) | | UserHeader defined by user | +| Transform | [Transform](#object.Transform) | | Transform defines transform operation (e.g. payload split) | +| Tombstone | [Tombstone](#object.Tombstone) | | Tombstone header that set up in deleted objects | +| Verify | [session.VerificationHeader](#session.VerificationHeader) | | Verify header that contains session public key and user's signature | +| HomoHash | [bytes](#bytes) | | Homomorphic hash of original object payload | +| PayloadChecksum | [bytes](#bytes) | | PayloadChecksum of actual object's payload | +| Integrity | [IntegrityHeader](#object.IntegrityHeader) | | Integrity header with checksum of all above headers in the object | +| StorageGroup | [StorageGroup](#object.StorageGroup) | | StorageGroup contains meta information for the data audit | + + + + +### Message IntegrityHeader + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| HeadersChecksum | [bytes](#bytes) | | Checksum of all above headers in the object | +| ChecksumSignature | [bytes](#bytes) | | User's signature of checksum to verify if it is correct | + + + + +### Message Link + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| type | [Link.Type](#object.Link.Type) | | Link type | +| ID | [bytes](#bytes) | | Object id | + + + + +### Message Object + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| SystemHeader | [SystemHeader](#object.SystemHeader) | | System header | +| Headers | [Header](#object.Header) | repeated | Extended headers | +| Payload | [bytes](#bytes) | | Object's payload | + + + + +### Message Range + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Offset | [uint64](#uint64) | | Offset of the data range | +| Length | [uint64](#uint64) | | Length of the data range | + + + + +### Message StorageGroup + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ValidationDataSize | [uint64](#uint64) | | Size of the all object's payloads included into storage group | +| ValidationHash | [bytes](#bytes) | | Homomorphic hash of all object's payloads included into storage group | +| lifetime | [StorageGroup.Lifetime](#object.StorageGroup.Lifetime) | | Time until storage group is valid | + + + + +### Message StorageGroup.Lifetime + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| unit | [StorageGroup.Lifetime.Unit](#object.StorageGroup.Lifetime.Unit) | | Lifetime type | +| Value | [int64](#int64) | | Lifetime value | + + + + +### Message SystemHeader + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Version | [uint64](#uint64) | | Version of the object structure | +| PayloadLength | [uint64](#uint64) | | Object payload length | +| ID | [bytes](#bytes) | | ObjectID is a UUID | +| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address | +| CID | [bytes](#bytes) | | ContainerID is a SHA256 hash of the container structure | +| CreatedAt | [CreationPoint](#object.CreationPoint) | | Timestamp of object creation | + + + + +### Message Tombstone + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Epoch | [uint64](#uint64) | | Epoch when tombstone was created | + + + + +### Message Transform + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| type | [Transform.Type](#object.Transform.Type) | | Type of object transformation | + + + + +### Message UserHeader + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Key | [string](#string) | | Key of the user's header | +| Value | [string](#string) | | Value of the user's header | + + + + + + +### Link.Type + + +| Name | Number | Description | +| ---- | ------ | ----------- | +| Unknown | 0 | | +| Parent | 1 | Parent object created during object transformation | +| Previous | 2 | Previous object in the linked list created during object transformation | +| Next | 3 | Next object in the linked list created during object transformation | +| Child | 4 | Child object created during object transformation | +| StorageGroup | 5 | Object that included into this storage group | + + + + + +### StorageGroup.Lifetime.Unit + + +| Name | Number | Description | +| ---- | ------ | ----------- | +| Unlimited | 0 | Storage group always valid | +| NeoFSEpoch | 1 | Storage group is valid until lifetime NeoFS epoch | +| UnixTime | 2 | Storage group is valid until lifetime unix timestamp | + + + + + +### Transform.Type + + +| Name | Number | Description | +| ---- | ------ | ----------- | +| Unknown | 0 | | +| Split | 1 | Object created after payload split | +| Sign | 2 | Object created after re-signing (doesn't used) | +| Mould | 3 | Object created after filling missing headers in the object | + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/docs/query.md b/docs/query.md new file mode 100644 index 00000000..9deb2c19 --- /dev/null +++ b/docs/query.md @@ -0,0 +1,86 @@ +# Protocol Documentation + + +## Table of Contents + +- [query/types.proto](#query/types.proto) + + - Messages + - [Filter](#query.Filter) + - [Query](#query.Query) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

+ +## query/types.proto + + + + + + + +### Message Filter + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| type | [Filter.Type](#query.Filter.Type) | | Type of filter | +| Name | [string](#string) | | Name of field that should be filtered | +| Value | [string](#string) | | Value that should be used for filter | + + + + +### Message Query + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Filters | [Filter](#query.Filter) | repeated | Filters is set of filters, should not be empty | + + + + + + +### Filter.Type +Type can be Exact or Regex + +| Name | Number | Description | +| ---- | ------ | ----------- | +| Exact | 0 | | +| Regex | 1 | | + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/docs/refs.md b/docs/refs.md new file mode 100644 index 00000000..c3051ab2 --- /dev/null +++ b/docs/refs.md @@ -0,0 +1,61 @@ +# Protocol Documentation + + +## Table of Contents + +- [refs/types.proto](#refs/types.proto) + + - Messages + - [Address](#refs.Address) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

+ +## refs/types.proto + + + + + + + +### Message Address +Address of object (container id + object id) + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ObjectID | [bytes](#bytes) | | ObjectID is an object identifier | +| CID | [bytes](#bytes) | | CID is container identifier | + + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/docs/session.md b/docs/session.md new file mode 100644 index 00000000..8ea703e9 --- /dev/null +++ b/docs/session.md @@ -0,0 +1,149 @@ +# Protocol Documentation + + +## Table of Contents + +- [session/service.proto](#session/service.proto) + - Services + - [Session](#session.Session) + + - Messages + - [CreateRequest](#session.CreateRequest) + - [CreateResponse](#session.CreateResponse) + + +- [session/types.proto](#session/types.proto) + + - Messages + - [Token](#session.Token) + - [VerificationHeader](#session.VerificationHeader) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

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

Top

+ +## session/types.proto + + + + + + + +### Message Token +User token granting rights for object manipulation + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Header | [VerificationHeader](#session.VerificationHeader) | | Header carries verification data of session key | +| OwnerID | [bytes](#bytes) | | Owner of manipulation object | +| FirstEpoch | [uint64](#uint64) | | Initial epoch of token lifetime | +| LastEpoch | [uint64](#uint64) | | Last epoch of token lifetime | +| ObjectID | [bytes](#bytes) | repeated | ID of manipulation object | +| Signature | [bytes](#bytes) | | Token signature. Signed by owner of manipulation object | +| ID | [bytes](#bytes) | | Token ID (UUID) | + + + + +### Message VerificationHeader + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| PublicKey | [bytes](#bytes) | | Session public key | +| KeySignature | [bytes](#bytes) | | Session public key signature. Signed by trusted side | + + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/docs/state.md b/docs/state.md new file mode 100644 index 00000000..6d240c1d --- /dev/null +++ b/docs/state.md @@ -0,0 +1,137 @@ +# Protocol Documentation + + +## Table of Contents + +- [state/service.proto](#state/service.proto) + - Services + - [Status](#state.Status) + + - Messages + - [HealthRequest](#state.HealthRequest) + - [HealthResponse](#state.HealthResponse) + - [MetricsRequest](#state.MetricsRequest) + - [MetricsResponse](#state.MetricsResponse) + - [NetmapRequest](#state.NetmapRequest) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

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