Skip to content

Git designed for AI agents.

9.9 KB
Raw Blame
syntax = "proto3";

package gitaly;

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

option go_package = "github.com/feder-cr/git-ai/proto/go/gitalypb";

// StorageCoreService administers the Graft storage core: the repository state
// kept in a strongly consistent database plus object storage, with the local
// git repositories of the nodes as caches (doc/graft/STORAGE.md). Its RPCs are
// for operators; agents may not call them.
service StorageCoreService {

  // ImportRepository registers a local repository that the storage core does
  // not know yet: its changelog history and reviews with the registration,
  // then one pack with every object reachable from its references, then
  // changeset 1 with all its references. A failed or interrupted import is
  // resumed by calling it again. On a repository that is already tracked it
  // brings the changelog entries and reviews written in the local files since
  // the import into the database (the step of switching from shadow to
  // authoritative mode) and leaves the references alone. It fails with
  // FailedPrecondition when the storage core is off.
  rpc ImportRepository(ImportRepositoryRequest) returns (ImportRepositoryResponse) {
    option (op_type) = {
      op: MUTATOR
    };
  }

  // GetStorageState returns how the storage core sees the repository and how
  // far this node's local copy is.
  rpc GetStorageState(GetStorageStateRequest) returns (GetStorageStateResponse) {
    option (op_type) = {
      op: ACCESSOR
    };
  }

  // VerifyRepository compares the local references with the database and
  // optionally checks the connectivity of the local repository. In
  // authoritative mode the local repository is caught up first.
  rpc VerifyRepository(VerifyRepositoryRequest) returns (VerifyRepositoryResponse) {
    option (op_type) = {
      op: ACCESSOR
    };
  }

  // CreateCheckpoint builds a checkpoint of the repository at its current
  // database head and records it: one pack of every object reachable from the
  // references at the head, with the reference snapshot, so that hydration
  // starts from it and garbage collection can delete the packs it covers. It
  // fails with FailedPrecondition outside authoritative mode.
  rpc CreateCheckpoint(CreateCheckpointRequest) returns (CreateCheckpointResponse) {
    option (op_type) = {
      op: MUTATOR
    };
  }

  // CollectGarbage deletes the packs of the repository that no reader needs
  // any more: the objects no row references once they were observed so at
  // least gc_grace ago, the changeset packs covered by a checkpoint at least
  // gc_grace old, and the checkpoints that one supersedes. It touches no other
  // repository. It fails with FailedPrecondition when the storage core is off,
  // or while another maintenance of the repository holds its lease.
  rpc CollectGarbage(CollectGarbageRequest) returns (CollectGarbageResponse) {
    option (op_type) = {
      op: MUTATOR
    };
  }

  // CollectRemovedRepositories deletes every object of the repositories of a
  // storage that were removed at least gc_grace ago. It first reconciles the
  // bucket: a repository ID with objects and neither a row nor a tombstone
  // gets a tombstone. It fails with FailedPrecondition when the storage core
  // is off.
  rpc CollectRemovedRepositories(CollectRemovedRepositoriesRequest) returns (CollectRemovedRepositoriesResponse) {
    option (op_type) = {
      op:          MUTATOR
      scope_level: STORAGE
    };
  }
}

// ImportRepositoryRequest is the request of ImportRepository.
message ImportRepositoryRequest {
  // repository is the local repository to import.
  Repository repository = 1 [(target_repository)=true];
}

// ImportRepositoryResponse is the response of ImportRepository.
message ImportRepositoryResponse {
  // sequence is the changeset sequence of the import (1).
  uint64 sequence = 1;
  // references is the number of references imported, HEAD included.
  uint32 references = 2;
  // pack_bytes is the size of the uploaded pack.
  int64 pack_bytes = 3;
  // changelog_entries is the number of changelog entries imported.
  uint32 changelog_entries = 4;
  // reviews is the number of reviews imported.
  uint32 reviews = 5;
}

// GetStorageStateRequest is the request of GetStorageState.
message GetStorageStateRequest {
  // repository is the repository to describe.
  Repository repository = 1 [(target_repository)=true];
}

// GetStorageStateResponse is the response of GetStorageState.
message GetStorageStateResponse {
  // mode is the storage core mode of this node: "off", "shadow" or
  // "authoritative".
  string mode = 1;
  // tracked is true when the database knows the repository.
  bool tracked = 2;
  // repository_id is the database ID of the repository (0 when untracked).
  int64 repository_id = 3;
  // head_sequence is the sequence of the repository's last changeset.
  uint64 head_sequence = 4;
  // applied_sequence is how far this node's local copy is; 0 when it has no
  // watermark (shadow mode, or never synchronized).
  uint64 applied_sequence = 5;
  // node_id is this node's name in the database.
  string node_id = 6;
}

