@warlock.js/core 5.29.0 → 5.31.0

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

@@ -1,27 +1,22 @@
 import { HttpError } from "../errors/errors.mjs";
-import { storage } from "../../storage/storage.mjs";
-import "../../storage/index.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 { Image } from "../../image/image.mjs";
 import "../../image/index.mjs";
-import { uploadsConfig } from "../uploads-config.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 { variantCacheKey, variantCachePath } from "./variant-cache-key.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 ../core/src/http/uploads/generate-image-variants.ts
-async function exists(target) {
-	try {
-		await fs.access(target);
-		return true;
-	} catch {
-		return false;
-	}
-}
+//#region ../../packages/core/src/http/uploads/generate-image-variants.ts
 function encodeUploadsPath(relativePath) {
 	return relativePath.split("/").map(encodeURIComponent).join("/");
 }
@@ -57,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`
@@ -76,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);
@@ -91,7 +86,8 @@ async function generateImageVariants(relativePath, options = {}) {
 		expectedFormat: sourceFormat
 	});
 	const { width: sourceWidth, height: sourceHeight } = await image.metadata();
-	const src = `/uploads/${encodeUploadsPath(source.relativePath)}`;
+	warnIfVariantCacheIsPublic(images.cacheDirectory);
+	const src = `${(options.urlPrefix ?? "/uploads").replace(/\/$/, "")}/${encodeUploadsPath(source.relativePath)}`;
 	const variants = {};
 	for (const name of names) {
 		const variant = images.variants[name];
@@ -106,15 +102,22 @@ async function generateImageVariants(relativePath, options = {}) {
 				variant,
 				format
 			});
-			const target = variantCachePath(images.cacheDirectory, hash, format);
-			if (!await exists(target)) await variantGenerations.run(hash, async () => {
-				if (await exists(target)) return;
-				await generateImageVariant({
+			const sourceKey = variantSourceKey(source.root, source.relativePath);
+			const generation = variantGenerationTag(stats.size, stats.mtimeMs);
+			const target = variantCachePath(images.cacheDirectory, {
+				sourceKey,
+				generation
+			}, hash, format);
+			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);
 		}
@@ -135,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 };

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

@@ -1 +1 @@
-{"version":3,"file":"generate-image-variants.mjs","names":[],"sources":["../../../../../../../../core/src/http/uploads/generate-image-variants.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport { Image } from \"../../image\";\nimport { storage } from \"../../storage\";\nimport { HttpError } from \"../errors\";\nimport { uploadsConfig } from \"../uploads-config\";\nimport type { ImageVariantOutputFormat } from \"../uploads-types\";\nimport { generateImageVariant } from \"./generate-image-variant\";\nimport { ImageVariantsConfigError } from \"./image-variants-config-error\";\nimport type {\n  GeneratedImageDescriptor,\n  GeneratedImageVariant,\n  VariantOutputFormat,\n} from \"./image-variant-types\";\nimport { loadVariantSource } from \"./load-variant-source\";\nimport { resolveImageVariantsConfig } from \"./resolve-image-variants-config\";\nimport { resolveVariantCandidate } from \"./resolve-variant-candidate\";\nimport { variantCacheKey, variantCachePath } from \"./variant-cache-key\";\nimport { variantGenerations } from \"./variant-generations\";\n\n/**\n * Options for `generateImageVariants`\n */\nexport type GenerateImageVariantsOptions = {\n  /**\n   * Limit generation to these variant names, instead of every variant in\n   * `uploads.images.variants`.\n   */\n  variants?: readonly string[];\n};\n\nasync function exists(target: string): Promise<boolean> {\n  try {\n    await fs.access(target);\n\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nfunction encodeUploadsPath(relativePath: string): string {\n  return relativePath.split(\"/\").map(encodeURIComponent).join(\"/\");\n}\n\nfunction variantUrl(src: string, name: string, format?: VariantOutputFormat): string {\n  const query = format\n    ? `variant=${encodeURIComponent(name)}&format=${format}`\n    : `variant=${encodeURIComponent(name)}`;\n\n  return `${src}?${query}`;\n}\n\nasync function readDerivativeDimensions(\n  target: string,\n): Promise<{ width: number; height: number }> {\n  const derivative = new Image(await fs.readFile(target));\n  const { width, height } = await derivative.metadata();\n\n  return { width: width ?? 0, height: height ?? 0 };\n}\n\n/**\n * Every distinct format a variant is rendered in: the source format plus\n * whatever `uploads.images.formats` adds, with duplicates dropped so a format\n * that is both the source format and an allowed format is generated once.\n */\nfunction outputFormatsFor(\n  sourceFormat: VariantOutputFormat,\n  configuredFormats: readonly ImageVariantOutputFormat[],\n): VariantOutputFormat[] {\n  return [...new Set<VariantOutputFormat>([sourceFormat, ...configuredFormats])];\n}\n\n/**\n * Render every configured variant of one uploaded image, right after it is\n * saved.\n *\n * Uses the exact same normalized config (`uploads.images`), cache key and\n * derivative path as `uploadedFileController`, so a variant generated here is\n * already on disk the first time `GET /uploads/<path>?variant=<name>` is\n * requested — no second render. `variantGenerations` (the single-flight used\n * by the route) is reused, so a concurrent request for a variant this call is\n * still generating joins the same run instead of starting a second one.\n *\n * The returned descriptor is plain JSON, safe to store next to the record\n * that owns the image, or to carry through loader data. On local storage the\n * `url`/`urls` already point at `uploadedFileController`; an app serving\n * uploads from object storage or a CDN should not proxy the remote files\n * through this route at all — store the descriptor once generation runs\n * against the same bucket the CDN serves from, or resolve its URLs through a\n * custom `ImageLoader` on the client instead.\n *\n * @param relativePath - path of the saved upload, relative to the storage root\n * @param options.variants - limit generation to these variant names\n * @throws ImageVariantsConfigError when there is no local storage root, or\n * `uploads.images` is not configured — both are server misconfiguration, not\n * a bad request\n * @throws HttpError(400) when a name in `options.variants` is not declared in\n * `uploads.images.variants`\n * @throws HttpError(404) when `relativePath` does not resolve to a file\n * inside the storage root\n * @throws HttpError(413) when the source is over `maxSourceBytes` or\n * `maxSourcePixels`\n * @throws HttpError(415) when the source is not jpeg, png, webp or avif\n */\nexport async function generateImageVariants(\n  relativePath: string,\n  options: GenerateImageVariantsOptions = {},\n): Promise<GeneratedImageDescriptor> {\n  const storageRoot = storage.root();\n\n  if (!storageRoot || storageRoot === \".\") {\n    throw new ImageVariantsConfigError(\n      \"generateImageVariants needs a local storage driver with a root.\",\n    );\n  }\n\n  const images = resolveImageVariantsConfig(uploadsConfig(\"images\"), storageRoot);\n\n  if (!images) {\n    throw new ImageVariantsConfigError(\"uploads.images is not configured.\");\n  }\n\n  const names = options.variants ?? Object.keys(images.variants);\n\n  for (const name of names) {\n    if (!Object.prototype.hasOwnProperty.call(images.variants, name)) {\n      throw new HttpError(400, `Unknown variant \"${name}\".`);\n    }\n  }\n\n  const candidate = await resolveVariantCandidate(relativePath, storageRoot, images);\n\n  if (!candidate) {\n    throw new HttpError(404, \"File Not Found\");\n  }\n\n  const { source, stats, sourceFormat } = candidate;\n\n  const image = await loadVariantSource(source.absolutePath, {\n    maxSourceBytes: images.maxSourceBytes,\n    maxSourcePixels: images.maxSourcePixels,\n    expectedFormat: sourceFormat,\n  });\n\n  const { width: sourceWidth, height: sourceHeight } = await image.metadata();\n  const src = `/uploads/${encodeUploadsPath(source.relativePath)}`;\n  const variants: Record<string, GeneratedImageVariant> = {};\n\n  for (const name of names) {\n    const variant = images.variants[name];\n    if (variant === undefined) {\n      throw new HttpError(400, `Unknown variant \"${name}\".`);\n    }\n    const formats = outputFormatsFor(sourceFormat, images.formats);\n    let dimensions: { width: number; height: number } | undefined;\n\n    for (const format of formats) {\n      const hash = variantCacheKey({\n        relativePath: source.relativePath,\n        sourceSize: stats.size,\n        sourceMtimeMs: stats.mtimeMs,\n        variant,\n        format,\n      });\n      const target = variantCachePath(images.cacheDirectory, hash, format);\n\n      if (!(await exists(target))) {\n        await variantGenerations.run(hash, async () => {\n          if (await exists(target)) return;\n\n          await generateImageVariant({ image: image.clone(), variant, format, targetPath: target });\n        });\n      }\n\n      if (dimensions === undefined) {\n        dimensions = await readDerivativeDimensions(target);\n      }\n    }\n\n    const urls: Partial<Record<ImageVariantOutputFormat, string>> = {};\n\n    for (const format of images.formats) {\n      urls[format] = variantUrl(src, name, format);\n    }\n\n    variants[name] = {\n      width: dimensions?.width ?? variant.width,\n      height:\n        dimensions?.height ??\n        variant.height ??\n        Math.round(variant.width * ((sourceHeight ?? 1) / (sourceWidth ?? 1))),\n      url: variantUrl(src, name),\n      ...(Object.keys(urls).length > 0 ? { urls } : {}),\n    };\n  }\n\n  return {\n    src,\n    width: sourceWidth ?? 0,\n    height: sourceHeight ?? 0,\n    variants,\n    ...(images.formats.length > 0 ? { formats: images.formats } : {}),\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"generate-image-variants.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/generate-image-variants.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport { Image } from \"../../image\";\nimport type { StorageDriverName } from \"../../storage/types\";\nimport { localDiskRoot } from \"./local-disk-root\";\nimport { remoteVariantDisk, remoteVariantSource } from \"./remote-variant-source\";\nimport { renderRemoteImageVariant } from \"./resolve-remote-image-variant\";\nimport { HttpError } from \"../errors\";\nimport { uploadsConfig } from \"../uploads-config\";\nimport type { ImageVariantOutputFormat } from \"../uploads-types\";\nimport { generateImageVariant } from \"./generate-image-variant\";\nimport {\n  pruneStaleVariantGenerationsIfCurrent,\n  retryOnVanishedDirectory,\n  warnIfVariantCacheIsPublic,\n} from \"./image-variant-cache\";\nimport { ImageVariantsConfigError } from \"./image-variants-config-error\";\nimport type {\n  GeneratedImageDescriptor,\n  GeneratedImageVariant,\n  VariantOutputFormat,\n} from \"./image-variant-types\";\nimport { loadVariantSource } from \"./load-variant-source\";\nimport { resolveImageVariantsConfig } from \"./resolve-image-variants-config\";\nimport { resolveVariantCandidate } from \"./resolve-variant-candidate\";\nimport {\n  variantCacheKey,\n  variantCachePath,\n  variantGenerationTag,\n  variantSourceDirectory,\n  variantSourceKey,\n} from \"./variant-cache-key\";\nimport { freshImageVariant, scheduleImageVariantCacheTrim } from \"./trim-image-variant-cache\";\nimport { variantGenerations } from \"./variant-generations\";\n\n/**\n * Options for `generateImageVariants`\n */\nexport type GenerateImageVariantsOptions = {\n  /**\n   * Limit generation to these variant names, instead of every variant in\n   * `uploads.images.variants`.\n   */\n  variants?: readonly string[];\n\n  /** Disk holding the source; defaults to the active disk. */\n  disk?: StorageDriverName;\n\n  /** Route prefix serving variants of this disk (and originals for local disks). Default /uploads. */\n  urlPrefix?: string;\n};\n\nfunction encodeUploadsPath(relativePath: string): string {\n  return relativePath.split(\"/\").map(encodeURIComponent).join(\"/\");\n}\n\nfunction variantUrl(src: string, name: string, format?: VariantOutputFormat): string {\n  const query = format\n    ? `variant=${encodeURIComponent(name)}&format=${format}`\n    : `variant=${encodeURIComponent(name)}`;\n\n  return `${src}?${query}`;\n}\n\nasync function readDerivativeDimensions(\n  target: string,\n): Promise<{ width: number; height: number }> {\n  const derivative = new Image(await fs.readFile(target));\n  const { width, height } = await derivative.metadata();\n\n  return { width: width ?? 0, height: height ?? 0 };\n}\n\n/**\n * Every distinct format a variant is rendered in: the source format plus\n * whatever `uploads.images.formats` adds, with duplicates dropped so a format\n * that is both the source format and an allowed format is generated once.\n */\nfunction outputFormatsFor(\n  sourceFormat: VariantOutputFormat,\n  configuredFormats: readonly ImageVariantOutputFormat[],\n): VariantOutputFormat[] {\n  return [...new Set<VariantOutputFormat>([sourceFormat, ...configuredFormats])];\n}\n\n/**\n * Render every configured variant of one uploaded image, right after it is\n * saved.\n *\n * Uses the exact same normalized config (`uploads.images`), cache key and\n * derivative path as `uploadedFileController`, so a variant generated here is\n * already on disk the first time `GET /uploads/<path>?variant=<name>` is\n * requested — no second render. `variantGenerations` (the single-flight used\n * by the route) is reused, so a concurrent request for a variant this call is\n * still generating joins the same run instead of starting a second one.\n *\n * The returned descriptor is plain JSON, safe to store next to the record\n * that owns the image, or to carry through loader data. On local storage the\n * `url`/`urls` already point at `uploadedFileController`; an app serving\n * uploads from object storage use the driver URL for the original, and\n * `options.urlPrefix` for the route serving locally cached derivatives.\n * Ingest downloads a remote source once for all variants and formats.\n * On-demand cache hits use ETag metadata; sources without ETags are hashed.\n *\n * @param relativePath - path of the saved upload, relative to the storage root\n * @param options.variants - limit generation to these variant names\n * @throws ImageVariantsConfigError when `uploads.images` is not\n * configured — this is server misconfiguration, not\n * a bad request\n * @throws HttpError(400) when a name in `options.variants` is not declared in\n * `uploads.images.variants`\n * @throws HttpError(404) when `relativePath` does not resolve to a file\n * inside the storage root\n * @throws HttpError(413) when the source is over `maxSourceBytes` or\n * `maxSourcePixels`\n * @throws HttpError(415) when the source is not jpeg, png, webp or avif\n */\nexport async function generateImageVariants(\n  relativePath: string,\n  options: GenerateImageVariantsOptions = {},\n): Promise<GeneratedImageDescriptor> {\n  const storageRoot = localDiskRoot(options.disk);\n\n  if (!storageRoot) return generateRemoteImageVariants(relativePath, options);\n\n  const images = resolveImageVariantsConfig(uploadsConfig(\"images\"), storageRoot);\n\n  if (!images) {\n    throw new ImageVariantsConfigError(\"uploads.images is not configured.\");\n  }\n\n  const names = options.variants ?? Object.keys(images.variants);\n\n  for (const name of names) {\n    if (!Object.prototype.hasOwnProperty.call(images.variants, name)) {\n      throw new HttpError(400, `Unknown variant \"${name}\".`);\n    }\n  }\n\n  const candidate = await resolveVariantCandidate(relativePath, storageRoot, images);\n\n  if (!candidate) {\n    throw new HttpError(404, \"File Not Found\");\n  }\n\n  const { source, stats, sourceFormat } = candidate;\n\n  const image = await loadVariantSource(source.absolutePath, {\n    maxSourceBytes: images.maxSourceBytes,\n    maxSourcePixels: images.maxSourcePixels,\n    expectedFormat: sourceFormat,\n  });\n\n  const { width: sourceWidth, height: sourceHeight } = await image.metadata();\n  warnIfVariantCacheIsPublic(images.cacheDirectory);\n\n  const src = `${(options.urlPrefix ?? \"/uploads\").replace(/\\/$/, \"\")}/${encodeUploadsPath(source.relativePath)}`;\n  const variants: Record<string, GeneratedImageVariant> = {};\n\n  for (const name of names) {\n    const variant = images.variants[name];\n    if (variant === undefined) {\n      throw new HttpError(400, `Unknown variant \"${name}\".`);\n    }\n    const formats = outputFormatsFor(sourceFormat, images.formats);\n    let dimensions: { width: number; height: number } | undefined;\n\n    for (const format of formats) {\n      const hash = variantCacheKey({\n        relativePath: source.relativePath,\n        sourceSize: stats.size,\n        sourceMtimeMs: stats.mtimeMs,\n        variant,\n        format,\n      });\n      const sourceKey = variantSourceKey(source.root, source.relativePath);\n      const generation = variantGenerationTag(stats.size, stats.mtimeMs);\n      const target = variantCachePath(\n        images.cacheDirectory,\n        { sourceKey, generation },\n        hash,\n        format,\n      );\n\n      if (!(await freshImageVariant(target, images.maxCacheAge))) {\n        // keyed on the target, which includes the disk root (see resolveImageVariant)\n        await variantGenerations.run(target, async () => {\n          if (await freshImageVariant(target, images.maxCacheAge)) return;\n\n          await retryOnVanishedDirectory(() =>\n            generateImageVariant({ image: image.clone(), variant, format, targetPath: target }),\n          );\n          scheduleImageVariantCacheTrim(images, target);\n          await pruneStaleVariantGenerationsIfCurrent(\n            source.absolutePath,\n            variantSourceDirectory(images.cacheDirectory, sourceKey),\n            generation,\n          );\n        });\n      }\n\n      if (dimensions === undefined) {\n        dimensions = await readDerivativeDimensions(target);\n      }\n    }\n\n    const urls: Partial<Record<ImageVariantOutputFormat, string>> = {};\n\n    for (const format of images.formats) {\n      urls[format] = variantUrl(src, name, format);\n    }\n\n    variants[name] = {\n      width: dimensions?.width ?? variant.width,\n      height:\n        dimensions?.height ??\n        variant.height ??\n        Math.round(variant.width * ((sourceHeight ?? 1) / (sourceWidth ?? 1))),\n      url: variantUrl(src, name),\n      ...(Object.keys(urls).length > 0 ? { urls } : {}),\n    };\n  }\n\n  return {\n    src,\n    width: sourceWidth ?? 0,\n    height: sourceHeight ?? 0,\n    variants,\n    ...(images.formats.length > 0 ? { formats: images.formats } : {}),\n  };\n}\n\nasync function generateRemoteImageVariants(\n  relativePath: string,\n  options: GenerateImageVariantsOptions,\n): Promise<GeneratedImageDescriptor> {\n  const disk = remoteVariantDisk(options.disk);\n  const images = resolveImageVariantsConfig(uploadsConfig(\"images\"), disk.cacheRoot);\n  if (!images) throw new ImageVariantsConfigError(\"uploads.images is not configured.\");\n  const names = options.variants ?? Object.keys(images.variants);\n  for (const name of names) {\n    if (!Object.prototype.hasOwnProperty.call(images.variants, name))\n      throw new HttpError(400, `Unknown variant \"${name}\".`);\n  }\n  const source = await remoteVariantSource(relativePath, disk, images);\n  if (!source) throw new HttpError(404, \"File Not Found\");\n  try {\n    const { image, sourceFormat } = await source.load();\n    const { width, height } = await image.metadata();\n    const variantSrc = `${(options.urlPrefix ?? \"/uploads\").replace(/\\/$/, \"\")}/${encodeUploadsPath(source.relativePath)}`;\n    const variants: Record<string, GeneratedImageVariant> = {};\n    for (const name of names) {\n      let dimensions: { width: number; height: number } | undefined;\n      for (const format of outputFormatsFor(sourceFormat, images.formats)) {\n        const resolved = await renderRemoteImageVariant(\n          {\n            path: relativePath,\n            variant: name,\n            ...(format === sourceFormat ? {} : { format }),\n          },\n          disk,\n          images,\n          source,\n        );\n        if (!resolved) throw new HttpError(404, \"File Not Found\");\n        dimensions ??= await readDerivativeDimensions(resolved.absolutePath);\n      }\n      variants[name] = {\n        width: dimensions?.width ?? 0,\n        height: dimensions?.height ?? 0,\n        url: variantUrl(variantSrc, name),\n        ...(images.formats.length\n          ? {\n              urls: Object.fromEntries(\n                images.formats.map((format) => [format, variantUrl(variantSrc, name, format)]),\n              ),\n            }\n          : {}),\n      };\n    }\n    return {\n      src: disk.driver.url(source.relativePath),\n      width: width ?? 0,\n      height: height ?? 0,\n      variants,\n      ...(images.formats.length ? { formats: images.formats } : {}),\n    };\n  } finally {\n    source.release();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAmDA,SAAS,kBAAkB,cAA8B;CACvD,OAAO,aAAa,MAAM,GAAG,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,KAAK,GAAG;AACjE;AAEA,SAAS,WAAW,KAAa,MAAc,QAAsC;CAKnF,OAAO,GAAG,IAAI,GAJA,SACV,WAAW,mBAAmB,IAAI,EAAE,UAAU,WAC9C,WAAW,mBAAmB,IAAI;AAGxC;AAEA,eAAe,yBACb,QAC4C;CAE5C,MAAM,EAAE,OAAO,WAAW,MAAM,IADT,MAAM,MAAM,GAAG,SAAS,MAAM,CACZ,CAAC,CAAC,SAAS;CAEpD,OAAO;EAAE,OAAO,SAAS;EAAG,QAAQ,UAAU;CAAE;AAClD;;;;;;AAOA,SAAS,iBACP,cACA,mBACuB;CACvB,OAAO,CAAC,GAAG,IAAI,IAAyB,CAAC,cAAc,GAAG,iBAAiB,CAAC,CAAC;AAC/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,eAAsB,sBACpB,cACA,UAAwC,CAAC,GACN;CACnC,MAAM,cAAc,cAAc,QAAQ,IAAI;CAE9C,IAAI,CAAC,aAAa,OAAO,4BAA4B,cAAc,OAAO;CAE1E,MAAM,SAAS,2BAA2B,cAAc,QAAQ,GAAG,WAAW;CAE9E,IAAI,CAAC,QACH,MAAM,IAAI,yBAAyB,mCAAmC;CAGxE,MAAM,QAAQ,QAAQ,YAAY,OAAO,KAAK,OAAO,QAAQ;CAE7D,KAAK,MAAM,QAAQ,OACjB,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,OAAO,UAAU,IAAI,GAC7D,MAAM,IAAI,UAAU,KAAK,oBAAoB,KAAK,GAAG;CAIzD,MAAM,YAAY,MAAM,wBAAwB,cAAc,aAAa,MAAM;CAEjF,IAAI,CAAC,WACH,MAAM,IAAI,UAAU,KAAK,gBAAgB;CAG3C,MAAM,EAAE,QAAQ,OAAO,iBAAiB;CAExC,MAAM,QAAQ,MAAM,kBAAkB,OAAO,cAAc;EACzD,gBAAgB,OAAO;EACvB,iBAAiB,OAAO;EACxB,gBAAgB;CAClB,CAAC;CAED,MAAM,EAAE,OAAO,aAAa,QAAQ,iBAAiB,MAAM,MAAM,SAAS;CAC1E,2BAA2B,OAAO,cAAc;CAEhD,MAAM,MAAM,IAAI,QAAQ,aAAa,WAAU,CAAE,QAAQ,OAAO,EAAE,EAAE,GAAG,kBAAkB,OAAO,YAAY;CAC5G,MAAM,WAAkD,CAAC;CAEzD,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,UAAU,OAAO,SAAS;EAChC,IAAI,YAAY,QACd,MAAM,IAAI,UAAU,KAAK,oBAAoB,KAAK,GAAG;EAEvD,MAAM,UAAU,iBAAiB,cAAc,OAAO,OAAO;EAC7D,IAAI;EAEJ,KAAK,MAAM,UAAU,SAAS;GAC5B,MAAM,OAAO,gBAAgB;IAC3B,cAAc,OAAO;IACrB,YAAY,MAAM;IAClB,eAAe,MAAM;IACrB;IACA;GACF,CAAC;GACD,MAAM,YAAY,iBAAiB,OAAO,MAAM,OAAO,YAAY;GACnE,MAAM,aAAa,qBAAqB,MAAM,MAAM,MAAM,OAAO;GACjE,MAAM,SAAS,iBACb,OAAO,gBACP;IAAE;IAAW;GAAW,GACxB,MACA,MACF;GAEA,IAAI,CAAE,MAAM,kBAAkB,QAAQ,OAAO,WAAW,GAEtD,MAAM,mBAAmB,IAAI,QAAQ,YAAY;IAC/C,IAAI,MAAM,kBAAkB,QAAQ,OAAO,WAAW,GAAG;IAEzD,MAAM,+BACJ,qBAAqB;KAAE,OAAO,MAAM,MAAM;KAAG;KAAS;KAAQ,YAAY;IAAO,CAAC,CACpF;IACA,8BAA8B,QAAQ,MAAM;IAC5C,MAAM,sCACJ,OAAO,cACP,uBAAuB,OAAO,gBAAgB,SAAS,GACvD,UACF;GACF,CAAC;GAGH,IAAI,eAAe,QACjB,aAAa,MAAM,yBAAyB,MAAM;EAEtD;EAEA,MAAM,OAA0D,CAAC;EAEjE,KAAK,MAAM,UAAU,OAAO,SAC1B,KAAK,UAAU,WAAW,KAAK,MAAM,MAAM;EAG7C,SAAS,QAAQ;GACf,OAAO,YAAY,SAAS,QAAQ;GACpC,QACE,YAAY,UACZ,QAAQ,UACR,KAAK,MAAM,QAAQ,UAAU,gBAAgB,MAAM,eAAe,GAAG;GACvE,KAAK,WAAW,KAAK,IAAI;GACzB,GAAI,OAAO,KAAK,IAAI,CAAC,CAAC,SAAS,IAAI,EAAE,KAAK,IAAI,CAAC;EACjD;CACF;CAEA,OAAO;EACL;EACA,OAAO,eAAe;EACtB,QAAQ,gBAAgB;EACxB;EACA,GAAI,OAAO,QAAQ,SAAS,IAAI,EAAE,SAAS,OAAO,QAAQ,IAAI,CAAC;CACjE;AACF;AAEA,eAAe,4BACb,cACA,SACmC;CACnC,MAAM,OAAO,kBAAkB,QAAQ,IAAI;CAC3C,MAAM,SAAS,2BAA2B,cAAc,QAAQ,GAAG,KAAK,SAAS;CACjF,IAAI,CAAC,QAAQ,MAAM,IAAI,yBAAyB,mCAAmC;CACnF,MAAM,QAAQ,QAAQ,YAAY,OAAO,KAAK,OAAO,QAAQ;CAC7D,KAAK,MAAM,QAAQ,OACjB,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,OAAO,UAAU,IAAI,GAC7D,MAAM,IAAI,UAAU,KAAK,oBAAoB,KAAK,GAAG;CAEzD,MAAM,SAAS,MAAM,oBAAoB,cAAc,MAAM,MAAM;CACnE,IAAI,CAAC,QAAQ,MAAM,IAAI,UAAU,KAAK,gBAAgB;CACtD,IAAI;EACF,MAAM,EAAE,OAAO,iBAAiB,MAAM,OAAO,KAAK;EAClD,MAAM,EAAE,OAAO,WAAW,MAAM,MAAM,SAAS;EAC/C,MAAM,aAAa,IAAI,QAAQ,aAAa,WAAU,CAAE,QAAQ,OAAO,EAAE,EAAE,GAAG,kBAAkB,OAAO,YAAY;EACnH,MAAM,WAAkD,CAAC;EACzD,KAAK,MAAM,QAAQ,OAAO;GACxB,IAAI;GACJ,KAAK,MAAM,UAAU,iBAAiB,cAAc,OAAO,OAAO,GAAG;IACnE,MAAM,WAAW,MAAM,yBACrB;KACE,MAAM;KACN,SAAS;KACT,GAAI,WAAW,eAAe,CAAC,IAAI,EAAE,OAAO;IAC9C,GACA,MACA,QACA,MACF;IACA,IAAI,CAAC,UAAU,MAAM,IAAI,UAAU,KAAK,gBAAgB;IACxD,eAAe,MAAM,yBAAyB,SAAS,YAAY;GACrE;GACA,SAAS,QAAQ;IACf,OAAO,YAAY,SAAS;IAC5B,QAAQ,YAAY,UAAU;IAC9B,KAAK,WAAW,YAAY,IAAI;IAChC,GAAI,OAAO,QAAQ,SACf,EACE,MAAM,OAAO,YACX,OAAO,QAAQ,KAAK,WAAW,CAAC,QAAQ,WAAW,YAAY,MAAM,MAAM,CAAC,CAAC,CAC/E,EACF,IACA,CAAC;GACP;EACF;EACA,OAAO;GACL,KAAK,KAAK,OAAO,IAAI,OAAO,YAAY;GACxC,OAAO,SAAS;GAChB,QAAQ,UAAU;GAClB;GACA,GAAI,OAAO,QAAQ,SAAS,EAAE,SAAS,OAAO,QAAQ,IAAI,CAAC;EAC7D;CACF,UAAU;EACR,OAAO,QAAQ;CACjB;AACF"}

