Define archive control v1 protocol

2026-07-22 11:59:57 +00:00
commit 7652262b4c
25 changed files with 1333 additions and 0 deletions
@@ -0,0 +1,130 @@
+syntax = "proto3";
+
+package archive_control.v1;
+
+import "archive_control/v1/common.proto";
+import "archive_control/v1/resource.proto";
+import "google/protobuf/timestamp.proto";
+
+enum JobOperation {
+  JOB_OPERATION_UNSPECIFIED = 0;
+  JOB_OPERATION_ARCHIVE = 1;
+  JOB_OPERATION_UNARCHIVE = 2;
+  JOB_OPERATION_EVICT_CACHE = 3;
+}
+
+enum JobState {
+  JOB_STATE_UNSPECIFIED = 0;
+  JOB_STATE_QUEUED = 1;
+  JOB_STATE_PREPARING = 2;
+  JOB_STATE_RUNNING = 3;
+  JOB_STATE_WAITING = 4;
+  JOB_STATE_STALLED = 5;
+  JOB_STATE_CANCELLING = 6;
+  JOB_STATE_ROLLING_BACK = 7;
+  JOB_STATE_CLEANUP_REQUIRED = 8;
+  JOB_STATE_SUCCEEDED = 9;
+  JOB_STATE_FAILED = 10;
+  JOB_STATE_CANCELLED = 11;
+}
+
+enum JobStepKind {
+  JOB_STEP_KIND_UNSPECIFIED = 0;
+  JOB_STEP_KIND_ROUTE_SETUP = 1;
+  JOB_STEP_KIND_PREFLIGHT = 2;
+  JOB_STEP_KIND_SOURCE_STAGE = 3;
+  JOB_STEP_KIND_SYNCTHING_TRANSFER = 4;
+  JOB_STEP_KIND_TARGET_MATERIALIZE = 5;
+  JOB_STEP_KIND_QB_VERIFY = 6;
+  JOB_STEP_KIND_STAGING_CLEANUP = 7;
+  JOB_STEP_KIND_VERIFY_ARCHIVE_COVERAGE = 8;
+  JOB_STEP_KIND_QB_REMOVE_ENTRY = 9;
+  JOB_STEP_KIND_SAFE_FILE_UNLINK = 10;
+  JOB_STEP_KIND_ROLLBACK = 11;
+}
+
+enum StepState {
+  STEP_STATE_UNSPECIFIED = 0;
+  STEP_STATE_NOT_STARTED = 1;
+  STEP_STATE_QUEUED = 2;
+  STEP_STATE_RUNNING = 3;
+  STEP_STATE_WAITING = 4;
+  STEP_STATE_STALLED = 5;
+  STEP_STATE_SUCCEEDED = 6;
+  STEP_STATE_FAILED = 7;
+  STEP_STATE_CANCELLED = 8;
+}
+
+message TransferJobSpec {
+  string source_client_id = 1;
+  string target_client_id = 2;
+  string route_id = 3;
+  SelectionSet requested_files = 4;
+  ResourceStateFingerprint source_fingerprint = 5;
+  ResourceStateFingerprint target_baseline_fingerprint = 6;
+  // Absent for a new target placement. Presence distinguishes an absent
+  // placement from an existing placement whose generation is invalidly zero.
+  optional uint64 expected_target_placement_generation = 7;
+  SelectionSet target_baseline_files = 8;
+  SelectionSet transfer_delta_files = 9;
+  uint64 requested_logical_bytes = 10;
+  uint64 transfer_delta_logical_bytes = 11;
+}
+
+message ArchiveCoverage {
+  string archive_client_id = 1;
+  SelectionSet covered_files = 2;
+  uint64 placement_generation = 3;
+  ResourceStateFingerprint fingerprint = 4;
+}
+
+message EvictionJobSpec {
+  string cache_client_id = 1;
+  SelectionSet files_to_evict = 2;
+  uint64 cache_placement_generation = 3;
+  ResourceStateFingerprint cache_fingerprint = 4;
+  repeated ArchiveCoverage archive_coverage = 5;
+}
+
+// JobDefinition is immutable after acceptance. Runtime state and calculated
+// transfer deltas belong in JobRecord and TransferManifest.
+message JobDefinition {
+  string job_id = 1;
+  string idempotency_key = 2;
+  JobOperation operation = 3;
+  ResourceId resource_id = 4;
+  string resource_display_name = 5;
+  google.protobuf.Timestamp created_at = 6;
+  oneof spec {
+    TransferJobSpec transfer = 10;
+    EvictionJobSpec eviction = 11;
+  }
+}
+
+message JobProgress {
+  JobStepKind step = 1;
+  uint32 display_step_number = 2;
+  uint32 display_step_total = 3;
+  StepState state = 4;
+  double fraction_complete = 5;
+  uint64 bytes_complete = 6;
+  uint64 bytes_total = 7;
+  double approximate_bytes_per_second = 8;
+  string detail = 9;
+  google.protobuf.Timestamp last_progress_at = 10;
+  // Weighted progress across all visible steps. This remains available while
+  // a job is waiting or stalled; fraction_complete is for the current step.
+  double overall_fraction_complete = 11;
+}
+
+message JobRecord {
+  JobDefinition definition = 1;
+  JobState state = 2;
+  bool committed = 3;
+  uint64 revision = 4;
+  JobProgress progress = 5;
+  Error error = 6;
+  google.protobuf.Timestamp updated_at = 7;
+  google.protobuf.Timestamp committed_at = 8;
+  google.protobuf.Timestamp finished_at = 9;
+}