arcbox-protocol 0.1.4

// 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);
}

// 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;
}

// 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;
}