Crate microvms_core

Expand description

The composition root for the MicroVMs client (ARCH-8). It wires production edges into application use cases and re-exports the domain, application, edges, and protocol APIs at the paths the CLI and bindings consume (ARCH-1).

§What this crate is for

The domain owns rules and values without I/O; the application owns use cases against ports; the edges implement those ports. This crate provides the production constructors while keeping callers independent of that wiring. It depends on neither the CLI nor the bindings (ARCH-4).

docs/PLATFORM.md records dated observations of AWS Lambda MicroVMs. Shared rules turn those observations into validation and defaults so callers receive the same behavior through Rust, the CLI, Python, and Node.js.

§How strongly a trap is closed

The spec ranks each closure, strongest first:

S1, inexpressible — the mistake cannot be written down. sizing::SizeClass is closed over the documented baselines; hooks::RunHookTimeout and hooks::BuildHookTimeout are separate types with no conversion between them, so a 3600-second build timeout cannot reach a field that caps at 60.
S2, expressible but rejected — the mistake can be written and the client refuses it locally, before any control-plane call, with an error naming the docs/PLATFORM.md finding. Weaker because the guard is code that can regress, but it costs seconds rather than a build cycle. Every boundary where a bare integer or string still has to be judged lands here: sizing::SizeClass::from_baseline_mib, and Region::from_str, which refuses a malformed region name.
S3, correct by default and overridable — weakest, because it protects the caller who does nothing and abandons the one who overrides. An S3 closure must say what the override costs.

A region is any well-formed name since 1.3.0 (#743): AWS adds MicroVMs regions faster than a release can follow, so TRAP-6 is a report rather than a refusal. A call that fails with the null-message AccessDeniedException in a region outside region::MEASURED_REGIONS names the region’s availability as a cause to verify.

§Every error message names its finding

A local reject explains itself by naming the docs/PLATFORM.md section that measured the behavior, because the codes and the guards exist precisely so a reader can go to the measurement rather than to a constraint. “access denied” sends someone to their IAM policy; the message a null-message denial in an unmeasured region actually raises sends them to the region first, then to CloudTrail.

§A guard that cannot fail is worse than no guard

Carried over from the Python era unchanged: every guard here has a falsification — a specific plausible edit that must turn a specific test red. “Delete the feature and the test fails” does not count. The clearest case is TRAP-13 in sizing: every documented peak is exactly four times its baseline, so a test against the shipped table cannot tell a table lookup from baseline * 4, and the guard has to drive the lookup over a table where the pattern does not hold.

§Layout

This crate is the composition root (ARCH-8). The code lives in the crates below it, and every item they export is re-exported here at the path it had in 0.10:

microvms-domain: the rules and values, with no I/O (ARCH-6): error, region, sizing, hooks, constants, cost, and the pure halves of names, preflight, identity and provision.
microvms-app: the use cases, written only against ports (ARCH-7): control, session, sandbox, agents, and the ports themselves, clock, entropy and adapters.
microvms-edges: the production port implementations: the signed transport, the reqwest backend, the sockets, the name registry on disk, provision’s fetch, and env, the one process-environment lookup.
protocol, the wire contract shared with the daemon.

What this crate adds is the wiring: prelude’s constructors (ControlPlane::new, Sandbox::new, Session::connect and the rest) put the production transport, clock, entropy and adapters into each type’s port-taking constructor, and the free functions that read the production clock or pool keep their paths here. use microvms_core::prelude::*; keeps a 0.10 call compiling. The shared test doubles are in testing, behind the test-support feature.

Re-exports§

pub use protocol;

Modules§

adapters: The adapters port and its production implementation.
agents: The coding-agent helpers docs/AGENT-VMS.md specifies, and the Bedrock minter.
clock: The one clock port and tokio’s clock.
constants: Every hardcoded service constraint, and the JSON the build gate checks them with.
control: The control-plane client, with the signed transport and the build services.
cost: What a run cost, and what a plan will cost, with every figure labelled.
defaults: The client’s defaults, by name: what every surface uses when its caller leaves a value out (#300).
duration: Seconds that arrive as a float, as a Duration.
entropy: The entropy port and the OS random pool.
env: The process environment, as the lookup this crate’s resolvers take.
error: One error type, two granularities.
history: Durable VM history composed with the shared file store and production clock.
hooks: The two hook-timeout ceilings, as two types that cannot be swapped.
identity: The host’s half of the tunnel identity proof: seed generation, derivation, and the pin.
ledger: Outstanding run records, with the local file store composed for CLI callers.
names: Named MicroVMs: the record, the store port, and the CLI’s registry on disk.
preflight: Whether a harness can launch here, checked before it queues work (#223).
prelude: The production wiring, under the method names it had in 0.10.
provision: Provisioning of the agentd daemon binary: one call that returns verified aarch64 bytes for the version a client drives (BIND-17 through BIND-20, issue #219).
region: An AWS region: any well-formed name, plus the regions AWS was measured running MicroVMs in (TRAP-6).
sandbox: The Sandbox lifecycle: one VM’s whole life, with the state machine the symspec model describes made true of the code.
secret_input: Host credential input from private files or caller-owned byte streams.
session: The in-VM client, with the reqwest backend and the sockets.
sizing: Size classes: what minimumMemoryInMiB actually buys, and what it bills.
workspace: Directory transfer: the manifest, the diff and the sync pass, over the real filesystem’s walk, hash, pack and guarded extraction (#260).

Structs§

BuildHookTimeout: A timeout for the ready or validate image-build hook: 1..=3600 seconds.
Error: A failure, classified once at the point it is raised.
RunHookTimeout: A timeout for the run, resume, suspend, or terminate hook: 1..=60 seconds.

Enums§

ErrorKind: The coarse failure classes, one per non-zero row of the CLI’s exit table.
Region: An AWS region, by its name.
SizeClass: One of the five documented size classes.
WireKind: The fine-grained taxonomy: one variant per condition the daemon or the transport distinguishes.

Constants§

VERSION: The crate’s own version, for a doctor or manifest command to report.