syntax = "proto3";

package gitaly;

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

option go_package = "gitlab.com/gitlab-org/gitaly/v15/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);

}

// This comment is left unintentionally blank.
message VoteTransactionRequest {
  // This comment is left unintentionally blank.
  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
  };

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

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

  // This comment is left unintentionally blank.
  TransactionState state = 1;
}

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

// This comment is left unintentionally blank.
message StopTransactionResponse {
}