@ultimat3/storage 29.4.0 → 30.0.0

package/src/expire.ts

@@ -0,0 +1,169 @@
+// Single responsibility: objects and upload sessions past a window the APP names, swept on any
+// disk. Bucket lifecycle rules stay the operator's (axiom 7); a local disk has none, and abandoned
+// parts bill silently forever without one, so a sweep that works the same on every disk is
+// mechanism. No timer here: `objectPurgeTarget` hands the sweep to the app's one `purge()` job.
+
+import {
+  assert,
+  type Clock,
+  finiteCount,
+  logger,
+  renderThrowable,
+  systemClock,
+} from '@ultimat3/core';
+import type { SweepFailure, SweepResult } from './attachment';
+import type { StorageDriver, StorageListEntry } from './driver';
+import type { MultipartSession } from './multipart';
+
+export interface ExpireObjectsInput {
+  readonly disk: StorageDriver;
+  /** Required and non-empty: a sweep of the whole disk is never a default. */
+  readonly prefix: string;
+  /** Age past which an object goes. Required: the window is the app's. */
+  readonly olderThanMs: number;
+  /** `true` spares an object the app still accounts for. */
+  readonly keep?: ((object: StorageListEntry) => boolean | Promise<boolean>) | undefined;
+  readonly clock?: Clock | undefined;
+}
+
+/** `SweepResult`'s two lists, plus what was spared: undated, inside the window, or kept. */
+export interface ExpireResult extends SweepResult {
+  readonly spared: readonly string[];
+}
+
+const screenPrefix = (caller: string, prefix: string): string => {
+  assert(
+    typeof prefix === 'string' && prefix !== '',
+    `${caller} was handed an empty prefix, which is the whole disk`,
+    `${caller}({ disk, prefix: 'exports/', olderThanMs })   # name the prefix the window applies to`,
+  );
+  return prefix;
+};
+
+const cutoffOf = (caller: string, olderThanMs: number, clock: Clock | undefined): number =>
+  // Screened first: `now - NaN` is NaN, and every age comparison against it reads "old enough".
+  (clock ?? systemClock).now().getTime() - finiteCount(caller, 'olderThanMs', olderThanMs, 0);
+
+/**
+ * Delete every object under `prefix` older than the window. An object with no reported age is
+ * spared, as `sweepOrphans` spares it; a refusal — a locked object included — is recorded in
+ * `failed` and the sweep goes on, never forced and never reported as deleted.
+ */
+export async function expireObjects(input: ExpireObjectsInput): Promise<ExpireResult> {
+  const prefix = screenPrefix('expireObjects', input.prefix);
+  const cutoff = cutoffOf('expireObjects', input.olderThanMs, input.clock);
+  const deleted: string[] = [];
+  const failed: SweepFailure[] = [];
+  const spared: string[] = [];
+  let cursor: string | null = null;
+  do {
+    const page = await input.disk.list({ prefix, cursor });
+    for (const object of page.rows) {
+      const modified = object.lastModified?.getTime();
+      if (modified === undefined || modified > cutoff || (await input.keep?.(object)) === true) {
+        spared.push(object.key);
+        continue;
+      }
+      try {
+        await input.disk.delete(object.key);
+        deleted.push(object.key);
+      } catch (error) {
+        failed.push({ key: object.key, reason: renderThrowable(error) });
+      }
+    }
+    cursor = page.nextCursor;
+  } while (cursor !== null);
+  return { deleted, failed, spared };
+}
+
+export interface AbortStaleUploadsInput {
+  readonly disk: StorageDriver;
+  /** Age past which an open session is abandoned. */
+  readonly olderThanMs: number;
+  /** Absent is every session on the disk: an open session under no prefix bills all the same. */
+  readonly prefix?: string | undefined;
+  /** Only sessions whose key this answers `true` for: a per-tenant kind no prefix spells. */
+  readonly match?: ((key: string) => boolean) | undefined;
+  readonly clock?: Clock | undefined;
+}
+
+export interface AbortResult {
+  readonly aborted: readonly MultipartSession[];
+  readonly failed: readonly SweepFailure[];
+  /** Undated or inside the window: possibly a phone still on the train. */
+  readonly spared: readonly MultipartSession[];
+}
+
+/** Abort every upload session opened before the window and never completed. */
+export async function abortStaleUploads(input: AbortStaleUploadsInput): Promise<AbortResult> {
+  const cutoff = cutoffOf('abortStaleUploads', input.olderThanMs, input.clock);
+  const multipart = input.disk.multipart;
+  if (multipart === undefined) return { aborted: [], failed: [], spared: [] };
+  const aborted: MultipartSession[] = [];
+  const failed: SweepFailure[] = [];
+  const spared: MultipartSession[] = [];
+  for (const session of await multipart.listUploads(input.prefix)) {
+    if (input.match !== undefined && !input.match(session.key)) continue;
+    const initiated = session.initiated?.getTime();
+    if (initiated === undefined || initiated > cutoff) {
+      spared.push(session);
+      continue;
+    }
+    try {
+      await multipart.abort(session.key, session.uploadId);
+      aborted.push(session);
+    } catch (error) {
+      failed.push({ key: session.key, reason: renderThrowable(error) });
+    }
+  }
+  return { aborted, failed, spared };
+}
+
+export interface ObjectPurgeTargetInput {
+  /** The step's name in the purge job, unique within it. */
+  readonly name: string;
+  readonly disk: StorageDriver;
+  readonly prefix: string;
+  /**
+   * Only keys this answers `true` for, under `prefix`: `org/<id>/imports/` is one kind of file
+   * under every tenant, and no prefix names it without also naming every avatar beside it.
+   */
+  readonly match?: ((key: string) => boolean) | undefined;
+  readonly olderThanMs: number;
+}
+
+/**
+ * Structurally `@ultimat3/jobs`' `PurgeTarget`, so this package imports nothing upward and the
+ * app's one `purge({ targets })` carries it. One pass expires the objects and aborts the sessions
+ * under the prefix, on the JOB's clock. A refusal is logged and counted out, never retried into a
+ * dead letter: a locked object stays locked on every attempt.
+ */
+export function objectPurgeTarget(input: ObjectPurgeTargetInput): {
+  readonly name: string;
+  purgeExpired(nowMs: number): Promise<number>;
+} {
+  const prefix = screenPrefix('objectPurgeTarget', input.prefix);
+  finiteCount('objectPurgeTarget', 'olderThanMs', input.olderThanMs, 0);
+  return {
+    name: input.name,
+    async purgeExpired(nowMs: number): Promise<number> {
+      const clock: Clock = { now: () => new Date(nowMs), monotonic: () => nowMs };
+      const window = { disk: input.disk, prefix, olderThanMs: input.olderThanMs, clock };
+      const match = input.match;
+      // Outside `match` is spared, never deleted: `keep` is `expireObjects`' own way of saying so.
+      const objects = await expireObjects(
+        match === undefined ? window : { ...window, keep: (object) => !match(object.key) },
+      );
+      const uploads = await abortStaleUploads({ ...window, match });
+      const failed = [...objects.failed, ...uploads.failed];
+      if (failed.length > 0) {
+        logger.warn('storage.expire.refused', {
+          target: input.name,
+          refused: failed.length,
+          first: failed[0]?.reason,
+        });
+      }
+      return objects.deleted.length + uploads.aborted.length;
+    },
+  };
+}

