Merge pull request #3 from nspcc-dev/documentation

Prepare documentation for NeoFS Proto library
This commit is contained in:
Alex Vanin 2019-11-20 21:50:06 +03:00 committed by GitHub
commit 7c0fef06fd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
41 changed files with 2348 additions and 136 deletions

83
.github/markdown.tmpl vendored Normal file
View file

@ -0,0 +1,83 @@
# Protocol Documentation
<a name="top"></a>
## 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}}
<a name="{{.Name}}"></a>
<p align="right"><a href="#top">Top</a></p>
## {{.Name}}
{{.Description}}
{{range .Services}}
<a name="{{.FullName}}"></a>
### 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}} <!-- end services -->
{{range .Messages}}
<a name="{{.FullName}}"></a>
### 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}} <!-- end messages -->
{{range .Enums}}
<a name="{{.FullName}}"></a>
### {{.LongName}}
{{.Description}}
| Name | Number | Description |
| ---- | ------ | ----------- |
{{range .Values -}}
| {{.Name}} | {{.Number}} | {{nobr .Description}} |
{{end}}
{{end}} <!-- end enums -->
{{end}}
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
{{range .Scalars -}}
| <a name="{{.ProtoType}}" /> {{.ProtoType}} | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} |
{{end}}

View file

@ -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: protoc:
@go mod tidy -v @go mod tidy -v
@go mod vendor @go mod vendor
@ -6,7 +29,9 @@ protoc:
# Install specific version for protobuf lib # Install specific version for protobuf lib
@go list -f '{{.Path}}/...@{{.Version}}' -m github.com/golang/protobuf | xargs go get -v @go list -f '{{.Path}}/...@{{.Version}}' -m github.com/golang/protobuf | xargs go get -v
# Protoc generate # Protoc generate
@find . -type f -name '*.proto' -not -path './vendor/*' \ @for f in `find . -type f -name '*.proto' -not -path './vendor/*'`; do \
-exec protoc \ echo "${B}${G}⇒ Processing $$f ${R}"; \
--proto_path=.:./vendor \ protoc \
--gofast_out=plugins=grpc,paths=source_relative:. '{}' \; --proto_path=.:./vendor:/usr/local/include \
--gofast_out=plugins=grpc,paths=source_relative:. $$f; \
done

View file

@ -9,6 +9,8 @@ Repository contains 13 packages that implement NeoFS core structures. These
packages mostly contain protobuf files with service and structure definitions packages mostly contain protobuf files with service and structure definitions
or NeoFS core types with complemented functions. or NeoFS core types with complemented functions.
There is a auto-generated documentation for protobuf files in [docs](docs).
### Accounting ### Accounting
Accounting package defines services and structures for accounting operations: 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 amount of assets. NeoFS smart contract takes binary formatted `cheque` as a
parameter in withdraw call. parameter in withdraw call.
#### API
Accounting package defines:
- [Accounting service](docs/accounting.md#accounting.Accounting)
- [Withdraw service](docs/accounting.md#accounting.Withdraw)
### Bootstrap ### Bootstrap
Bootstrap package defines bootstrap service which is used by storage nodes to Bootstrap package defines bootstrap service which is used by storage nodes to
connect to the storage network. connect to the storage network.
#### API
Bootstrap package defines:
- [Bootstrap service](docs/bootstrap.md#bootstrap.Bootstrap)
### Chain ### Chain
Chain package contains util functions for operations with NEO Blockchain types: 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 Objects in NeoFS are stored in containers. Container defines storage
policy for the objects. policy for the objects.
#### API
Bootstrap package defines:
- [Container service](docs/container.md#container.Service)
### Decimal ### Decimal
Decimal defines custom decimal implementation which is used in accounting 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 a core storage structure in NeoFS. Package contains detailed information
about object internal structure. about object internal structure.
#### API
Object package defines:
- [Object service](docs/object.md#object.Service)
### Query ### Query
Query package defines structure for object search requests. 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 operations require an established session with pair of session keys signed by
owner of the object. owner of the object.
#### API
Session package defines:
- [Session service](docs/session.md#session.Session)
### State ### State
State package defines service and structures for metrics gathering. State package defines service and structures for metrics gathering.
#### API
State package defines:
- [Status service](docs/state.md#state.Status)
## How to use ## How to use
NeoFS-proto packages contain godoc documentation. Examples of using most of NeoFS-proto packages contain godoc documentation. Examples of using most of

Binary file not shown.

View file

@ -8,16 +8,24 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
// Accounting is a service that provides access for accounting balance
// information
service Accounting { service Accounting {
// Balance returns current balance status of the NeoFS user
rpc Balance(BalanceRequest) returns (BalanceResponse); rpc Balance(BalanceRequest) returns (BalanceResponse);
} }
message BalanceRequest { message BalanceRequest {
// OwnerID is a wallet address
bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 2; uint32 TTL = 2;
} }
message BalanceResponse { message BalanceResponse {
// Balance contains current account balance state
decimal.Decimal Balance = 1; 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; repeated Account LockAccounts = 2;
} }

Binary file not shown.

View file

@ -7,61 +7,63 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
// Snapshot accounting messages
message Account { message Account {
// OwnerID is a wallet address
bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// Address is identifier of accounting record
string Address = 2; string Address = 2;
// ParentAddress is identifier of parent accounting record
string ParentAddress = 3; string ParentAddress = 3;
// ActiveFunds is amount of active (non locked) funds for account
decimal.Decimal ActiveFunds = 4; decimal.Decimal ActiveFunds = 4;
// Lifetime is time until account is valid (used for lock accounts)
Lifetime Lifetime = 5 [(gogoproto.nullable) = false]; Lifetime Lifetime = 5 [(gogoproto.nullable) = false];
// LockTarget is the purpose of lock funds (it might be withdraw or payment for storage)
LockTarget LockTarget = 6; LockTarget LockTarget = 6;
// LockAccounts contains child accounts with locked funds
repeated Account LockAccounts = 7; repeated Account LockAccounts = 7;
} }
// LockTarget must be one of two options
message LockTarget { message LockTarget {
oneof Target { oneof Target {
// WithdrawTarget used when user requested withdraw
WithdrawTarget WithdrawTarget = 1; WithdrawTarget WithdrawTarget = 1;
// ContainerCreateTarget used when user requested creation of container
ContainerCreateTarget ContainerCreateTarget = 2; ContainerCreateTarget ContainerCreateTarget = 2;
} }
} }
// Snapshot balance messages
message Balances { message Balances {
// Accounts contains multiple account snapshots
repeated Account Accounts = 1 [(gogoproto.nullable) = false]; repeated Account Accounts = 1 [(gogoproto.nullable) = false];
} }
// PayIn / PayOut messages
message PayIO { message PayIO {
// BlockID contains id of the NEO block where withdraw or deposit
// call was invoked
uint64 BlockID = 1; uint64 BlockID = 1;
// Transactions contains all transactions that founded in block
// and used for PayIO
repeated Tx Transactions = 2 [(gogoproto.nullable) = false]; 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 { message Lifetime {
// Unit can be Unlimited, based on NeoFS epoch or Neo block
enum Unit { enum Unit {
Unlimited = 0; Unlimited = 0;
NeoFSEpoch = 1; NeoFSEpoch = 1;
NeoBlock = 2; NeoBlock = 2;
} }
// Unit describes how lifetime is measured in account
Unit unit = 1 [(gogoproto.customname) = "Unit"]; Unit unit = 1 [(gogoproto.customname) = "Unit"];
// Value describes how long lifetime will be valid
int64 Value = 2; int64 Value = 2;
} }
// Transaction messages
message Tx { message Tx {
// Type can be withdrawal, payIO or inner
enum Type { enum Type {
Unknown = 0; Unknown = 0;
Withdraw = 1; Withdraw = 1;
@ -69,38 +71,54 @@ message Tx {
Inner = 3; Inner = 3;
} }
// Type describes target of transaction
Type type = 1 [(gogoproto.customname) = "Type"]; Type type = 1 [(gogoproto.customname) = "Type"];
// From describes sender of funds
string From = 2; string From = 2;
// To describes receiver of funds
string To = 3; string To = 3;
// Amount describes amount of funds
decimal.Decimal Amount = 4; decimal.Decimal Amount = 4;
bytes PublicKeys = 5; // of sender // PublicKeys contains public key of sender
bytes PublicKeys = 5;
} }
message Settlement { message Settlement {
message Receiver { message Receiver {
// To is the address of funds recipient
string To = 1; string To = 1;
// Amount is the amount of funds that will be sent
decimal.Decimal Amount = 2; decimal.Decimal Amount = 2;
} }
message Container { message Container {
// CID is container identifier
bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; 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]; repeated bytes SGIDs = 2 [(gogoproto.customtype) = "SGID", (gogoproto.nullable) = false];
} }
message Tx { message Tx {
// From is the address of the sender of funds
string From = 1; string From = 1;
// Container that successfully had passed the audit
Container Container = 2 [(gogoproto.nullable) = false]; Container Container = 2 [(gogoproto.nullable) = false];
// Receivers is a set of addresses of funds recipients
repeated Receiver Receivers = 3 [(gogoproto.nullable) = false]; repeated Receiver Receivers = 3 [(gogoproto.nullable) = false];
} }
// Epoch contains an epoch when settlement was accepted
uint64 Epoch = 1; uint64 Epoch = 1;
// Transactions is a set of transactions
repeated Tx Transactions = 2; repeated Tx Transactions = 2;
} }
message ContainerCreateTarget { message ContainerCreateTarget {
// CID is container identifier
bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
} }
message WithdrawTarget { message WithdrawTarget {
// Cheque is a string representation of cheque id
string Cheque = 1; string Cheque = 1;
} }

Binary file not shown.

View file

@ -7,55 +7,88 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
// Withdraw is a service that provides withdraw assets operations from the NeoFS
service Withdraw { service Withdraw {
// Get returns cheque if it was signed by inner ring nodes
rpc Get(GetRequest) returns (GetResponse); rpc Get(GetRequest) returns (GetResponse);
// Put ask inner ring nodes to sign a cheque for withdraw invoke
rpc Put(PutRequest) returns (PutResponse); rpc Put(PutRequest) returns (PutResponse);
// List shows all user's checks
rpc List(ListRequest) returns (ListResponse); rpc List(ListRequest) returns (ListResponse);
// Delete allows user to remove unused cheque
rpc Delete(DeleteRequest) returns (DeleteResponse); rpc Delete(DeleteRequest) returns (DeleteResponse);
} }
message Item { message Item {
// ID is a cheque identifier
bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false];
// OwnerID is a wallet address
bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// Amount of funds
decimal.Decimal Amount = 3; decimal.Decimal Amount = 3;
// Height is the neo blockchain height until the cheque is valid
uint64 Height = 4; uint64 Height = 4;
// Payload contains cheque representation in bytes
bytes Payload = 5; bytes Payload = 5;
} }
message GetRequest { message GetRequest {
// ID is cheque identifier
bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false];
// OwnerID is a wallet address
bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 3; uint32 TTL = 3;
} }
message GetResponse { message GetResponse {
// Item is cheque with meta information
Item Withdraw = 1; Item Withdraw = 1;
} }
message PutRequest { message PutRequest {
// OwnerID is a wallet address
bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// Amount of funds
decimal.Decimal Amount = 2; decimal.Decimal Amount = 2;
// Height is the neo blockchain height until the cheque is valid
uint64 Height = 3; uint64 Height = 3;
// MessageID is a nonce for uniq request (UUIDv4)
bytes MessageID = 4 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false]; bytes MessageID = 4 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false];
// Signature is a signature of the sent request
bytes Signature = 5; bytes Signature = 5;
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 6; uint32 TTL = 6;
} }
message PutResponse { message PutResponse {
// ID is cheque identifier
bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false];
} }
message ListRequest { message ListRequest {
// OwnerID is a wallet address
bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 2; uint32 TTL = 2;
} }
message ListResponse { message ListResponse {
// Item is a set of cheques with meta information
repeated Item Items = 1; repeated Item Items = 1;
} }
message DeleteRequest { message DeleteRequest {
// ID is cheque identifier
bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false];
// OwnerID is a wallet address
bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; 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]; bytes MessageID = 3 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false];
// Signature is a signature of the sent request
bytes Signature = 4; bytes Signature = 4;
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 5; uint32 TTL = 5;
} }
// DeleteResponse is empty
message DeleteResponse {} message DeleteResponse {}

Binary file not shown.

View file

@ -7,14 +7,19 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; 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 { service Bootstrap {
// Process is method that allows to register node in the network and receive actual netmap
rpc Process(Request) returns (bootstrap.SpreadMap); rpc Process(Request) returns (bootstrap.SpreadMap);
} }
// Request message to communicate between DHT nodes
message Request { 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"]; int32 type = 1 [(gogoproto.customname) = "Type" , (gogoproto.nullable) = false, (gogoproto.customtype) = "NodeType"];
// Info contains information about node
bootstrap.NodeInfo info = 2 [(gogoproto.nullable) = false]; bootstrap.NodeInfo info = 2 [(gogoproto.nullable) = false];
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 3; uint32 TTL = 3;
} }

