arcbox-protocol 0.8.2

Protocol definitions for ArcBox (ttrpc/protobuf)
docs.rs failed to build arcbox-protocol-0.8.2
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Visit the last successful build: arcbox-protocol-0.0.1-alpha.1

arcbox-protocol

Protocol Buffer message and service definitions for ArcBox.

Overview

This crate provides generated Rust types for arcbox.v1 protobuf schemas, re-exported through:

  • arcbox_protocol::v1::* (canonical)
  • compatibility modules (arcbox_protocol::machine, ::container, ::agent, etc.)
  • selected crate-root re-exports for convenience

Modules

Module Source proto Description
common common.proto Shared types (Empty, Mount, PortBinding, ...)
machine machine.proto Machine lifecycle + agent passthrough requests
container container.proto Container lifecycle and exec messages
image image.proto Image pull/list/inspect/remove messages
agent agent.proto Guest agent health/runtime messages
api api.proto Network/system/volume/migration API messages

Generated code

build.rs writes prost output into src/generated/ (not OUT_DIR) and runs rustfmt on it; the result is committed. After any .proto edit, rebuild (cargo build -p arcbox-protocol) and commit the regenerated files in the same change. A new .proto file must be registered in both arcbox-protocol/build.rs and arcbox-grpc/build.rs.

Protocol evolution

The daemon and the in-VM arcbox-agent are distributed separately, so a running guest may speak an older schema than the host. Two mechanisms keep skew safe:

  • Additive-only schemas. CI runs buf breaking against master (.github/workflows/ci.yml): never remove or renumber fields; use reserved when retiring them.
  • Boot handshake. The agent reports AgentPingResponse.protocol_version (arcbox_constants::wire::AGENT_PROTOCOL_VERSION); the host rejects agents below MIN_AGENT_PROTOCOL_VERSION before watching readiness. Bump the protocol version when a change alters the meaning of existing messages; purely additive, ignorable fields don't need one.

Usage

PrepareMigrationResponse.replacements always contains the target replacement summary, including when empty. For a runnable prepare, the summary describes the plan saved under plan_id. Before RunMigration, clients must compare the target names with the user's confirmation. If the summary is absent, the daemon cannot provide this check. The full plan, including container environments, remains available only for an explicit dry run.

use arcbox_protocol::{CreateContainerRequest, PullImageRequest};

let create = CreateContainerRequest {
    name: "demo".to_string(),
    image: "alpine:latest".to_string(),
    cmd: vec!["echo".to_string(), "hello".to_string()],
    tty: false,
    stdin_open: false,
    ..Default::default()
};

let pull = PullImageRequest {
    reference: "nginx:latest".to_string(),
    ..Default::default()
};

assert_eq!(create.image, "alpine:latest");
assert_eq!(pull.reference, "nginx:latest");

License

MIT OR Apache-2.0