syntax = "proto3"; package neo.fs.v2.object; option go_package = "github.com/nspcc-dev/neofs-api-go/v2/object/grpc;object"; option csharp_namespace = "NeoFS.API.v2.Object"; import "object/types.proto"; import "refs/types.proto"; import "session/types.proto"; // Object service provides API for manipulating with the object. service ObjectService { // Get the object from container. Response uses gRPC stream. First response // message carry object of requested address. Chunk messages are parts of // the object's payload if it is needed. All messages except first carry // chunks. Requested object can be restored by concatenation of object // message payload and all chunks keeping receiving order. rpc Get(GetRequest) returns (stream GetResponse); // Put the object into container. Request uses gRPC stream. First message // SHOULD BE type of PutHeader. Container id and Owner id of object SHOULD // BE set. Session token SHOULD BE obtained before put operation (see // session package). Chunk messages considered by server as part of object // payload. All messages except first SHOULD BE chunks. Chunk messages // SHOULD BE sent in direct order of fragmentation. rpc Put(stream PutRequest) returns (PutResponse); // Delete the object from a container rpc Delete(DeleteRequest) returns (DeleteResponse); // Head returns the object without data payload. Object in the // response has system header only. If full headers flag is set, extended // headers are also present. rpc Head(HeadRequest) returns (HeadResponse); // Search 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 (stream SearchResponse); // GetRange of data payload. Range is a pair (offset, length). // Requested range can be restored by concatenation of all chunks // keeping receiving order. rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse); // 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); } // Get object request message GetRequest { // Request body message Body { // Address of the requested object. neo.fs.v2.refs.Address address = 1; // Carries the raw option flag of the request. // Raw request is sent to receive only the objects // that are physically stored on the server. bool raw = 2; } // Body of get object request message. Body body = 1; // Carries request meta information. Header data is used only to regulate message // transport and does not affect request execution. neo.fs.v2.session.RequestMetaHeader meta_header = 2; // Carries request verification information. This header is used to authenticate // the nodes of the message route and check the correctness of transmission. neo.fs.v2.session.RequestVerificationHeader verify_header = 3; } // get object response message GetResponse { // Response body message Body { // Initialization parameters of the object got from NeoFS. message Init { // Object ID neo.fs.v2.refs.ObjectID object_id = 1; // Object signature neo.fs.v2.refs.Signature signature = 2; // Object header. Header header = 3; } // Carries the single message of the response stream. oneof object_part { // Initialization parameters of the object stream. Init init = 1; // Part of the object payload. bytes chunk = 2; } } // Body of get object response message. Body body = 1; // Carries response meta information. Header data is used only to regulate // message transport and does not affect request execution. neo.fs.v2.session.ResponseMetaHeader meta_header = 2; // Carries response verification information. This header is used to // authenticate the nodes of the message route and check the correctness // of transmission. neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; } // Put object request message PutRequest { // Request body message Body { // Groups initialization parameters of object placement in NeoFS. message Init { // Object ID, where available neo.fs.v2.refs.ObjectID object_id = 1; // Object signature, were available neo.fs.v2.refs.Signature signature = 2; // Header of the object to save in the system. Header header = 3; // Number of the object copies to store within the RPC call. // Default zero value is processed according to the // container placement rules. uint32 copies_number = 4; } // Carries the single part of the query stream. oneof object_part { // Carries the initialization parameters of the object stream. Init init = 1; // Carries part of the object payload. bytes chunk = 2; } } // Body of put object request message. Body body = 1; // Carries request meta information. Header data is used only to regulate message // transport and does not affect request execution. neo.fs.v2.session.RequestMetaHeader meta_header = 2; // Carries request verification information. This header is used to authenticate // the nodes of the message route and check the correctness of transmission. neo.fs.v2.session.RequestVerificationHeader verify_header = 3; } // Put object response message PutResponse { // Response body message Body { // Carries identifier of the saved object. // It is used to access an object in the container. neo.fs.v2.refs.ObjectID object_id = 1; } // Body of put object response message. Body body = 1; // Carries response meta information. Header data is used only to regulate // message transport and does not affect request execution. neo.fs.v2.session.ResponseMetaHeader meta_header = 2; // Carries response verification information. This header is used to // authenticate the nodes of the message route and check the correctness // of transmission. neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; } // Object Delete request message DeleteRequest { // Request body message Body { // Carries the address of the object to be deleted. neo.fs.v2.refs.Address address = 1; } // Body of delete object request message. Body body = 1; // Carries request meta information. Header data is used only to regulate message // transport and does not affect request execution. neo.fs.v2.session.RequestMetaHeader meta_header = 2; // Carries request verification information. This header is used to authenticate // the nodes of the message route and check the correctness of transmission. neo.fs.v2.session.RequestVerificationHeader verify_header = 3; } // DeleteResponse is empty because we cannot guarantee permanent object removal // in distributed system. message DeleteResponse { // Response body message Body { } // Body of delete object response message. Body body = 1; // Carries response meta information. Header data is used only to regulate // message transport and does not affect request execution. neo.fs.v2.session.ResponseMetaHeader meta_header = 2; // Carries response verification information. This header is used to // authenticate the nodes of the message route and check the correctness // of transmission. neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; } // Object head request message HeadRequest { // Request body message Body { // Address of the object with the requested header. neo.fs.v2.refs.Address address = 1; // Return only minimal header subset bool main_only = 2; // 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. bool raw = 3; } // Body of head object request message. Body body = 1; // Carries request meta information. Header data is used only to regulate message // transport and does not affect request execution. neo.fs.v2.session.RequestMetaHeader meta_header = 2; // Carries request verification information. This header is used to authenticate // the nodes of the message route and check the correctness of transmission. neo.fs.v2.session.RequestVerificationHeader verify_header = 3; } // Tuple of full object header and signature of object ID. message HeaderWithSignature { // Full object header Header header = 1; // Signed object_id to verify full header's authenticity through following steps: // 1. Calculate SHA-256 of marshalled Headers structure. // 2. Check if the resulting hash matched ObjectID // 3. Check if ObjectID's signature in signature field is correct. neo.fs.v2.refs.Signature signature = 2; } // Head response message HeadResponse { // Response body message Body { // Carries the requested object header or it's part oneof head{ // Full object header with object ID signature Header HeaderWithSignature = 1; // Short object header ShortHeader short_header = 2; } } // Body of head object response message. Body body = 1; // Carries response meta information. Header data is used only to regulate // message transport and does not affect request execution. neo.fs.v2.session.ResponseMetaHeader meta_header = 2; // Carries response verification information. This header is used to // authenticate the nodes of the message route and check the correctness // of transmission. neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; } // Search objects request message SearchRequest { // Request body message Body { // Carries search container identifier. neo.fs.v2.refs.ContainerID container_id = 1; // Version of the Query Language used uint32 version = 2; // Filter structure message Filter { // Match type to use MatchType match_type = 1; // Header name to match string name = 2; // Header value to match string value = 3; } // List of search expressions repeated Filter filters = 3; } // Body of search object request message. Body body = 1; // Carries request meta information. Header data is used only to regulate message // transport and does not affect request execution. neo.fs.v2.session.RequestMetaHeader meta_header = 2; // Carries request verification information. This header is used to authenticate // the nodes of the message route and check the correctness of transmission. neo.fs.v2.session.RequestVerificationHeader verify_header = 3; } // Search response message SearchResponse { // Response body message Body { // Carries list of object identifiers that match the search query repeated neo.fs.v2.refs.ObjectID id_list = 1; } // Body of search object response message. Body body = 1; // Carries response meta information. Header data is used only to regulate // message transport and does not affect request execution. neo.fs.v2.session.ResponseMetaHeader meta_header = 2; // Carries response verification information. This header is used to // authenticate the nodes of the message route and check the correctness // of transmission. neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; } // Range groups the parameters of object payload range. message Range { // Carries the offset of the range from the object payload start. uint64 offset = 1; // Carries the length of the object payload range. uint64 length = 2; } // Request to get part of object's payload message GetRangeRequest { // Request Body message Body { // Address carries address of the object that contains the requested payload range. neo.fs.v2.refs.Address address = 1; // Range carries the parameters of the requested payload range. Range range = 2; } // Body of get range object request message. Body body = 1; // Carries request meta information. Header data is used only to regulate message // transport and does not affect request execution. neo.fs.v2.session.RequestMetaHeader meta_header = 2; // Carries request verification information. This header is used to authenticate // the nodes of the message route and check the correctness of transmission. neo.fs.v2.session.RequestVerificationHeader verify_header = 3; } // Get part of object's payload message GetRangeResponse { // Response body message Body { // Carries part of the object payload. bytes chunk = 1; } // Body of get range object response message. Body body = 1; // Carries response meta information. Header data is used only to regulate // message transport and does not affect request execution. neo.fs.v2.session.ResponseMetaHeader meta_header = 2; // Carries response verification information. This header is used to // authenticate the nodes of the message route and check the correctness // of transmission. neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; } // Get hash of object's payload part message GetRangeHashRequest { // Request body message Body { // Carries address of the object that contains the requested payload range. neo.fs.v2.refs.Address address = 1; // Carries the list of object payload range to calculate homomorphic hash. repeated Range ranges = 2; // Carries binary salt to XOR object payload ranges before hash calculation. bytes salt = 3; // Checksum algorithm type neo.fs.v2.refs.ChecksumType type = 4; } // Body of get range hash object request message. Body body = 1; // Carries request meta information. Header data is used only to regulate message // transport and does not affect request execution. neo.fs.v2.session.RequestMetaHeader meta_header = 2; // Carries request verification information. This header is used to authenticate // the nodes of the message route and check the correctness of transmission. neo.fs.v2.session.RequestVerificationHeader verify_header = 3; } // Get hash of object's payload part message GetRangeHashResponse { // Response body message Body { // Checksum algorithm type neo.fs.v2.refs.ChecksumType type = 1; // List of range hashes in a binary format. repeated bytes hash_list = 2; } // Body of get range hash object response message. Body body = 1; // Carries response meta information. Header data is used only to regulate // message transport and does not affect request execution. neo.fs.v2.session.ResponseMetaHeader meta_header = 2; // Carries response verification information. This header is used to // authenticate the nodes of the message route and check the correctness // of transmission. neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; }