@ultimat3/cli 29.4.0 → 30.1.0

package/src/runtime-assets-site-cache.ts

@@ -0,0 +1,55 @@
+// A byte-bounded, least-recently-used memo with single flight: what keeps a public image variant
+// from being decoded twice. Concurrent first requests share one promise, so a burst of visitors to
+// a fresh deploy is one decode, not one each — and the bound holds the process's memory flat.
+
+export interface VariantLru<T> {
+  /** The kept answer for `key`, the one in flight, or `make()`'s — kept if `sizeOf` sizes it. */
+  get(key: string, make: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * `sizeOf` answering `undefined` means "answer, never keep" — a refusal is cheap to recompute and
+ * must not hold a slot a real variant could. An entry larger than the whole budget is never kept.
+ */
+export function variantLru<T>(
+  maxBytes: number,
+  sizeOf: (value: T) => number | undefined,
+): VariantLru<T> {
+  const kept = new Map<string, { readonly value: T; readonly bytes: number }>();
+  const flying = new Map<string, Promise<T>>();
+  let total = 0;
+
+  const keep = (key: string, value: T): void => {
+    const bytes = sizeOf(value);
+    if (bytes === undefined || bytes > maxBytes) return;
+    kept.set(key, { value, bytes });
+    total += bytes;
+    // A Map iterates in insertion order, and a hit re-inserts: the first key is the coldest.
+    for (const [cold, entry] of kept) {
+      if (total <= maxBytes) break;
+      kept.delete(cold);
+      total -= entry.bytes;
+    }
+  };
+
+  return {
+    get(key, make) {
+      const hit = kept.get(key);
+      if (hit !== undefined) {
+        kept.delete(key);
+        kept.set(key, hit);
+        return Promise.resolve(hit.value);
+      }
+      const pending = flying.get(key);
+      if (pending !== undefined) return pending;
+      const made = make()
+        .then((value) => {
+          keep(key, value);
+          return value;
+        })
+        .finally(() => flying.delete(key));
+      flying.set(key, made);
+      return made;
+    },
+  };
+}

package/src/runtime-assets-site.ts

@@ -0,0 +1,136 @@
+// The variants of a public site image, served: `responsiveImage({ src: asset('assets/hero.png') })`
+// mints `?w=&f=` candidates, and `/assets` answered every one with the full original. This wraps the
+// plain route with exactly the variants the markup can mint for that source, decoded once per
+// content hash through the pipeline `/media` uses — and refuses every other query before a decode.
+
+import { finiteCount, probeImage, sniffImageFormat } from '@ultimat3/core';
+import type { Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse } from '@ultimat3/http';
+import type { ImageQuery, ImageTransformDriver } from '@ultimat3/seo';
+import {
+  builtinImageDriver,
+  DEFAULT_FORMATS,
+  DEFAULT_WIDTHS,
+  parseImageQuery,
+  usableWidths,
+} from '@ultimat3/seo';
+import { variantLru } from './runtime-assets-site-cache';
+import { SITE_ASSET_CACHE, siteAssetRoutes } from './site-asset-routes';
+import type { SiteAsset, SiteAssetTable } from './site-assets';
+import { parseHashedAssetUrl } from './site-assets';
+
+/** What one process holds of decoded variants. Bounded: an edited asset in `x dev` adds entries. */
+export const SITE_VARIANT_CACHE_BYTES = 64 * 1024 * 1024;
+
+/** The sources core's pipeline decodes. An SVG, an icon or a film has no width to resize to. */
+const RASTERS: ReadonlySet<string> = new Set(['png', 'jpeg', 'webp', 'gif']);
+
+export interface SiteVariantOptions {
+  /** `assetRoutes`' `images`: one driver for `/media` and `/assets`. Omitted, core's pipeline. */
+  readonly images?: ImageTransformDriver | undefined;
+  /** Bytes of variants kept in memory, least recently used evicted. */
+  readonly cacheBytes?: number;
+}
+
+type Answer =
+  | { readonly bytes: Uint8Array; readonly contentType: string }
+  | { readonly refused: string; readonly widths: readonly number[] };
+
+const undeclared = (asset: SiteAsset, cause: string, widths: readonly number[]): Response =>
+  jsonResponse(
+    {
+      ok: false,
+      error: {
+        code: 'X_ASSET_VARIANT_UNDECLARED',
+        cause: `${asset.url}: ${cause} — /assets answers only the variants responsiveImage() mints, so a public URL is never a resize service`,
+        fix: `responsiveImage({ src: asset('${asset.path}'), width, height, alt })   # declared here: ?w=${widths.join('|') || 'none'} with ?f=${DEFAULT_FORMATS.join('|')} or no f; an upload under /media answers any width`,
+        meta: { url: asset.url, widths: [...widths], formats: [...DEFAULT_FORMATS] },
+      },
+    },
+    { status: 404 },
+  );
+
+/**
+ * Why a query names no declared variant, or `undefined` when it names one. Widths are the srcset's
+ * own (`usableWidths` over `DEFAULT_WIDTHS`, asked rather than restated), formats `DEFAULT_FORMATS`
+ * or the source's own, and never a quality: `responsiveImage` writes none.
+ */
+function undeclaredBy(query: ImageQuery, widths: readonly number[]): string | undefined {
+  if (query.quality !== undefined) return `?q=${String(query.quality)} is a quality`;
+  if (query.format !== undefined && !(DEFAULT_FORMATS as readonly string[]).includes(query.format))
+    return `?f=${query.format} is not an offered format`;
+  if (query.width !== undefined && !widths.includes(query.width))
+    return `?w=${String(query.width)} is not a srcset width of this source`;
+  return undefined;
+}
+
+/** The current asset a pathname names, or `undefined` for whatever the plain route answers. */
+function currentAsset(table: SiteAssetTable, pathname: string): SiteAsset | undefined {
+  const named = parseHashedAssetUrl(pathname);
+  if (named === undefined) return undefined;
+  try {
+    const asset = table.resolve(named.path);
+    return asset.hash === named.hash ? asset : undefined;
+  } catch {
+    // The plain route answers a missing file with its own code; this one only stands aside.
+    return undefined;
+  }
+}
+
+/**
+ * `/assets/*file`, the plain route for every request without a transform query — and for a URL
+ * that names no current asset, so a stale hash keeps its one answer — and a declared variant else.
+ */
+export function siteAssetVariantRoutes(
+  table: SiteAssetTable,
+  options: SiteVariantOptions = {},
+): readonly Route[] {
+  const cache = variantLru<Answer>(
+    finiteCount(
+      'siteAssetVariantRoutes',
+      'cacheBytes',
+      options.cacheBytes ?? SITE_VARIANT_CACHE_BYTES,
+    ),
+    (answer) => ('bytes' in answer ? answer.bytes.byteLength : undefined),
+  );
+  return siteAssetRoutes(table).map((plain) => ({
+    ...plain,
+    handler: async (request: UltimateRequest, ctx): Promise<Response> => {
+      const query = parseImageQuery(request.url.searchParams);
+      const asset = query === null ? undefined : currentAsset(table, request.pathname);
+      if (query === null || asset === undefined) return plain.handler(request, ctx);
+
+      const key = `${asset.hash}:${String(query.width ?? 'own')}:${query.format ?? 'own'}:${String(query.quality ?? '')}`;
+      const answer = await cache.get(key, async (): Promise<Answer> => {
+        const source = await Bun.file(asset.file).bytes();
+        const format = sniffImageFormat(source);
+        if (format === null || !RASTERS.has(format)) {
+          return { refused: 'the file is not a raster image', widths: [] };
+        }
+        // A header read: past `MAX_IMAGE_PIXELS` it is core's `X_IMAGE_TOO_LARGE`, before a decode.
+        const intrinsic = probeImage(source).width;
+        const widths = usableWidths(intrinsic, DEFAULT_WIDTHS);
+        const why = undeclaredBy(query, widths);
+        if (why !== undefined) return { refused: why, widths };
+        const driver = options.images ?? builtinImageDriver({ read: async () => source });
+        const made = await driver.transform({
+          src: asset.url,
+          width: query.width ?? intrinsic,
+          ...(query.format === undefined ? {} : { format: query.format }),
+        });
+        return { bytes: made.bytes, contentType: made.contentType };
+      });
+      if ('refused' in answer) return undeclared(asset, answer.refused, answer.widths);
+      return applyCacheHeaders(
+        // Copied: a `Uint8Array` may sit on a `SharedArrayBuffer`, which `Response` refuses.
+        new Response(new Uint8Array(answer.bytes), {
+          headers: {
+            'content-type': answer.contentType,
+            'content-length': String(answer.bytes.byteLength),
+          },
+        }),
+        SITE_ASSET_CACHE,
+      );
+    },
+  }));
+}

package/src/runtime-assets.ts

@@ -6,12 +6,19 @@
 // from `runtime-storage.ts`, because the same bytes are reachable through both.
 
 import { probeImage } from '@ultimat3/core';
-import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders } from '@ultimat3/http';
+import type { ObjectSource, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders, notModified, objectResponse } from '@ultimat3/http';
 import type { ImageQuery, ImageTransformDriver } from '@ultimat3/seo';
 import { builtinImageDriver, DEFAULT_WIDTHS, parseImageQuery, usableWidths } from '@ultimat3/seo';
-import type { ImageTransform, Storage, VariantFormat } from '@ultimat3/storage';
-import { DEFAULT_QUALITY, isTenantScoped, isVariantFormat, variantKey } from '@ultimat3/storage';
+import type { ImageTransform, Storage, StorageObject, VariantFormat } from '@ultimat3/storage';
+import {
+  DEFAULT_QUALITY,
+  isVariantFormat,
+  objectNotFound,
+  variantFormatOf,
+  variantKey,
+  variantRevision,
+} from '@ultimat3/storage';
 import { faviconRoute } from './favicon';
 // The icon matrix's source, its base path and its renderer live in their own module so that
 // `pwa-artifacts.ts` — which this file imports for the manifest route — can reach them without
@@ -21,15 +28,16 @@ import { iconPlan, iconRenderer } from './icon-assets';
 import type { PwaArtifacts } from './pwa-artifacts';
 import { pwaManifestRoute } from './pwa-artifacts';
 import { revalidatedResponse } from './revalidated-response';
+import { siteAssetVariantRoutes } from './runtime-assets-site';
 import {
   AUTHORIZED_OBJECT_CACHE,
   assertReadableKey,
+  assertVariantCurrent,
   authorizeStorageRead,
+  readStorageObject,
   STORAGE_READ_PERMISSION,
 } from './runtime-storage';
-import { siteAssetRoutes } from './site-asset-routes';
 import { siteAssetTable } from './site-assets';
-import { storedObjectHeaders } from './stored-object-headers';
 
 /**
  * Storage-backed images. `responsiveImage({ src: '/media/<key>' })` mints its variants under it.
@@ -42,14 +50,6 @@ import { storedObjectHeaders } from './stored-object-headers';
  */
 export const MEDIA_BASE_PATH = '/media';
 
-/**
- * A content-addressed variant answers forever with the same bytes, so the immutable hint is a fact
- * about the key. It is NOT a fact about this route — see `mediaCache`. The generated ICONS are not
- * content-addressed (`/icons/icon-192.png` names a size, not bytes), so they revalidate instead —
- * see `revalidatedResponse`.
- */
-const IMMUTABLE_IMAGE: CacheHint = { mode: 'immutable' };
-
 /**
  * Whether a variant is one the framework itself can MINT, and therefore one worth storing.
  *
@@ -78,65 +78,105 @@ const isMintableWidth = (width: number | undefined, intrinsic: number): boolean
 const isMintableQuality = (quality: number | undefined): boolean =>
   quality === undefined || quality === DEFAULT_QUALITY;
 
-const imageResponse = (bytes: Uint8Array, contentType: string, cache: CacheHint): Response =>
-  applyCacheHeaders(
-    // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
-    // `SharedArrayBuffer`, which `Response` does not accept, and copying is what makes that true
-    // by construction rather than by a cast that would only silence it.
-    new Response(new Uint8Array(bytes), {
-      headers: { 'content-type': contentType, ...storedObjectHeaders(contentType) },
-    }),
-    cache,
-  );
-
 /**
- * Immutable is a claim about the KEY, and a tenant-scoped key names one org's private object: a
- * CDN or shared proxy that stores it under a public URL for a year hands it to every other tenant,
- * which is the cross-tenant read one hop removed. `/media` declared `public, max-age=31536000,
- * immutable` for exactly those keys until this branch. Applied in the handler rather than declared
- * in `meta.cache` because the posture is decided by the key, which no route declaration can see —
- * the pipeline's `cache-headers` stage only fills a `cache-control` a handler did not set.
+ * Bytes already in hand, as `objectResponse` asks for them. Copied, not passed through: a
+ * `Uint8Array<ArrayBufferLike>` may be backed by a `SharedArrayBuffer`, which `Response` does not
+ * accept, and copying is what makes that true by construction rather than by a cast.
  */
-const mediaCache = (key: string): CacheHint =>
-  isTenantScoped(key) ? AUTHORIZED_OBJECT_CACHE : IMMUTABLE_IMAGE;
+const heldBytes = (bytes: Uint8Array): ObjectSource['open'] => {
+  const body = new Uint8Array(bytes);
+  return (range) => (range === undefined ? body : body.subarray(range.start, range.end + 1));
+};
 
 /**
  * `exactOptionalPropertyTypes` makes an explicit `undefined` a different answer from an absent
  * key, and `variantKey` reads presence — so a spread, never an assignment.
  */
-function storageTransform(query: ImageQuery, format: VariantFormat | undefined): ImageTransform {
+function storageTransform(
+  query: ImageQuery,
+  format: VariantFormat,
+  revision: string,
+): ImageTransform {
   return {
     ...(query.width === undefined ? {} : { width: query.width }),
-    ...(format === undefined ? {} : { format }),
+    format,
     ...(query.quality === undefined ? {} : { quality: query.quality }),
+    revision,
   };
 }
 
 /**
- * A cache hit costs one `exists` and one `get`; a miss costs a decode. The source is read once
- * either way and handed to the driver rather than fetched again — `read` exists so seo never has
- * to guess whether a `src` is a path, a key or a URL, and here it is unambiguously a storage key.
+ * The validator of one transform of one revision of a source. Built only from the source's own
+ * etag and values this route parsed, so a `?f=` no format names never reaches a header: `undefined`
+ * there, and the driver refuses that URL. An unknowable source etag is `undefined` too.
+ */
+function variantEtag(
+  source: StorageObject,
+  query: ImageQuery,
+  format: VariantFormat | undefined,
+): string | undefined {
+  const bare = source.etag.replace(/^(W\/)?"|"$/g, '');
+  if (bare === '') return undefined;
+  if (format === undefined && query.format !== undefined) return undefined;
+  const transform = [
+    query.width === undefined ? 'intrinsic' : `w${query.width}`,
+    format ?? 'source',
+    ...(query.quality === undefined ? [] : [`q${query.quality}`]),
+  ];
+  return `"${bare}-${transform.join('-')}"`;
+}
+
+/**
+ * The source is STATED first, so a deleted one is `X_STORAGE_NOT_FOUND` on every disk before any
+ * variant is consulted, and its etag decides the key: a variant is looked up under the revision and
+ * the format it would be made in, so an overwrite misses it and `?w=` cannot share a key with
+ * `?w=&f=webp`. A key no one can state honestly (a `gif`, an unknowable etag) is served, never
+ * stored. A revalidation costs one `stat`, a hit one `exists` and one `get`, a miss a decode.
  */
 async function transformedVariant(
   storage: Storage,
+  request: UltimateRequest,
   key: string,
   query: ImageQuery,
   images: ImageTransformDriver | undefined,
 ): Promise<Response> {
   const disk = storage.disk();
+  await assertVariantCurrent(disk, storage.defaultDisk, key);
+  const object = await disk.stat(key);
+  if (object === undefined) throw objectNotFound(storage.defaultDisk, key);
+
   // A format storage cannot name has no variant key, so it cannot be cached. The driver refuses
   // it with core's `X_IMAGE_UNSUPPORTED`; refusing it here too would give one bad URL two codes.
+  const named = query.format;
   const format =
-    query.format !== undefined && isVariantFormat(query.format) ? query.format : undefined;
-  const cacheable = query.format === undefined || format !== undefined;
-  const cached = cacheable ? variantKey(key, storageTransform(query, format)) : undefined;
-  // The SOURCE key decides the posture, not the variant's: `variantKey` keeps the source's prefix,
-  // so a variant of `org/<id>/…` is one org's object too, and reading the hint off the derived key
-  // would be a second answer to a question the source already settled.
-  const cache = mediaCache(key);
+    named === undefined
+      ? variantFormatOf(object.contentType)
+      : isVariantFormat(named)
+        ? named
+        : undefined;
+  const revision = variantRevision(object.etag);
+  const cached =
+    format === undefined || revision === undefined
+      ? undefined
+      : variantKey(key, storageTransform(query, format, revision));
+
+  const etag = variantEtag(object, query, format);
+  // Before anything is read: this is the request a revalidating browser makes for every image.
+  const fresh = etag === undefined ? undefined : notModified(request, etag);
+  if (fresh !== undefined) return applyCacheHeaders(fresh, AUTHORIZED_OBJECT_CACHE);
+  const answer = (contentType: string, bytes: Uint8Array): Promise<Response> =>
+    objectResponse(
+      request,
+      {
+        object: { contentType, size: bytes.byteLength, etag },
+        open: heldBytes(bytes),
+      },
+      { cache: AUTHORIZED_OBJECT_CACHE },
+    );
+
   if (cached !== undefined && (await disk.exists(cached))) {
     const hit = await disk.get(cached);
-    return imageResponse(hit.bytes, hit.object.contentType, cache);
+    return answer(hit.object.contentType, hit.bytes);
   }
 
   const source = await disk.get(key);
@@ -157,12 +197,15 @@ async function transformedVariant(
   });
   if (
     cached !== undefined &&
+    // The bytes just decoded are the revision the key names, or an overwrite landed in between and
+    // this variant would answer for bytes it was not made from.
+    source.object.etag === object.etag &&
     isMintableWidth(query.width, intrinsic) &&
     isMintableQuality(query.quality)
   ) {
     await disk.put(cached, variant.bytes, { contentType: variant.contentType });
   }
-  return imageResponse(variant.bytes, variant.contentType, cache);
+  return answer(variant.contentType, variant.bytes);
 }
 
 /**
@@ -181,17 +224,17 @@ async function mediaResponse(
   authorizeStorageRead({ disk: storage.defaultDisk, key: requested }, ctx);
   const key = assertReadableKey(storage, storage.defaultDisk, requested, ctx.actor);
   const query = parseImageQuery(request.url.searchParams);
-  if (query !== null) return transformedVariant(storage, key, query, images);
-  // No transform asked for: the object itself, still under the storage key's own safety checks.
-  const read = await storage.disk().get(key);
-  return imageResponse(read.bytes, read.object.contentType, mediaCache(key));
+  if (query !== null) return transformedVariant(storage, request, key, query, images);
+  // No transform asked for: the object itself, read and answered exactly as `/_storage` answers it.
+  const served = await readStorageObject(storage, { disk: storage.defaultDisk, key }, ctx.actor);
+  return objectResponse(request, served, { cache: AUTHORIZED_OBJECT_CACHE });
 }
 
 export interface AssetRoutesOptions {
   /** App root. The source icon is resolved against it; storage keys never are. */
   readonly root: string;
   readonly storage: Storage;
-  /** Replaces `builtinImageDriver` for `/media/*`. Omitted, core's PNG/JPEG/WebP pipeline. */
+  /** Replaces `builtinImageDriver` for `/media/*` and `/assets/*`. Omitted, core's pipeline. */
   readonly images?: ImageTransformDriver;
   /**
    * `manifest.webmanifest`, resolved at boot by `pwa-artifacts.ts`. Absent when the app declares
@@ -230,7 +273,7 @@ export function assetRoutes(options: AssetRoutesOptions): readonly Route[] {
   // whatever is on the app's only disk, which is every tenant's uploads, so it takes `/_storage`'s
   // declaration verbatim. `enforcedBy: 'handler'` for the reason that route gives — the `authz`
   // stage resolves a policy from `@ultimat3/render`'s page table, which this route is not in.
-  // `cache` declares the conservative posture; `mediaCache` narrows or widens it per key.
+  // No key's bytes are fixed and every answer is authorized for one actor, so one posture for all.
   routes.push({
     method: 'GET',
     path: `${MEDIA_BASE_PATH}/*key`,
@@ -252,8 +295,9 @@ export function assetRoutes(options: AssetRoutesOptions): readonly Route[] {
   routes.push(faviconRoute(options.root));
   // And every other public file of the site: `apps/web/site/assets/**` at the hashed URLs
   // `asset()` mints, immutable. The same table `loadApp` installed for the renderer, so the URL a
-  // document names and the URL this answers are one computation.
-  routes.push(...siteAssetRoutes(siteAssetTable(options.root)));
+  // document names and the URL this answers are one computation. A raster also answers the
+  // `?w=&f=` variants a served `responsiveImage` mints for it, through the same driver as `/media`.
+  routes.push(...siteAssetVariantRoutes(siteAssetTable(options.root), { images: options.images }));
   // Same rule one asset further along: the icons above are the ones this manifest NAMES, so the
   // two belong to one surface and cannot be mounted from two places without drifting apart.
   if (options.pwa !== undefined) routes.push(pwaManifestRoute(options.pwa));

package/src/runtime-bindings.ts

@@ -5,6 +5,8 @@
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import type { RealtimeConfig } from '@ultimat3/core';
+import { renderThrowable } from '@ultimat3/core';
+import { StorageUnwritableError } from './errors';
 import { REALTIME_DEFAULTS } from './runtime-realtime';
 import { safeUrlLabel } from './safe-url-label';
 
@@ -57,6 +59,22 @@ const s3EndpointOf = (env: Env): string | undefined => nonEmpty(env['S3_ENDPOINT
  */
 export const storageIsExternal = (env: Env): boolean => s3EndpointOf(env) !== undefined;
 
+/**
+ * `.x/`, coded. A read-only root filesystem (the chart's `readOnlyRootFilesystem: true`) with
+ * `DATABASE_URL` set and no `S3_ENDPOINT` threw a bare `EROFS`/`EACCES` here — every role,
+ * `ROLE=migrate` included — before `startStorage`'s own coded refusal of the same disk could run.
+ */
+function makeStateDir(stateDir: string): void {
+  try {
+    mkdirSync(stateDir, { recursive: true });
+  } catch (cause) {
+    throw new StorageUnwritableError(
+      `the embedded database or storage disk needs the state directory ${stateDir} and it could not be created: ${renderThrowable(cause)}`,
+      `export ULTIMATE_STATE_DIR=/tmp/ultimate-state   # any writable directory or volume; or set DATABASE_URL, S3_ENDPOINT and S3_BUCKET so nothing embedded needs ${stateDir}`,
+    );
+  }
+}
+
 /**
  * Embedded Postgres is PGlite on disk under `.x/`, so a restart keeps the data and a `x db reset`
  * is a directory delete rather than a container dance.
@@ -76,9 +94,7 @@ export function resolveServices(
   // do, in-process events never touch the disk. A container whose bindings are external runs
   // non-root over a read-only app directory, and a mkdir there is an EACCES at boot for a directory
   // that would have stayed empty — which an unset NATS_URL alone used to trigger.
-  if (databaseUrl === undefined || s3Endpoint === undefined) {
-    mkdirSync(stateDir, { recursive: true });
-  }
+  if (databaseUrl === undefined || s3Endpoint === undefined) makeStateDir(stateDir);
   return {
     root,
     stateDir,

package/src/runtime-cache.ts

@@ -4,7 +4,7 @@
 // and lru unconditionally, redis on `REDIS_URL` and cdn on any real purge driver, so the key was
 // declared, validated at boot, documented, and read by nothing.
 
-import type { CacheTier, PurgeDriver } from '@ultimat3/cache';
+import type { CacheTier, PurgeDriver, RedisLike } from '@ultimat3/cache';
 import {
   CacheDriverUnavailableError,
   cdnTier,
@@ -28,6 +28,7 @@ import {
   logger,
   renderThrowable,
 } from '@ultimat3/core';
+import { redisClient, redisUrlSource } from '@ultimat3/core/redis';
 import type { Transport, TransportSubscription } from '@ultimat3/realtime/server';
 import type { Env } from './runtime-bindings';
 
@@ -69,6 +70,8 @@ export interface CacheTiersOptions {
    * `FIRST_DIAL_GRACE_MS`; a test of an OUTAGE passes 0.
    */
   readonly firstDialGraceMs?: number | undefined;
+  /** The client a `redis` rung reads, for the URL `env` names. Default core's `redisClient`. */
+  readonly redisClient?: ((url: string) => RedisLike) | undefined;
 }
 
 /**
@@ -100,14 +103,15 @@ export const cacheTiersOf = (config: AppConfig | undefined): readonly CacheTierN
   config?.cache.tiers ?? DEFAULT_CACHE_TIERS;
 
 /**
- * `REDIS_URL` is the same "an unset variable means the embedded default" law the db, events,
- * storage, mail and CDN bindings follow — and it is the variable Bun's own `Bun.redis` reads, so a
- * tier selected here and a client built there cannot point at two servers.
+ * The client for `url`, built at its first command, never at selection: `redisTier` dials nothing
+ * until it is read, and handing it a built client would dial at boot. `client` is memoised per URL
+ * (core's `redisClient`), so asking it per command is one lookup.
  */
