Crate smolvm_protocol

Expand description

Protocol types for smolvm host-guest communication.

This crate defines the wire protocol for vsock communication between the smolvm host and the guest agent (smolvm-agent).

§Protocol Overview

Communication uses JSON-encoded messages over vsock. Each message is prefixed with a 4-byte big-endian length header.

+----------------+-------------------+
| Length (4 BE)  | JSON payload      |
+----------------+-------------------+

base64_bytes: Serde helper for encoding Vec<u8> as a base64 string in JSON.
cid: vsock CID constants.
error_codes: Error codes for agent responses.
guest_env: Shared environment-variable contract between the host launcher and guest agent.
image_ref: Image reference canonicalization.
ports: Well-known vsock ports.
retry: Retry utilities for transient failure recovery.
secrets: Secret reference types shared across smolvm surfaces.

Envelope: Envelope that wraps any message with an optional trace ID for correlation.
ImageInfo: Image information returned by Query/ListImages.
OverlayInfo: Overlay preparation result.
RegistryAuth: Registry authentication credentials for pulling images.
StorageStatus: Storage status information.

AgentRequest: Agent request types (for image management and OCI operations).
AgentResponse: Agent response types.
DecodeError: Error decoding a wire message.
GuestMessage: Messages from workload VM to host.
HostMessage: Messages from host to workload VM.

AGENT_READY_MARKER: Filename of the virtiofs-visible marker the agent creates when it is ready to accept vsock connections.
FILE_TRANSFER_MAX_TOTAL: Hard ceiling on a single file transfer in either direction.
FILE_WRITE_CHUNK_SIZE: Payload bytes per streaming upload chunk. Deliberately small — equal to FILE_WRITE_SINGLE_SHOT_MAX — so each chunk’s encoded frame (~1.4 MB) fits inside typical kernel Unix-socket send buffers (SO_SNDBUF defaults on the order of 200–256 KiB but can grow). Larger chunks would force write_all to spin waiting for the agent to drain, and any latency spike trips the 10 s write timeout with EAGAIN — exactly the failure David reproduced before this fix landed.
FILE_WRITE_SINGLE_SHOT_MAX: Files at or below this size are written with a single FileWrite message. Larger files must stream via FileWriteBegin + FileWriteChunk so no single frame approaches MAX_FRAME_SIZE (base64 + JSON inflation is ~1.4x).
LAYER_CHUNK_SIZE: Chunk size for streaming layer data (~16 MB raw, ~21 MB as base64 JSON).
MAX_FRAME_SIZE: Maximum frame size (32 MB - layer exports use chunked streaming).
PROTOCOL_VERSION: Protocol version.