frostfs-api/container/service.proto

syntax = "proto3";

package frost.fs.container;

import "container/types.proto";
import "refs/types.proto";
import "session/types.proto";

// `ContainerService` provides API to interact with `Container` smart contract
// in FrostFS sidechain via other FrostFS nodes. All of those actions can be
// done equivalently by directly issuing transactions and RPC calls to sidechain
// nodes.
service ContainerService {
  // `Put` invokes `Container` smart contract's `Put` method and returns
  // response immediately. After a new block is issued in sidechain, request is
  // verified by Inner Ring nodes. After one more block in sidechain, the
  // container is added into smart contract storage.
  //
  // Statuses:
  // - **OK** (0, SECTION_SUCCESS): \
  //   request to save the container has been sent to the sidechain;
  // - Common failures (SECTION_FAILURE_COMMON);
  // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
  //   container create access denied.
  rpc Put(PutRequest) returns (PutResponse);

  // `Delete` invokes `Container` smart contract's `Delete` method and returns
  // response immediately. After a new block is issued in sidechain, request is
  // verified by Inner Ring nodes. After one more block in sidechain, the
  // container is added into smart contract storage.
  //
  // Statuses:
  // - **OK** (0, SECTION_SUCCESS): \
  //   request to remove the container has been sent to the sidechain;
  // - Common failures (SECTION_FAILURE_COMMON);
  // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
  //   container delete access denied.
  rpc Delete(DeleteRequest) returns (DeleteResponse);

  // Returns container structure from `Container` smart contract storage.
  //
  // Statuses:
  // - **OK** (0, SECTION_SUCCESS): \
  //   container has been successfully read;
  // - Common failures (SECTION_FAILURE_COMMON);
  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
  //   requested container not found;
  // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
  //   access to container is denied.
  rpc Get(GetRequest) returns (GetResponse);

  // Returns all owner's containers from 'Container` smart contract' storage.
  //
  // Statuses:
  // - **OK** (0, SECTION_SUCCESS): \
  //   container list has been successfully read;
  // - Common failures (SECTION_FAILURE_COMMON);
  // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
  //   container list access denied.
  rpc List(ListRequest) returns (ListResponse);
}

// New FrostFS Container creation request
message PutRequest {
  // Container creation request has container structure's signature as a
  // separate field. It's not stored in sidechain, just verified on container
  // creation by `Container` smart contract. `ContainerID` is a SHA256 hash of
  // the stable-marshalled container strucutre, hence there is no need for
  // additional signature checks.
  message Body {
    // Container structure to register in FrostFS
    container.Container container = 1;

    // Signature of a stable-marshalled container according to RFC-6979.
    frost.fs.refs.SignatureRFC6979 signature = 2;
  }
  // Body of container put request message.
  Body body = 1;

  // Carries request meta information. Header data is used only to regulate
  // message transport and does not affect request execution.
  frost.fs.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.
  frost.fs.session.RequestVerificationHeader verify_header = 3;
}

// New FrostFS Container creation response
message PutResponse {
  // Container put response body contains information about the newly registered
  // container as seen by `Container` smart contract. `ContainerID` can be
  // calculated beforehand from the container structure and compared to the one
  // returned here to make sure everything has been done as expected.
  message Body {
    // Unique identifier of the newly created container
    frost.fs.refs.ContainerID container_id = 1;
  }
  // Body of container put response message.
  Body body = 1;

  // Carries response meta information. Header data is used only to regulate
  // message transport and does not affect request execution.
  frost.fs.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.
  frost.fs.session.ResponseVerificationHeader verify_header = 3;
}

// Container removal request
message DeleteRequest {
  // Container removal request body has signed `ContainerID` as a proof of
  // the container owner's intent. The signature will be verified by `Container`
  // smart contract, so signing algorithm must be supported by NeoVM.
  message Body {
    // Identifier of the container to delete from FrostFS
    frost.fs.refs.ContainerID container_id = 1;

    // `ContainerID` signed with the container owner's key according to
    // RFC-6979.
    frost.fs.refs.SignatureRFC6979 signature = 2;
  }
  // Body of container delete request message.
  Body body = 1;

  // Carries request meta information. Header data is used only to regulate
  // message transport and does not affect request execution.
  frost.fs.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.
  frost.fs.session.RequestVerificationHeader verify_header = 3;
}

// `DeleteResponse` has an empty body because delete operation is asynchronous
// and done via consensus in Inner Ring nodes.
message DeleteResponse {
  // `DeleteResponse` has an empty body because delete operation is asynchronous
  // and done via consensus in Inner Ring nodes.
  message Body {}
  // Body of container delete response message.
  Body body = 1;

  // Carries response meta information. Header data is used only to regulate
  // message transport and does not affect request execution.
  frost.fs.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.
  frost.fs.session.ResponseVerificationHeader verify_header = 3;
}

// Get container structure
message GetRequest {
  // Get container structure request body.
  message Body {
    // Identifier of the container to get
    frost.fs.refs.ContainerID container_id = 1;
  }
  // Body of container get request message.
  Body body = 1;

  // Carries request meta information. Header data is used only to regulate
  // message transport and does not affect request execution.
  frost.fs.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.
  frost.fs.session.RequestVerificationHeader verify_header = 3;
}

// Get container structure
message GetResponse {
  // Get container response body does not have container structure signature. It
  // has been already verified upon container creation.
  message Body {
    // Requested container structure
    Container container = 1;

    // Signature of a stable-marshalled container according to RFC-6979.
    frost.fs.refs.SignatureRFC6979 signature = 2;

    // Session token if the container has been created within the session
    frost.fs.session.SessionToken session_token = 3;
  }
  // Body of container get response message.
  Body body = 1;

  // Carries response meta information. Header data is used only to regulate
  // message transport and does not affect request execution.
  frost.fs.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.
  frost.fs.session.ResponseVerificationHeader verify_header = 3;
}

// List containers
message ListRequest {
  // List containers request body.
  message Body {
    // Identifier of the container owner
    frost.fs.refs.OwnerID owner_id = 1;
  }
  // Body of list containers request message
  Body body = 1;

  // Carries request meta information. Header data is used only to regulate
  // message transport and does not affect request execution.
  frost.fs.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.
  frost.fs.session.RequestVerificationHeader verify_header = 3;
}

// List containers
message ListResponse {
  // List containers response body.
  message Body {
    // List of `ContainerID`s belonging to the requested `OwnerID`
    repeated refs.ContainerID container_ids = 1;
  }

  // Body of list containers response message.
  Body body = 1;

  // Carries response meta information. Header data is used only to regulate
  // message transport and does not affect request execution.
  frost.fs.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.
  frost.fs.session.ResponseVerificationHeader verify_header = 3;
}