Module ensure 

Content-addressed build-or-reuse for an image: what Sandbox::ensure_image does (#221).

A harness with many concurrent trials of one task needs one image for them all: the one already built, the one a sibling trial is building, or — when there is none — one it builds itself. This module is that composition, from build inputs to a usable image:

1. Name (IMAGE-6). <prefix>-<hash12>, the hash over the artifact’s inputs (the daemon, the Dockerfile, the build context — artifact_content_hash_with_context) plus the base image, the size class and every field the service sets only when it creates the image (identity repair, inherit_workdir, the hook timeouts, the log destination), because an image is created on one base at one size with those fixed. Equal inputs name one image; any changed input names a fresh one, which is what keeps a stale snapshot, or one built without a field the caller asked for, from being served under a reused name.
2. Artifact (IMAGE-7). The Dockerfile, the daemon, and the context, zipped with fixed dates and modes, so equal inputs are one object at one content-addressed key.
3. ARN and upload (IMAGE-8). The service takes image ARNs, not names, so the ARN is built from the caller’s account, looked up once per sandbox (super::services::BuildServices::caller_account). The artifact goes to s3://<bucket>/<prefix>/<name>/artifact.zip, and only when a build is needed.
4. Decide (IMAGE-9, IMAGE-10). After each describe, plan says what to do: reuse a ready image, wait for one building, delete a failed one (or, under force, any one) and wait for the name to be free, or build.
5. Race (IMAGE-11). Two trials that both find the name free both create; the service accepts one and refuses the other. The loser describes again and waits for the winner’s build, returning it only once it is ready, and marks it reused.

crates/model/src/image.rs is this module as a Stateright model: two concurrent callers against a platform that moves the image through its states, checked over every interleaving. The decision table there is plan’s, row for row.

Everything local happens before the first call

prepare derives the name, the key, the artifact, and the create request, and runs the create call’s preflight, with zero calls. A request this client refuses costs nothing: not the account lookup, not a describe, not the upload.

Timeouts

The build wait is the one build uses — WaitOpts::default, 45 minutes with a four-minute stall probe — or the caller’s wait_timeout. The wait for a deleted name to free up is DEFAULT_DELETE_TIMEOUT.

Structs

EnsureImageRequest

Everything Sandbox::ensure_image needs.

EnsuredImage

What Sandbox::ensure_image returns.

Prepared

Everything prepare decided locally: the name, the key, the artifact, and the create request, with the create’s preflight already passed.

Enums

Found

What a describe of the ensured image found.

Plan

What ensure_image does next with what a describe found.

Constants

DEFAULT_DELETE_TIMEOUT

How long a deleted image may take to free its name before ensure_image gives up.

Functions

artifact_key

The artifact’s S3 key: <prefix>/<name>/artifact.zip, with the prefix’s empty segments dropped so no key starts with or doubles a / (IMAGE-8).

ensured_image_name

The image name for a prefix and an identity hash: <prefix>-<hash12> (IMAGE-6).

image_identity_hash

The identity an ensured image is named for (IMAGE-6): the artifact’s content hash, the base image’s name (what baseImageArn names), and the size class’s baseline, for an image created with CreateImageRequest::new’s create-only fields.

pinned_identity_hash

image_identity_hash with the base version a build pins (#258): a pinned base builds on that version whatever the service’s default later becomes, so the pin is identity.

plan

The decision ensure_image makes after each describe (IMAGE-9, IMAGE-10).

prepare

The local half of ensure_image: every name, key, and artifact decision and every guard, with zero calls.

s3_location

The bucket and key of an s3://<bucket>/<key> URI, refused when it isn’t one S3 admits.