package/esm/http/uploads/image-variant-cache-entries.mjs

@@ -0,0 +1,78 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+
+//#region ../../packages/core/src/http/uploads/image-variant-cache-entries.ts
+const SHARD = /^[a-f0-9]{2}$/;
+const SOURCE = /^[a-f0-9]{64}$/;
+const GENERATION = /^(?:\d+--?\d+|[a-f0-9]{64})$/;
+const DERIVATIVE = /^[a-f0-9]{64}\.(?:jpg|png|webp|avif)$/;
+const TEMPORARY = /^(?:[a-f0-9]{64}\.(?:jpg|png|webp|avif)\.tmp-[a-f0-9]{16}|\.source\.json\.[a-f0-9]{12}\.tmp)$/;
+async function entries(directory) {
+	try {
+		return await fs.readdir(directory, { withFileTypes: true });
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+/** Recognize only generation directories and files emitted by the image writers; never traverse symlinks. */
+async function* variantSourceCacheGenerations(sourceDirectory, keepGeneration) {
+	try {
+		for (const directory of [path.dirname(sourceDirectory), sourceDirectory]) if (!(await fs.lstat(directory)).isDirectory()) return;
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+	for (const generation of await entries(sourceDirectory)) {
+		if (generation.name === keepGeneration || !generation.isDirectory() || !GENERATION.test(generation.name)) continue;
+		const directory = path.join(sourceDirectory, generation.name);
+		const found = [];
+		for (const file of await entries(directory)) {
+			if (!file.isFile()) continue;
+			const type = DERIVATIVE.test(file.name) ? "derivative" : file.name === "source.json" ? "manifest" : TEMPORARY.test(file.name) ? "temporary" : void 0;
+			if (type) found.push({
+				target: path.join(directory, file.name),
+				type
+			});
+		}
+		yield {
+			directory,
+			entries: found
+		};
+	}
+}
+/** Every directory component must match the generated cache layout. */
+async function* variantCacheGenerations(cacheDirectory) {
+	for (const shard of await entries(cacheDirectory)) {
+		if (!shard.isDirectory() || !SHARD.test(shard.name)) continue;
+		const directory = path.join(cacheDirectory, shard.name);
+		for (const source of await entries(directory)) {
+			if (!source.isDirectory() || !SOURCE.test(source.name) || !source.name.startsWith(shard.name)) continue;
+			yield* variantSourceCacheGenerations(path.join(directory, source.name));
+		}
+	}
+}
+async function* flatten(generations) {
+	for await (const generation of generations) yield* generation.entries;
+}
+/** Recognized files of one source's generations, optionally skipping the `keepGeneration` directory. */
+function variantSourceCacheEntries(sourceDirectory, keepGeneration) {
+	return flatten(variantSourceCacheGenerations(sourceDirectory, keepGeneration));
+}
+/** Recognized files of every source in the cache. */
+function variantCacheEntries(cacheDirectory) {
+	return flatten(variantCacheGenerations(cacheDirectory));
+}
+/** Keep directories in place so removing cache data cannot remove user folders. */
+async function purgeVariantCacheEntries(entries) {
+	let removed = false;
+	for await (const entry of entries) {
+		await fs.rm(entry.target, { force: true });
+		removed = true;
+	}
+	return removed;
+}
+
+//#endregion
+export { purgeVariantCacheEntries, variantCacheEntries, variantCacheGenerations, variantSourceCacheEntries };
+//# sourceMappingURL=image-variant-cache-entries.mjs.map

package/esm/http/uploads/image-variant-cache-entries.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-variant-cache-entries.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/image-variant-cache-entries.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport path from \"node:path\";\n\nconst SHARD = /^[a-f0-9]{2}$/;\nconst SOURCE = /^[a-f0-9]{64}$/;\nconst GENERATION = /^(?:\\d+--?\\d+|[a-f0-9]{64})$/;\nconst DERIVATIVE = /^[a-f0-9]{64}\\.(?:jpg|png|webp|avif)$/;\nconst TEMPORARY =\n  /^(?:[a-f0-9]{64}\\.(?:jpg|png|webp|avif)\\.tmp-[a-f0-9]{16}|\\.source\\.json\\.[a-f0-9]{12}\\.tmp)$/;\n\nexport type VariantCacheEntry = {\n  target: string;\n  type: \"derivative\" | \"manifest\" | \"temporary\";\n};\n\n/** One generation-shaped directory (a real directory, never a symlink) and its recognized files. */\nexport type VariantCacheGeneration = {\n  directory: string;\n  entries: VariantCacheEntry[];\n};\n\nasync function entries(directory: string) {\n  try {\n    return await fs.readdir(directory, { withFileTypes: true });\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") return [];\n    throw error;\n  }\n}\n\n/** Recognize only generation directories and files emitted by the image writers; never traverse symlinks. */\nexport async function* variantSourceCacheGenerations(\n  sourceDirectory: string,\n  keepGeneration?: string,\n): AsyncGenerator<VariantCacheGeneration> {\n  try {\n    // Checking the final component alone still follows a symlinked shard.\n    for (const directory of [path.dirname(sourceDirectory), sourceDirectory]) {\n      if (!(await fs.lstat(directory)).isDirectory()) return;\n    }\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") return;\n    throw error;\n  }\n  for (const generation of await entries(sourceDirectory)) {\n    if (\n      generation.name === keepGeneration ||\n      !generation.isDirectory() ||\n      !GENERATION.test(generation.name)\n    )\n      continue;\n    const directory = path.join(sourceDirectory, generation.name);\n    const found: VariantCacheEntry[] = [];\n    for (const file of await entries(directory)) {\n      if (!file.isFile()) continue;\n      const type = DERIVATIVE.test(file.name)\n        ? \"derivative\"\n        : file.name === \"source.json\"\n          ? \"manifest\"\n          : TEMPORARY.test(file.name)\n            ? \"temporary\"\n            : undefined;\n      if (type) found.push({ target: path.join(directory, file.name), type });\n    }\n    yield { directory, entries: found };\n  }\n}\n\n/** Every directory component must match the generated cache layout. */\nexport async function* variantCacheGenerations(\n  cacheDirectory: string,\n): AsyncGenerator<VariantCacheGeneration> {\n  for (const shard of await entries(cacheDirectory)) {\n    if (!shard.isDirectory() || !SHARD.test(shard.name)) continue;\n    const directory = path.join(cacheDirectory, shard.name);\n    for (const source of await entries(directory)) {\n      if (!source.isDirectory() || !SOURCE.test(source.name) || !source.name.startsWith(shard.name))\n        continue;\n      yield* variantSourceCacheGenerations(path.join(directory, source.name));\n    }\n  }\n}\n\nasync function* flatten(\n  generations: AsyncIterable<VariantCacheGeneration>,\n): AsyncGenerator<VariantCacheEntry> {\n  for await (const generation of generations) yield* generation.entries;\n}\n\n/** Recognized files of one source's generations, optionally skipping the `keepGeneration` directory. */\nexport function variantSourceCacheEntries(\n  sourceDirectory: string,\n  keepGeneration?: string,\n): AsyncGenerator<VariantCacheEntry> {\n  return flatten(variantSourceCacheGenerations(sourceDirectory, keepGeneration));\n}\n\n/** Recognized files of every source in the cache. */\nexport function variantCacheEntries(cacheDirectory: string): AsyncGenerator<VariantCacheEntry> {\n  return flatten(variantCacheGenerations(cacheDirectory));\n}\n\n/** Keep directories in place so removing cache data cannot remove user folders. */\nexport async function purgeVariantCacheEntries(\n  entries: AsyncIterable<VariantCacheEntry>,\n): Promise<boolean> {\n  let removed = false;\n  for await (const entry of entries) {\n    await fs.rm(entry.target, { force: true });\n    removed = true;\n  }\n  return removed;\n}\n"],"mappings":";;;;AAGA,MAAM,QAAQ;AACd,MAAM,SAAS;AACf,MAAM,aAAa;AACnB,MAAM,aAAa;AACnB,MAAM,YACJ;AAaF,eAAe,QAAQ,WAAmB;CACxC,IAAI;EACF,OAAO,MAAM,GAAG,QAAQ,WAAW,EAAE,eAAe,KAAK,CAAC;CAC5D,SAAS,OAAO;EACd,IAAK,MAAgC,SAAS,UAAU,OAAO,CAAC;EAChE,MAAM;CACR;AACF;;AAGA,gBAAuB,8BACrB,iBACA,gBACwC;CACxC,IAAI;EAEF,KAAK,MAAM,aAAa,CAAC,KAAK,QAAQ,eAAe,GAAG,eAAe,GACrE,IAAI,EAAE,MAAM,GAAG,MAAM,SAAS,EAAC,CAAE,YAAY,GAAG;CAEpD,SAAS,OAAO;EACd,IAAK,MAAgC,SAAS,UAAU;EACxD,MAAM;CACR;CACA,KAAK,MAAM,cAAc,MAAM,QAAQ,eAAe,GAAG;EACvD,IACE,WAAW,SAAS,kBACpB,CAAC,WAAW,YAAY,KACxB,CAAC,WAAW,KAAK,WAAW,IAAI,GAEhC;EACF,MAAM,YAAY,KAAK,KAAK,iBAAiB,WAAW,IAAI;EAC5D,MAAM,QAA6B,CAAC;EACpC,KAAK,MAAM,QAAQ,MAAM,QAAQ,SAAS,GAAG;GAC3C,IAAI,CAAC,KAAK,OAAO,GAAG;GACpB,MAAM,OAAO,WAAW,KAAK,KAAK,IAAI,IAClC,eACA,KAAK,SAAS,gBACZ,aACA,UAAU,KAAK,KAAK,IAAI,IACtB,cACA;GACR,IAAI,MAAM,MAAM,KAAK;IAAE,QAAQ,KAAK,KAAK,WAAW,KAAK,IAAI;IAAG;GAAK,CAAC;EACxE;EACA,MAAM;GAAE;GAAW,SAAS;EAAM;CACpC;AACF;;AAGA,gBAAuB,wBACrB,gBACwC;CACxC,KAAK,MAAM,SAAS,MAAM,QAAQ,cAAc,GAAG;EACjD,IAAI,CAAC,MAAM,YAAY,KAAK,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG;EACrD,MAAM,YAAY,KAAK,KAAK,gBAAgB,MAAM,IAAI;EACtD,KAAK,MAAM,UAAU,MAAM,QAAQ,SAAS,GAAG;GAC7C,IAAI,CAAC,OAAO,YAAY,KAAK,CAAC,OAAO,KAAK,OAAO,IAAI,KAAK,CAAC,OAAO,KAAK,WAAW,MAAM,IAAI,GAC1F;GACF,OAAO,8BAA8B,KAAK,KAAK,WAAW,OAAO,IAAI,CAAC;EACxE;CACF;AACF;AAEA,gBAAgB,QACd,aACmC;CACnC,WAAW,MAAM,cAAc,aAAa,OAAO,WAAW;AAChE;;AAGA,SAAgB,0BACd,iBACA,gBACmC;CACnC,OAAO,QAAQ,8BAA8B,iBAAiB,cAAc,CAAC;AAC/E;;AAGA,SAAgB,oBAAoB,gBAA2D;CAC7F,OAAO,QAAQ,wBAAwB,cAAc,CAAC;AACxD;;AAGA,eAAsB,yBACpB,SACkB;CAClB,IAAI,UAAU;CACd,WAAW,MAAM,SAAS,SAAS;EACjC,MAAM,GAAG,GAAG,MAAM,QAAQ,EAAE,OAAO,KAAK,CAAC;EACzC,UAAU;CACZ;CACA,OAAO;AACT"}

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

@@ -0,0 +1,185 @@
+import { rootPath } from "../../utils/paths.mjs";
+import { configuredLocalDiskRoots } from "../../storage/local-disk-roots.mjs";
+import { ImageVariantsConfigError } from "./image-variants-config-error.mjs";
+import { purgeVariantCacheEntries, variantSourceCacheEntries } from "./image-variant-cache-entries.mjs";
+import { uploadsConfig } from "../uploads-config.mjs";
+import { isPathInside, isPathWithin } from "./is-path-inside.mjs";
+import { variantGenerationTag, variantSourceDirectory, variantSourceKey } from "./variant-cache-key.mjs";
+import config from "@mongez/config";
+import { log } from "@warlock.js/logger";
+import path from "node:path";
+import fs from "node:fs";
+import fs$1 from "node:fs/promises";
+
+//#region ../../packages/core/src/http/uploads/image-variant-cache.ts
+async function realpathOrSelf(target) {
+	try {
+		return await fs$1.realpath(target);
+	} catch {
+		return target;
+	}
+}
+function canonicalDirectory(target) {
+	const resolved = path.resolve(target);
+	try {
+		return fs.realpathSync(resolved);
+	} catch (error) {
+		const code = error.code;
+		if (code !== "ENOENT") throw new ImageVariantsConfigError(`uploads.images.cacheDirectory (or a local disk root) could not be resolved: ${resolved} (${code ?? "unknown error"})`, { cause: error });
+		const parent = path.dirname(resolved);
+		if (parent === resolved) throw error;
+		return path.join(canonicalDirectory(parent), path.basename(resolved));
+	}
+}
+/** Most distinct cache/disk-root combinations whose overlap check is remembered. */
+const OVERLAP_CHECKS_LIMIT = 64;
+/**
+* Overlap check outcomes, keyed by the cache directory, the disk root and
+* every configured local root. A disk registered later changes the key, so
+* it is checked again; the stored error is rethrown for a refused layout.
+*/
+const overlapChecks = /* @__PURE__ */ new Map();
+function checkCacheOverlap(directory, diskRoot) {
+	const roots = [diskRoot, ...configuredLocalDiskRoots()];
+	const key = [directory, ...roots].join("\0");
+	if (overlapChecks.has(key)) {
+		const failure = overlapChecks.get(key);
+		if (failure) throw failure;
+		return;
+	}
+	let failure;
+	try {
+		const realCache = canonicalDirectory(directory);
+		for (const root of roots) if (isPathWithin(canonicalDirectory(root), realCache)) {
+			failure = new ImageVariantsConfigError("uploads.images.cacheDirectory must not equal or contain the storage root of any local disk (including symlinks).");
+			break;
+		}
+	} catch (error) {
+		if (!(error instanceof ImageVariantsConfigError)) throw error;
+		failure = error;
+	}
+	if (overlapChecks.size >= OVERLAP_CHECKS_LIMIT) {
+		const oldest = overlapChecks.keys().next();
+		if (!oldest.done) overlapChecks.delete(oldest.value);
+	}
+	overlapChecks.set(key, failure);
+	if (failure) throw failure;
+}
+/**
+* The derivative cache directory for a local disk: `uploads.images.cacheDirectory`
+* when the app sets one (shared by every disk; derivatives are keyed by the
+* disk's real root, so they never collide), otherwise
+* `<diskRoot>/.cache/image-variants`. The same rule as
+* `resolveImageVariantsConfig`. Refuses any cache that equals or contains
+* any configured local root, resolving symlinks before comparison. The
+* outcome is remembered per cache, disk root and configured local roots, so
+* repeated requests do not resolve the same paths again.
+*
+* @throws ImageVariantsConfigError when a cache overlaps a local disk root, or
+* when the cache or a root cannot be resolved (for example `ENOTDIR`, `EACCES`)
+*/
+function variantCacheDirectoryFor(diskRoot, images = uploadsConfig("images")) {
+	const configured = images?.cacheDirectory;
+	const directory = configured ? path.resolve(configured) : path.join(path.resolve(diskRoot), ".cache", "image-variants");
+	checkCacheOverlap(directory, diskRoot);
+	return directory;
+}
+/**
+* The directory holding every derivative of one file on a local disk, or
+* `undefined` when the file is not inside the disk root. The file does not
+* need to exist any more: only its parent directory is resolved through
+* symlinks, exactly as `resolveUploadPath` resolved it when the derivative
+* was made.
+*/
+async function variantSourceDirectoryForFile(diskRoot, absolutePath) {
+	const realRoot = await realpathOrSelf(path.resolve(diskRoot));
+	const realParent = await realpathOrSelf(path.dirname(path.resolve(absolutePath)));
+	const realPath = path.join(realParent, path.basename(absolutePath));
+	if (!isPathInside(realPath, realRoot)) return void 0;
+	const relativePath = path.relative(realRoot, realPath).split(path.sep).join("/");
+	return variantSourceDirectory(variantCacheDirectoryFor(diskRoot), variantSourceKey(realRoot, relativePath));
+}
+/**
+* Remove every cached derivative of one file on a local disk.
+*
+* @returns `true` when recognized cache files were removed
+*/
+async function purgeImageVariantsOfFile(diskRoot, absolutePath) {
+	const directory = await variantSourceDirectoryForFile(diskRoot, absolutePath);
+	if (!directory) return false;
+	return purgeVariantCacheEntries(variantSourceCacheEntries(directory));
+}
+/**
+* Remove derivatives made from older versions of a source (a different size
+* or mtime), keeping only the `keep` generation. Called after a derivative of
+* the current version has been written, so a source rewritten in place does
+* not leave its old derivatives behind. Only recognized cache files in
+* generation-shaped directories are removed; unrelated entries and all
+* directories and symlinks stay in place.
+*/
+async function pruneStaleVariantGenerations(sourceDirectory, keep) {
+	await purgeVariantCacheEntries(variantSourceCacheEntries(sourceDirectory, keep));
+}
+/**
+* {@link pruneStaleVariantGenerations}, but only while `keep` is still the
+* source's current generation.
+*
+* A request that read the source before it was rewritten renders an old
+* generation; if it pruned afterwards it would delete the derivatives of the
+* newer version another request had just written. Re-reading the source's
+* size and mtime right before pruning keeps a stale request from doing that.
+*/
+async function pruneStaleVariantGenerationsIfCurrent(sourceAbsolutePath, sourceDirectory, keep) {
+	let current;
+	try {
+		const stats = await fs$1.stat(sourceAbsolutePath);
+		current = variantGenerationTag(stats.size, stats.mtimeMs);
+	} catch {
+		return;
+	}
+	if (current !== keep) return;
+	await pruneStaleVariantGenerations(sourceDirectory, keep);
+}
+/**
+* True for "no such file or directory"
+*/
+function isMissingFileError(error) {
+	return error?.code === "ENOENT";
+}
+/**
+* Run a derivative write, once more if it fails because its directory
+* vanished: a concurrent request for a newer version of the source may prune
+* the generation directory between `mkdir` and the atomic rename.
+*/
+async function retryOnVanishedDirectory(write) {
+	try {
+		await write();
+	} catch (error) {
+		if (!isMissingFileError(error)) throw error;
+		await write();
+	}
+}
+let warnedPublicCache = false;
+/**
+* Warn once when the derivative cache sits inside the public folder.
+*
+* A configured `uploads.images.cacheDirectory` is shared by every local disk,
+* so derivatives of a private disk land beside public ones. Inside
+* `public/` (or `storage.publicRoot`) they are served to anyone, bypassing
+* whatever guards the private disk's own route. The paths are hashes, but
+* they are derived from the disk root and the file path, which are not
+* secret.
+*/
+function warnIfVariantCacheIsPublic(cacheDirectory) {
+	if (warnedPublicCache) return;
+	const configured = config.get("storage.publicRoot", rootPath("public"));
+	const publicRoots = (Array.isArray(configured) ? configured : [configured]).filter((root) => typeof root === "string" && root.length > 0).map((root) => path.resolve(root));
+	const resolved = path.resolve(cacheDirectory);
+	if (!publicRoots.some((root) => resolved === root || isPathInside(resolved, root))) return;
+	warnedPublicCache = true;
+	log.warn("uploads", "image-variants", `The image variant cache (${resolved}) is inside the public folder, so every cached derivative, private disks included, is publicly served. Move uploads.images.cacheDirectory outside public/.`);
+}
+
+//#endregion
+export { isMissingFileError, pruneStaleVariantGenerationsIfCurrent, purgeImageVariantsOfFile, retryOnVanishedDirectory, variantCacheDirectoryFor, warnIfVariantCacheIsPublic };
+//# sourceMappingURL=image-variant-cache.mjs.map

package/esm/http/uploads/image-variant-cache.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-variant-cache.mjs","names":["fs","fsSync"],"sources":["../../../../../../../../../packages/core/src/http/uploads/image-variant-cache.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { log } from \"@warlock.js/logger\";\nimport fs from \"node:fs/promises\";\nimport fsSync from \"node:fs\";\nimport { configuredLocalDiskRoots } from \"../../storage/local-disk-roots\";\nimport type { UploadsImagesConfigurations } from \"../uploads-types\";\nimport { ImageVariantsConfigError } from \"./image-variants-config-error\";\nimport { purgeVariantCacheEntries, variantSourceCacheEntries } from \"./image-variant-cache-entries\";\nimport path from \"node:path\";\nimport { rootPath } from \"../../utils/paths\";\nimport { uploadsConfig } from \"../uploads-config\";\nimport { isPathInside, isPathWithin } from \"./is-path-inside\";\nimport {\n  variantGenerationTag,\n  variantSourceDirectory,\n  variantSourceKey,\n} from \"./variant-cache-key\";\n\n/*\n * Cache housekeeping for image derivatives. Deliberately free of any\n * import of the storage manager or drivers: the local driver calls into this module when it\n * deletes or moves a file, and storage must not import back into the HTTP\n * layer that already imports storage.\n */\n\nasync function realpathOrSelf(target: string): Promise<string> {\n  try {\n    return await fs.realpath(target);\n  } catch {\n    return target;\n  }\n}\n\nfunction canonicalDirectory(target: string): string {\n  const resolved = path.resolve(target);\n  try {\n    return fsSync.realpathSync(resolved);\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code !== \"ENOENT\") {\n      // ENOTDIR, EACCES, ELOOP, ...: a configuration problem, reported as one.\n      throw new ImageVariantsConfigError(\n        `uploads.images.cacheDirectory (or a local disk root) could not be resolved: ${resolved} (${code ?? \"unknown error\"})`,\n        { cause: error },\n      );\n    }\n    const parent = path.dirname(resolved);\n    if (parent === resolved) throw error;\n    // Resolve the nearest existing ancestor too, so a symlink followed by a\n    // not-yet-created directory cannot hide an overlap with a future disk root.\n    return path.join(canonicalDirectory(parent), path.basename(resolved));\n  }\n}\n\n/** Most distinct cache/disk-root combinations whose overlap check is remembered. */\nconst OVERLAP_CHECKS_LIMIT = 64;\n\n/**\n * Overlap check outcomes, keyed by the cache directory, the disk root and\n * every configured local root. A disk registered later changes the key, so\n * it is checked again; the stored error is rethrown for a refused layout.\n */\nconst overlapChecks = new Map<string, ImageVariantsConfigError | undefined>();\n\nfunction checkCacheOverlap(directory: string, diskRoot: string): void {\n  const roots = [diskRoot, ...configuredLocalDiskRoots()];\n  const key = [directory, ...roots].join(\"\\0\");\n  if (overlapChecks.has(key)) {\n    const failure = overlapChecks.get(key);\n    if (failure) throw failure;\n    return;\n  }\n  let failure: ImageVariantsConfigError | undefined;\n  try {\n    const realCache = canonicalDirectory(directory);\n    for (const root of roots) {\n      if (isPathWithin(canonicalDirectory(root), realCache)) {\n        failure = new ImageVariantsConfigError(\n          \"uploads.images.cacheDirectory must not equal or contain the storage root of any local disk (including symlinks).\",\n        );\n        break;\n      }\n    }\n  } catch (error) {\n    // Only configuration errors are remembered; anything else is retried next time.\n    if (!(error instanceof ImageVariantsConfigError)) throw error;\n    failure = error;\n  }\n  if (overlapChecks.size >= OVERLAP_CHECKS_LIMIT) {\n    const oldest = overlapChecks.keys().next();\n    if (!oldest.done) overlapChecks.delete(oldest.value);\n  }\n  overlapChecks.set(key, failure);\n  if (failure) throw failure;\n}\n\n/**\n * Forget remembered cache overlap checks, so the next check resolves every\n * path again (tests). Changes to the configured disks are detected without it;\n * a directory replaced by a symlink at runtime is not.\n */\nexport function resetVariantCacheOverlapChecks(): void {\n  overlapChecks.clear();\n}\n\n/**\n * The derivative cache directory for a local disk: `uploads.images.cacheDirectory`\n * when the app sets one (shared by every disk; derivatives are keyed by the\n * disk's real root, so they never collide), otherwise\n * `<diskRoot>/.cache/image-variants`. The same rule as\n * `resolveImageVariantsConfig`. Refuses any cache that equals or contains\n * any configured local root, resolving symlinks before comparison. The\n * outcome is remembered per cache, disk root and configured local roots, so\n * repeated requests do not resolve the same paths again.\n *\n * @throws ImageVariantsConfigError when a cache overlaps a local disk root, or\n * when the cache or a root cannot be resolved (for example `ENOTDIR`, `EACCES`)\n */\nexport function variantCacheDirectoryFor(\n  diskRoot: string,\n  images: Pick<UploadsImagesConfigurations, \"cacheDirectory\"> | undefined = uploadsConfig(\"images\"),\n): string {\n  const configured = images?.cacheDirectory;\n  const directory = configured\n    ? path.resolve(configured)\n    : path.join(path.resolve(diskRoot), \".cache\", \"image-variants\");\n  checkCacheOverlap(directory, diskRoot);\n  return directory;\n}\n\n/**\n * The directory holding every derivative of one file on a local disk, or\n * `undefined` when the file is not inside the disk root. The file does not\n * need to exist any more: only its parent directory is resolved through\n * symlinks, exactly as `resolveUploadPath` resolved it when the derivative\n * was made.\n */\nexport async function variantSourceDirectoryForFile(\n  diskRoot: string,\n  absolutePath: string,\n): Promise<string | undefined> {\n  const realRoot = await realpathOrSelf(path.resolve(diskRoot));\n  const realParent = await realpathOrSelf(path.dirname(path.resolve(absolutePath)));\n  const realPath = path.join(realParent, path.basename(absolutePath));\n\n  if (!isPathInside(realPath, realRoot)) return undefined;\n\n  const relativePath = path.relative(realRoot, realPath).split(path.sep).join(\"/\");\n\n  return variantSourceDirectory(\n    variantCacheDirectoryFor(diskRoot),\n    variantSourceKey(realRoot, relativePath),\n  );\n}\n\n/**\n * Remove every cached derivative of one file on a local disk.\n *\n * @returns `true` when recognized cache files were removed\n */\nexport async function purgeImageVariantsOfFile(\n  diskRoot: string,\n  absolutePath: string,\n): Promise<boolean> {\n  const directory = await variantSourceDirectoryForFile(diskRoot, absolutePath);\n\n  if (!directory) return false;\n\n  return purgeVariantCacheEntries(variantSourceCacheEntries(directory));\n}\n\n/**\n * Remove derivatives made from older versions of a source (a different size\n * or mtime), keeping only the `keep` generation. Called after a derivative of\n * the current version has been written, so a source rewritten in place does\n * not leave its old derivatives behind. Only recognized cache files in\n * generation-shaped directories are removed; unrelated entries and all\n * directories and symlinks stay in place.\n */\nexport async function pruneStaleVariantGenerations(\n  sourceDirectory: string,\n  keep: string,\n): Promise<void> {\n  await purgeVariantCacheEntries(variantSourceCacheEntries(sourceDirectory, keep));\n}\n\n/**\n * {@link pruneStaleVariantGenerations}, but only while `keep` is still the\n * source's current generation.\n *\n * A request that read the source before it was rewritten renders an old\n * generation; if it pruned afterwards it would delete the derivatives of the\n * newer version another request had just written. Re-reading the source's\n * size and mtime right before pruning keeps a stale request from doing that.\n */\nexport async function pruneStaleVariantGenerationsIfCurrent(\n  sourceAbsolutePath: string,\n  sourceDirectory: string,\n  keep: string,\n): Promise<void> {\n  let current: string;\n\n  try {\n    const stats = await fs.stat(sourceAbsolutePath);\n    current = variantGenerationTag(stats.size, stats.mtimeMs);\n  } catch {\n    // the source is gone; its derivatives are purged by the delete itself\n    return;\n  }\n\n  if (current !== keep) return;\n\n  await pruneStaleVariantGenerations(sourceDirectory, keep);\n}\n\n/**\n * True for \"no such file or directory\"\n */\nexport function isMissingFileError(error: unknown): boolean {\n  return (error as NodeJS.ErrnoException | undefined)?.code === \"ENOENT\";\n}\n\n/**\n * Run a derivative write, once more if it fails because its directory\n * vanished: a concurrent request for a newer version of the source may prune\n * the generation directory between `mkdir` and the atomic rename.\n */\nexport async function retryOnVanishedDirectory(write: () => Promise<void>): Promise<void> {\n  try {\n    await write();\n  } catch (error) {\n    if (!isMissingFileError(error)) throw error;\n\n    await write();\n  }\n}\n\nlet warnedPublicCache = false;\n\n/**\n * Warn once when the derivative cache sits inside the public folder.\n *\n * A configured `uploads.images.cacheDirectory` is shared by every local disk,\n * so derivatives of a private disk land beside public ones. Inside\n * `public/` (or `storage.publicRoot`) they are served to anyone, bypassing\n * whatever guards the private disk's own route. The paths are hashes, but\n * they are derived from the disk root and the file path, which are not\n * secret.\n */\nexport function warnIfVariantCacheIsPublic(cacheDirectory: string): void {\n  if (warnedPublicCache) return;\n\n  const configured = config.get(\"storage.publicRoot\", rootPath(\"public\")) as unknown;\n  const publicRoots = (Array.isArray(configured) ? configured : [configured])\n    .filter((root): root is string => typeof root === \"string\" && root.length > 0)\n    .map((root) => path.resolve(root));\n  const resolved = path.resolve(cacheDirectory);\n\n  if (!publicRoots.some((root) => resolved === root || isPathInside(resolved, root))) return;\n\n  warnedPublicCache = true;\n  log.warn(\n    \"uploads\",\n    \"image-variants\",\n    `The image variant cache (${resolved}) is inside the public folder, so every cached derivative, private disks included, is publicly served. Move uploads.images.cacheDirectory outside public/.`,\n  );\n}\n\n/**\n * Forget that the public-cache warning was shown (tests).\n */\nexport function resetVariantCacheWarnings(): void {\n  warnedPublicCache = false;\n}\n"],"mappings":"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"}

