Git designed for AI agents.
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;
}