-function redisUrl(env: Env): string | undefined {
-  const url = env['REDIS_URL']?.trim();
-  return url === undefined || url === '' ? undefined : url;
-}
+const lazyRedis = (url: string, client: (url: string) => RedisLike): RedisLike => ({
+  get: (key) => client(url).get(key),
+  set: (key, value) => client(url).set(key, value),
+  send: (command, args) => client(url).send(command, args),
+});
 
 /**
  * One rung, or a refusal. A process that cannot build what it was configured to build must not
@@ -125,16 +129,20 @@ function buildTier(name: CacheTierName, options: CacheTiersOptions): CacheTier {
       return memoTier();
     case 'lru':
       return lruTier();
-    case 'redis':
-      if (redisUrl(options.env) === undefined) {
+    case 'redis': {
+      // `REDIS_URL` then `VALKEY_URL`, out of the boot's env: core's own order (`redisUrlSource`),
+      // so the URL checked here is the URL the client dials.
+      const source = redisUrlSource(options.env);
+      if (source === undefined) {
         throw new CacheDriverUnavailableError({
           driver: 'redis',
           cause:
-            'cache.tiers names it and REDIS_URL is unset, so this process would read a per-process ladder while the config declares a shared one',
+            'cache.tiers names it and REDIS_URL (or VALKEY_URL) is unset, so this process would read a per-process ladder while the config declares a shared one',
           fix: 'set REDIS_URL in .env, or drop the redis tier from cache.tiers in app.config.ts',
         });
       }
-      return redisTier();
+      return redisTier({ client: lazyRedis(source.url, options.redisClient ?? redisClient) });
+    }
     case 'cdn':
       // A noop tier would put a `cdn` line in every invalidation report claiming keys an edge that
       // does not exist had accepted — and the `/_x` cache panel renders those reports, so the lie
@@ -159,8 +167,9 @@ function buildTier(name: CacheTierName, options: CacheTiersOptions): CacheTier {
  */
 function warnUnnamed(options: CacheTiersOptions): void {
   const named = new Set(options.tiers);
-  if (!named.has('redis') && redisUrl(options.env) !== undefined) {
-    logger.warn('cache.tier.unnamed', { tier: 'redis', source: 'REDIS_URL' });
+  const redis = redisUrlSource(options.env);
+  if (!named.has('redis') && redis !== undefined) {
+    logger.warn('cache.tier.unnamed', { tier: 'redis', source: redis.key });
   }
   if (!named.has('cdn') && !isNoopPurgeDriver(options.purge)) {
     logger.warn('cache.tier.unnamed', { tier: 'cdn', source: options.purge.name });