Binary file not shown.

View file

@ -10,13 +10,19 @@ option (gogoproto.stringer_all) = false;
option (gogoproto.goproto_stringer_all) = false; option (gogoproto.goproto_stringer_all) = false;
message SpreadMap { message SpreadMap {
// Epoch is current epoch for netmap
uint64 Epoch = 1; uint64 Epoch = 1;
// NetMap is a set of NodeInfos
repeated NodeInfo NetMap = 2 [(gogoproto.nullable) = false]; repeated NodeInfo NetMap = 2 [(gogoproto.nullable) = false];
} }
message NodeInfo { message NodeInfo {
// Address is a node [multi-address](https://github.com/multiformats/multiaddr)
string Address = 1 [(gogoproto.jsontag) = "address"]; string Address = 1 [(gogoproto.jsontag) = "address"];
// PubKey is a compressed public key representation in bytes
bytes PubKey = 2 [(gogoproto.jsontag) = "pubkey,omitempty"]; 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"]; 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"]; uint64 Status = 4 [(gogoproto.jsontag) = "status", (gogoproto.nullable) = false, (gogoproto.customtype) = "NodeStatus"];
} }

Binary file not shown.

View file

@ -8,61 +8,87 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
// Container service provides API for manipulating with the container.
service Service { 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); 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); rpc Delete(DeleteRequest) returns (DeleteResponse);
// Get container // Get container returns container instance
rpc Get(GetRequest) returns (GetResponse); rpc Get(GetRequest) returns (GetResponse);
// List returns all user's containers
rpc List(ListRequest) returns (ListResponse); rpc List(ListRequest) returns (ListResponse);
} }
// NewRequest message to create new container
message PutRequest { message PutRequest {
// MessageID is a nonce for uniq container id calculation
bytes MessageID = 1 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false]; 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]; 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]; netmap.PlacementRule rules = 4 [(gogoproto.nullable) = false];
// Signature of the user (owner id)
bytes Signature = 5; bytes Signature = 5;
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 6; uint32 TTL = 6;
} }
// PutResponse message to respond about container uuid
message PutResponse { message PutResponse {
// CID (container id) is a SHA256 hash of the container structure
bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
} }
message DeleteRequest { message DeleteRequest {
// CID (container id) is a SHA256 hash of the container structure
bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 2; uint32 TTL = 2;
// Signature of the container owner
bytes Signature = 3; bytes Signature = 3;
} }
// DeleteResponse is empty because delete operation is asynchronous and done
// via consensus in inner ring nodes
message DeleteResponse { } message DeleteResponse { }
// GetRequest message to fetch container placement rules
message GetRequest { message GetRequest {
// CID (container id) is a SHA256 hash of the container structure
bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 2; uint32 TTL = 2;
} }
// GetResponse message with container structure
message GetResponse { message GetResponse {
// Container is a structure that contains placement rules and owner id
container.Container Container = 1; container.Container Container = 1;
} }
// ListRequest message to list containers for user
message ListRequest { message ListRequest {
// OwnerID is a wallet address
bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 2; uint32 TTL = 2;
} }
// ListResponse message to respond about all user containers
message ListResponse { message ListResponse {
// CID (container id) is list of SHA256 hashes of the container structures
repeated bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; repeated bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
} }

View file

@ -9,8 +9,8 @@ option (gogoproto.stable_marshaler_all) = true;
// The Container service definition. // The Container service definition.
message Container { message Container {
bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (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]; bytes Salt = 2 [(gogoproto.customtype) = "UUID", (gogoproto.nullable) = false]; // Salt is a nonce for unique container id calculation.
uint64 Capacity = 3; 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]; netmap.PlacementRule Rules = 4 [(gogoproto.nullable) = false]; // Rules define storage policy for the object inside the container.
} }