package/src/grant-multipart.ts

@@ -0,0 +1,196 @@
+// Single responsibility: the server half of an upload in parts — open a session under
+// `grantUpload`'s policy gate, sign a part, list what landed, complete, abort. Each is a function the
+// app wraps in its own `action()`, and each is held to the ACTOR's tenant, so an upload id read off a
+// request reaches nothing outside the caller's org.
+
+import { assert } from '@ultimat3/core';
+import type { StorageDriver, StorageObject } from './driver';
+import { orgMismatch, tooLarge } from './errors';
+import { multipartUnsupported, partsInvalid } from './errors-multipart';
+import { decideGrant, type GrantUploadInput } from './grant';
+import {
+  type CompletedPart,
+  MAX_PART_BYTES,
+  MAX_PARTS,
+  MIN_PART_BYTES,
+  type MultipartCapability,
+  matchParts,
+  partBytesFor,
+  type UploadedPart,
+} from './multipart';
+import { isWithinOrg } from './path';
+import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
+import type { UploadPolicy } from './upload';
+
+export interface GrantMultipartInput extends GrantUploadInput {
+  /** A part size the app prefers; raised to what 10,000 parts need, never below S3's 5 MiB. */
+  readonly partBytes?: number | undefined;
+}
+
+export interface MultipartGrant {
+  readonly key: string;
+  readonly uploadId: string;
+  /** Every part but the last is exactly this long. */
+  readonly partBytes: number;
+  /** How many parts the declared size takes at `partBytes`. */
+  readonly maxParts: number;
+  /** Normalised: the type the object is created under. */
+  readonly contentType: string;
+  /** The declared size, already held to the policy. The client's claim: `policy` is the bound. */
+  readonly size: number;
+  /** Epoch ms: the part URLs' window from now. Each `signPart` opens a fresh one. */
+  readonly expiresAt: number;
+}
+
+/** What names one open session. `orgId` is the actor's, resolved server-side. */
+export interface UploadSessionInput {
+  readonly disk: StorageDriver;
+  readonly orgId: string;
+  readonly key: string;
+  readonly uploadId: string;
+}
+
+export interface SignPartInput extends UploadSessionInput {
+  readonly partNumber: number;
+  /** This part's exact size: `partBytes`, or less for the last part. Signed. */
+  readonly size: number;
+  /** The policy the grant was made under: a part no object under its `maxBytes` holds is refused. */
+  readonly policy: UploadPolicy;
+  readonly expiresInMs?: number | undefined;
+}
+
+export interface CompleteUploadInput extends UploadSessionInput {
+  /** Ascending. Etags are optional: the disk's own, read by `listParts` here, are what is sent. */
+  readonly parts: readonly CompletedPart[];
+  /** The policy the grant was made under: a completed object past its `maxBytes` is refused. */
+  readonly policy: UploadPolicy;
+}
+
+const capabilityOf = (disk: StorageDriver, key: string): MultipartCapability => {
+  if (disk.multipart === undefined) throw multipartUnsupported(disk.name, key);
+  return disk.multipart;
+};
+
+/** The key a session was opened for, held to the actor's org exactly as `accept.ts` holds a URL. */
+const sessionOf = (input: UploadSessionInput): MultipartCapability => {
+  // Every session a grant opens is under `org/<id>/`, so a key outside the actor's org is refused
+  // whether or not another tenant owns it: no shared prefix takes parts.
+  if (!isWithinOrg(input.key, input.orgId)) {
+    throw orgMismatch(input.key, input.orgId);
+  }
+  return capabilityOf(input.disk, input.key);
+};
+
+/**
+ * The type says required; an untyped caller upgrading from the call without one does not read
+ * types, and with no policy nothing bounds what the session stores — `promoteAttachment`'s guard.
+ */
+const assertPolicy = (caller: string, policy: UploadPolicy | undefined, fix: string): number => {
+  assert(
+    typeof policy?.maxBytes === 'number',
+    `${caller} was called with no policy, so nothing bounds the size of the upload in parts`,
+    fix,
+  );
+  return policy.maxBytes;
+};
+
+/**
+ * The smallest object part `partNumber` at `size` bytes can belong to. Every part before it is at
+ * least S3's floor and at least as long as it (each but the last is exactly `partBytes`), so an
+ * honest grant's part never implies more than its declared size, and so never more than the policy.
+ */
+const impliedBytes = (partNumber: number, size: number): number =>
+  Math.max((partNumber - 1) * MIN_PART_BYTES + size, partNumber * size);
+
+/** The part size: the app's preference, raised to what the size and the protocol require. */
+const partSizeFor = (size: number, preferred: number | undefined): number => {
+  const floor = partBytesFor(size);
+  if (preferred === undefined) return floor;
+  assert(
+    Number.isSafeInteger(preferred) && preferred >= MIN_PART_BYTES && preferred <= MAX_PART_BYTES,
+    `grantMultipart was handed partBytes ${String(preferred)}, outside S3's ${MIN_PART_BYTES}..${MAX_PART_BYTES} bytes`,
+    `grantMultipart({ disk, orgId, request, partBytes: ${MIN_PART_BYTES} })   # or omit it`,
+  );
+  return Math.max(floor, preferred);
+};
+
+/** Refuses as `grantUpload` refuses, then opens the session the parts go into. */
+export async function grantMultipart(input: GrantMultipartInput): Promise<MultipartGrant> {
+  const granted = decideGrant('grantMultipart', input);
+  const multipart = capabilityOf(input.disk, granted.key);
+  const partBytes = partSizeFor(granted.size, input.partBytes);
+  const uploadId = await multipart.create(granted.key, { contentType: granted.contentType });
+  return {
+    key: granted.key,
+    uploadId,
+    partBytes,
+    maxParts: Math.ceil(granted.size / partBytes),
+    contentType: granted.contentType,
+    size: granted.size,
+    expiresAt: granted.now + granted.expiresInMs,
+  };
+}
+
+/**
+ * One part's URL, its length inside the signature. A part past what an object under the policy
+ * holds is `X_STORAGE_TOO_LARGE`, so a session's parts cannot outgrow the policy before the
+ * `completeUpload` that would refuse them: unassembled parts bill too.
+ */
+export async function signPart(input: SignPartInput): Promise<string> {
+  const maxBytes = assertPolicy(
+    'signPart',
+    input.policy,
+    'signPart({ disk, orgId, key, uploadId, partNumber, size, policy: uploadPolicy({ maxBytes }) }) — the policy the grant was made under',
+  );
+  const multipart = sessionOf(input);
+  const { partNumber, size } = input;
+  assert(
+    Number.isSafeInteger(partNumber) && partNumber >= 1 && partNumber <= MAX_PARTS,
+    `signPart was handed partNumber ${String(partNumber)}, outside 1..${MAX_PARTS}`,
+    'signPart({ disk, orgId, key, uploadId, partNumber: 1, size })',
+  );
+  assert(
+    Number.isSafeInteger(size) && size >= 1 && size <= MAX_PART_BYTES,
+    `signPart was handed size ${String(size)}, not a part of 1..${MAX_PART_BYTES} bytes`,
+    'signPart({ disk, orgId, key, uploadId, partNumber, size: grant.partBytes })',
+  );
+  const implied = impliedBytes(partNumber, size);
+  if (implied > maxBytes) throw tooLarge(input.key, implied, maxBytes);
+  return multipart.signPart(input.key, input.uploadId, partNumber, {
+    contentLength: size,
+    expiresInMs: input.expiresInMs === undefined ? DEFAULT_SIGNED_URL_TTL_MS : input.expiresInMs,
+  });
+}
+
+/** What landed, ascending — the resume: a client sends only the parts not here. */
+export function listParts(input: UploadSessionInput): Promise<readonly UploadedPart[]> {
+  return sessionOf(input).listParts(input.key, input.uploadId);
+}
+
+/**
+ * The parts named, checked against what the disk holds, then assembled. The etags sent are the
+ * disk's own, so the browser never needs a bucket's CORS to expose `ETag`. A total past the policy
+ * aborts the session: those bytes were never going to be promoted.
+ */
+export async function completeUpload(input: CompleteUploadInput): Promise<StorageObject> {
+  const maxBytes = assertPolicy(
+    'completeUpload',
+    input.policy,
+    'completeUpload({ disk, orgId, key, uploadId, parts, policy: uploadPolicy({ maxBytes }) }) — the policy the grant was made under',
+  );
+  const multipart = sessionOf(input);
+  const stored = await multipart.listParts(input.key, input.uploadId);
+  const matched = matchParts(input.parts, stored);
+  if ('problem' in matched) throw partsInvalid(input.key, input.uploadId, matched.problem);
+  const total = matched.parts.reduce((sum, part) => sum + part.size, 0);
+  if (total > maxBytes) {
+    await multipart.abort(input.key, input.uploadId);
+    throw tooLarge(input.key, total, maxBytes);
+  }
+  return multipart.complete(input.key, input.uploadId, matched.parts);
+}
+
+/** Drops the session and every part. An id already gone is the state asked for. */
+export function abortUpload(input: UploadSessionInput): Promise<void> {
+  return sessionOf(input).abort(input.key, input.uploadId);
+}

