backrest/proto/v1/operations.proto

syntax = "proto3";

package v1;

option go_package = "github.com/garethgeorge/backrest/gen/go/v1";

import "v1/restic.proto";
import "v1/config.proto";
import "types/value.proto";

message OperationList {
  repeated Operation operations = 1;
}

// Operation is the basic unit of record in backrest
message Operation {
  // required, primary ID of the operation. ID is sequential based on creation time of the operation.
  int64 id = 1;
  int64 original_id = 13;
  // modno increments with each change to the operation. This supports easy diffing.
  int64 modno = 12;
  // flow id groups operations together, e.g. by an execution of a plan.
  // must be unique within the context of a repo.
  int64 flow_id = 10;
  int64 original_flow_id = 14;
  // repo id is a string identifier for the repo, and repo_guid is the globally unique ID of the repo.
  string repo_id = 2;
  string repo_guid = 15;
  // plan id e.g. a scheduled set of operations (or system) that created this operation.
  string plan_id = 3; 
  // instance ID that the operation is attributed to, not necessarily the same as the instance that created it.
  string instance_id = 11; 
  // original instance guid is the verifiable instance that created the operation. Only set for remote operations created by sync.
  string original_instance_keyid = 16;
  // optional snapshot id if associated with a snapshot.
  string snapshot_id = 8; 
  OperationStatus status = 4;
  // required, unix time in milliseconds of the operation's creation (ID is derived from this)
  int64 unix_time_start_ms = 5; 
  // ptional, unix time in milliseconds of the operation's completion
  int64 unix_time_end_ms = 6;
  // optional, human readable context message, typically an error message.
  string display_message = 7;
  // logref can point to arbitrary logs associated with the operation.
  string logref = 9; 

  oneof op {
    OperationBackup operation_backup = 100;
    OperationIndexSnapshot operation_index_snapshot = 101;
    OperationForget operation_forget = 102;
    OperationPrune operation_prune = 103;
    OperationRestore operation_restore = 104;
    OperationStats operation_stats = 105;
    OperationRunHook operation_run_hook = 106;
    OperationCheck operation_check = 107;
    OperationRunCommand operation_run_command = 108;
  } 
}

// OperationEvent is used in the wireformat to stream operation changes to clients
message OperationEvent {
  oneof event {
    types.Empty keep_alive = 1;
    OperationList created_operations = 2;
    OperationList updated_operations = 3;
    types.Int64List deleted_operations = 4;
  }
}

// OperationEventType indicates whether the operation was created or updated
enum OperationEventType {
  EVENT_UNKNOWN = 0;
  EVENT_CREATED = 1;
  EVENT_UPDATED = 2;
  EVENT_DELETED = 3;
}

enum OperationStatus {
  STATUS_UNKNOWN = 0; // used to indicate that the status is unknown.
  STATUS_PENDING = 1; // used to indicate that the operation is pending.
  STATUS_INPROGRESS = 2; // used to indicate that the operation is in progress.
  STATUS_SUCCESS = 3; // used to indicate that the operation completed successfully.
  STATUS_WARNING = 7; // used to indicate that the operation completed with warnings.
  STATUS_ERROR = 4; // used to indicate that the operation failed.
  STATUS_SYSTEM_CANCELLED = 5; // indicates operation cancelled by the system.
  STATUS_USER_CANCELLED = 6; // indicates operation cancelled by the user.
}

message OperationBackup {
  BackupProgressEntry last_status = 3;
  repeated BackupProgressError errors = 4;
  bool dry_run = 5; // indicates this was a dry run backup (no snapshot created)
}

// OperationIndexSnapshot tracks that a snapshot was detected by backrest. 
message OperationIndexSnapshot {
  ResticSnapshot snapshot = 2; // the snapshot that was indexed.
  bool forgot = 3; // tracks whether this snapshot is forgotten yet.
}

// OperationForget tracks a forget operation.
message OperationForget {
  repeated ResticSnapshot forget = 1;
  RetentionPolicy policy = 2;
}

// OperationPrune tracks a prune operation.
message OperationPrune {
  string output = 1 [deprecated = true]; // output of the prune.
  string output_logref = 2; // logref of the prune output.
}

// OperationCheck tracks a check operation.
message OperationCheck {
  string output = 1 [deprecated = true]; // output of the check operation.
  string output_logref = 2; // logref of the check output.
}

// OperationRunCommand tracks a long running command. Commands are grouped into a flow ID for each session.
message OperationRunCommand {
  string command = 1;
  string output_logref = 2;
  int64 output_size_bytes = 3; // not necessarily authoritative, tracked as an optimization to allow clients to avoid fetching very large outputs.
}

// OperationRestore tracks a restore operation.
message OperationRestore {
  string path = 1; // path in the snapshot to restore.
  string target = 2; // location to restore it to.
  RestoreProgressEntry last_status = 3; // status of the restore.
}

// OperationStats tracks a stats operation.
message OperationStats {
  RepoStats stats = 1;
}

// OperationRunHook tracks a hook that was run.
message OperationRunHook {
  int64 parent_op = 4; // ID of the operation that ran the hook.
  string name = 1; // description of the hook that was run. typically repo/hook_idx or plan/hook_idx.
  string output_logref = 2; // logref of the hook's output. DEPRECATED.
  Hook.Condition condition = 3; // triggering condition of the hook.
}