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;
}