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 image_ref::image_repo;

pub use image_ref::normalize_image_ref;

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.

error_codes

Error codes for agent responses.

forkpoint

Stable guest paths used to coordinate a live fork.

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.

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

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.

OverlayInfo

Overlay preparation result.

RegistryAuth

Registry authentication credentials for pulling images.

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.

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).