frostfs-api/object/service.proto

syntax = "proto3";

package object;

option go_package = "github.com/nspcc-dev/neofs-api-go/object";
option csharp_namespace = "NeoFS.API.Object";

import "refs/types.proto";
import "object/types.proto";
import "service/meta.proto";
import "service/verify.proto";

// Object service provides API for manipulating with the object.
service Service {
    // 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);
}

message GetRequest {
    // Carries the address of the requested object.
    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;

    // Carries request meta information. Header data is used only to regulate message
    // 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 GetResponse {
    // Carries the single message of the response stream.
    oneof ObjectPart {
        // Carries the object header.
        Header Header = 1;

        // Carries part of the object payload.
        bytes Chunk = 2;
    }
}

message PutRequest {
    // Groups initialization parameters of object placement in NeoFS.
    message Init {
        // Carries the header of the object to save in the system.
        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;
    }

    // Carries the single part of the query stream.
    oneof Part {
        // Carries the initialization parameters of the object stream.
        Init init = 1;

        // Carries part of the object payload.
        bytes Chunk = 2;
    }

    // Carries request meta information. Header data is used only to regulate message
    // 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 PutResponse {
    // Carries identifier of the saved object.
    // It is used to access an object in the container.
    refs.ObjectID ObjectID = 1;
}

message DeleteRequest {
    // Carries the address of the object to be deleted.
    refs.Address Address = 1;

    // Carries identifier the object owner.
    refs.OwnerID OwnerID = 2;

    // Carries request meta information. Header data is used only to regulate message
    // 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;
}

// DeleteResponse is empty because we cannot guarantee permanent object removal
// in distributed system.
message DeleteResponse {
}

message HeadRequest {
    // Carries the address of the object with the requested header.
    refs.Address Address = 1;

    // Carries the option to crop header to main part.
    bool MainOnly = 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;

    // Carries request meta information. Header data is used only to regulate message
    // 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 HeadResponse {
    // Carries the requested object header.
    Header Header = 1;
}

message SearchRequest {
    // Carries search container identifier.
    refs.ContainerID ContainerID = 1;

    message Query {
        uint32 Version = 1;

        message Filter {
            enum MatchType {
                MatchUnknown = 0;
                StringEqual = 1;
            }

            MatchType matchType = 1;

            string Name = 2;

            string Value = 3;
        }

        repeated Filter Filters = 2;
    }

    Query query = 2;

    // Carries request meta information. Header data is used only to regulate message
    // 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 SearchResponse {
    // Carries list of object identifiers that match the search query.
    repeated refs.ObjectID IDList = 1;
}

// 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;
}

message GetRangeRequest {
    // Address carries address of the object that contains the requested payload range.
    refs.Address Address = 1;

    // Range carries the parameters of the requested payload range.
    Range Range = 2;

    // Carries request meta information. Header data is used only to regulate message
    // 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 GetRangeResponse {
    // Carries part of the object payload.
    bytes Chunk = 1;
}

message GetRangeHashRequest {
    // Carries address of the object that contains the requested payload range.
    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;

    // Carries request meta information. Header data is used only to regulate message
    // 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 {
    // Carries list of homomorphic hashes in a binary format.
    repeated bytes HashList = 1;
}