frostfs-api/proto-docs/service.md
Stanislav Bogatyrev a78b8a1ea5 Move all service types to types.proto
Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>
2020-08-18 15:04:15 +03:00

10 KiB

Protocol Documentation

Table of Contents

Top

service/types.proto

Message BearerToken

BearerToken has information about request ACL rules with limited lifetime

Field Type Label Description
body BearerToken.Body Bearer Token body
signature Signature Signature of BearerToken body

Message BearerToken.Body

Bearer Token body

Field Type Label Description
eacl_table neo.fs.v2.acl.EACLTable EACLTable carries table of extended ACL rules
owner_id neo.fs.v2.refs.OwnerID OwnerID carries identifier of the token owner
lifetime TokenLifetime Token expiration and valid time period parameters

Message ObjectSessionContext

Context information for Session Tokens related to ObjectService requests

Field Type Label Description
verb ObjectSessionContext.Verb Verb is a type of request for which the token is issued
address neo.fs.v2.refs.Address Related Object address

Message RequestMetaHeader

Information about the request

Field Type Label Description
version Version Client API version.
epoch uint64 Client local epoch number. Set to 0 if unknown.
ttl uint32 Maximum number of nodes in the request route.
x_headers XHeader repeated Request X-Headers.
session_token SessionToken Token is a token of the session within which the request is sent
bearer_token BearerToken Bearer is a Bearer token of the request
origin RequestMetaHeader RequestMetaHeader of the origin request.

Message RequestVerificationHeader

Verification info for request signed by all intermediate nodes

Field Type Label Description
body_signature Signature Request Body signature. Should be generated once by request initiator.
meta_signature Signature Request Meta signature is added and signed by any intermediate node
origin_signature Signature Sign previous hops
origin RequestVerificationHeader Chain of previous hops signatures

Message ResponseMetaHeader

Information about the response

Field Type Label Description
version Version Server API version.
epoch uint64 Server local epoch number.
ttl uint32 Maximum number of nodes in the response route.
x_headers XHeader repeated Response X-Headers.
origin ResponseMetaHeader Carries response meta header of the origin response.

Message ResponseVerificationHeader

Verification info for response signed by all intermediate nodes

Field Type Label Description
body_signature Signature Response Body signature. Should be generated once by answering node.
meta_signature Signature Response Meta signature is added and signed by any intermediate node
origin_signature Signature Sign previous hops
origin ResponseVerificationHeader Chain of previous hops signatures

Message SessionToken

NeoFS session token.

Field Type Label Description
body SessionToken.Body Session Token body
signature Signature Signature is a signature of session token information

Message SessionToken.Body

Session token body

Field Type Label Description
id bytes ID is a token identifier. valid UUIDv4 represented in bytes
owner_id neo.fs.v2.refs.OwnerID OwnerID carries identifier of the session initiator.
lifetime TokenLifetime Lifetime is a lifetime of the session
session_key bytes SessionKey is a public key of session key
object ObjectSessionContext ObjectService session context.

Message Signature

Signature of something in NeoFS

Field Type Label Description
key bytes Public key used for signing.
sign bytes Signature

Message TokenLifetime

Lifetime parameters of the token. Filed names taken from rfc7519.

Field Type Label Description
exp uint64 Expiration Epoch
nbf uint64 Not valid before Epoch
iat uint64 Issued at Epoch

Message Version

Represents API version used by node.

Field Type Label Description
major uint32 Major API version.
minor uint32 Minor API version.

Message XHeader

Extended headers for Request/Response

Field Type Label Description
key string Key of the X-Header.
value string Value of the X-Header.

ObjectSessionContext.Verb

Object request verbs

Name Number Description
VERB_UNSPECIFIED 0 Unknown verb
PUT 1 Refers to object.Put RPC call
GET 2 Refers to object.Get RPC call
HEAD 3 Refers to object.Head RPC call
SEARCH 4 Refers to object.Search RPC call
DELETE 5 Refers to object.Delete RPC call
RANGE 6 Refers to object.GetRange RPC call
RANGEHASH 7 Refers to object.GetRangeHash RPC call

Scalar Value Types

.proto Type Notes C++ Type Java Type Python Type
double double double float
float float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long
uint32 Uses variable-length encoding. uint32 int int/long
uint64 Uses variable-length encoding. uint64 long int/long
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str