syntax = "proto3";

package gitaly;

import "lint.proto";
import "shared.proto";

option go_package = "gitlab.com/gitlab-org/gitaly/v16/proto/go/gitalypb";

// RefTransaction is a service which provides RPCs to interact with reference
// transactions. Reference transactions are used in the context of Gitaly
// Cluster to ensure that all nodes part of a single transaction perform the
// same change: given a set of changes, the changes are hashed and the hash is
// then voted on.
service RefTransaction {
  option (intercepted) = true;

  // VoteTransaction casts a vote on a transaction to establish whether the
  // node is doing the same change as all the other nodes part of the
  // transaction. This RPC blocks until quorum has been reached, which may be
  // _before_ all nodes have cast a vote.
  //
  // This RPC may return one of the following error codes:
  //
  // - `NotFound` in case the transaction could not be found.
  // - `Canceled` in case the transaction has been canceled before quorum was
  //   reached.
  rpc VoteTransaction (VoteTransactionRequest) returns (VoteTransactionResponse);

  // StopTransaction gracefully stops a transaction. This RPC can be used if
  // only a subset of nodes executes specific code which may cause the
  // transaction to fail. One such example is Git hooks, which only execute on
  // the primary Gitaly noded. Other nodes which vote on this transaction will
  // get a response with the `STOP` state being set.
  //
  // This RPC may return one of the following error codes:
  //
  // - `NotFound` in case the transaction could not be found.
  // - `Canceled` in case the transaction has been canceled before quorum was
  //   reached.
  rpc StopTransaction (StopTransactionRequest) returns (StopTransactionResponse);

}

// VoteTransactionRequest ...
message VoteTransactionRequest {
  // Phase ...
  enum Phase {
    // UNKNOWN_PHASE is the unknown voting phase. This value has been the
    // default because phases have been introduced. Eventually, using this
    // phase will become unsupported.
    UNKNOWN_PHASE = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
    // PREPARED_PHASE is the prepratory phase. The data that is about to change
    // is locked for concurrent modification, but changes have not yet been
    // written to disk.
    PREPARED_PHASE = 1; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
    // COMMITTED_PHASE is the committing phase. Data has been committed to disk
    // and will be visible in all subsequent requests.
    COMMITTED_PHASE  = 2; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
    // SYNCHRONIZED_PHASE is the synchronizing phase. This is used to synchronize nodes with each other on a
    // specific event.
    SYNCHRONIZED_PHASE = 3;  // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
  };

  // repository ...
  Repository repository = 1[(target_repository)=true];
  // transaction_id is the ID of the transaction we're processing.
  uint64 transaction_id = 2;
  // node is the name of the Gitaly node that's voting on a transaction.
  string node = 3;
  // reference_updates_hash is the SHA1 of the references that are to be updated.
  bytes reference_updates_hash = 4;
  // phase is the voting phase.
  Phase phase = 5;
}

// VoteTransactionResponse ...
message VoteTransactionResponse {
  // TransactionState is the outcome of the given transaction telling the client whether the
  // transaction should be committed or rolled back.
  enum TransactionState {
    // COMMIT ...
    COMMIT = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
    // ABORT ...
    ABORT = 1; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
    // STOP ...
    STOP = 2; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
  }

  // state ...
  TransactionState state = 1;
}

// StopTransactionRequest ...
message StopTransactionRequest {
  // repository ...
  Repository repository = 1[(target_repository)=true];
  // transaction_id is the ID of the transaction we're processing.
  uint64 transaction_id = 2;
}

// StopTransactionResponse ...
message StopTransactionResponse {
}
