visor/pkg/shim/v1/taskserver/task_server.proto

// Copyright 2026 The gVisor Authors.
//
// 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 gvisor.task;

option go_package = "gvisor.task.v1.Task";

message Debug {
  string debug_log = 1;
  int32 debug_log_fd = 2;
}

// CheckpointRequest covers both standard and FS checkpoint options used by the
// agent.
message CheckpointRequest {
  string id = 1;
  string image_path = 2;
  bool direct = 3;
  bool leave_running = 4;
  bool fs_checkpoint =
      5;  // true for fscheckpoint, false for standard checkpoint

  // Standard checkpoint options
  string compression = 6;
  bool exclude_committed_zero_pages = 7;
  string save_restore_exec_argv = 8;
  string save_restore_exec_timeout = 9;
  string cuda_checkpoint_path = 10;

  // Debugging
  Debug debug = 11;

  // Additional flags from runsc checkpoint
  bool cuda_checkpoint_sequential = 12;
  string work_path = 13;

  // Flags from runsc fscheckpoint
  string fs_path = 14;
}

message CheckpointResponse {}

// WaitRequest supports waiting for different lifecycle events.
message WaitRequest {
  string id = 1;
  enum WaitType {
    UNKNOWN = 0;
    CHECKPOINT = 1;
    RESTORE = 2;
    FSCHECKPOINT = 3;
    FSRESTORE = 4;
  }
  WaitType wait_type = 2;

  // Debugging
  Debug debug = 3;

  // Process waiting flags
  int32 pid = 4;
  int32 root_pid = 5;
}

message WaitResponse {
  int32 exit_status = 1;
}

// StateRequest/Response for container status checks.
message StateRequest {
  string id = 1;

  // Debugging
  Debug debug = 2;
}

message StateResponse {
  string id = 1;
  string state = 2;  // e.g., "running", "stopped"
  int32 pid = 3;
}

message VersionRequest {}

message VersionResponse {
  string version = 1;
}

service TaskService {
  // Checkpoint triggers a memory or rootfs checkpoint for the container.
  rpc Checkpoint(CheckpointRequest) returns (CheckpointResponse);
  // Wait blocks until a lifecycle event (checkpoint, restore, etc.) completes.
  rpc Wait(WaitRequest) returns (WaitResponse);
  // State returns the current status of the container.
  rpc State(StateRequest) returns (StateResponse);
  // Version returns the version info of the runsc binary.
  rpc Version(VersionRequest) returns (VersionResponse);
}