Binary file not shown.

View file

@ -6,9 +6,12 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
// Decimal is a structure used for representation of assets amount
message Decimal { message Decimal {
option (gogoproto.goproto_stringer) = false; option (gogoproto.goproto_stringer) = false;
// Value is value number
int64 Value = 1; int64 Value = 1;
// Precision is precision number
uint32 Precision = 2; uint32 Precision = 2;
} }

0
docs/.gitkeep Normal file
View file

488
docs/accounting.md Normal file
View file

@ -0,0 +1,488 @@
# Protocol Documentation
<a name="top"></a>
## Table of Contents
- [accounting/service.proto](#accounting/service.proto)
- Services
- [Accounting](#accounting.Accounting)
- Messages
- [BalanceRequest](#accounting.BalanceRequest)
- [BalanceResponse](#accounting.BalanceResponse)
- [accounting/types.proto](#accounting/types.proto)
- Messages
- [Account](#accounting.Account)
- [Balances](#accounting.Balances)
- [ContainerCreateTarget](#accounting.ContainerCreateTarget)
- [Lifetime](#accounting.Lifetime)
- [LockTarget](#accounting.LockTarget)
- [PayIO](#accounting.PayIO)
- [Settlement](#accounting.Settlement)
- [Settlement.Container](#accounting.Settlement.Container)
- [Settlement.Receiver](#accounting.Settlement.Receiver)
- [Settlement.Tx](#accounting.Settlement.Tx)
- [Tx](#accounting.Tx)
- [WithdrawTarget](#accounting.WithdrawTarget)
- [accounting/withdraw.proto](#accounting/withdraw.proto)
- Services
- [Withdraw](#accounting.Withdraw)
- Messages
- [DeleteRequest](#accounting.DeleteRequest)
- [DeleteResponse](#accounting.DeleteResponse)
- [GetRequest](#accounting.GetRequest)
- [GetResponse](#accounting.GetResponse)
- [Item](#accounting.Item)
- [ListRequest](#accounting.ListRequest)
- [ListResponse](#accounting.ListResponse)
- [PutRequest](#accounting.PutRequest)
- [PutResponse](#accounting.PutResponse)
- [Scalar Value Types](#scalar-value-types)
<a name="accounting/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## accounting/service.proto
<a name="accounting.Accounting"></a>
### Service "accounting.Accounting"
Accounting is a service that provides access for accounting balance
information
```
rpc Balance(BalanceRequest) returns (BalanceResponse);
```
#### Method Balance
Balance returns current balance status of the NeoFS user
| Name | Input | Output |
| ---- | ----- | ------ |
| Balance | [BalanceRequest](#accounting.BalanceRequest) | [BalanceResponse](#accounting.BalanceResponse) |
<!-- end services -->
<a name="accounting.BalanceRequest"></a>
### Message BalanceRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<a name="accounting.BalanceResponse"></a>
### Message BalanceResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Balance | [decimal.Decimal](#decimal.Decimal) | | Balance contains current account balance state |
| LockAccounts | [Account](#accounting.Account) | repeated | LockAccounts contains information about locked funds. Locked funds appear when user pays for storage or withdraw assets. |
<!-- end messages -->
<!-- end enums -->
<a name="accounting/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## accounting/types.proto
<!-- end services -->
<a name="accounting.Account"></a>
### Message Account
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address |
| Address | [string](#string) | | Address is identifier of accounting record |
| ParentAddress | [string](#string) | | ParentAddress is identifier of parent accounting record |
| ActiveFunds | [decimal.Decimal](#decimal.Decimal) | | ActiveFunds is amount of active (non locked) funds for account |
| Lifetime | [Lifetime](#accounting.Lifetime) | | Lifetime is time until account is valid (used for lock accounts) |
| LockTarget | [LockTarget](#accounting.LockTarget) | | LockTarget is the purpose of lock funds (it might be withdraw or payment for storage) |
| LockAccounts | [Account](#accounting.Account) | repeated | LockAccounts contains child accounts with locked funds |
<a name="accounting.Balances"></a>
### Message Balances
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Accounts | [Account](#accounting.Account) | repeated | Accounts contains multiple account snapshots |
<a name="accounting.ContainerCreateTarget"></a>
### Message ContainerCreateTarget
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| CID | [bytes](#bytes) | | CID is container identifier |
<a name="accounting.Lifetime"></a>
### Message Lifetime
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| unit | [Lifetime.Unit](#accounting.Lifetime.Unit) | | Unit describes how lifetime is measured in account |
| Value | [int64](#int64) | | Value describes how long lifetime will be valid |
<a name="accounting.LockTarget"></a>
### Message LockTarget
LockTarget must be one of two options
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| WithdrawTarget | [WithdrawTarget](#accounting.WithdrawTarget) | | WithdrawTarget used when user requested withdraw |
| ContainerCreateTarget | [ContainerCreateTarget](#accounting.ContainerCreateTarget) | | ContainerCreateTarget used when user requested creation of container |
<a name="accounting.PayIO"></a>
### Message PayIO
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| BlockID | [uint64](#uint64) | | BlockID contains id of the NEO block where withdraw or deposit call was invoked |
| Transactions | [Tx](#accounting.Tx) | repeated | Transactions contains all transactions that founded in block and used for PayIO |
<a name="accounting.Settlement"></a>
### Message Settlement
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Epoch | [uint64](#uint64) | | Epoch contains an epoch when settlement was accepted |
| Transactions | [Settlement.Tx](#accounting.Settlement.Tx) | repeated | Transactions is a set of transactions |
<a name="accounting.Settlement.Container"></a>
### Message Settlement.Container
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| CID | [bytes](#bytes) | | CID is container identifier |
| SGIDs | [bytes](#bytes) | repeated | SGIDs is a set of storage groups that successfully passed the audit |
<a name="accounting.Settlement.Receiver"></a>
### Message Settlement.Receiver
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| To | [string](#string) | | To is the address of funds recipient |
| Amount | [decimal.Decimal](#decimal.Decimal) | | Amount is the amount of funds that will be sent |
<a name="accounting.Settlement.Tx"></a>
### Message Settlement.Tx
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| From | [string](#string) | | From is the address of the sender of funds |
| Container | [Settlement.Container](#accounting.Settlement.Container) | | Container that successfully had passed the audit |
| Receivers | [Settlement.Receiver](#accounting.Settlement.Receiver) | repeated | Receivers is a set of addresses of funds recipients |
<a name="accounting.Tx"></a>
### Message Tx
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| type | [Tx.Type](#accounting.Tx.Type) | | Type describes target of transaction |
| From | [string](#string) | | From describes sender of funds |
| To | [string](#string) | | To describes receiver of funds |
| Amount | [decimal.Decimal](#decimal.Decimal) | | Amount describes amount of funds |
| PublicKeys | [bytes](#bytes) | | PublicKeys contains public key of sender |
<a name="accounting.WithdrawTarget"></a>
### Message WithdrawTarget
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Cheque | [string](#string) | | Cheque is a string representation of cheque id |
<!-- end messages -->
<a name="accounting.Lifetime.Unit"></a>
### Lifetime.Unit
Unit can be Unlimited, based on NeoFS epoch or Neo block
| Name | Number | Description |
| ---- | ------ | ----------- |
| Unlimited | 0 | |
| NeoFSEpoch | 1 | |
| NeoBlock | 2 | |
<a name="accounting.Tx.Type"></a>
### Tx.Type
Type can be withdrawal, payIO or inner
| Name | Number | Description |
| ---- | ------ | ----------- |
| Unknown | 0 | |
| Withdraw | 1 | |
| PayIO | 2 | |
| Inner | 3 | |
<!-- end enums -->
<a name="accounting/withdraw.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## accounting/withdraw.proto
<a name="accounting.Withdraw"></a>
### Service "accounting.Withdraw"
Withdraw is a service that provides withdraw assets operations from the NeoFS
```
rpc Get(GetRequest) returns (GetResponse);
rpc Put(PutRequest) returns (PutResponse);
rpc List(ListRequest) returns (ListResponse);
rpc Delete(DeleteRequest) returns (DeleteResponse);
```
#### Method Get
Get returns cheque if it was signed by inner ring nodes
| Name | Input | Output |
| ---- | ----- | ------ |
| Get | [GetRequest](#accounting.GetRequest) | [GetResponse](#accounting.GetResponse) |
#### Method Put
Put ask inner ring nodes to sign a cheque for withdraw invoke
| Name | Input | Output |
| ---- | ----- | ------ |
| Put | [PutRequest](#accounting.PutRequest) | [PutResponse](#accounting.PutResponse) |
#### Method List
List shows all user's checks
| Name | Input | Output |
| ---- | ----- | ------ |
| List | [ListRequest](#accounting.ListRequest) | [ListResponse](#accounting.ListResponse) |
#### Method Delete
Delete allows user to remove unused cheque
| Name | Input | Output |
| ---- | ----- | ------ |
| Delete | [DeleteRequest](#accounting.DeleteRequest) | [DeleteResponse](#accounting.DeleteResponse) |
<!-- end services -->
<a name="accounting.DeleteRequest"></a>
### Message DeleteRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ID | [bytes](#bytes) | | ID is cheque identifier |
| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address |
| MessageID | [bytes](#bytes) | | MessageID is a nonce for uniq request (UUIDv4) |
| Signature | [bytes](#bytes) | | Signature is a signature of the sent request |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<a name="accounting.DeleteResponse"></a>
### Message DeleteResponse
DeleteResponse is empty
<a name="accounting.GetRequest"></a>
### Message GetRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ID | [bytes](#bytes) | | ID is cheque identifier |
| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<a name="accounting.GetResponse"></a>
### Message GetResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Withdraw | [Item](#accounting.Item) | | Item is cheque with meta information |
<a name="accounting.Item"></a>
### Message Item
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ID | [bytes](#bytes) | | ID is a cheque identifier |
| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address |
| Amount | [decimal.Decimal](#decimal.Decimal) | | Amount of funds |
| Height | [uint64](#uint64) | | Height is the neo blockchain height until the cheque is valid |
| Payload | [bytes](#bytes) | | Payload contains cheque representation in bytes |
<a name="accounting.ListRequest"></a>
### Message ListRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<a name="accounting.ListResponse"></a>
### Message ListResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Items | [Item](#accounting.Item) | repeated | Item is a set of cheques with meta information |
<a name="accounting.PutRequest"></a>
### Message PutRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address |
| Amount | [decimal.Decimal](#decimal.Decimal) | | Amount of funds |
| Height | [uint64](#uint64) | | Height is the neo blockchain height until the cheque is valid |
| MessageID | [bytes](#bytes) | | MessageID is a nonce for uniq request (UUIDv4) |
| Signature | [bytes](#bytes) | | Signature is a signature of the sent request |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<a name="accounting.PutResponse"></a>
### Message PutResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ID | [bytes](#bytes) | | ID is cheque identifier |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

132
docs/bootstrap.md Normal file
View file

@ -0,0 +1,132 @@
# Protocol Documentation
<a name="top"></a>
## Table of Contents
- [bootstrap/service.proto](#bootstrap/service.proto)
- Services
- [Bootstrap](#bootstrap.Bootstrap)
- Messages
- [Request](#bootstrap.Request)
- [bootstrap/types.proto](#bootstrap/types.proto)
- Messages
- [NodeInfo](#bootstrap.NodeInfo)
- [SpreadMap](#bootstrap.SpreadMap)
- [Scalar Value Types](#scalar-value-types)
<a name="bootstrap/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## bootstrap/service.proto
<a name="bootstrap.Bootstrap"></a>
### Service "bootstrap.Bootstrap"
Bootstrap service allows neofs-node to connect to the network. Node should
perform at least one bootstrap request in the epoch to stay in the network
for the next epoch.
```
rpc Process(Request) returns (SpreadMap);
```
#### Method Process
Process is method that allows to register node in the network and receive actual netmap
| Name | Input | Output |
| ---- | ----- | ------ |
| Process | [Request](#bootstrap.Request) | [SpreadMap](#bootstrap.SpreadMap) |
<!-- end services -->
<a name="bootstrap.Request"></a>
### Message Request
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| type | [int32](#int32) | | Type is NodeType, can be InnerRingNode (type=1) or StorageNode (type=2) |
| info | [NodeInfo](#bootstrap.NodeInfo) | | Info contains information about node |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<!-- end messages -->
<!-- end enums -->
<a name="bootstrap/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## bootstrap/types.proto
<!-- end services -->
<a name="bootstrap.NodeInfo"></a>
### Message NodeInfo
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Address | [string](#string) | | Address is a node [multi-address](https://github.com/multiformats/multiaddr) |
| PubKey | [bytes](#bytes) | | PubKey is a compressed public key representation in bytes |
| Options | [string](#string) | repeated | Options is set of node optional information, such as storage capacity, node location, price and etc |
| Status | [uint64](#uint64) | | Status is bitmap status of the node |
<a name="bootstrap.SpreadMap"></a>
### Message SpreadMap
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Epoch | [uint64](#uint64) | | Epoch is current epoch for netmap |
| NetMap | [NodeInfo](#bootstrap.NodeInfo) | repeated | NetMap is a set of NodeInfos |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

232
docs/container.md Normal file
View file

@ -0,0 +1,232 @@
# Protocol Documentation
<a name="top"></a>
## Table of Contents
- [container/service.proto](#container/service.proto)
- Services
- [Service](#container.Service)
- Messages
- [DeleteRequest](#container.DeleteRequest)
- [DeleteResponse](#container.DeleteResponse)
- [GetRequest](#container.GetRequest)
- [GetResponse](#container.GetResponse)
- [ListRequest](#container.ListRequest)
- [ListResponse](#container.ListResponse)
- [PutRequest](#container.PutRequest)
- [PutResponse](#container.PutResponse)
- [container/types.proto](#container/types.proto)
- Messages
- [Container](#container.Container)
- [Scalar Value Types](#scalar-value-types)
<a name="container/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## container/service.proto
<a name="container.Service"></a>
### Service "container.Service"
Container service provides API for manipulating with the container.
```
rpc Put(PutRequest) returns (PutResponse);
rpc Delete(DeleteRequest) returns (DeleteResponse);
rpc Get(GetRequest) returns (GetResponse);
rpc List(ListRequest) returns (ListResponse);
```
#### Method Put
Put request proposes container to the inner ring nodes. They will
accept new container if user has enough deposit. All containers
are accepted by the consensus, therefore it is asynchronous process.
| Name | Input | Output |
| ---- | ----- | ------ |
| Put | [PutRequest](#container.PutRequest) | [PutResponse](#container.PutResponse) |
#### Method Delete
Delete container removes it from the inner ring container storage. It
also asynchronous process done by consensus.
| Name | Input | Output |
| ---- | ----- | ------ |
| Delete | [DeleteRequest](#container.DeleteRequest) | [DeleteResponse](#container.DeleteResponse) |
#### Method Get
Get container returns container instance
| Name | Input | Output |
| ---- | ----- | ------ |
| Get | [GetRequest](#container.GetRequest) | [GetResponse](#container.GetResponse) |
#### Method List
List returns all user's containers
| Name | Input | Output |
| ---- | ----- | ------ |
| List | [ListRequest](#container.ListRequest) | [ListResponse](#container.ListResponse) |
<!-- end services -->
<a name="container.DeleteRequest"></a>
### Message DeleteRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| CID | [bytes](#bytes) | | CID (container id) is a SHA256 hash of the container structure |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
| Signature | [bytes](#bytes) | | Signature of the container owner |
<a name="container.DeleteResponse"></a>
### Message DeleteResponse
DeleteResponse is empty because delete operation is asynchronous and done
via consensus in inner ring nodes
<a name="container.GetRequest"></a>
### Message GetRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| CID | [bytes](#bytes) | | CID (container id) is a SHA256 hash of the container structure |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<a name="container.GetResponse"></a>
### Message GetResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Container | [Container](#container.Container) | | Container is a structure that contains placement rules and owner id |
<a name="container.ListRequest"></a>
### Message ListRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<a name="container.ListResponse"></a>
### Message ListResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| CID | [bytes](#bytes) | repeated | CID (container id) is list of SHA256 hashes of the container structures |
<a name="container.PutRequest"></a>
### Message PutRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| MessageID | [bytes](#bytes) | | MessageID is a nonce for uniq container id calculation |
| Capacity | [uint64](#uint64) | | Capacity defines amount of data that can be stored in the container (doesn't used for now). |
| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address |
| rules | [netmap.PlacementRule](#netmap.PlacementRule) | | Rules define storage policy for the object inside the container. |
| Signature | [bytes](#bytes) | | Signature of the user (owner id) |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<a name="container.PutResponse"></a>
### Message PutResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| CID | [bytes](#bytes) | | CID (container id) is a SHA256 hash of the container structure |
<!-- end messages -->
<!-- end enums -->
<a name="container/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## container/types.proto
<!-- end services -->
<a name="container.Container"></a>
### Message Container
The Container service definition.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address. |
| Salt | [bytes](#bytes) | | Salt is a nonce for unique container id calculation. |
| Capacity | [uint64](#uint64) | | Capacity defines amount of data that can be stored in the container (doesn't used for now). |
| Rules | [netmap.PlacementRule](#netmap.PlacementRule) | | Rules define storage policy for the object inside the container. |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

61
docs/decimal.md Normal file
View file

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

566
docs/object.md Normal file
View file

@ -0,0 +1,566 @@
# Protocol Documentation
<a name="top"></a>
## Table of Contents
- [object/service.proto](#object/service.proto)
- Services
- [Service](#object.Service)
- Messages
- [DeleteRequest](#object.DeleteRequest)
- [DeleteResponse](#object.DeleteResponse)
- [GetRangeHashRequest](#object.GetRangeHashRequest)
- [GetRangeHashResponse](#object.GetRangeHashResponse)
- [GetRangeRequest](#object.GetRangeRequest)
- [GetRangeResponse](#object.GetRangeResponse)
- [GetRequest](#object.GetRequest)
- [GetResponse](#object.GetResponse)
- [HeadRequest](#object.HeadRequest)
- [HeadResponse](#object.HeadResponse)
- [PutRequest](#object.PutRequest)
- [PutRequest.PutHeader](#object.PutRequest.PutHeader)
- [PutResponse](#object.PutResponse)
- [SearchRequest](#object.SearchRequest)
- [SearchResponse](#object.SearchResponse)
- [object/types.proto](#object/types.proto)
- Messages
- [CreationPoint](#object.CreationPoint)
- [Header](#object.Header)
- [IntegrityHeader](#object.IntegrityHeader)
- [Link](#object.Link)
- [Object](#object.Object)
- [Range](#object.Range)
- [StorageGroup](#object.StorageGroup)
- [StorageGroup.Lifetime](#object.StorageGroup.Lifetime)
- [SystemHeader](#object.SystemHeader)
- [Tombstone](#object.Tombstone)
- [Transform](#object.Transform)
- [UserHeader](#object.UserHeader)
- [Scalar Value Types](#scalar-value-types)
<a name="object/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## object/service.proto
<a name="object.Service"></a>
### Service "object.Service"
Object service provides API for manipulating with the object.
```
rpc Get(GetRequest) returns (stream GetResponse);
rpc Put(stream PutRequest) returns (PutResponse);
rpc Delete(DeleteRequest) returns (DeleteResponse);
rpc Head(HeadRequest) returns (HeadResponse);
rpc Search(SearchRequest) returns (SearchResponse);
rpc GetRange(GetRangeRequest) returns (GetRangeResponse);
rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
```
#### Method Get
Get the object from container. Response uses gRPC stream. First response
message carry object of requested address. Chunk messages are parts of
the object's payload if it is needed. All messages except first carry
chunks. Requested object can be restored by concatenation of object
message payload and all chunks keeping receiving order.
| Name | Input | Output |
| ---- | ----- | ------ |
| Get | [GetRequest](#object.GetRequest) | [GetResponse](#object.GetResponse) |
#### Method Put
Put the object into container. Request uses gRPC stream. First message
SHOULD BE type of PutHeader. Container id and Owner id of object SHOULD
BE set. Session token SHOULD BE obtained before put operation (see
session package). Chunk messages considered by server as part of object
payload. All messages except first SHOULD BE chunks. Chunk messages
SHOULD BE sent in direct order of fragmentation.
| Name | Input | Output |
| ---- | ----- | ------ |
| Put | [PutRequest](#object.PutRequest) | [PutResponse](#object.PutResponse) |
#### Method Delete
Delete the object from a container
| Name | Input | Output |
| ---- | ----- | ------ |
| Delete | [DeleteRequest](#object.DeleteRequest) | [DeleteResponse](#object.DeleteResponse) |
#### Method Head
Head returns the object without data payload. Object in the
response has system header only. If full headers flag is set, extended
headers are also present.
| Name | Input | Output |
| ---- | ----- | ------ |
| Head | [HeadRequest](#object.HeadRequest) | [HeadResponse](#object.HeadResponse) |
#### Method Search
Search objects in container. Version of query language format SHOULD BE
set to 1. Search query represented in serialized format (see query
package).
| Name | Input | Output |
| ---- | ----- | ------ |
| Search | [SearchRequest](#object.SearchRequest) | [SearchResponse](#object.SearchResponse) |
#### Method GetRange
GetRange of data payload. Ranges are set of pairs (offset, length).
Fragments order in response corresponds to ranges order in request.
| Name | Input | Output |
| ---- | ----- | ------ |
| GetRange | [GetRangeRequest](#object.GetRangeRequest) | [GetRangeResponse](#object.GetRangeResponse) |
#### Method GetRangeHash
GetRangeHash returns homomorphic hash of object payload range after XOR
operation. Ranges are set of pairs (offset, length). Hashes order in
response corresponds to ranges order in request. Homomorphic hash is
calculated for XORed data.
| Name | Input | Output |
| ---- | ----- | ------ |
| GetRangeHash | [GetRangeHashRequest](#object.GetRangeHashRequest) | [GetRangeHashResponse](#object.GetRangeHashResponse) |
<!-- end services -->
<a name="object.DeleteRequest"></a>
### Message DeleteRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value |
| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) |
| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
| Token | [session.Token](#session.Token) | | Token with session public key and user's signature |
<a name="object.DeleteResponse"></a>
### Message DeleteResponse
DeleteResponse is empty because we cannot guarantee permanent object removal
in distributed system.
<a name="object.GetRangeHashRequest"></a>
### Message GetRangeHashRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value |
| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) |
| Ranges | [Range](#object.Range) | repeated | Ranges of object's payload to calculate homomorphic hash |
| Salt | [bytes](#bytes) | | Salt is used to XOR object's payload ranges before hashing, it can be nil |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<a name="object.GetRangeHashResponse"></a>
### Message GetRangeHashResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Hashes | [bytes](#bytes) | repeated | Homomorphic hashes of all ranges |
<a name="object.GetRangeRequest"></a>
### Message GetRangeRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value |
| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) |
| Ranges | [Range](#object.Range) | repeated | Ranges of object's payload to return |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<a name="object.GetRangeResponse"></a>
### Message GetRangeResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Fragments | [bytes](#bytes) | repeated | Fragments of object's payload |
<a name="object.GetRequest"></a>
### Message GetRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value |
| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<a name="object.GetResponse"></a>
### Message GetResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| object | [Object](#object.Object) | | Object header and some payload |
| Chunk | [bytes](#bytes) | | Chunk of remaining payload |
<a name="object.HeadRequest"></a>
### Message HeadRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value |
| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) |
| FullHeaders | [bool](#bool) | | FullHeaders can be set true for extended headers in the object |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<a name="object.HeadResponse"></a>
### Message HeadResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Object | [Object](#object.Object) | | Object without payload |
<a name="object.PutRequest"></a>
### Message PutRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Header | [PutRequest.PutHeader](#object.PutRequest.PutHeader) | | Header should be the first message in the stream |
| Chunk | [bytes](#bytes) | | Chunk should be a remaining message in stream should be chunks |
<a name="object.PutRequest.PutHeader"></a>
### Message PutRequest.PutHeader
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value |
| Object | [Object](#object.Object) | | Object with at least container id and owner id fields |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
| Token | [session.Token](#session.Token) | | Token with session public key and user's signature |
<a name="object.PutResponse"></a>
### Message PutResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) |
<a name="object.SearchRequest"></a>
### Message SearchRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Epoch | [uint64](#uint64) | | Epoch is set by user to 0, node set epoch to the actual value |
| Version | [uint32](#uint32) | | Version of search query format |
| ContainerID | [bytes](#bytes) | | ContainerID for searching the object |
| Query | [bytes](#bytes) | | Query in the binary serialized format |
| TTL | [uint32](#uint32) | | TTL must be larger than zero, it decreased in every neofs-node |
<a name="object.SearchResponse"></a>
### Message SearchResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Addresses | [refs.Address](#refs.Address) | repeated | Addresses of found objects |
<!-- end messages -->
<!-- end enums -->
<a name="object/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## object/types.proto
<!-- end services -->
<a name="object.CreationPoint"></a>
### Message CreationPoint
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| UnixTime | [int64](#int64) | | Date of creation in unixtime format |
| Epoch | [uint64](#uint64) | | Date of creation in NeoFS epochs |
<a name="object.Header"></a>
### Message Header
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Link | [Link](#object.Link) | | Link to other objects |
| Redirect | [refs.Address](#refs.Address) | | RedirectNot used yet |
| UserHeader | [UserHeader](#object.UserHeader) | | UserHeader defined by user |
| Transform | [Transform](#object.Transform) | | Transform defines transform operation (e.g. payload split) |
| Tombstone | [Tombstone](#object.Tombstone) | | Tombstone header that set up in deleted objects |
| Verify | [session.VerificationHeader](#session.VerificationHeader) | | Verify header that contains session public key and user's signature |
| HomoHash | [bytes](#bytes) | | Homomorphic hash of original object payload |
| PayloadChecksum | [bytes](#bytes) | | PayloadChecksum of actual object's payload |
| Integrity | [IntegrityHeader](#object.IntegrityHeader) | | Integrity header with checksum of all above headers in the object |
| StorageGroup | [StorageGroup](#object.StorageGroup) | | StorageGroup contains meta information for the data audit |
<a name="object.IntegrityHeader"></a>
### Message IntegrityHeader
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| HeadersChecksum | [bytes](#bytes) | | Checksum of all above headers in the object |
| ChecksumSignature | [bytes](#bytes) | | User's signature of checksum to verify if it is correct |
<a name="object.Link"></a>
### Message Link
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| type | [Link.Type](#object.Link.Type) | | Link type |
| ID | [bytes](#bytes) | | Object id |
<a name="object.Object"></a>
### Message Object
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| SystemHeader | [SystemHeader](#object.SystemHeader) | | System header |
| Headers | [Header](#object.Header) | repeated | Extended headers |
| Payload | [bytes](#bytes) | | Object's payload |
<a name="object.Range"></a>
### Message Range
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Offset | [uint64](#uint64) | | Offset of the data range |
| Length | [uint64](#uint64) | | Length of the data range |
<a name="object.StorageGroup"></a>
### Message StorageGroup
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ValidationDataSize | [uint64](#uint64) | | Size of the all object's payloads included into storage group |
| ValidationHash | [bytes](#bytes) | | Homomorphic hash of all object's payloads included into storage group |
| lifetime | [StorageGroup.Lifetime](#object.StorageGroup.Lifetime) | | Time until storage group is valid |
<a name="object.StorageGroup.Lifetime"></a>
### Message StorageGroup.Lifetime
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| unit | [StorageGroup.Lifetime.Unit](#object.StorageGroup.Lifetime.Unit) | | Lifetime type |
| Value | [int64](#int64) | | Lifetime value |
<a name="object.SystemHeader"></a>
### Message SystemHeader
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Version | [uint64](#uint64) | | Version of the object structure |
| PayloadLength | [uint64](#uint64) | | Object payload length |
| ID | [bytes](#bytes) | | ObjectID is a UUID |
| OwnerID | [bytes](#bytes) | | OwnerID is a wallet address |
| CID | [bytes](#bytes) | | ContainerID is a SHA256 hash of the container structure |
| CreatedAt | [CreationPoint](#object.CreationPoint) | | Timestamp of object creation |
<a name="object.Tombstone"></a>
### Message Tombstone
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Epoch | [uint64](#uint64) | | Epoch when tombstone was created |
<a name="object.Transform"></a>
### Message Transform
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| type | [Transform.Type](#object.Transform.Type) | | Type of object transformation |
<a name="object.UserHeader"></a>
### Message UserHeader
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Key | [string](#string) | | Key of the user's header |
| Value | [string](#string) | | Value of the user's header |
<!-- end messages -->
<a name="object.Link.Type"></a>
### Link.Type
| Name | Number | Description |
| ---- | ------ | ----------- |
| Unknown | 0 | |
| Parent | 1 | Parent object created during object transformation |
| Previous | 2 | Previous object in the linked list created during object transformation |
| Next | 3 | Next object in the linked list created during object transformation |
| Child | 4 | Child object created during object transformation |
| StorageGroup | 5 | Object that included into this storage group |
<a name="object.StorageGroup.Lifetime.Unit"></a>
### StorageGroup.Lifetime.Unit
| Name | Number | Description |
| ---- | ------ | ----------- |
| Unlimited | 0 | Storage group always valid |
| NeoFSEpoch | 1 | Storage group is valid until lifetime NeoFS epoch |
| UnixTime | 2 | Storage group is valid until lifetime unix timestamp |
<a name="object.Transform.Type"></a>
### Transform.Type
| Name | Number | Description |
| ---- | ------ | ----------- |
| Unknown | 0 | |
| Split | 1 | Object created after payload split |
| Sign | 2 | Object created after re-signing (doesn't used) |
| Mould | 3 | Object created after filling missing headers in the object |
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

86
docs/query.md Normal file
View file

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

61
docs/refs.md Normal file
View file

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

149
docs/session.md Normal file
View file

@ -0,0 +1,149 @@
# Protocol Documentation
<a name="top"></a>
## Table of Contents
- [session/service.proto](#session/service.proto)
- Services
- [Session](#session.Session)
- Messages
- [CreateRequest](#session.CreateRequest)
- [CreateResponse](#session.CreateResponse)
- [session/types.proto](#session/types.proto)
- Messages
- [Token](#session.Token)
- [VerificationHeader](#session.VerificationHeader)
- [Scalar Value Types](#scalar-value-types)
<a name="session/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## session/service.proto
<a name="session.Session"></a>
### Service "session.Session"
Open a trusted session to manipulate an object. In order to put or
delete object client have to obtain session token with trusted node.
Trusted node will modify client's object (add missing headers, checksums,
homomorphic hash) and sign id with session key. Session is established
during 4-step handshake in one gRPC stream
```
rpc Create(stream CreateRequest) returns (stream CreateResponse);
```
#### Method Create
| Name | Input | Output |
| ---- | ----- | ------ |
| Create | [CreateRequest](#session.CreateRequest) | [CreateResponse](#session.CreateResponse) |
<!-- end services -->
<a name="session.CreateRequest"></a>
### Message CreateRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Init | [Token](#session.Token) | | Message to init session opening. Carry: owner of manipulation object; ID of manipulation object; token lifetime bounds. |
| Signed | [Token](#session.Token) | | Signed Init message response (Unsigned) from server with user private key |
<a name="session.CreateResponse"></a>
### Message CreateResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Unsigned | [Token](#session.Token) | | Unsigned token with token ID and session public key generated on server side |
| Result | [Token](#session.Token) | | Resulting token which can be used for object placing through an trusted intermediary |
<!-- end messages -->
<!-- end enums -->
<a name="session/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## session/types.proto
<!-- end services -->
<a name="session.Token"></a>
### Message Token
User token granting rights for object manipulation
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Header | [VerificationHeader](#session.VerificationHeader) | | Header carries verification data of session key |
| OwnerID | [bytes](#bytes) | | Owner of manipulation object |
| FirstEpoch | [uint64](#uint64) | | Initial epoch of token lifetime |
| LastEpoch | [uint64](#uint64) | | Last epoch of token lifetime |
| ObjectID | [bytes](#bytes) | repeated | ID of manipulation object |
| Signature | [bytes](#bytes) | | Token signature. Signed by owner of manipulation object |
| ID | [bytes](#bytes) | | Token ID (UUID) |
<a name="session.VerificationHeader"></a>
### Message VerificationHeader
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| PublicKey | [bytes](#bytes) | | Session public key |
| KeySignature | [bytes](#bytes) | | Session public key signature. Signed by trusted side |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

137
docs/state.md Normal file
View file

@ -0,0 +1,137 @@
# Protocol Documentation
<a name="top"></a>
## Table of Contents
- [state/service.proto](#state/service.proto)
- Services
- [Status](#state.Status)
- Messages
- [HealthRequest](#state.HealthRequest)
- [HealthResponse](#state.HealthResponse)
- [MetricsRequest](#state.MetricsRequest)
- [MetricsResponse](#state.MetricsResponse)
- [NetmapRequest](#state.NetmapRequest)
- [Scalar Value Types](#scalar-value-types)
<a name="state/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## state/service.proto
<a name="state.Status"></a>
### Service "state.Status"
Status service provides node's healthcheck and status info
```
rpc Netmap(NetmapRequest) returns (.bootstrap.SpreadMap);
rpc Metrics(MetricsRequest) returns (MetricsResponse);
rpc HealthCheck(HealthRequest) returns (HealthResponse);
```
#### Method Netmap
Netmap request allows to receive current [bootstrap.SpreadMap](bootstrap.md#bootstrap.SpreadMap)
| Name | Input | Output |
| ---- | ----- | ------ |
| Netmap | [NetmapRequest](#state.NetmapRequest) | [.bootstrap.SpreadMap](#bootstrap.SpreadMap) |
#### Method Metrics
Metrics request allows to receive metrics in prometheus format
| Name | Input | Output |
| ---- | ----- | ------ |
| Metrics | [MetricsRequest](#state.MetricsRequest) | [MetricsResponse](#state.MetricsResponse) |
#### Method HealthCheck
HealthCheck request allows to check health status of the node.
If node unhealthy field Status would contains detailed info.
| Name | Input | Output |
| ---- | ----- | ------ |
| HealthCheck | [HealthRequest](#state.HealthRequest) | [HealthResponse](#state.HealthResponse) |
<!-- end services -->
<a name="state.HealthRequest"></a>
### Message HealthRequest
HealthRequest message to check current state
<a name="state.HealthResponse"></a>
### Message HealthResponse
HealthResponse message with current state
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Healthy | [bool](#bool) | | Healthy is true when node alive and healthy |
| Status | [string](#string) | | Status contains detailed information about health status |
<a name="state.MetricsRequest"></a>
### Message MetricsRequest
MetricsRequest message to request node metrics
<a name="state.MetricsResponse"></a>
### Message MetricsResponse
MetricsResponse contains [][]byte,
every []byte is marshaled MetricFamily proto message
from github.com/prometheus/client_model/metrics.proto
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Metrics | [bytes](#bytes) | repeated | |
<a name="state.NetmapRequest"></a>
### Message NetmapRequest
NetmapRequest message to request current node netmap
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

Binary file not shown.

View file

@ -9,111 +9,132 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
// Object service provides API for manipulating with the object.
service Service { 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); 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); rpc Put(stream PutRequest) returns (PutResponse);
// Delete the object from a container // Delete the object from a container
rpc Delete(DeleteRequest) returns (DeleteResponse); 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); 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); 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); 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); rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
} }
message GetRequest { message GetRequest {
uint64 Epoch = 1; uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value
refs.Address Address = 2 [(gogoproto.nullable) = false]; refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id)
uint32 TTL = 3; uint32 TTL = 3; // TTL must be larger than zero, it decreased in every neofs-node
} }
message GetResponse { message GetResponse {
oneof R { oneof R {
Object object = 1; Object object = 1; // Object header and some payload
bytes Chunk = 2; bytes Chunk = 2; // Chunk of remaining payload
} }
} }
message PutRequest { message PutRequest {
message PutHeader { message PutHeader {
uint64 Epoch = 1; uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value
Object Object = 2; Object Object = 2; // Object with at least container id and owner id fields
uint32 TTL = 3; uint32 TTL = 3; // TTL must be larger than zero, it decreased in every neofs-node
session.Token Token = 4; session.Token Token = 4; // Token with session public key and user's signature
} }
oneof R { oneof R {
PutHeader Header = 1; PutHeader Header = 1; // Header should be the first message in the stream
bytes Chunk = 2; bytes Chunk = 2; // Chunk should be a remaining message in stream should be chunks
} }
} }
message PutResponse { 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 { message DeleteRequest {
uint64 Epoch = 1; uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value
refs.Address Address = 2 [(gogoproto.nullable) = false]; refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id)
bytes OwnerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "OwnerID"]; bytes OwnerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "OwnerID"]; // OwnerID is a wallet address
uint32 TTL = 4; uint32 TTL = 4; // TTL must be larger than zero, it decreased in every neofs-node
session.Token Token = 5; 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 {} message DeleteResponse {}
// HeadRequest.FullHeader == true, for fetch all headers
message HeadRequest { message HeadRequest {
uint64 Epoch = 1; 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"]; refs.Address Address = 2 [(gogoproto.nullable) = false, (gogoproto.customtype) = "Address"]; // Address of object (container id + object id)
bool FullHeaders = 3; bool FullHeaders = 3; // FullHeaders can be set true for extended headers in the object
uint32 TTL = 4; uint32 TTL = 4; // TTL must be larger than zero, it decreased in every neofs-node
} }
message HeadResponse { message HeadResponse {
Object Object = 1; Object Object = 1; // Object without payload
} }
message SearchRequest { message SearchRequest {
uint64 Epoch = 1; uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value
uint32 Version = 2; uint32 Version = 2; // Version of search query format
bytes ContainerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "CID"]; bytes ContainerID = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "CID"]; // ContainerID for searching the object
bytes Query = 4; bytes Query = 4; // Query in the binary serialized format
uint32 TTL = 5; uint32 TTL = 5; // TTL must be larger than zero, it decreased in every neofs-node
} }
message SearchResponse { message SearchResponse {
repeated refs.Address Addresses = 1 [(gogoproto.nullable) = false]; repeated refs.Address Addresses = 1 [(gogoproto.nullable) = false]; // Addresses of found objects
} }
message GetRangeRequest { message GetRangeRequest {
uint64 Epoch = 1; uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value
refs.Address Address = 2 [(gogoproto.nullable) = false]; refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id)
repeated Range Ranges = 3 [(gogoproto.nullable) = false]; repeated Range Ranges = 3 [(gogoproto.nullable) = false]; // Ranges of object's payload to return
uint32 TTL = 4; uint32 TTL = 4; // TTL must be larger than zero, it decreased in every neofs-node
} }
message GetRangeResponse { message GetRangeResponse {
repeated bytes Fragments = 1; repeated bytes Fragments = 1; // Fragments of object's payload
} }
message GetRangeHashRequest { message GetRangeHashRequest {
uint64 Epoch = 1; uint64 Epoch = 1; // Epoch is set by user to 0, node set epoch to the actual value
refs.Address Address = 2 [(gogoproto.nullable) = false]; refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id)
repeated Range Ranges = 3 [(gogoproto.nullable) = false]; repeated Range Ranges = 3 [(gogoproto.nullable) = false]; // Ranges of object's payload to calculate homomorphic hash
bytes Salt = 4; bytes Salt = 4; // Salt is used to XOR object's payload ranges before hashing, it can be nil
uint32 TTL = 5; uint32 TTL = 5; // TTL must be larger than zero, it decreased in every neofs-node
} }
message GetRangeHashResponse { 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
} }

View file

@ -9,99 +9,97 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
message Range { message Range {
uint64 Offset = 1; uint64 Offset = 1; // Offset of the data range
uint64 Length = 2; uint64 Length = 2; // Length of the data range
} }
message UserHeader { message UserHeader {
string Key = 1; string Key = 1; // Key of the user's header
string Value = 2; string Value = 2; // Value of the user's header
} }
message Header { message Header {
oneof Value { oneof Value {
Link Link = 1; Link Link = 1; // Link to other objects
refs.Address Redirect = 2; refs.Address Redirect = 2; // RedirectNot used yet
UserHeader UserHeader = 3; UserHeader UserHeader = 3; // UserHeader defined by user
Transform Transform = 4; Transform Transform = 4; // Transform defines transform operation (e.g. payload split)
Tombstone Tombstone = 5; Tombstone Tombstone = 5; // Tombstone header that set up in deleted objects
// session-related info: session.VerificationHeader session.VerificationHeader Verify = 6; // Verify header that contains session public key and user's signature
session.VerificationHeader Verify = 6; bytes HomoHash = 7 [(gogoproto.customtype) = "Hash"]; // Homomorphic hash of original object payload
// integrity-related info bytes PayloadChecksum = 8; // PayloadChecksum of actual object's payload
bytes HomoHash = 7 [(gogoproto.customtype) = "Hash"]; IntegrityHeader Integrity = 9; // Integrity header with checksum of all above headers in the object
bytes PayloadChecksum = 8; StorageGroup StorageGroup = 10; // StorageGroup contains meta information for the data audit
IntegrityHeader Integrity = 9;
StorageGroup StorageGroup = 10;
} }
} }
message Tombstone { message Tombstone {
uint64 Epoch = 1; uint64 Epoch = 1; // Epoch when tombstone was created
} }
message SystemHeader { message SystemHeader {
uint64 Version = 1; uint64 Version = 1; // Version of the object structure
uint64 PayloadLength = 2; uint64 PayloadLength = 2; // Object payload length
bytes ID = 3 [(gogoproto.customtype) = "ID", (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]; bytes OwnerID = 4 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; // OwnerID is a wallet address
bytes CID = 5 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; bytes CID = 5 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; // ContainerID is a SHA256 hash of the container structure
CreationPoint CreatedAt = 6 [(gogoproto.nullable) = false]; CreationPoint CreatedAt = 6 [(gogoproto.nullable) = false]; // Timestamp of object creation
} }
message CreationPoint { message CreationPoint {
int64 UnixTime = 1; int64 UnixTime = 1; // Date of creation in unixtime format
uint64 Epoch = 2; uint64 Epoch = 2; // Date of creation in NeoFS epochs
} }
message IntegrityHeader { message IntegrityHeader {
bytes HeadersChecksum = 1; bytes HeadersChecksum = 1; // Checksum of all above headers in the object
bytes ChecksumSignature = 2; bytes ChecksumSignature = 2; // User's signature of checksum to verify if it is correct
} }
message Link { message Link {
enum Type { enum Type {
Unknown = 0; Unknown = 0;
Parent = 1; Parent = 1; // Parent object created during object transformation
Previous = 2; Previous = 2; // Previous object in the linked list created during object transformation
Next = 3; Next = 3; // Next object in the linked list created during object transformation
Child = 4; Child = 4; // Child object created during object transformation
StorageGroup = 5; StorageGroup = 5; // Object that included into this storage group
} }
Type type = 1; Type type = 1; // Link type
bytes ID = 2 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false]; bytes ID = 2 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false]; // Object id
} }
message Transform { message Transform {
enum Type { enum Type {
Unknown = 0; Unknown = 0;
Split = 1; Split = 1; // Object created after payload split
Sign = 2; Sign = 2; // Object created after re-signing (doesn't used)
Mould = 3; Mould = 3; // Object created after filling missing headers in the object
} }
Type type = 1; Type type = 1; // Type of object transformation
} }
message Object { message Object {
SystemHeader SystemHeader = 1 [(gogoproto.nullable) = false]; SystemHeader SystemHeader = 1 [(gogoproto.nullable) = false]; // System header
repeated Header Headers = 2 [(gogoproto.nullable) = false]; repeated Header Headers = 2 [(gogoproto.nullable) = false]; // Extended headers
bytes Payload = 3; bytes Payload = 3; // Object's payload
} }
message StorageGroup { message StorageGroup {
uint64 ValidationDataSize = 1; uint64 ValidationDataSize = 1; // Size of the all object's payloads included into storage group
bytes ValidationHash = 2 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false]; bytes ValidationHash = 2 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false]; // Homomorphic hash of all object's payloads included into storage group
message Lifetime { message Lifetime {
enum Unit { enum Unit {
Unlimited = 0; Unlimited = 0; // Storage group always valid
NeoFSEpoch = 1; NeoFSEpoch = 1; // Storage group is valid until lifetime NeoFS epoch
UnixTime = 2; UnixTime = 2; // Storage group is valid until lifetime unix timestamp
} }
Unit unit = 1 [(gogoproto.customname) = "Unit"]; Unit unit = 1 [(gogoproto.customname) = "Unit"]; // Lifetime type
int64 Value = 2; int64 Value = 2; // Lifetime value
} }
Lifetime lifetime = 3 [(gogoproto.customname) = "Lifetime"]; Lifetime lifetime = 3 [(gogoproto.customname) = "Lifetime"]; // Time until storage group is valid
} }

Binary file not shown.

View file

@ -9,17 +9,23 @@ option (gogoproto.stable_marshaler_all) = true;
message Filter { message Filter {
option (gogoproto.goproto_stringer) = false; option (gogoproto.goproto_stringer) = false;
// Type can be Exact or Regex
enum Type { enum Type {
Exact = 0; Exact = 0;
Regex = 1; Regex = 1;
} }
// Type of filter
Type type = 1 [(gogoproto.customname) = "Type"]; Type type = 1 [(gogoproto.customname) = "Type"];
// Name of field that should be filtered
string Name = 2; string Name = 2;
// Value that should be used for filter
string Value = 3; string Value = 3;
} }
message Query { message Query {
option (gogoproto.goproto_stringer) = false; option (gogoproto.goproto_stringer) = false;
// Filters is set of filters, should not be empty
repeated Filter Filters = 1 [(gogoproto.nullable) = false]; repeated Filter Filters = 1 [(gogoproto.nullable) = false];
} }

Binary file not shown.

View file

@ -9,7 +9,10 @@ option (gogoproto.stable_marshaler_all) = true;
option (gogoproto.stringer_all) = false; option (gogoproto.stringer_all) = false;
option (gogoproto.goproto_stringer_all) = false; option (gogoproto.goproto_stringer_all) = false;
// Address of object (container id + object id)
message Address { message Address {
bytes ObjectID = 1[(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false]; // UUID // ObjectID is an object identifier
bytes CID = 2[(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; // sha256 bytes ObjectID = 1[(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false];
// CID is container identifier
bytes CID = 2[(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
} }

Binary file not shown.

View file

@ -7,21 +7,41 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
service Session { 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); rpc Create (stream CreateRequest) returns (stream CreateResponse);
} }
message CreateRequest { message CreateRequest {
// Message should be one of
oneof Message { oneof Message {
// Message to init session opening. Carry:
// owner of manipulation object;
// ID of manipulation object;
// token lifetime bounds.
session.Token Init = 1; session.Token Init = 1;
// Signed Init message response (Unsigned) from server with user private key
session.Token Signed = 2; session.Token Signed = 2;
} }
} }
message CreateResponse { message CreateResponse {
oneof Message { oneof Message {
// Unsigned token with token ID and session public key generated on server side
session.Token Unsigned = 1; session.Token Unsigned = 1;
// Resulting token which can be used for object placing through an trusted intermediary
session.Token Result = 2; session.Token Result = 2;
} }
} }

Binary file not shown.

View file

@ -7,16 +7,26 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
message VerificationHeader { message VerificationHeader {
// Session public key
bytes PublicKey = 1; bytes PublicKey = 1;
// Session public key signature. Signed by trusted side
bytes KeySignature = 2; bytes KeySignature = 2;
} }
// User token granting rights for object manipulation
message Token { message Token {
// Header carries verification data of session key
VerificationHeader Header = 1 [(gogoproto.nullable) = false]; VerificationHeader Header = 1 [(gogoproto.nullable) = false];
// Owner of manipulation object
bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// Initial epoch of token lifetime
uint64 FirstEpoch = 3; uint64 FirstEpoch = 3;
// Last epoch of token lifetime
uint64 LastEpoch = 4; uint64 LastEpoch = 4;
// ID of manipulation object
repeated bytes ObjectID = 5 [(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false]; repeated bytes ObjectID = 5 [(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false];
// Token signature. Signed by owner of manipulation object
bytes Signature = 6; bytes Signature = 6;
// Token ID (UUID)
bytes ID = 7 [(gogoproto.customtype) = "TokenID", (gogoproto.nullable) = false]; bytes ID = 7 [(gogoproto.customtype) = "TokenID", (gogoproto.nullable) = false];
} }

Binary file not shown.

View file

@ -7,10 +7,14 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
// The Status service definition. // Status service provides node's healthcheck and status info
service Status { service Status {
// Netmap request allows to receive current [bootstrap.SpreadMap](bootstrap.md#bootstrap.SpreadMap)
rpc Netmap(NetmapRequest) returns (bootstrap.SpreadMap); rpc Netmap(NetmapRequest) returns (bootstrap.SpreadMap);
// Metrics request allows to receive metrics in prometheus format
rpc Metrics(MetricsRequest) returns (MetricsResponse); 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); rpc HealthCheck(HealthRequest) returns (HealthResponse);
} }
@ -32,6 +36,8 @@ message HealthRequest {}
// HealthResponse message with current state // HealthResponse message with current state
message HealthResponse { message HealthResponse {
// Healthy is true when node alive and healthy
bool Healthy = 1; bool Healthy = 1;
// Status contains detailed information about health status
string Status = 2; string Status = 2;
} }