Crate smolvm_protocol 

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      |
+----------------+-------------------+

Re-exports

pub use credentials::CredentialBinding;

pub use credentials::CredentialPolicy;

pub use image_ref::image_repo;

pub use image_ref::normalize_image_ref;

pub use intercept::InterceptEndpoint;

pub use secrets::SecretRef;

pub use secrets::SecretSourceKind;

Modules

base64_bytes

Serde helper for encoding Vec<u8> as a base64 string in JSON.

cid

vsock CID constants.

credentials

Credential policy: which credential bindings a machine may use, and where.

error_codes

Error codes for agent responses.

forkpoint

Stable guest paths used to coordinate a live branch.

fsnotify_mask

fsnotify event masks, mirroring the kernel’s FS_* bits in include/linux/fsnotify_backend.h. Shared by the host watcher (which maps a host filesystem event to one of these) and the guest agent (which forwards the raw bits to /proc/smolvm-fsnotify). Only the subset relevant to file-watching tools is defined.

guest_env

Shared environment-variable contract between the host launcher and guest agent.

image_ref

Image reference canonicalization.

intercept

Host-side stream interception handshake.

ports

Well-known vsock ports.

publish_socket

Shared spec for user-published host↔guest Unix-socket bridges.

retry

Retry utilities for transient failure recovery.

secrets

Secret reference types shared across smolvm surfaces.

Structs

DirectoryEntry

One entry of a AgentRequest::ListDirectory result.

Envelope

Envelope that wraps any message with an optional trace ID for correlation.

FsNotifyEvent

A single host-originated filesystem change to replay into the guest.

ImageInfo

Image information returned by Query/ListImages.

MemoryStatus

The guest’s own account of machine memory, from /proc/meminfo.

OverlayInfo

Overlay preparation result.

RegistryAuth

Registry authentication credentials for pulling images.

S3Volume

One S3-compatible bucket to mount inside the workload container.

StorageStatus

Storage status information.

Enums

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.

Constants

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.

QUIESCED_SHUTDOWN_CAPABILITY

The agent can freeze internal filesystems before acknowledging shutdown.

ROSETTA_GUEST_PATH

Guest mount point for the Rosetta 2 Linux runtime. The ptrace wrapper execs <ROSETTA_GUEST_PATH>/rosetta (the translator), so this path is baked into both the wrapper and the binfmt_misc registration.

ROSETTA_TAG

virtiofs tag under which the host exposes the Rosetta 2 Linux runtime to the guest. Shared host↔guest so the launcher’s krun_add_virtiofs tag and the guest agent’s mount -t virtiofs source can’t drift apart.

Functions

decode_message

Decode a message from wire format.

encode_message

Encode a message to wire format (length-prefixed JSON).