package/esm/http/uploads/image-variant-types.d.mts

@@ -1,6 +1,6 @@
 import { ImageVariantDefinition, ImageVariantOutputFormat } from "../uploads-types.mjs";
 
-//#region ../core/src/http/uploads/image-variant-types.d.ts
+//#region ../../packages/core/src/http/uploads/image-variant-types.d.ts
 /**
  * The `uploads.images` config after validation, with every default applied
  */
@@ -10,6 +10,8 @@ type ResolvedImageVariantsConfig = {
   maxSourceBytes: number;
   maxSourcePixels: number;
   cacheDirectory: string;
+  maxCacheBytes: number;
+  maxCacheAge: number;
 };
 /**
  * Raster formats a variant can be generated from, detected by magic bytes

package/esm/http/uploads/image-variant-types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"image-variant-types.d.mts","names":[],"sources":["../../../../../../../../core/src/http/uploads/image-variant-types.ts"],"mappings":";;;;;AAKA;KAAY,2BAAA;EACV,QAAA,EAAU,QAAA,CAAS,MAAA,SAAe,sBAAA;EAClC,OAAA,WAAkB,wBAAA;EAClB,cAAA;EACA,eAAA;EACA,cAAA;AAAA;;;;KAMU,mBAAA;;;;KAKA,mBAAA,GAAsB,mBAAmB;;;;KAKzC,mBAAA,GAAsB,mBAAmB;AAVrD;;;AAAA,KAeY,iBAAA;EACN,IAAA;AAAA;EACA,IAAA;EAAiB,OAAA;EAAiB,MAAA;AAAA;EAClC,IAAA;EAAiB,MAAA;AAAA;;AAR8B;AAKrD;;;;;;KAaY,qBAAA;EAX4B;;;EAetC,KAAA;EAd2B;AAU7B;;EASE,MAAA;EAUsB;;;EALtB,GAAA;EAKc;;;EAAd,IAAA,GAAO,OAAA,CAAQ,MAAA,CAAO,wBAAA;AAAA;;;;;KAOZ,wBAAA;EAAA;;;EAIV,GAAA;EAemB;;;EAVnB,KAAA;EAe2C;;;EAV3C,MAAA;EAKA;;;EAAA,QAAA,EAAU,QAAA,CAAS,MAAA,SAAe,qBAAA;EAKlC;;;EAAA,OAAA,YAAmB,wBAAA;AAAA"}
+{"version":3,"file":"image-variant-types.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/image-variant-types.ts"],"mappings":";;;;;AAKA;KAAY,2BAAA;EACV,QAAA,EAAU,QAAA,CAAS,MAAA,SAAe,sBAAA;EAClC,OAAA,WAAkB,wBAAA;EAClB,cAAA;EACA,eAAA;EACA,cAAA;EACA,aAAA;EACA,WAAA;AAAA;;;;KAMU,mBAAA;;;;KAKA,mBAAA,GAAsB,mBAAmB;;;;KAKzC,mBAAA,GAAsB,mBAAmB;AAVrD;;;AAAA,KAeY,iBAAA;EACN,IAAA;AAAA;EACA,IAAA;EAAiB,OAAA;EAAiB,MAAA;AAAA;EAClC,IAAA;EAAiB,MAAA;AAAA;;AAR8B;AAKrD;;;;;;KAaY,qBAAA;EAX4B;;;EAetC,KAAA;EAd2B;AAU7B;;EASE,MAAA;EAUsB;;;EALtB,GAAA;EAKc;;;EAAd,IAAA,GAAO,OAAA,CAAQ,MAAA,CAAO,wBAAA;AAAA;;;;;KAOZ,wBAAA;EAAA;;;EAIV,GAAA;EAemB;;;EAVnB,KAAA;EAe2C;;;EAV3C,MAAA;EAKA;;;EAAA,QAAA,EAAU,QAAA,CAAS,MAAA,SAAe,qBAAA;EAKlC;;;EAAA,OAAA,YAAmB,wBAAA;AAAA"}

package/esm/http/uploads/image-variants-config-error.d.mts

@@ -1,4 +1,4 @@
-//#region ../core/src/http/uploads/image-variants-config-error.d.ts
+//#region ../../packages/core/src/http/uploads/image-variants-config-error.d.ts
 /**
  * Thrown when the `uploads.images` configuration is invalid.
  *
@@ -6,7 +6,9 @@
  * on the first image instead of producing unbounded or surprising derivatives.
  */
 declare class ImageVariantsConfigError extends Error {
-  constructor(message: string);
+  /** Stable Warlock error code; `warlock explain WL1005` prints the fix. */
+  readonly code = "WL1005";
+  constructor(message: string, options?: ErrorOptions);
 }
 //#endregion
 export { ImageVariantsConfigError };

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