// VerifyRepositoryRequest is the request of VerifyRepository.
message VerifyRepositoryRequest {
  // repository is the repository to verify.
  Repository repository = 1 [(target_repository)=true];
  // check_connectivity also runs a connectivity check of the local repository.
  bool check_connectivity = 2;
}

// VerifyRepositoryResponse is the response of VerifyRepository.
message VerifyRepositoryResponse {
  // ReferenceDivergence is a reference whose local value differs from the
  // database.
  message ReferenceDivergence {
    // reference is the fully qualified reference name (or HEAD).
    bytes reference = 1;
    // local_target is the local value: a hex object ID, "ref:<name>" for a
    // symbolic reference, empty when the reference is absent locally.
    string local_target = 2;
    // database_target is the database value, in the same format.
    string database_target = 3;
  }

  // head_sequence is the database sequence the references were compared at.
  uint64 head_sequence = 1;
  // divergences lists every reference that differs; empty when consistent.
  repeated ReferenceDivergence divergences = 2;
  // connectivity_ok is true when the connectivity check ran and passed.
  bool connectivity_ok = 3;
  // connectivity_error describes a failed connectivity check.
  string connectivity_error = 4;
}

// CreateCheckpointRequest is the request of CreateCheckpoint.
message CreateCheckpointRequest {
  // repository is the repository to checkpoint.
  Repository repository = 1 [(target_repository)=true];
}

// CreateCheckpointResponse is the response of CreateCheckpoint.
message CreateCheckpointResponse {
  // checkpoint_sequence is the changeset sequence the checkpoint is at; 0 when
  // the repository has no object to consolidate (every reference is symbolic).
  uint64 checkpoint_sequence = 1;
  // created is false when a checkpoint at the head existed already.
  bool created = 2;
  // pack_bytes is the size of the checkpoint's pack.
  int64 pack_bytes = 3;
  // references is the number of references in the checkpoint's snapshot.
  uint32 references = 4;
}

// CollectGarbageRequest is the request of CollectGarbage.
message CollectGarbageRequest {
  // repository is the repository whose packs are collected.
  Repository repository = 1 [(target_repository)=true];
  // dry_run reports what would be deleted and changes nothing.
  bool dry_run = 2;
}

// CollectGarbageResponse is the response of CollectGarbage.
message CollectGarbageResponse {
  // boundary is the sequence of the newest checkpoint at least gc_grace old;
  // 0 when there is none.
  uint64 boundary = 1;
  // covered_deleted is the number of changeset packs covered by the boundary.
  uint32 covered_deleted = 2;
  // checkpoints_dropped is the number of checkpoints superseded by the boundary.
  uint32 checkpoints_dropped = 3;
  // orphans_deleted is the number of unreferenced objects observed at least
  // gc_grace ago.
  uint32 orphans_deleted = 4;
  // orphans_observed is the number of unreferenced objects seen for the first
  // time.
  uint32 orphans_observed = 5;
  // orphans_in_grace is the number of unreferenced objects observed less than
  // gc_grace ago.
  uint32 orphans_in_grace = 6;
  // packs_deleted is the number of objects deleted (to delete in a dry run).
  uint32 packs_deleted = 7;
  // bytes_reclaimed is the size of those objects.
  int64 bytes_reclaimed = 8;
  // dry_run tells that nothing was deleted or recorded.
  bool dry_run = 9;
}

// CollectRemovedRepositoriesRequest is the request of
// CollectRemovedRepositories.
message CollectRemovedRepositoriesRequest {
  // storage_name is the storage whose removed repositories are collected.
  string storage_name = 1 [(storage)=true];
  // dry_run reports what would be deleted and changes nothing.
  bool dry_run = 2;
}

// CollectRemovedRepositoriesResponse is the response of
// CollectRemovedRepositories.
message CollectRemovedRepositoriesResponse {
  // repositories is the number of removed repositories whose objects were
  // deleted (to delete in a dry run).
  uint32 repositories = 1;
  // packs_deleted is the number of objects deleted.
  uint32 packs_deleted = 2;
  // bytes_reclaimed is the size of those objects.
  int64 bytes_reclaimed = 3;
  // dry_run tells that nothing was deleted or recorded.
  bool dry_run = 4;
  // leaks_found is the number of repository IDs the reconciliation found with
  // objects in the bucket and neither a row nor a tombstone (a row deleted
  // without one).
  uint32 leaks_found = 5;
  // leaks_tombstoned is the number of tombstones the reconciliation recorded
  // for them; their objects are deleted once the tombstone is gc_grace old.
  uint32 leaks_tombstoned = 6;
  // ids_ahead_of_allocator is the number of repository IDs above the
  // database's allocator that have objects in the bucket (a database restored
  // from an older backup). They are never touched.
  uint32 ids_ahead_of_allocator = 7;
}