@warlock.js/core 5.30.0 → 5.32.0

package/esm/http/types.d.mts

@@ -1,18 +1,20 @@
 import { HttpRateLimitConfig } from "./build-rate-limit-options.mjs";
+import { StreamQueueOptions } from "./bounded-stream-queue.mjs";
 import { HttpLoggingConfig } from "./request-log-snapshot.mjs";
 import { Response } from "./response.mjs";
 import { CspConfig } from "./csp.mjs";
 import { HttpErrorMapper } from "./error-mapper.mjs";
 import { HttpTracingConfig } from "./tracing/tracing.type.mjs";
 import { Middleware } from "../router/types.mjs";
+import "../router/index.mjs";
 import { FastifyHttpOptions } from "fastify";
 import { CookieSerializeOptions } from "@fastify/cookie";
 import { FastifyCorsOptions } from "@fastify/cors";
 import { Server } from "node:http";
+import { SecureServerOptions } from "node:http2";
 import React from "react";
-
 //#region ../../packages/core/src/http/types.d.ts
-type RequestEvent = "executingMiddleware" | "executedMiddleware" | "executingAction" | "executedAction";
+export type RequestEvent = "executingMiddleware" | "executedMiddleware" | "executingAction" | "executedAction";
 /**
  * Private, server-only, per-request data bag — `request.locals`.
  *
@@ -36,7 +38,7 @@ type RequestEvent = "executingMiddleware" | "executedMiddleware" | "executingAct
  * }
  * ```
  */
