Skip to main content

Module control

microvms_app

Module control 

Source
Expand description

The control-plane client: SigV4-signed rest-json, and every trap closed before the request leaves the process.

§The shape of the thing

ControlPlane is the whole surface. It holds a transport::Transport (signed and real, or a contract recorder in a test), a Region, and a Clock — and every operation is a method on it. There is no builder, no config struct, and no partially constructed state: ControlPlane::new (microvms_core::prelude::ControlPlaneExt) resolves credentials and either yields a usable client or says why not.

§What is closed here, and how strongly

  • TRAP-1 — token: image tokens are always fresh. Run tokens are fresh unless explicitly persisted for recovery of one launch. Never reuse them for a new VM.
  • TRAP-2 — image: a build stuck in CREATING past the stall grace with every build PENDING is rejected naming the replay signature. S2.
  • TRAP-3 — CreateImageRequest::repair_guest_identity is a bool, and the request injects ["ALL"] itself. There is no capability list to put CAP_SYS_ADMIN in. S1.
  • TRAP-4 — connector::ConnectorIntent: connectors are derived ARNs from a closed intent enum. S1.
  • TRAP-5 — RunHookPayload: 4096 bytes inclusive, checked before any call. S2, and the type means an unchecked string cannot reach the field.
  • TRAP-8 — ControlPlane::wait_for_running: a terminal state before RUNNING is rejected with the state and stateReason attached. S2.
  • TRAP-11, revised again — mint_shell_auth_token exists now, and the guard changed ground with it: the closure is no longer the method’s absence but the exec path’s separation from it, which is why the test still counts the calls a full lifecycle made and asserts zero shell operations among them. The connector half is unchanged: SHELL_INGRESS is a connector::ConnectorIntent variant, and the lifecycle test asserts a launch carries exactly the connectors its caller asked for. See connector.

§TRAP-11 is the one that needs saying out loud

CreateMicrovmShellAuthToken is implemented — issue #69 builds microvm shell on it, and ControlPlane::mint_shell_auth_token is its one door. The original reason for staying away entirely — that the shell gates a console-only debugging flow, not a programmatic exec path — did not survive measurement: docs/PLATFORM.md (2026-08-15) found a real PTY over a WebSocket, programmatically drivable. What holds is narrower: one interactive session is not programmatic exec — no exec ids, no idempotency, no separated stdout/stderr, no exit codes — so the exec path never requests the shell connector and never mints a shell token, and the shell is its own surface ([crate::session::shell]) rather than a method the exec path can wander into.

§Nothing in this module reads the service model at runtime

Every constraint is a constant in crate::constants, checked by the build gate against the pinned model (TRAP-12). That matters because botocore’s VALIDATED_METADATA_ATTRS is {required, min, document, union} — max, pattern, and enum violations go to the wire — so every guard in this module is load-bearing rather than belt-and-braces, and “the SDK validates the model already” was never true.

§And “botocore validates min” was never true of this client

The sentence above is about max, pattern, and enum, and for a while it left min implicitly exempt: min is in VALIDATED_METADATA_ATTRS, so a min violation really is refused before the wire — by botocore. This client does not use botocore. It signs with aws-sigv4 and sends with reqwest, and validate.py is nowhere in the dependency graph. That reasoning came from the deleted Python client, where it held, and it did not survive the port; issue #24 measured the consequence, maxIdleDurationSeconds: 59 on the wire.

So the rule is simpler than it was: every constraint the model states on a member this client sends is enforced by this module or by nothing. The guards below are the whole of it:

Three constraints are closed by a type rather than by a function, which is the stronger form: RunHookPayload cannot hold over 4096 bytes, ops::VersionStatus and ops::HookState cannot spell a value the enum does not have, and connector::ConnectorIntent cannot name a connector the platform does not publish. A constraint the type system enforces cannot be forgotten at a call site.

Re-exports§

pub use artifact::BaseImage;
pub use artifact::Ecosystem;
pub use artifact::ProjectFiles;
pub use artifact::WrapOptions;
pub use artifact::artifact_content_hash;
pub use artifact::build_artifact;
pub use artifact::default_dockerfile;
pub use artifact::wrap_dockerfile;
pub use connector::ConnectorIntent;
pub use connector::EgressPosture;
pub use connector::PLATFORM_HONOURS_OMITTED_EGRESS;
pub use connector::egress_posture_for;
pub use context::BuildContext;
pub use context::ContextEntry;
pub use ensure::EnsureImageRequest;
pub use ensure::EnsuredImage;
pub use image::Image;
pub use image::WaitOpts;
pub use microvm::Microvm;
pub use microvm::MicrovmFilter;
pub use microvm::ProxyToken;
pub use microvm::RunHookPayload;
pub use services::BuildServices;
pub use crate::clock::Clock;

Modules§

artifact
The build artifact: a zip of the daemon binary, a Dockerfile, and — when the caller passes ProjectFiles — the project’s dependency files.
connector
Managed connector intents and customer-managed VPC egress connector validation.
context
A task’s build context: the files a Dockerfile may COPY, read from a directory the way docker build reads one (#221, IMAGE-7).
ensure
Content-addressed build-or-reuse for an image: what Sandbox::ensure_image does (#221).
image
Image create, the build wait, and the stalled-build probe (TRAP-1, TRAP-2).
microvm
Launch, the launch wait, the lifecycle calls, and the proxy token (TRAP-5, TRAP-8).
ops
The wire shapes, transcribed member-for-member from the pinned service model.
project
Which manifest+lockfile pair a project directory holds (#74, #264).
services
The two calls outside the MicroVMs API that ensure_image makes: the caller’s account, for the image ARN, and the artifact upload (#221, IMAGE-8).
token
Idempotency tokens, unique per attempt by construction (TRAP-1).
transport
The control plane’s rest-json calls, and the seam a transport implements.

Structs§

ControlPlane
The control-plane client.
CreateImageRequest
Everything CreateMicrovmImage needs, with the traps closed in the type.
RunMicrovmRequest
Everything RunMicrovm needs.

Constants§

DEFAULT_AGENT_PORT
The default agent port, matching the daemon’s own default.

Functions§

hooks_block
The Hooks block with all six hooks enabled and both timeout families set.
require_duration_in_range
Rejects a maximumDurationInSeconds outside the service range.
require_idle_duration
Rejects an idlePolicy.maxIdleDurationSeconds under the model’s min: 60.
require_non_blank
Rejects a NonBlankString value the service would reject.
require_valid_identifier
Rejects a MicrovmIdentifier/MicrovmImageIdentifier the service would reject.
require_valid_image_name
Rejects an image name the service would reject, before the artifact upload.
require_valid_log_group
Rejects a logging.cloudWatch.logGroup the service would reject, before the artifact upload.
require_valid_log_stream
Rejects a caller-supplied logging.cloudWatch.logStream prefix the resolved name could not legally carry, before the artifact upload.
require_valid_port
Rejects a port the PortNumber or HooksPortInteger shapes would reject. Minimum 1.
require_valid_role_arn
Rejects a RoleArn the service would reject, before the artifact upload.
require_valid_tags
Rejects a tag map the service would reject, naming the key and the half that failed.
require_valid_version
Rejects a Version/NonBlankString value the service would reject.