package/src/grant.ts

@@ -10,6 +10,7 @@ import type { AttachmentTarget } from './attachment';
 import { attachmentKey, pendingKey, quarantineKey, uploadName } from './attachment';
 import type { StorageDriver } from './driver';
 import { contentTypeNotAllowed, tooLarge } from './errors';
+import { uploadSizeUndeclared } from './errors-stream';
 import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
 import type { UploadPolicy } from './upload';
 import { normalizeContentType, uploadPolicy } from './upload';
@@ -19,10 +20,11 @@ export interface UploadRequest {
   readonly filename: string;
   readonly contentType: string;
   /**
-   * Optional, and never trusted: it only buys the client an early refusal. The bytes are counted
-   * again by `acceptSignedUpload`, which is the authority, so a lie here changes nothing.
+   * The file's size in bytes. Required, because it is what the URL binds: an s3 disk signs it as the
+   * exact `Content-Length`, and the local disks sign it as the ceiling `acceptSignedUpload` counts
+   * against. A lie here shrinks the client's own upload; it cannot pass the policy's `maxBytes`.
    */
-  readonly size?: number | undefined;
+  readonly size: number;
 }
 
 export interface UploadGrant {
@@ -32,6 +34,7 @@ export interface UploadGrant {
   readonly method: 'PUT';
   /** Normalised. The client MUST send exactly this as `Content-Type` or the accept refuses. */
   readonly contentType: string;
+  /** What the URL accepts: the declared `size`, already held to the policy. */
   readonly maxBytes: number;
   /** Epoch ms. The grant's own view of the window; the signature is what actually enforces it. */
   readonly expiresAt: number;
@@ -57,12 +60,21 @@ export interface GrantUploadInput {
   readonly uploadId?: (() => string) | undefined;
 }
 
+/** What every grant decides before it signs: the key, the type and size the policy accepted. */
+export interface GrantedUpload {
+  readonly key: string;
+  readonly contentType: string;
+  readonly size: number;
+  readonly expiresInMs: number;
+  readonly now: number;
+}
+
 /**
- * Refuses before it signs. A URL only exists for a request the policy already accepted, so an
- * over-limit or disallowed upload costs one round trip instead of a full transfer — and the
- * signature then carries the same two constraints, so the client cannot widen either of them.
+ * The refusals both grants share — `grantUpload`'s one PUT and `grantMultipart`'s parts — so a
+ * request one refuses the other refuses too: the key derived, never the client's; the type held to
+ * the allowlist; the size to the policy; the window screened.
  */
-export async function grantUpload(input: GrantUploadInput): Promise<UploadGrant> {
+export function decideGrant(caller: string, input: GrantUploadInput): GrantedUpload {
   const policy = input.policy ?? uploadPolicy();
   const clock = input.clock ?? systemClock;
   const declared = normalizeContentType(input.request.contentType);
@@ -78,33 +90,38 @@ export async function grantUpload(input: GrantUploadInput): Promise<UploadGrant>
     throw contentTypeNotAllowed(key, declared, policy.allowedContentTypes);
   }
   const size = input.request.size;
-  if (size !== undefined && Number.isSafeInteger(size) && size > policy.maxBytes) {
-    throw tooLarge(key, size, policy.maxBytes);
-  }
+  // Off the wire, so the type promises nothing here. An empty file has nothing to upload.
+  if (!Number.isSafeInteger(size) || size < 1) throw uploadSizeUndeclared(key, size);
+  if (size > policy.maxBytes) throw tooLarge(key, size, policy.maxBytes);
 
   // Refused here as well as in the presigner one call down: `expiresAt: now + NaN` is `NaN` in the
-  // grant this function RETURNS, and the message a caller can act on names `grantUpload`'s
-  // own option rather than `buildSignedUrl`'s.
-  // `=== undefined`, never `??`, for the reason `buildSignedUrl` states: `??` coalesces on `null`
-  // too, so an explicit one took the default instead of this refusal.
+  // grant this function RETURNS, and the message a caller can act on names the grant's own option
+  // rather than `buildSignedUrl`'s. `=== undefined`, never `??`, for the reason `buildSignedUrl`
+  // states: `??` coalesces on `null` too, so an explicit one took the default instead.
   const expiresInMs = finiteCount(
-    'grantUpload',
+    caller,
     'expiresInMs',
     input.expiresInMs === undefined ? DEFAULT_SIGNED_URL_TTL_MS : input.expiresInMs,
     1,
   );
+  return { key, contentType: declared, size, expiresInMs, now: clock.now().getTime() };
+}
+
+/**
+ * Refuses before it signs. A URL only exists for a request the policy already accepted, so an
+ * over-limit or disallowed upload costs one round trip instead of a full transfer. The signature
+ * then carries the size on every disk, so the client cannot widen it: at the provider's PUT on s3
+ * (403 on any other length), and at `acceptSignedUpload` on the local disks. The content type is
+ * signed only on a disk that signs its own URLs; on s3, `promoteAttachment` sniffs it.
+ */
+export async function grantUpload(input: GrantUploadInput): Promise<UploadGrant> {
+  const { key, contentType, size, expiresInMs, now } = decideGrant('grantUpload', input);
   const url = await input.disk.signedUrl(key, {
     method: 'PUT',
-    maxBytes: policy.maxBytes,
-    contentType: declared,
+    maxBytes: size,
+    contentLength: size,
+    contentType,
     expiresInMs,
   });
-  return {
-    key,
-    url,
-    method: 'PUT',
-    contentType: declared,
-    maxBytes: policy.maxBytes,
-    expiresAt: clock.now().getTime() + expiresInMs,
-  };
+  return { key, url, method: 'PUT', contentType, maxBytes: size, expiresAt: now + expiresInMs };
 }

package/src/image-warm.ts

@@ -0,0 +1,84 @@
+// Single responsibility: write a stored image's variants AHEAD of the first request, under the exact
+// keys the media route looks up, so no visitor pays the decode. The job an upload enqueues calls
+// this; the request path then answers `exists` + `get` and never reaches the pipeline.
+
+import {
+  assert,
+  finiteCount,
+  IMAGE_MIME_TYPES,
+  isUltimateError,
+  probeImage,
+  transformImageBytes,
+} from '@ultimat3/core';
+import type { StorageDriver } from './driver';
+import { type VariantFormat, variantKey, variantRevision } from './image';
+
+export interface WarmVariantsInput {
+  readonly disk: StorageDriver;
+  /** The SOURCE object's key, as the media route is asked for it. */
+  readonly key: string;
+  /** Whole pixels. Widths above the source's are skipped: the route never stores an upscale. */
+  readonly widths: readonly number[];
+  /** `avif` is accepted by the type and fails per variant with core's `X_IMAGE_UNSUPPORTED`. */
+  readonly formats: readonly VariantFormat[];
+}
+
+/** A variant that was not written: its key, and the failure's code and cause. */
+export interface WarmFailure {
+  readonly key: string;
+  /** `X_IMAGE_UNSUPPORTED` for an `avif`, a storage code for a refused `put`. */
+  readonly code: string;
+  readonly cause: string;
+}
+
+export interface WarmVariantsResult {
+  /** The variant keys written, in width-then-format order. */
+  readonly written: readonly string[];
+  /** One entry per variant that could not be made or stored; the others were still written. */
+  readonly failed: readonly WarmFailure[];
+  /** Widths above the source's intrinsic width: never minted, never stored. */
+  readonly skipped: readonly number[];
+}
+
+/**
+ * Every `widths` x `formats` variant of `key`, keyed as `variantKey(key, { width, format,
+ * revision })` with the revision read off THIS read's etag — the one the bytes were made from, so
+ * an overwrite racing the warm-up can only leave keys its new etag never names. The transform spec
+ * is the builtin image driver's (`width` + `format`, default quality), so a warmed variant is the
+ * object the route would have stored itself.
+ *
+ * The source is READ and PROBED once, and the probe holds it to core's `MAX_IMAGE_PIXELS` before
+ * any pixel is decoded; each variant is then one pipeline pass over the bytes already in hand.
+ */
+export async function warmVariants(input: WarmVariantsInput): Promise<WarmVariantsResult> {
+  for (const width of input.widths) finiteCount('warmVariants', 'widths', width, 1);
+  const source = await input.disk.get(input.key);
+  const revision = variantRevision(source.object.etag);
+  assert(
+    revision !== undefined,
+    `warmVariants('${input.key}'): the source etag "${source.object.etag}" carries no 8-hex revision, so no variant of it has a key the media route would read`,
+    `x doctor --json   # the disk driver answers no content etag; variants of ${input.key} are served, never stored`,
+  );
+  // A header read: past `MAX_IMAGE_PIXELS` it is core's `X_IMAGE_TOO_LARGE` before any decode.
+  const info = probeImage(source.bytes);
+  const written: string[] = [];
+  const failed: WarmFailure[] = [];
+  const skipped = input.widths.filter((width) => width > info.width);
+  for (const width of input.widths.filter((one) => one <= info.width)) {
+    for (const format of input.formats) {
+      const key = variantKey(input.key, { width, format, revision });
+      try {
+        const bytes = await transformImageBytes(source.bytes, { width, format });
+        await input.disk.put(key, bytes, {
+          contentType: IMAGE_MIME_TYPES[probeImage(bytes).format],
+        });
+        written.push(key);
+      } catch (error) {
+        // Coded failures are per-variant answers; anything uncoded is a defect and is not swallowed.
+        if (!isUltimateError(error)) throw error;
+        failed.push({ key, code: error.code, cause: error.cause });
+      }
+    }
+  }
+  return { written, failed, skipped };
+}

package/src/image.ts

@@ -4,6 +4,7 @@
 // bytes, `transformImage()` returns exactly the size `fitDimensions()` already promised.
 
 import {
+  assert,
   assertFiniteImageQuality,
   blurDataUrl,
   finiteCount,
@@ -13,6 +14,7 @@ import {
   transformImageBytes,
 } from '@ultimat3/core';
 import { assertSafeKey } from './path';
+import { normalizeContentType } from './upload';
 
 /**
  * The formats a stored VARIANT can be minted in — a strict subset of the ones `@ultimat3/core`
@@ -41,6 +43,50 @@ export type VariantFormat = (typeof VARIANT_FORMATS)[number];
 export const isVariantFormat = (format: string): format is VariantFormat =>
   (VARIANT_FORMATS as readonly string[]).includes(format);
 
+/** The source encodings core can write back, so a variant with no `?f=` keeps its source's. */
+const SOURCE_VARIANT_FORMATS: ReadonlyMap<string, VariantFormat> = new Map([
+  ['image/png', 'png'],
+  ['image/jpeg', 'jpeg'],
+  ['image/webp', 'webp'],
+]);
+
+/**
+ * The format a variant of this stored type is written in when nobody named one. `undefined` (a
+ * `gif`) means no key can state what the transform will answer: such a variant is served, never
+ * stored. Without this `variantKey` read the absent format as `webp` while the driver kept the
+ * source's, so `?w=320` and `?w=320&f=webp` shared one key and the first request chose the bytes.
+ */
+export const variantFormatOf = (contentType: string): VariantFormat | undefined =>
+  SOURCE_VARIANT_FORMATS.get(normalizeContentType(contentType));
+
+const REVISION = /^[0-9a-f]{8}$/;
+/** The `@…r<8 hex>.<ext>` only `variantKey({ revision })` writes. The last `@` is the variant's. */
+const REVISIONED_VARIANT = /^(.+)@(?:[^@/]*-)?r([0-9a-f]{8})\.(?:avif|webp|jpg|png)$/;
+
+/** The source and revision a stored variant's key names, or `undefined` for any other key. */
+export function variantSourceOf(
+  key: string,
+): { readonly source: string; readonly revision: string } | undefined {
+  const match = REVISIONED_VARIANT.exec(key);
+  return match?.[1] === undefined || match[2] === undefined
+    ? undefined
+    : { source: match[1], revision: match[2] };
+}
+
+/**
+ * The part of a source's etag a variant key carries, so an overwritten source misses every variant
+ * of its old bytes. Hex only, because a provider's etag arrives quoted and a multipart one carries
+ * `-<parts>`. `undefined` when the etag is unknowable (`''`) or too short to tell two revisions
+ * apart: that variant has no honest key, so it is served, never stored.
+ */
+export function variantRevision(etag: string): string | undefined {
+  const revision = etag
+    .toLowerCase()
+    .replace(/[^0-9a-f]/g, '')
+    .slice(0, 8);
+  return REVISION.test(revision) ? revision : undefined;
+}
+
 /** `cover` fills the box and crops the overflow; `contain` fits inside it, no crop. */
 export type ImageFit = 'cover' | 'contain';
 
@@ -51,6 +97,8 @@ export interface ImageTransform {
   /** 1-100. Omitted means the format default (`DEFAULT_QUALITY`). */
   readonly quality?: number | undefined;
   readonly fit?: ImageFit | undefined;
+  /** `variantRevision(source.etag)`: which bytes this variant was made from. Absent, unkeyed. */
+  readonly revision?: string | undefined;
 }
 
 export interface ImageSize {
@@ -116,6 +164,15 @@ export function variantKey(sourceKey: string, transform: ImageTransform): string
     transform.quality === undefined ? DEFAULT_QUALITY : transform.quality,
   );
   if (quality !== DEFAULT_QUALITY) parts.push(`q${quality}`);
+  const { revision } = transform;
+  if (revision !== undefined) {
+    assert(
+      REVISION.test(revision),
+      'variantKey was given a revision that is not 8 hex digits, so it would mint a key nothing can derive again',
+      'variantKey(key, { width, revision: variantRevision(object.etag) })',
+    );
+    parts.push(`r${revision}`);
+  }
   if (parts.length === 0) parts.push('full');
   return assertSafeKey(`${safe}@${parts.join('-')}.${FORMAT_EXTENSIONS[format]}`);
 }