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/inventory.proto";
+import "archive_control/v1/job.proto";
+import "archive_control/v1/resource.proto";
+import "archive_control/v1/route.proto";
+import "google/protobuf/timestamp.proto";
+
+message AssignJobCommand {
+  JobDefinition job = 1;
+  uint64 expected_job_revision = 2;
+  uint64 expected_last_event_sequence = 3;
+}
+
+message ExecuteStepCommand {
+  string job_id = 1;
+  uint64 expected_job_revision = 2;
+  JobStepKind step = 3;
+  uint32 attempt = 4;
+  uint64 expected_last_event_sequence = 5;
+}
+
+message CancelJobCommand {
+  string job_id = 1;
+  uint64 expected_job_revision = 2;
+  string reason = 3;
+  uint64 expected_last_event_sequence = 4;
+}
+
+message EnsureRouteCommand {
+  EnsureRouteSpec route = 1;
+}
+
+message RequestJobSnapshotCommand {
+  repeated string job_ids = 1;
+}
+
+message Command {
+  string command_id = 1;
+  google.protobuf.Timestamp created_at = 2;
+  oneof payload {
+    AssignJobCommand assign_job = 10;
+    ExecuteStepCommand execute_step = 11;
+    CancelJobCommand cancel_job = 12;
+    EnsureRouteCommand ensure_route = 13;
+    InventoryQuery inventory_query = 14;
+    RequestJobSnapshotCommand request_job_snapshot = 15;
+  }
+}
+
+enum CommandAckStatus {
+  COMMAND_ACK_STATUS_UNSPECIFIED = 0;
+  COMMAND_ACK_STATUS_ACCEPTED = 1;
+  COMMAND_ACK_STATUS_DUPLICATE = 2;
+  COMMAND_ACK_STATUS_REJECTED = 3;
+}
+
+// CommandAck confirms durable acceptance/rejection, not completion. Completion
+// is reported by JobEvent, InventoryChunk, RouteUpdate, or JobSnapshot.
+message CommandAck {
+  string command_id = 1;
+  CommandAckStatus status = 2;
+  Error error = 3;
+}
+
+enum JobEventType {
+  JOB_EVENT_TYPE_UNSPECIFIED = 0;
+  JOB_EVENT_TYPE_ASSIGNED = 1;
+  JOB_EVENT_TYPE_STEP_STARTED = 2;
+  JOB_EVENT_TYPE_PROGRESS = 3;
+  JOB_EVENT_TYPE_WAITING = 4;
+  JOB_EVENT_TYPE_STALLED = 5;
+  JOB_EVENT_TYPE_STEP_SUCCEEDED = 6;
+  JOB_EVENT_TYPE_COMMITTED = 7;
+  JOB_EVENT_TYPE_CANCELLING = 8;
+  JOB_EVENT_TYPE_ROLLBACK_STARTED = 9;
+  JOB_EVENT_TYPE_ROLLBACK_SUCCEEDED = 10;
+  JOB_EVENT_TYPE_CLEANUP_REQUIRED = 11;
+  JOB_EVENT_TYPE_SUCCEEDED = 12;
+  JOB_EVENT_TYPE_FAILED = 13;
+  JOB_EVENT_TYPE_CANCELLED = 14;
+}
+
+message JobEvent {
+  string event_id = 1;
+  string job_id = 2;
+  uint64 sequence = 3;
+  uint64 job_revision = 4;
+  JobEventType type = 5;
+  JobState state = 6;
+  bool committed = 7;
+  JobProgress progress = 8;
+  Error error = 9;
+  ResourceStateFingerprint observed_resource = 10;
+  Placement observed_placement = 11;
+  google.protobuf.Timestamp occurred_at = 12;
+}
+
+message JobSnapshot {
+  JobRecord job = 1;
+  uint64 last_event_sequence = 2;
+  repeated string in_flight_command_ids = 3;
+}
+
+message ClientStateSnapshot {
+  string snapshot_id = 1;
+  repeated JobSnapshot active_jobs = 2;
+  repeated LocalRoute routes = 3;
+  repeated ServiceHealth services = 4;
+  google.protobuf.Timestamp observed_at = 5;
+}
+
+message RouteUpdate {
+  string command_id = 1;
+  LocalRoute route = 2;
+  RouteVerification verification = 3;
+  Error error = 4;
+  string update_id = 5;
+  // Monotonic for this command_id; duplicate sequences must have identical
+  // content and gaps are reconciled through ClientStateSnapshot.
+  uint64 sequence = 6;
+}
+
+message ProtocolError {
+  Error error = 1;
+  string offending_message_id = 2;
+}