syntax = "proto3";

package frostfs.v2.apemanager;

import "ape/types.proto";
import "session/types.proto";

option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/apemanager/grpc;apemanager";

// `APEManagerService` provides API to manage rule chains within sidechain's
// `Policy` smart contract.
service APEManagerService {
  // Add a rule chain for a specific target to `Policy` smart contract.
  //
  // Statuses:
  // - **OK** (0, SECTION_SUCCESS): \
  //   the chain has been successfully added;
  // - Common failures (SECTION_FAILURE_COMMON);
  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
  //   container (as target) not found;
  // - **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \
  //   the operation is denied by the service.
  rpc AddChain(AddChainRequest) returns (AddChainResponse);

  // Remove a rule chain for a specific target from `Policy` smart contract.
  // RemoveChain is an idempotent operation: removal of non-existing rule chain
  // also means success.
  //
  // Statuses:
  // - **OK** (0, SECTION_SUCCESS): \
  //   the chain has been successfully removed;
  // - Common failures (SECTION_FAILURE_COMMON);
  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
  //   container (as target) not found;
  // - **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \
  //   the operation is denied by the service.
  rpc RemoveChain(RemoveChainRequest) returns (RemoveChainResponse);

  // List chains defined for a specific target from `Policy` smart contract.
  //
  // Statuses:
  // - **OK** (0, SECTION_SUCCESS): \
  //   chains have been successfully listed;
  // - Common failures (SECTION_FAILURE_COMMON);
  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
  //   container (as target) not found;
  // - **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \
  //   the operation is denied by the service.
  rpc ListChains(ListChainsRequest) returns (ListChainsResponse);
}

message AddChainRequest {
  message Body {
    // A target for which a rule chain is added.
    frostfs.v2.ape.ChainTarget target = 1;

    // The chain to set for the target.
    frostfs.v2.ape.Chain chain = 2;
  }

  // The request's body.
  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;
}

message AddChainResponse {
  message Body {
    // Chain ID assigned for the added rule chain.
    // If chain ID is left empty in the request, then
    // it will be generated.
    bytes chain_id = 1;
  }

  // The response's body.
  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;
}

message RemoveChainRequest {
  message Body {
    // Target for which a rule chain is removed.
    frostfs.v2.ape.ChainTarget target = 1;

    // Chain ID assigned for the rule chain.
    bytes chain_id = 2;
  }

  // The request's body.
  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;
}

message RemoveChainResponse {
  // Since RemoveChain is an idempotent operation, then the only indicator that
  // operation could not be performed is an error returning to a client.
  message Body {}

  // The response's body.
  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;
}

message ListChainsRequest {
  message Body {
    // Target for which rule chains are listed.
    frostfs.v2.ape.ChainTarget target = 1;
  }

  // The request's body.
  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;
}

message ListChainsResponse {
  message Body {
    // The list of chains defined for the reqeusted target.
    repeated frostfs.v2.ape.Chain chains = 1;
  }

  // The response's body.
  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;
}