@@ -1 +1 @@
-{"version":3,"file":"image-variants-config-error.d.mts","names":[],"sources":["../../../../../../../../core/src/http/uploads/image-variants-config-error.ts"],"mappings":";;AAMA;;;;;cAAa,wBAAA,SAAiC,KAAK;cAC9B,OAAA;AAAA"}
+{"version":3,"file":"image-variants-config-error.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/image-variants-config-error.ts"],"mappings":";;AAMA;;;;;cAAa,wBAAA,SAAiC,KAAK;;WAEjC,IAAA;cAEG,OAAA,UAAiB,OAAA,GAAU,YAAA;AAAA"}

package/esm/http/uploads/image-variants-config-error.mjs

@@ -1,4 +1,4 @@
-//#region ../core/src/http/uploads/image-variants-config-error.ts
+//#region ../../packages/core/src/http/uploads/image-variants-config-error.ts
 /**
 * Thrown when the `uploads.images` configuration is invalid.
 *
@@ -6,8 +6,9 @@
 * on the first image instead of producing unbounded or surprising derivatives.
 */
 var ImageVariantsConfigError = class extends Error {
-	constructor(message) {
-		super(`Invalid uploads.images configuration: ${message}`);
+	constructor(message, options) {
+		super(`Invalid uploads.images configuration: ${message}`, options);
+		this.code = "WL1005";
 		this.name = "ImageVariantsConfigError";
 	}
 };

package/esm/http/uploads/image-variants-config-error.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"image-variants-config-error.mjs","names":[],"sources":["../../../../../../../../core/src/http/uploads/image-variants-config-error.ts"],"sourcesContent":["/**\n * Thrown when the `uploads.images` configuration is invalid.\n *\n * Raised the first time a variant is requested, so a bad config fails loudly\n * on the first image instead of producing unbounded or surprising derivatives.\n */\nexport class ImageVariantsConfigError extends Error {\n  public constructor(message: string) {\n    super(`Invalid uploads.images configuration: ${message}`);\n\n    this.name = \"ImageVariantsConfigError\";\n  }\n}\n"],"mappings":";;;;;;;AAMA,IAAa,2BAAb,cAA8C,MAAM;CAClD,AAAO,YAAY,SAAiB;EAClC,MAAM,yCAAyC,SAAS;EAExD,KAAK,OAAO;CACd;AACF"}
+{"version":3,"file":"image-variants-config-error.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/image-variants-config-error.ts"],"sourcesContent":["/**\n * Thrown when the `uploads.images` configuration is invalid.\n *\n * Raised the first time a variant is requested, so a bad config fails loudly\n * on the first image instead of producing unbounded or surprising derivatives.\n */\nexport class ImageVariantsConfigError extends Error {\n  /** Stable Warlock error code; `warlock explain WL1005` prints the fix. */\n  public readonly code = \"WL1005\";\n\n  public constructor(message: string, options?: ErrorOptions) {\n    super(`Invalid uploads.images configuration: ${message}`, options);\n\n    this.name = \"ImageVariantsConfigError\";\n  }\n}\n"],"mappings":";;;;;;;AAMA,IAAa,2BAAb,cAA8C,MAAM;CAIlD,AAAO,YAAY,SAAiB,SAAwB;EAC1D,MAAM,yCAAyC,WAAW,OAAO;cAH5C;EAKrB,KAAK,OAAO;CACd;AACF"}

