//  Copyright 2026 Google LLC
//
//  Licensed under the Apache License, Version 2.0 (the "License");
//  you may not use this file except in compliance with the License.
//  You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.

syntax = "proto3";

package ateom;

option go_package = "github.com/agent-substrate/substrate/proto/ateompb";

// Ateom is the interface to control a single gVisor (or, in the future microVM)
// guest inside a worker pod.
//
// Each ateom server has two main states, "available" and "executing".
//
// When the ateom is "available", the substrate control plane is free to either
// boot a new workload (using RunWorkload), or restore an existing workload from
// a checkpoint (using RestoreWorkload).  These calls move the ateom into
// "executing" state.
//
// When the ateom is "executing", the substrate control plane can checkpoint the
// running workload (with CheckpointWorkload).  This moves the ateom back to
// "free" state.
service Ateom {
  // RunWorkload tells ateom to begin running a new workload (one or more
  // containers, potentially with shared filesystems).
  rpc RunWorkload(RunWorkloadRequest) returns (RunWorkloadResponse) {}

  // CheckpointWorkload tells ateom to save the current state of the running
  // workload to object storage, and then completely reset itself to a blank
  // state (back to "available" state.)
  rpc CheckpointWorkload(CheckpointWorkloadRequest) returns (CheckpointWorkloadResponse) {}

  // RestoreWorkload restores a workload from checkpoint that was previously
  // written by CheckpointWorkload.  Ateom will handle downloading the correct
  // gVisor / runsc version to match the checkpoint.
  rpc RestoreWorkload(RestoreWorkloadRequest) returns (RestoreWorkloadResponse) {}
}

message RunWorkloadRequest {
  string actor_template_namespace = 1;
  string actor_template_name      = 2;
  string actor_id                 = 3;

  string runsc_path = 4;

  WorkloadSpec spec = 5;
}

// WorkloadSpec parallels Pod, but with far fewer configurable fields.
message WorkloadSpec {
  repeated Container containers = 1;
}

message Container {
  string name = 1;
}

message RunWorkloadResponse {
}

message CheckpointWorkloadRequest {
  string actor_template_namespace = 1;
  string actor_template_name      = 2;
  string actor_id                 = 3;

  string runsc_path = 4;

  WorkloadSpec spec = 5;

  // An object storage URI prefix below which the checkpoint data will be
  // stored.
  //
  // The structure of the checkpoint should generally be treated as opaque. For
  // gVisor, the checkpoint consists of a checkpoint.img file that contains the
  // memory, sentry state, and filesystem deltas.
  //
  // For example: "gs://bucket/actors/1234/snapshots/5678/"
  string snapshot_uri_prefix = 6;
}

message CheckpointWorkloadResponse {

}

message RestoreWorkloadRequest {
  string actor_template_namespace = 1;
  string actor_template_name      = 2;
  string actor_id                 = 3;

  string runsc_path = 4;

  WorkloadSpec spec = 5;

  // The object storage URI prefix of the snapshot to restore.
  string snapshot_uri_prefix = 6;
}

message RestoreWorkloadResponse {

}
