arcbox-protocol 0.4.10

// Agent service protocol definitions.
//
// This service runs inside the guest VM and handles requests from the host.

syntax = "proto3";

package arcbox.v1;

import "common.proto";

// AgentService runs inside the guest VM.
service AgentService {
    // Health check.
    rpc Ping(AgentPingRequest) returns (AgentPingResponse);

    // Gets system information.
    rpc GetSystemInfo(Empty) returns (SystemInfo);

    // Ensures guest runtime stack (containerd/dockerd) is ready.
    rpc EnsureRuntime(RuntimeEnsureRequest) returns (RuntimeEnsureResponse);

    // Gets guest runtime stack status.
    rpc GetRuntimeStatus(RuntimeStatusRequest) returns (RuntimeStatusResponse);

    // Starts the native Kubernetes cluster inside the guest.
    rpc StartKubernetes(KubernetesStartRequest) returns (KubernetesStartResponse);

    // Stops the native Kubernetes cluster inside the guest.
    rpc StopKubernetes(KubernetesStopRequest) returns (KubernetesStopResponse);

    // Deletes the native Kubernetes cluster state inside the guest.
    rpc DeleteKubernetes(KubernetesDeleteRequest) returns (KubernetesDeleteResponse);

    // Returns native Kubernetes cluster status from the guest.
    rpc GetKubernetesStatus(KubernetesStatusRequest) returns (KubernetesStatusResponse);

    // Returns kubeconfig content exported from the guest cluster.
    rpc GetKubeconfig(KubernetesKubeconfigRequest) returns (KubernetesKubeconfigResponse);

    // Requests graceful guest shutdown. The agent responds immediately,
    // then performs orderly process teardown and powers off the VM.
    rpc Shutdown(ShutdownRequest) returns (ShutdownResponse);

    // Triggers an immediate fstrim on data mount points to reclaim sparse
    // file space on the host.
    rpc DiskTrim(DiskTrimRequest) returns (DiskTrimResponse);
}

// Ping request.
message AgentPingRequest {
    // Optional payload.
    string message = 1;
    // Host wall-clock time in Unix seconds. Agent sets clock when > 0.
    int64 timestamp_secs = 2;
}

// Ping response.
message AgentPingResponse {
    // Response payload.
    string message = 1;
    // Agent version.
    string version = 2;
}

// System information from the guest.
message SystemInfo {
    // Kernel version.
    string kernel_version = 1;
    // OS name.
    string os_name = 2;
    // OS version.
    string os_version = 3;
    // Architecture.
    string arch = 4;
    // Total memory in bytes.
    uint64 total_memory = 5;
    // Available memory in bytes.
    uint64 available_memory = 6;
    // Number of CPUs.
    uint32 cpu_count = 7;
    // Load average (1, 5, 15 minutes).
    repeated double load_average = 8;
    // Hostname.
    string hostname = 9;
    // Uptime in seconds.
    uint64 uptime = 10;
    // Guest IP addresses (excluding loopback).
    repeated string ip_addresses = 11;
}

// Request to ensure runtime services are available.
message RuntimeEnsureRequest {
    // Whether to attempt starting services when not ready.
    bool start_if_needed = 1;
}

// Response from runtime ensure operation.
message RuntimeEnsureResponse {
    // Whether runtime is ready for Docker API requests.
    bool ready = 1;
    // Runtime endpoint exposed to host proxy.
    string endpoint = 2;
    // Additional status detail.
    string message = 3;
    // Outcome of this ensure call: "started", "reused", or "failed".
    string status = 4;
}

// Request for runtime status.
message RuntimeStatusRequest {}

// Runtime status report.
message RuntimeStatusResponse {
    // Whether containerd socket is reachable.
    bool containerd_ready = 1;
    // Whether Docker socket is reachable.
    bool docker_ready = 2;
    // Runtime endpoint exposed to host proxy.
    string endpoint = 3;
    // Human-readable detail for diagnostics.
    string detail = 4;
    // Per-service status entries for fine-grained observability.
    repeated ServiceStatus services = 5;
}

