Skip to main content

Module control

microvms_core

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 resolves credentials and either yields a usable client or says why not.

§What is closed here, and how strongly

  • TRAP-1 — token: no clientToken parameter exists on any request type. S1.
  • 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 — there is no mint_shell_auth_token method and no SHELL_INGRESS intent. Both halves are closed by absence, which is why the test for them counts calls a full lifecycle made rather than asserting a refusal.

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

CreateMicrovmShellAuthToken is in the service model and this client does not implement it. That is not an omission to be filled in later: it gates ctr task exec through a console terminal, scoped to debugging and recommended disabled in production, and it is not a programmatic exec path despite the name. The absence is the closure — a method here would be a method a caller could reach.

§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::artifact_content_hash;
pub use artifact::build_artifact;
pub use artifact::default_dockerfile;
pub use connector::ConnectorIntent;
pub use image::Image;
pub use image::WaitOpts;
pub use microvm::Microvm;
pub use microvm::ProxyToken;
pub use microvm::RunHookPayload;

Modules§

artifact
The build artifact: a zip of the daemon binary and a Dockerfile.
connector
Network connectors: a closed intent enum, and the ARN each one derives (TRAP-4).
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.
token
Idempotency tokens, unique per attempt by construction (TRAP-1).
transport
The signed rest-json transport, and the seam a test replaces it at.

Structs§

ControlPlane
The control-plane client.
CreateImageRequest
Everything CreateMicrovmImage needs, with the traps closed in the type.
RunMicrovmRequest
Everything RunMicrovm needs.
SystemClock
The real clock: Instant and tokio::time::sleep.

Constants§

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

Traits§

Clock
Monotonic time and sleeping, injectable so a wait can be tested without waiting.

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