package/esm/http/uploads/index.d.mts

@@ -1,4 +1,6 @@
 import { DetectedImageFormat, GeneratedImageDescriptor, GeneratedImageVariant, ResolvedImageVariantsConfig, UploadedFileQuery, VariantOutputFormat, VariantSourceFormat } from "./image-variant-types.mjs";
 import { GenerateImageVariantsOptions, generateImageVariants } from "./generate-image-variants.mjs";
 import { ImageVariantsConfigError } from "./image-variants-config-error.mjs";
-import { uploadedFileController } from "./uploaded-file.controller.mjs";
+import { PurgeImageVariantsOptions, purgeImageVariants } from "./purge-image-variants.mjs";
+import { ResolveImageVariantInput, ResolvedImageVariant, resolveImageVariant } from "./resolve-image-variant.mjs";
+import { UploadedFileControllerOptions, createUploadedFileController, uploadedFileController } from "./uploaded-file.controller.mjs";

package/esm/http/uploads/index.mjs

@@ -1,5 +1,7 @@
 import { ImageVariantsConfigError } from "./image-variants-config-error.mjs";
 import { generateImageVariants } from "./generate-image-variants.mjs";
-import { uploadedFileController } from "./uploaded-file.controller.mjs";
+import { purgeImageVariants } from "./purge-image-variants.mjs";
+import { resolveImageVariant } from "./resolve-image-variant.mjs";
+import { createUploadedFileController, uploadedFileController } from "./uploaded-file.controller.mjs";
 
 export {  };

package/esm/http/uploads/is-path-inside.mjs

@@ -1,6 +1,6 @@
 import path from "node:path";
 
-//#region ../core/src/http/uploads/is-path-inside.ts
+//#region ../../packages/core/src/http/uploads/is-path-inside.ts
 /**
 * Whether `candidate` is strictly inside `directory` (never equal to it).
 *