// Request to trigger an immediate fstrim on data mount points.
message DiskTrimRequest {}

// Response from a disk trim operation.
message DiskTrimResponse {
    // Human-readable result summary (e.g. bytes trimmed per mount).
    string result = 1;
}

// Notification that a container's published port bindings changed.
message PortBindingsChanged {
    // Container ID.
    string container_id = 1;
    // Current published bindings from dockerd inspect output.
    repeated PortBinding bindings = 2;
}

// Notification that a container no longer has active published ports.
message PortBindingsRemoved {
    // Container ID.
    string container_id = 1;
}

// Individual service status within the guest runtime stack.
message ServiceStatus {
    // Service name (e.g. "containerd", "dockerd", "runc").
    string name = 1;
    // Service status: "ready", "not_ready", or "error".
    string status = 2;
    // Human-readable detail for diagnostics (error message, socket path, etc.).
    string detail = 3;
}

// Request to start the native Kubernetes cluster.
message KubernetesStartRequest {}

// Response from starting the native Kubernetes cluster.
message KubernetesStartResponse {
    // Whether the cluster process is running.
    bool running = 1;
    // Whether the Kubernetes API endpoint is reachable.
    bool api_ready = 2;
    // API endpoint exposed to the host.
    string endpoint = 3;
    // Human-readable detail for diagnostics.
    string detail = 4;
}

// Request to stop the native Kubernetes cluster.
message KubernetesStopRequest {}

// Response from stopping the native Kubernetes cluster.
message KubernetesStopResponse {
    // Whether the cluster is fully stopped.
    bool stopped = 1;
    // Human-readable detail for diagnostics.
    string detail = 2;
}

// Request to delete the native Kubernetes cluster state.
message KubernetesDeleteRequest {}

// Response from deleting the native Kubernetes cluster state.
message KubernetesDeleteResponse {
    // Human-readable detail for diagnostics.
    string detail = 1;
}

// Request for Kubernetes cluster status.
message KubernetesStatusRequest {}

// Runtime status report for the native Kubernetes cluster.
message KubernetesStatusResponse {
    // Whether the cluster process is running.
    bool running = 1;
    // Whether the Kubernetes API endpoint is reachable.
    bool api_ready = 2;
    // API endpoint exposed to the host.
    string endpoint = 3;
    // Human-readable detail for diagnostics.
    string detail = 4;
    // Per-service status entries for fine-grained observability.
    repeated ServiceStatus services = 5;
}

// Request for managed kubeconfig content.
message KubernetesKubeconfigRequest {}

// Managed kubeconfig payload exported from the guest cluster.
message KubernetesKubeconfigResponse {
    // Raw kubeconfig YAML.
    string kubeconfig = 1;
    // ArcBox-managed context name.
    string context_name = 2;
    // API endpoint embedded in the exported kubeconfig.
    string endpoint = 3;
}

// Graceful shutdown request from host.
message ShutdownRequest {
    // Grace period in seconds for processes to exit after SIGTERM.
    // 0 means use the agent's default (currently 25 seconds).
    uint32 timeout_seconds = 1;
}

// Shutdown acknowledgement. Sent before the agent begins teardown.
message ShutdownResponse {
    // Always true when the agent accepts the request.
    bool accepted = 1;
}

// Test-only: read a file through `mmap(MAP_SHARED)` to force the guest
// kernel to issue `FUSE_SETUPMAPPING` and exercise the VirtioFS DAX path.
// Used by the ABX-362 E2E harness. Not intended for production callers.
message MmapReadFileRequest {
    // Absolute guest path (typically a file inside a VirtioFS mount).
    string path = 1;
    // Byte offset within the file.
    uint64 offset = 2;
    // Number of bytes to read. Rounded up to a page boundary internally;
    // the response trims back to the requested length.
    uint64 length = 3;
}

// Response to `MmapReadFileRequest`.
message MmapReadFileResponse {
    // Bytes read, trimmed to the originally requested length.
    bytes data = 1;
    // Number of bytes actually read (<= length). Short if file smaller
    // than offset+length.
    uint64 bytes_read = 2;
}