dkirillov/frostfs-api
1
0
Fork 0
forked from TrueCloudLab/frostfs-api
Code Issues Pull requests Projects Releases Packages Wiki Activity

object: Tidy up the format

Browse source 
Signed-off-by: Leonard Lyubich <leonard@nspcc.ru>
This commit is contained in:
Leonard Lyubich 2020-08-06 02:45:39 +03:00 committed by Stanislav Bogatyrev
parent ad5126f53f
commit 05a885e142
2 changed files with 162 additions and 114 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

186
object/service.proto
View file

@ -1,5 +1,7 @@
syntax = "proto3"; syntax = "proto3";
package object; package object;
option go_package = "github.com/nspcc-dev/neofs-api-go/object"; option go_package = "github.com/nspcc-dev/neofs-api-go/object";
option csharp_namespace = "NeoFS.API.Object"; option csharp_namespace = "NeoFS.API.Object";
@ -51,61 +53,84 @@ service Service {
} }
message GetRequest { message GetRequest {
// Address of object (container id + object id) // Carries the address of the requested object.
refs.Address Address = 1; refs.Address Address = 1;
// Raw carries the raw option flag of the request.
// Carries the raw option flag of the request.
// Raw request is sent to receive only the objects // Raw request is sent to receive only the objects
// that are physically stored on the server. // that are physically stored on the server.
bool Raw = 2; bool Raw = 2;
// RequestMetaHeader contains information about request meta headers (should be embedded into message)
service.RequestMetaHeader Meta = 98; // Carries request meta information. Header data is used only to regulate message
// RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) // transport and does not affect request execution.
service.RequestVerificationHeader Verify = 99; service.RequestMetaHeader MetaHeader = 98;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
service.RequestVerificationHeader VerifyHeader = 99;
} }
message GetResponse { message GetResponse {
oneof R { // Carries the single message of the response stream.
// Object header and some payload oneof ObjectPart {
Object object = 1; // Carries the object header.
// Chunk of remaining payload Header Header = 1;
bytes Chunk = 2;
// Carries part of the object payload.
bytes Chunk = 2;
} }
} }
message PutRequest { message PutRequest {
message PutHeader { // Groups initialization parameters of object placement in NeoFS.
// Object with at least container id and owner id fields message Init {
Object Object = 1; // Carries the header of the object to save in the system.
// Number of the object copies to store within the RPC call (zero is processed according to the placement rules) Header Header = 1;
// Carries the number of the object copies to store
// within the RPC call. Default zero value is processed according
// to the container placement rules.
uint32 CopiesNumber = 2; uint32 CopiesNumber = 2;
} }
oneof R { // Carries the single part of the query stream.
// Header should be the first message in the stream oneof Part {
PutHeader Header = 1; // Carries the initialization parameters of the object stream.
// Chunk should be a remaining message in stream should be chunks Init init = 1;
bytes Chunk = 2;
// Carries part of the object payload.
bytes Chunk = 2;
} }
// RequestMetaHeader contains information about request meta headers (should be embedded into message) // Carries request meta information. Header data is used only to regulate message
service.RequestMetaHeader Meta = 98; // transport and does not affect request execution.
// RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) service.RequestMetaHeader MetaHeader = 98;
service.RequestVerificationHeader Verify = 99;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
service.RequestVerificationHeader VerifyHeader = 99;
} }
message PutResponse { message PutResponse {
// Address of object (container id + object id) // Carries identifier of the saved object.
refs.Address Address = 1; // It is used to access an object in the container.
refs.ObjectID ObjectID = 1;
} }
message DeleteRequest { message DeleteRequest {
// Address of object (container id + object id) // Carries the address of the object to be deleted.
refs.Address Address = 1; refs.Address Address = 1;
// OwnerID carries identifier of the object owner.
// Carries identifier the object owner.
refs.OwnerID OwnerID = 2; refs.OwnerID OwnerID = 2;
// RequestMetaHeader contains information about request meta headers (should be embedded into message)
service.RequestMetaHeader Meta = 98; // Carries request meta information. Header data is used only to regulate message
// RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) // transport and does not affect request execution.
service.RequestVerificationHeader Verify = 99; service.RequestMetaHeader MetaHeader = 98;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
service.RequestVerificationHeader VerifyHeader = 99;
} }
// DeleteResponse is empty because we cannot guarantee permanent object removal // DeleteResponse is empty because we cannot guarantee permanent object removal
@ -114,26 +139,33 @@ message DeleteResponse {
} }
message HeadRequest { message HeadRequest {
// Address of object (container id + object id) // Carries the address of the object with the requested header.
refs.Address Address = 1; refs.Address Address = 1;
// FullHeaders can be set true for extended headers in the object
bool FullHeaders = 2; // Carries the option to crop header to main part.
// Raw carries the raw option flag of the request. bool MainOnly = 2;
// Carries the raw option flag of the request.
// Raw request is sent to receive only the headers of the objects // Raw request is sent to receive only the headers of the objects
// that are physically stored on the server. // that are physically stored on the server.
bool Raw = 3; bool Raw = 3;
// RequestMetaHeader contains information about request meta headers (should be embedded into message)
service.RequestMetaHeader Meta = 98; // Carries request meta information. Header data is used only to regulate message
// RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) // transport and does not affect request execution.
service.RequestVerificationHeader Verify = 99; service.RequestMetaHeader MetaHeader = 98;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
service.RequestVerificationHeader VerifyHeader = 99;
} }
message HeadResponse { message HeadResponse {
// Object without payload // Carries the requested object header.
Object Object = 1; Header Header = 1;
} }
message SearchRequest { message SearchRequest {
// ContainerID carries search container identifier. // Carries search container identifier.
refs.ContainerID ContainerID = 1; refs.ContainerID ContainerID = 1;
message Query { message Query {
@ -157,55 +189,71 @@ message SearchRequest {
Query query = 2; Query query = 2;
// RequestMetaHeader contains information about request meta headers (should be embedded into message) // Carries request meta information. Header data is used only to regulate message
service.RequestMetaHeader Meta = 98; // transport and does not affect request execution.
// RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) service.RequestMetaHeader MetaHeader = 98;
service.RequestVerificationHeader Verify = 99;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
service.RequestVerificationHeader VerifyHeader = 99;
} }
message SearchResponse { message SearchResponse {
// Addresses of found objects // Carries list of object identifiers that match the search query.
repeated refs.Address Addresses = 1; repeated refs.ObjectID IDList = 1;
} }
// Range groups the parameters of object payload range.
message Range { message Range {
// Offset of the data range // Carries the offset of the range from the object payload start.
uint64 Offset = 1; uint64 Offset = 1;
// Length of the data range
// Carries the length of the object payload range.
uint64 Length = 2; uint64 Length = 2;
} }
message GetRangeRequest { message GetRangeRequest {
// Address of object (container id + object id) // Address carries address of the object that contains the requested payload range.
refs.Address Address = 1; refs.Address Address = 1;
// Range of object's payload to return
// Range carries the parameters of the requested payload range.
Range Range = 2; Range Range = 2;
// RequestMetaHeader contains information about request meta headers (should be embedded into message)
service.RequestMetaHeader Meta = 98; // Carries request meta information. Header data is used only to regulate message
// RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) // transport and does not affect request execution.
service.RequestVerificationHeader Verify = 99; service.RequestMetaHeader MetaHeader = 98;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
service.RequestVerificationHeader VerifyHeader = 99;
} }
message GetRangeResponse { message GetRangeResponse {
// Fragment of object's payload // Carries part of the object payload.
bytes Fragment = 1; bytes Chunk = 1;
} }
message GetRangeHashRequest { message GetRangeHashRequest {
// Address of object (container id + object id) // Carries address of the object that contains the requested payload range.
refs.Address Address = 1; refs.Address Address = 1;
// Ranges of object's payload to calculate homomorphic hash
// Carries the list of object payload range to calculate homomorphic hash.
repeated Range Ranges = 2; repeated Range Ranges = 2;
// Salt is used to XOR object's payload ranges before hashing, it can be nil
bytes Salt = 3; // Carries binary salt to XOR object payload ranges before hash calculation.
// RequestMetaHeader contains information about request meta headers (should be embedded into message) bytes Salt = 3;
service.RequestMetaHeader Meta = 98;
// RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) // Carries request meta information. Header data is used only to regulate message
service.RequestVerificationHeader Verify = 99; // transport and does not affect request execution.
service.RequestMetaHeader MetaHeader = 98;
// Carries request verification information. This header is used to authenticate
// the nodes of the message route and check the correctness of transmission.
service.RequestVerificationHeader VerifyHeader = 99;
} }
message GetRangeHashResponse { message GetRangeHashResponse {
// Hashes is a homomorphic hashes of all ranges // Carries list of homomorphic hashes in a binary format.
repeated bytes Hashes = 1; repeated bytes HashList = 1;
} }

90
proto-docs/object.md
View file

@ -19,7 +19,7 @@
- [HeadRequest](#object.HeadRequest) - [HeadRequest](#object.HeadRequest)
- [HeadResponse](#object.HeadResponse) - [HeadResponse](#object.HeadResponse)
- [PutRequest](#object.PutRequest) - [PutRequest](#object.PutRequest)
- [PutRequest.PutHeader](#object.PutRequest.PutHeader) - [PutRequest.Init](#object.PutRequest.Init)
- [PutResponse](#object.PutResponse) - [PutResponse](#object.PutResponse)
- [Range](#object.Range) - [Range](#object.Range)
- [SearchRequest](#object.SearchRequest) - [SearchRequest](#object.SearchRequest)
@ -148,10 +148,10 @@ calculated for XORed data.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) | | Address | [refs.Address](#refs.Address) | | Carries the address of the object to be deleted. |
| OwnerID | [refs.OwnerID](#refs.OwnerID) | | OwnerID carries identifier of the object owner. | | OwnerID | [refs.OwnerID](#refs.OwnerID) | | Carries identifier the object owner. |
| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | | MetaHeader | [service.RequestMetaHeader](#service.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | | VerifyHeader | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
<a name="object.DeleteResponse"></a> <a name="object.DeleteResponse"></a>
@ -170,11 +170,11 @@ in distributed system.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) | | Address | [refs.Address](#refs.Address) | | Carries address of the object that contains the requested payload range. |
| Ranges | [Range](#object.Range) | repeated | Ranges of object's payload to calculate homomorphic hash | | Ranges | [Range](#object.Range) | repeated | Carries the list of object payload range to calculate homomorphic hash. |
| Salt | [bytes](#bytes) | | Salt is used to XOR object's payload ranges before hashing, it can be nil | | Salt | [bytes](#bytes) | | Carries binary salt to XOR object payload ranges before hash calculation. |
| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | | MetaHeader | [service.RequestMetaHeader](#service.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | | VerifyHeader | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
<a name="object.GetRangeHashResponse"></a> <a name="object.GetRangeHashResponse"></a>
@ -185,7 +185,7 @@ in distributed system.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| Hashes | [bytes](#bytes) | repeated | Hashes is a homomorphic hashes of all ranges | | HashList | [bytes](#bytes) | repeated | Carries list of homomorphic hashes in a binary format. |
<a name="object.GetRangeRequest"></a> <a name="object.GetRangeRequest"></a>
@ -196,10 +196,10 @@ in distributed system.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) | | Address | [refs.Address](#refs.Address) | | Address carries address of the object that contains the requested payload range. |
| Range | [Range](#object.Range) | | Range of object's payload to return | | Range | [Range](#object.Range) | | Range carries the parameters of the requested payload range. |
| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | | MetaHeader | [service.RequestMetaHeader](#service.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | | VerifyHeader | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
<a name="object.GetRangeResponse"></a> <a name="object.GetRangeResponse"></a>
@ -210,7 +210,7 @@ in distributed system.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| Fragment | [bytes](#bytes) | | Fragment of object's payload | | Chunk | [bytes](#bytes) | | Carries part of the object payload. |
<a name="object.GetRequest"></a> <a name="object.GetRequest"></a>
@ -221,10 +221,10 @@ in distributed system.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) | | Address | [refs.Address](#refs.Address) | | Carries the address of the requested object. |
| Raw | [bool](#bool) | | Raw carries the raw option flag of the request. Raw request is sent to receive only the objects that are physically stored on the server. | | Raw | [bool](#bool) | | Carries the raw option flag of the request. Raw request is sent to receive only the objects that are physically stored on the server. |
| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | | MetaHeader | [service.RequestMetaHeader](#service.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | | VerifyHeader | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
<a name="object.GetResponse"></a> <a name="object.GetResponse"></a>
@ -235,8 +235,8 @@ in distributed system.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| object | [Object](#object.Object) | | Object header and some payload | | Header | [Header](#object.Header) | | Carries the object header. |
| Chunk | [bytes](#bytes) | | Chunk of remaining payload | | Chunk | [bytes](#bytes) | | Carries part of the object payload. |
<a name="object.HeadRequest"></a> <a name="object.HeadRequest"></a>
@ -247,11 +247,11 @@ in distributed system.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) | | Address | [refs.Address](#refs.Address) | | Carries the address of the object with the requested header. |
| FullHeaders | [bool](#bool) | | FullHeaders can be set true for extended headers in the object | | MainOnly | [bool](#bool) | | Carries the option to crop header to main part. |
| Raw | [bool](#bool) | | Raw carries the raw option flag of the request. Raw request is sent to receive only the headers of the objects that are physically stored on the server. | | Raw | [bool](#bool) | | Carries the raw option flag of the request. Raw request is sent to receive only the headers of the objects that are physically stored on the server. |
| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | | MetaHeader | [service.RequestMetaHeader](#service.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | | VerifyHeader | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
<a name="object.HeadResponse"></a> <a name="object.HeadResponse"></a>
@ -262,7 +262,7 @@ in distributed system.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| Object | [Object](#object.Object) | | Object without payload | | Header | [Header](#object.Header) | | Carries the requested object header. |
<a name="object.PutRequest"></a> <a name="object.PutRequest"></a>
@ -273,22 +273,22 @@ in distributed system.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| Header | [PutRequest.PutHeader](#object.PutRequest.PutHeader) | | Header should be the first message in the stream | | init | [PutRequest.Init](#object.PutRequest.Init) | | Carries the initialization parameters of the object stream. |
| Chunk | [bytes](#bytes) | | Chunk should be a remaining message in stream should be chunks | | Chunk | [bytes](#bytes) | | Carries part of the object payload. |
| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | | MetaHeader | [service.RequestMetaHeader](#service.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | | VerifyHeader | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
<a name="object.PutRequest.PutHeader"></a> <a name="object.PutRequest.Init"></a>
### Message PutRequest.PutHeader
### Message PutRequest.Init
Groups initialization parameters of object placement in NeoFS.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| Object | [Object](#object.Object) | | Object with at least container id and owner id fields | | Header | [Header](#object.Header) | | Carries the header of the object to save in the system. |
| CopiesNumber | [uint32](#uint32) | | Number of the object copies to store within the RPC call (zero is processed according to the placement rules) | | CopiesNumber | [uint32](#uint32) | | Carries the number of the object copies to store within the RPC call. Default zero value is processed according to the container placement rules. |
<a name="object.PutResponse"></a> <a name="object.PutResponse"></a>
@ -299,19 +299,19 @@ in distributed system.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) | | ObjectID | [refs.ObjectID](#refs.ObjectID) | | Carries identifier of the saved object. It is used to access an object in the container. |
<a name="object.Range"></a> <a name="object.Range"></a>
### Message Range ### Message Range
Range groups the parameters of object payload range.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| Offset | [uint64](#uint64) | | Offset of the data range | | Offset | [uint64](#uint64) | | Carries the offset of the range from the object payload start. |
| Length | [uint64](#uint64) | | Length of the data range | | Length | [uint64](#uint64) | | Carries the length of the object payload range. |
<a name="object.SearchRequest"></a> <a name="object.SearchRequest"></a>
@ -322,10 +322,10 @@ in distributed system.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| ContainerID | [refs.ContainerID](#refs.ContainerID) | | ContainerID carries search container identifier. | | ContainerID | [refs.ContainerID](#refs.ContainerID) | | Carries search container identifier. |
| query | [SearchRequest.Query](#object.SearchRequest.Query) | | | | query | [SearchRequest.Query](#object.SearchRequest.Query) | | |
| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | | MetaHeader | [service.RequestMetaHeader](#service.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | | VerifyHeader | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
<a name="object.SearchRequest.Query"></a> <a name="object.SearchRequest.Query"></a>
@ -361,7 +361,7 @@ in distributed system.
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| Addresses | [refs.Address](#refs.Address) | repeated | Addresses of found objects | | IDList | [refs.ObjectID](#refs.ObjectID) | repeated | Carries list of object identifiers that match the search query. |
<!-- end messages --> <!-- end messages -->