Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

3.5 KB
Raw Blame
syntax = "proto3";

package fastpath.v2;

option go_package = "github.com/alibaba/opensandbox/ingress/pkg/fastpath/v2;fastpathv2";

// This is the lifecycle and ResolveEndpoint subset of opensandbox-group/fast-sandbox
// FastPath v2. Field numbers and the fully-qualified RPC names must remain
// wire-compatible with that source. The lifecycle subset is exercised against
// the server's generated Python bindings (see pkg/fastpath/v2/testdata).
service FastPathService {
  rpc GetSandbox(GetSandboxRequest) returns (GetSandboxResponse);
  rpc ResumeSandbox(ResumeSandboxRequest) returns (ResumeSandboxResponse);
  rpc ResolveEndpoint(ResolveEndpointRequest) returns (ResolveEndpointResponse);
}

message NamespacedName {
  string namespace = 1;
  string name = 2;
}

message SandboxReference {
  NamespacedName namespaced_name = 2;
  string expected_uid = 3;
}

enum RuntimeState {
  RUNTIME_STATE_UNSPECIFIED = 0;
  RUNTIME_STATE_UNKNOWN = 1;
  RUNTIME_STATE_PENDING = 2;
  RUNTIME_STATE_CREATING = 3;
  RUNTIME_STATE_READY = 4;
  RUNTIME_STATE_STOPPING = 5;
  RUNTIME_STATE_STOPPED = 6;
  RUNTIME_STATE_FAILED = 7;
  RUNTIME_STATE_UNAVAILABLE = 8;
  RUNTIME_STATE_PAUSING = 9;
  RUNTIME_STATE_PAUSED = 10;
  RUNTIME_STATE_RESUMING = 11;
}

enum SandboxState {
  SANDBOX_STATE_UNSPECIFIED = 0;
  SANDBOX_STATE_RUNNING = 1;
  SANDBOX_STATE_PAUSED = 2;
}

enum DataPlaneState {
  DATA_PLANE_STATE_UNSPECIFIED = 0;
  DATA_PLANE_STATE_UNKNOWN = 1;
  DATA_PLANE_STATE_PENDING = 2;
  DATA_PLANE_STATE_PUBLISHING = 3;
  DATA_PLANE_STATE_READY = 4;
  DATA_PLANE_STATE_DRAINING = 5;
  DATA_PLANE_STATE_FAILED = 6;
  DATA_PLANE_STATE_UNAVAILABLE = 7;
}

message SandboxIdentity {
  string uid = 1;
  string name = 2;
  string namespace = 3;
}

message RuntimeInfo {
  RuntimeState state = 1;
}

message DataPlaneInfo {
  DataPlaneState state = 1;
}

message CheckpointInfo {
  string checkpoint_id = 1;
  string manifest_ref = 2;
  string artifact_digest = 3;
  int64 size_bytes = 4;
  int64 paused_unix_seconds = 5;
  string fastlet_name = 6;
}

message SandboxInfo {
  SandboxIdentity identity = 1;
  int64 applied_generation = 2;
  RuntimeInfo runtime = 3;
  DataPlaneInfo data_plane = 4;
  // Tags 5 (infra_components) and 6 (action_bindings) exist in the upstream
  // schema; reserved so a future subset field cannot silently claim them.
  reserved 5, 6;
  bool ready = 7;
  SandboxState state = 8;
  CheckpointInfo checkpoint = 9;
}

message GetSandboxRequest {
  SandboxReference sandbox = 1;
  int64 expected_generation = 2;
}

message GetSandboxResponse {
  SandboxInfo sandbox = 1;
  int64 generation = 2;
}

message ResumeSandboxRequest {
  string request_id = 1;
  SandboxReference sandbox = 2;
  int64 expected_generation = 3;
  string expected_checkpoint_id = 4;
}

message ResumeSandboxResponse {
  SandboxInfo sandbox = 1;
  int64 generation = 2;
}

message EndpointTarget {
  oneof target {
    string component_name = 1;
    uint32 port = 2;
  }
}

enum EndpointAccessMode {
  CENTRAL_PROXY = 0;
  DIRECT_FASTLET_PROXY = 1;
}

message ResolveEndpointRequest {
  SandboxReference sandbox = 1;
  EndpointTarget target = 2;
  EndpointAccessMode access_mode = 3;
  int64 expected_generation = 4;
}

message ResolvedEndpoint {
  string component_name = 1;
  string protocol = 2;
  uint32 port = 3;
}

message ResolveEndpointResponse {
  string sandbox_uid = 1;
  ResolvedEndpoint endpoint = 2;
  string proxy_endpoint = 3;
  map<string, string> required_headers = 4;
  int64 route_generation = 5;
  int64 expires_at_unix_seconds = 6;
}