-interface RequestLocals {
+export interface RequestLocals {
   /**
    * Whether this request has, at any point, been assigned a
    * `decodedAccessToken` — set by its accessor in `request.ts`, never by
@@ -64,105 +66,105 @@ interface RequestLocals {
  * `interface`, because nothing in core augments it — auth's own richer
  * shape is simply assignable here.
  */
-type DecodedAccessToken = {
+export type DecodedAccessToken = {
   userType?: string;
 };
 /**
  * Allowed response type
  */
-type ReturnedResponse =
+export type ReturnedResponse =
 /**
  * Can be a response object
  */
-Response
+Response |
 /**
  * Or a promise returning a response object
  */
-| Promise<Response>
+Promise<Response> |
 /**
  * Or an object
  */
-| Record<string, any>
+Record<string, any> |
 /**
  * Or a promise returning an object
  */
-| Promise<Record<string, any>>
+Promise<Record<string, any>> |
 /**
  * Or an array
  */
-| any[]
+any[] |
 /**
  * Or a promise returning an array
  */
-| Promise<any[]>;
+Promise<any[]>;
 /**
  * Response Event Types
  */
-type ResponseEvent =
+export type ResponseEvent =
 /**
  * Triggered before sending the response
  */
-"sending"
+"sending" |
 /**
  * Triggered before sending json response
  */
-| "sendingJson"
+"sendingJson" |
 /**
  * Triggered after sending success json response
  */
-| "sendingSuccessJson"
+"sendingSuccessJson" |
 /**
  * Triggered after sending bad request json response
  */
-| "sendingBadRequestJson"
+"sendingBadRequestJson" |
 /**
  * Triggered after sending the response regardless of the response status code
  */
-| "sent"
+"sent" |
 /**
  * Triggered after sending the response if the response status code is 2xx
  */
-| "success"
+"success" |
 /**
  * Triggered after sending the response if the response status code is 201
  */
-| "successCreate"
+"successCreate" |
 /**
  * Triggered after sending the response if the response status code is 400
  */
-| "badRequest"
+"badRequest" |
 /**
  * Triggered after sending the response if the response status code is 401
  */
-| "unauthorized"
+"unauthorized" |
 /**
  * Triggered after sending the response if the response status code is 403
  */
-| "forbidden"
+"forbidden" |
 /**
  * Triggered after sending the response if the response status code is 404
  */
-| "notFound"
+"notFound" |
 /**
  * Triggered after sending the response if the response status code is 413
  */
-| "contentTooLarge"
+"contentTooLarge" |
 /**
  * Triggered after sending the response if the response status code is 429
  */
-| "throttled"
+"throttled" |
 /**
  * Triggered after sending the response if the response status code is 500
  */
-| "serverError"
+"serverError" |
 /**
  * Triggered after sending the response if the response status code is 4xx or 5xx
  */
-| "error";
+"error";
 /**
  * Partial Middleware
  */
-interface PartialMiddleware {
+export interface PartialMiddleware {
   /**
    * Routes list
    * @example routes: ["/users", "/posts"]
@@ -188,11 +190,16 @@ interface PartialMiddleware {
  * `gracefulShutdown.forceCloseConnections`) have their own `http.*` keys;
  * setting them here as well overrides those keys.
  */
-type HttpServerOptions = FastifyHttpOptions<Server>;
+export type HttpServerOptions = Omit<FastifyHttpOptions<Server>, "http2"> & {
+  /** Enable HTTP/2 while retaining the framework's HTTP-compatible reply API. */
+  http2?: boolean;
+  https?: SecureServerOptions;
+  http2SessionTimeout?: number;
+};
 /**
  * Http Configurations list
  */
-interface HttpConfigurations {
+export interface HttpConfigurations {
   /**
    * Options for the underlying Fastify server, applied when it is created.
    *
@@ -228,6 +235,14 @@ interface HttpConfigurations {
    * handling. See {@link HttpErrorMapper}.
    */
   errorMapper?: HttpErrorMapper;
+  /**
+   * In `warlock dev`, warn once per route about POST/PUT/PATCH/DELETE routes
+   * that have no auth middleware and no `public: true`. Development only;
+   * production never checks. Set `false` to silence the warning entirely.
+   *
+   * @default true
+   */
+  warnUnguardedRoutes?: boolean;
   /**
    * Server port
    */
@@ -453,6 +468,13 @@ interface HttpConfigurations {
      * @default "/ready"
      */
     readinessPath?: string;
+    /**
+     * Include built-in liveness/readiness probes in the global rate-limit policy.
+     * Leave false so client traffic cannot exhaust infrastructure probe quotas.
+     *
+     * @default false
+     */
+    rateLimit?: boolean;
   };
   /**
    * Host
@@ -485,7 +507,9 @@ interface HttpConfigurations {
 /**
  * Options for `response.stream()`.
  */
-type ResponseStreamOptions = {
+export type ResponseStreamOptions = StreamQueueOptions & {
+  /** Application/cache headers override defaults before flushing; framing and connection headers are ignored. */
+  headers?: Record<string, string>;
   /**
    * How many of the most recent chunks (from `send()`, `write()` and
    * `render()`) to keep on `response.body` after `end()`, for logging and
@@ -496,7 +520,7 @@ type ResponseStreamOptions = {
    */
   retainChunks?: number;
 };
-type ResponseStreamController = {
+export type ResponseStreamController = {
   /**
    * Send data to the client. Does not wait for the client; for long-lived or
    * high-volume streams use `write()` (or `drain()`) so the producer slows
@@ -504,10 +528,13 @@ type ResponseStreamController = {
    * client disconnected; throws after `end()`.
    */
   send: (data: string | Uint8Array) => void;
+  /** Bounded synchronous write; false when closed or overflow rejects this chunk. */
+  enqueue: (data: string | Uint8Array) => boolean;
   /**
    * Send data and wait until the transport can take more. Resolves `true`
    * when it can, `false` when the stream ended or the client disconnected —
-   * stop producing then.
+   * stop producing then. In drop mode, true means the stream is ready to continue;
+   * inspect dropped to detect rejected output and schedule a resync.
    */
   write: (data: string | Uint8Array) => Promise<boolean>;
   /**
@@ -537,6 +564,8 @@ type ResponseStreamController = {
    * Whether the transport is currently holding more than its high-water mark.
    */
   backpressured: boolean;
+  /** Chunks/events/comments rejected by onOverflow: "drop", including send/write/render paths. */
+  readonly dropped: number;
   /**
    * Detect whether stream is ended (by `end()` or a client disconnect)
    */
@@ -545,7 +574,9 @@ type ResponseStreamController = {
 /**
  * Options for `response.sse()`.
  */
-type ResponseSSEOptions = {
+export type ResponseSSEOptions = StreamQueueOptions & {
+  /** Application/cache headers override defaults before flushing; framing and connection headers are ignored. */
+  headers?: Record<string, string>;
   /**
    * How many of the most recent events to keep on `response.body` after
    * `end()`, for logging and debugging. Sent events are otherwise not kept,
@@ -555,7 +586,11 @@ type ResponseSSEOptions = {
    */
   retainEvents?: number;
 };
-type ResponseSSEController = {
+/** Wire serialization for one SSE event. Raw strings are split into safe data lines. */
+export type ResponseSSEMessageOptions = {
+  raw?: boolean;
+};
+export type ResponseSSEController = {
   /**
    * Send an SSE event to the client. Does not wait for the client; for
    * long-lived or high-volume streams use `write()` (or `drain()`) so the
@@ -564,13 +599,16 @@ type ResponseSSEController = {
    * @param data - Event data (will be JSON stringified)
    * @param id - Optional event ID for client-side Last-Event-ID tracking
    */
-  send: (event: string, data: any, id?: string) => ResponseSSEController;
+  send: (event: string | undefined, data: any, id?: string, options?: ResponseSSEMessageOptions) => ResponseSSEController;
+  /** Bounded synchronous event; undefined event omits the event field. */
+  enqueue: (event: string | undefined, data: unknown, id?: string, options?: ResponseSSEMessageOptions) => boolean;
   /**
    * Send an SSE event and wait until the transport can take more.
    * Resolves `true` when it can, `false` when the stream ended or the client
-   * disconnected — stop producing then.
+   * disconnected — stop producing then. In drop mode, true means ready to continue;
+   * inspect dropped to detect rejected output and schedule a resync.
    */
-  write: (event: string, data: any, id?: string) => Promise<boolean>;
+  write: (event: string | undefined, data: any, id?: string, options?: ResponseSSEMessageOptions) => Promise<boolean>;
   /**
    * Wait until output buffered for the client has been flushed. Resolves
    * `true` immediately when nothing is backed up, `false` when the stream
@@ -586,6 +624,8 @@ type ResponseSSEController = {
    * Whether the transport is currently holding more than its high-water mark.
    */
   backpressured: boolean;
+  /** Chunks/events/comments rejected by onOverflow: "drop", including send/write/render paths. */
+  readonly dropped: number;
   /**
    * Send a comment to keep the connection alive (invisible to client)
    */
@@ -605,5 +645,4 @@ type ResponseSSEController = {
   ended: boolean;
 };
 //#endregion
-export { DecodedAccessToken, HttpConfigurations, HttpServerOptions, PartialMiddleware, RequestEvent, RequestLocals, ResponseEvent, ResponseSSEController, ResponseSSEOptions, ResponseStreamController, ResponseStreamOptions, ReturnedResponse };
 //# sourceMappingURL=types.d.mts.map

package/esm/http/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/http/types.ts"],"mappings":"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"}
+{"version":3,"file":"types.d.mts","names":["NodeHttpServer","Http2SecureOptions"],"sources":["../../../../../../../../packages/core/src/http/types.ts"],"mappings":";;;;;;;;;;;;;;;;YAeY;;;;;;;;;;;;;;;;;;;;;;;;iBA6BK;;;;;;;;;;;;;;EAcf;;;;;;;;;;;;;;YAeU;EACV;;;;;YAMU;;;;AAIR;;;;AAIA,QAAQ;;;;AAIR;;;;AAIA,QAAQ;;;;;;;;AAQR;;;;YAKQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiEK;;;;;EAKf;;;;;;EAMA;;;;EAIA,YAAY;;;;;;;;;;;YAYF,oBAAoB,KAAK,mBAAmBA;;EAEtD;EACA,QAAQC;EACR;;;;;iBAMe;;;;;;;;;;;;;;;;;;;EAmBf,gBAAgB;;;;;;;;;EAShB;;;;;;;EAOA,cAAc;;;;;;;;EAQd;;;;EAIA;;;;EAIA;;;;;;;EAOA,UAAU;;;;EAIV,OAAO;;;;;;EAMP;;;;;EAKA;;;;;;IAME;;;;;;IAMA;;;;;;IAMA;;;;;;;;;;;EAWF;;;;;;;;;;;;;;;;;;;;EAoBA,6CAA6C,iBAAiB;EAC9D;;;;IAIE;;;;IAIA,UAAU;;;;;;;;;;;EAWZ,MAAM;;;;EAIN,YAAY;;;;;;;;EAQZ;;;;;;IAME;;;;IAIA;;;;;;;IAOA;;;;;EAKF;;;;;;IAME;;;;;;IAMA;;;;;;;IAOA;;;;IAIA;;;;;EAKF;;;;;;;IAOE;;;;;;IAMA;;;;;;IAMA;;;;;EAKF;;;;;;;IAOE;;;;;;;;IAQA;;;;;EAKF;;;;;;IAME;;;;;;;IAOA;;;;;;;IAOA;;;;;;;IAOA;;;;;EAKF;;;;EAIA;;;;IAIE,MAAM;;;;IAIN,OAAO;;;;IAIP,SAAS;;;;;;;EAOX,UAAU;;;;;YAMA,wBAAwB;;EAElC,UAAU;;;;;;;;;EASV;;YAGU;;;;;;;EAOV,OAAO,eAAe;;EAEtB,UAAU,eAAe;;;;;;;EAOzB,QAAQ,eAAe,eAAe;;;;EAItC,SAAS,MAAM,MAAM;;;;;;EAMrB,aAAa;;;;EAIb;;;;EAIA,eAAe,wBAAwB;;;;;EAKvC,QAAQ;;;;EAIR;;WAES;;;;EAIT;;;;;YAMU,qBAAqB;;EAE/B,UAAU;;;;;;;;EAQV;;;YAIU;EAA8B;;YAE9B;;;;;;;;;EASV,OACE,2BACA,WACA,aACA,UAAU,8BACP;;EAEL,UACE,2BACA,eACA,aACA,UAAU;;;;;;;EAQZ,QACE,2BACA,WACA,aACA,UAAU,8BACP;;;;;;EAML,aAAa;;;;;EAKb,QAAQ;;;;EAIR;;WAES;;;;EAIT,UAAU,oBAAoB;;;;EAI9B,WAAW;;;;;EAKX,eAAe,wBAAwB;;;;EAIvC"}

package/esm/http/uploaded-file.d.mts

@@ -2,10 +2,11 @@ import { StorageFile } from "../storage/storage-file.mjs";
 import { ScopedStorage } from "../storage/scoped-storage.mjs";
 import { StorageDriverName } from "../storage/types.mjs";
 import { storage } from "../storage/storage.mjs";
+import "../storage/index.mjs";
 import { Image, ImageFormat, ImageTransformOptions } from "../image/image.mjs";
+import "../image/index.mjs";
 import { ImageTransformCallback, PrefixConfig, SaveAsOptions, SaveOptions, UploadedFileImageOptions } from "./uploads-types.mjs";
 import { MultipartFile } from "@fastify/multipart";
-
 //#region ../../packages/core/src/http/uploaded-file.d.ts
 type UploadedFileMetadata = {
   name: string;
@@ -23,7 +24,7 @@ type UploadedFileMetadata = {
  * the one exception and it is optional for exactly that reason: present when
  * the file has already been buffered, absent otherwise, never guessed.
  */
-type UploadedFileJson = {
+export type UploadedFileJson = {
   name: string;
   mimeType: string;
   extension: string;
@@ -35,7 +36,7 @@ type UploadedFileJson = {
 /**
  * Options for validating file before saving
  */
-type FileValidationOptions = {
+export type FileValidationOptions = {
   /**
    * List of allowed MIME types
    *
@@ -83,7 +84,7 @@ type FileValidationOptions = {
  * const file = await uploadedFile.use("s3").save("avatars");
  * ```
  */
-declare class UploadedFile {
+export declare class UploadedFile {
   protected readonly fileData: MultipartFile;
   /**
    * File buffered content
@@ -492,5 +493,5 @@ declare class UploadedFile {
   toBase64(): Promise<string>;
 }
 //#endregion
-export { FileValidationOptions, UploadedFile, UploadedFileJson };
+export {};
 //# sourceMappingURL=uploaded-file.d.mts.map

package/esm/http/uploaded-file.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"uploaded-file.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/http/uploaded-file.ts"],"mappings":"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"}
+{"version":3,"file":"uploaded-file.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/http/uploaded-file.ts"],"mappings":";;;;;;;;;;KAiBK;EACH;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;YAWU;EACV;EACA;EACA;EACA;EACA;EACA;EACA;;;;;YAMU;;;;;;EAMV;;;;;;EAOA;;;;;;EAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA+BW;qBA4C2B,UAAU;;;;;YAvCtC,sBAAsB;;;;;;EAOzB;;;;;YAMG,UAAU;;;;;YAMV,eAAe;;;;;YAMf,eAAe;;;;;YAMf,mBAAmB,wBAAwB;;;;;;;EAQrD,YAAsC,UAAU;;;;;;MAerC;;;;;;MASA;;;;;;MASA;;;;EAOE,YAAY,QAAQ;;;;;;EAsBpB,QAAQ;;;;;;EAUR,UAAU,QAAQ;;;;MAgBpB;;;;MAOA;;;;MAOA;;;;;;;;;;;;;;;;EAuBJ,IAAI,QAAQ;;;;;;;;;;;;;;;;EAwBZ,OAAO,eAAe;;;;;;;;;;;;;;;EAmBtB,QAAQ;;;;;;;;;;;;;;;EAsBR,OAAO,QAAQ;;;;;;;;;;;;EAgBf,OAAO;;;;;;;;;;;;EAgBP,KAAK;;;;;;;;;;;EAkBL;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCA,UAAU,QAAQ,wBAAwB;;;;;;;;;;;;;;;;;;EAsBpC,WAAW,QAAQ;;;;;;EAanB,cAAc;IAAU;IAAgB;;;;;;;;;;;;;;;;EA0BxC,SAAS,SAAS,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2D1C,KAAK,mBAAmB,UAAU,cAAc,QAAQ;;;;;;;;;;;;;;;;;EA8BxD,OAAO,kBAAkB,UAAU,gBAAgB,QAAQ;;;;;;MAc7D,eAAe;;;;;YAYV,eACd,kBACA,SAAS,oBACR,QAAQ;;;;;YA0BK,uBAAuB,QAAQ;;;;;YA4BrC,kBAAkB,KAAK,QAAQ;;;;;YAkC/B;;;;;YAQA,eAAe,SAAS,oBAAoB,uBAAuB;;;;;YAYnE,gBAAgB,UAAU;;;;;YAwB1B,cAAc,SAAS;;;;;YAiDvB,iBAAiB,gBAAgB;;;;;YASjC,WAAW;;;;;YAQX,cAAc,mBAAmB,gBAAgB;;;;;YAiBjD;;;;;YAiBA;;;;;YAgBA,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6C3B,UAAU;;;;;;;EAkBJ,YAAY"}

package/esm/http/uploads/generate-image-variant.mjs

@@ -1,5 +1,5 @@
-import path from "node:path";
 import { randomBytes } from "node:crypto";
+import path from "node:path";
 import fs from "node:fs/promises";
 
 //#region ../../packages/core/src/http/uploads/generate-image-variant.ts

package/esm/http/uploads/generate-image-variants.d.mts

@@ -1,15 +1,19 @@
+import { StorageDriverName } from "../../storage/types.mjs";
 import { GeneratedImageDescriptor } from "./image-variant-types.mjs";
-
 //#region ../../packages/core/src/http/uploads/generate-image-variants.d.ts
 /**
  * Options for `generateImageVariants`
  */
-type GenerateImageVariantsOptions = {
+export type GenerateImageVariantsOptions = {
   /**
    * Limit generation to these variant names, instead of every variant in
    * `uploads.images.variants`.
    */
   variants?: readonly string[];
+  /** Disk holding the source; defaults to the active disk. */
+  disk?: StorageDriverName;
+  /** Route prefix serving variants of this disk (and originals for local disks). Default /uploads. */
+  urlPrefix?: string;
 };
 /**
  * Render every configured variant of one uploaded image, right after it is
@@ -25,15 +29,15 @@ type GenerateImageVariantsOptions = {
  * The returned descriptor is plain JSON, safe to store next to the record
  * that owns the image, or to carry through loader data. On local storage the
  * `url`/`urls` already point at `uploadedFileController`; an app serving
- * uploads from object storage or a CDN should not proxy the remote files
- * through this route at all — store the descriptor once generation runs
- * against the same bucket the CDN serves from, or resolve its URLs through a
- * custom `ImageLoader` on the client instead.
+ * uploads from object storage use the driver URL for the original, and
+ * `options.urlPrefix` for the route serving locally cached derivatives.
+ * Ingest downloads a remote source once for all variants and formats.
+ * On-demand cache hits use ETag metadata; sources without ETags are hashed.
  *
  * @param relativePath - path of the saved upload, relative to the storage root
  * @param options.variants - limit generation to these variant names
- * @throws ImageVariantsConfigError when there is no local storage root, or
- * `uploads.images` is not configured — both are server misconfiguration, not
+ * @throws ImageVariantsConfigError when `uploads.images` is not
+ * configured — this is server misconfiguration, not
  * a bad request
  * @throws HttpError(400) when a name in `options.variants` is not declared in
  * `uploads.images.variants`
@@ -43,7 +47,6 @@ type GenerateImageVariantsOptions = {
  * `maxSourcePixels`
  * @throws HttpError(415) when the source is not jpeg, png, webp or avif
  */
-declare function generateImageVariants(relativePath: string, options?: GenerateImageVariantsOptions): Promise<GeneratedImageDescriptor>;
+export declare function generateImageVariants(relativePath: string, options?: GenerateImageVariantsOptions): Promise<GeneratedImageDescriptor>;
 //#endregion
-export { GenerateImageVariantsOptions, generateImageVariants };
 //# sourceMappingURL=generate-image-variants.d.mts.map

package/esm/http/uploads/generate-image-variants.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-image-variants.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/generate-image-variants.ts"],"mappings":";;;;;AAiCA;KAAY,4BAAA;;;AAKF;AA8EV;EA9EE,QAAQ;AAAA;;;;;;;;;;;;AAiFyB;;;;;;;;;;;;;;;;;;;;;iBAHb,qBAAA,CACpB,YAAA,UACA,OAAA,GAAS,4BAAA,GACR,OAAA,CAAQ,wBAAA"}
+{"version":3,"file":"generate-image-variants.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/generate-image-variants.ts"],"mappings":";;;;;;YAqCY;;;;;EAKV;;EAGA,OAAO;;EAGP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAoEoB,sBACpB,sBACA,UAAS,+BACR,QAAQ"}

package/esm/http/uploads/generate-image-variants.mjs

@@ -1,28 +1,22 @@
 import { HttpError } from "../errors/errors.mjs";
+import { ImageVariantsConfigError } from "./image-variants-config-error.mjs";
 import { uploadsConfig } from "../uploads-config.mjs";
 import { variantCacheKey, variantCachePath, variantGenerationTag, variantSourceDirectory, variantSourceKey } from "./variant-cache-key.mjs";
 import { pruneStaleVariantGenerationsIfCurrent, retryOnVanishedDirectory, warnIfVariantCacheIsPublic } from "./image-variant-cache.mjs";
-import { storage } from "../../storage/storage.mjs";
-import "../../storage/index.mjs";
 import { Image } from "../../image/image.mjs";
 import "../../image/index.mjs";
-import { generateImageVariant } from "./generate-image-variant.mjs";
-import { ImageVariantsConfigError } from "./image-variants-config-error.mjs";
+import { localDiskRoot } from "./local-disk-root.mjs";
 import { loadVariantSource } from "./load-variant-source.mjs";
+import { remoteVariantDisk, remoteVariantSource } from "./remote-variant-source.mjs";
+import { generateImageVariant } from "./generate-image-variant.mjs";
 import { resolveImageVariantsConfig } from "./resolve-image-variants-config.mjs";
-import { resolveVariantCandidate } from "./resolve-variant-candidate.mjs";
+import { freshImageVariant, scheduleImageVariantCacheTrim } from "./trim-image-variant-cache.mjs";
 import { variantGenerations } from "./variant-generations.mjs";
+import { renderRemoteImageVariant } from "./resolve-remote-image-variant.mjs";
+import { resolveVariantCandidate } from "./resolve-variant-candidate.mjs";
 import fs from "node:fs/promises";
 
 //#region ../../packages/core/src/http/uploads/generate-image-variants.ts
-async function exists(target) {
-	try {
-		await fs.access(target);
-		return true;
-	} catch {
-		return false;
-	}
-}
 function encodeUploadsPath(relativePath) {
 	return relativePath.split("/").map(encodeURIComponent).join("/");
 }
@@ -42,7 +36,7 @@ async function readDerivativeDimensions(target) {
 * that is both the source format and an allowed format is generated once.
 */
 function outputFormatsFor(sourceFormat, configuredFormats) {
-	return [...new Set([sourceFormat, ...configuredFormats])];
+	return [.../* @__PURE__ */ new Set([sourceFormat, ...configuredFormats])];
 }
 /**
 * Render every configured variant of one uploaded image, right after it is
@@ -58,15 +52,15 @@ function outputFormatsFor(sourceFormat, configuredFormats) {
 * The returned descriptor is plain JSON, safe to store next to the record
 * that owns the image, or to carry through loader data. On local storage the
 * `url`/`urls` already point at `uploadedFileController`; an app serving
-* uploads from object storage or a CDN should not proxy the remote files
-* through this route at all — store the descriptor once generation runs
-* against the same bucket the CDN serves from, or resolve its URLs through a
-* custom `ImageLoader` on the client instead.
+* uploads from object storage use the driver URL for the original, and
+* `options.urlPrefix` for the route serving locally cached derivatives.
+* Ingest downloads a remote source once for all variants and formats.
+* On-demand cache hits use ETag metadata; sources without ETags are hashed.
 *
 * @param relativePath - path of the saved upload, relative to the storage root
 * @param options.variants - limit generation to these variant names
-* @throws ImageVariantsConfigError when there is no local storage root, or
-* `uploads.images` is not configured — both are server misconfiguration, not
+* @throws ImageVariantsConfigError when `uploads.images` is not
+* configured — this is server misconfiguration, not
 * a bad request
 * @throws HttpError(400) when a name in `options.variants` is not declared in
 * `uploads.images.variants`
@@ -77,8 +71,8 @@ function outputFormatsFor(sourceFormat, configuredFormats) {
 * @throws HttpError(415) when the source is not jpeg, png, webp or avif
 */
 async function generateImageVariants(relativePath, options = {}) {
-	const storageRoot = storage.root();
-	if (!storageRoot || storageRoot === ".") throw new ImageVariantsConfigError("generateImageVariants needs a local storage driver with a root.");
+	const storageRoot = localDiskRoot(options.disk);
+	if (!storageRoot) return generateRemoteImageVariants(relativePath, options);
 	const images = resolveImageVariantsConfig(uploadsConfig("images"), storageRoot);
 	if (!images) throw new ImageVariantsConfigError("uploads.images is not configured.");
 	const names = options.variants ?? Object.keys(images.variants);
@@ -93,7 +87,7 @@ async function generateImageVariants(relativePath, options = {}) {
 	});
 	const { width: sourceWidth, height: sourceHeight } = await image.metadata();
 	warnIfVariantCacheIsPublic(images.cacheDirectory);
-	const src = `/uploads/${encodeUploadsPath(source.relativePath)}`;
+	const src = `${(options.urlPrefix ?? "/uploads").replace(/\/$/, "")}/${encodeUploadsPath(source.relativePath)}`;
 	const variants = {};
 	for (const name of names) {
 		const variant = images.variants[name];
@@ -114,14 +108,15 @@ async function generateImageVariants(relativePath, options = {}) {
 				sourceKey,
 				generation
 			}, hash, format);
-			if (!await exists(target)) await variantGenerations.run(target, async () => {
-				if (await exists(target)) return;
+			if (!await freshImageVariant(target, images.maxCacheAge)) await variantGenerations.run(target, async () => {
+				if (await freshImageVariant(target, images.maxCacheAge)) return;
 				await retryOnVanishedDirectory(() => generateImageVariant({
 					image: image.clone(),
 					variant,
 					format,
 					targetPath: target
 				}));
+				scheduleImageVariantCacheTrim(images, target);
 				await pruneStaleVariantGenerationsIfCurrent(source.absolutePath, variantSourceDirectory(images.cacheDirectory, sourceKey), generation);
 			});
 			if (dimensions === void 0) dimensions = await readDerivativeDimensions(target);
@@ -143,6 +138,48 @@ async function generateImageVariants(relativePath, options = {}) {
 		...images.formats.length > 0 ? { formats: images.formats } : {}
 	};
 }
+async function generateRemoteImageVariants(relativePath, options) {
+	const disk = remoteVariantDisk(options.disk);
+	const images = resolveImageVariantsConfig(uploadsConfig("images"), disk.cacheRoot);
+	if (!images) throw new ImageVariantsConfigError("uploads.images is not configured.");
+	const names = options.variants ?? Object.keys(images.variants);
+	for (const name of names) if (!Object.prototype.hasOwnProperty.call(images.variants, name)) throw new HttpError(400, `Unknown variant "${name}".`);
+	const source = await remoteVariantSource(relativePath, disk, images);
+	if (!source) throw new HttpError(404, "File Not Found");
+	try {
+		const { image, sourceFormat } = await source.load();
+		const { width, height } = await image.metadata();
+		const variantSrc = `${(options.urlPrefix ?? "/uploads").replace(/\/$/, "")}/${encodeUploadsPath(source.relativePath)}`;
+		const variants = {};
+		for (const name of names) {
+			let dimensions;
+			for (const format of outputFormatsFor(sourceFormat, images.formats)) {
+				const resolved = await renderRemoteImageVariant({
+					path: relativePath,
+					variant: name,
+					...format === sourceFormat ? {} : { format }
+				}, disk, images, source);
+				if (!resolved) throw new HttpError(404, "File Not Found");
+				dimensions ??= await readDerivativeDimensions(resolved.absolutePath);
+			}
+			variants[name] = {
+				width: dimensions?.width ?? 0,
+				height: dimensions?.height ?? 0,
+				url: variantUrl(variantSrc, name),
+				...images.formats.length ? { urls: Object.fromEntries(images.formats.map((format) => [format, variantUrl(variantSrc, name, format)])) } : {}
+			};
+		}
+		return {
+			src: disk.driver.url(source.relativePath),
+			width: width ?? 0,
+			height: height ?? 0,
+			variants,
+			...images.formats.length ? { formats: images.formats } : {}
+		};
+	} finally {
+		source.release();
+	}
+}
 
 //#endregion
 export { generateImageVariants };