frostfs-api/object/service.proto

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
      HeaderWithSignature header = 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;
}