@warlock.js/core 5.30.0 → 5.32.0

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

@@ -1 +1 @@
-{"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 { 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 {\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 { 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  warnIfVariantCacheIsPublic(images.cacheDirectory);\n\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 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 exists(target))) {\n        // keyed on the target, which includes the disk root (see resolveImageVariant)\n        await variantGenerations.run(target, async () => {\n          if (await exists(target)) return;\n\n          await retryOnVanishedDirectory(() =>\n            generateImageVariant({ image: image.clone(), variant, format, targetPath: target }),\n          );\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"],"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":"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"}

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, variantSourceCacheGenerations };
+//# 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

@@ -1,10 +1,14 @@
 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 } from "./is-path-inside.mjs";
+import { isPathInside, isPathWithin } from "./is-path-inside.mjs";
 import { variantGenerationTag, variantSourceDirectory, variantSourceKey } from "./variant-cache-key.mjs";
-import config from "@mongez/config";
+import baseConfig from "@mongez/config";
 import { log } from "@warlock.js/logger";
 import path from "node:path";
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 
 //#region ../../packages/core/src/http/uploads/image-variant-cache.ts
@@ -15,16 +19,70 @@ async function realpathOrSelf(target) {
 		return target;
 	}
 }
+function canonicalDirectory(target) {
+	const resolved = path.resolve(target);
+	try {
+		return fsSync.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`.
+* `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) {
-	const configured = uploadsConfig("images")?.cacheDirectory;
-	return configured ? path.resolve(configured) : path.join(path.resolve(diskRoot), ".cache", "image-variants");
+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
@@ -44,39 +102,23 @@ async function variantSourceDirectoryForFile(diskRoot, absolutePath) {
 /**
 * Remove every cached derivative of one file on a local disk.
 *
-* @returns `true` when a cache directory for the file existed and was removed
+* @returns `true` when recognized cache files were removed
 */
 async function purgeImageVariantsOfFile(diskRoot, absolutePath) {
 	const directory = await variantSourceDirectoryForFile(diskRoot, absolutePath);
 	if (!directory) return false;
-	try {
-		await fs.access(directory);
-	} catch {
-		return false;
-	}
-	await fs.rm(directory, {
-		recursive: true,
-		force: true
-	});
-	return true;
+	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.
+* 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) {
-	let entries;
-	try {
-		entries = await fs.readdir(sourceDirectory);
-	} catch {
-		return;
-	}
-	await Promise.all(entries.filter((entry) => entry !== keep).map((entry) => fs.rm(path.join(sourceDirectory, entry), {
-		recursive: true,
-		force: true
-	})));
+	await purgeVariantCacheEntries(variantSourceCacheEntries(sourceDirectory, keep));
 }
 /**
 * {@link pruneStaleVariantGenerations}, but only while `keep` is still the
@@ -130,7 +172,7 @@ let warnedPublicCache = false;
 */
 function warnIfVariantCacheIsPublic(cacheDirectory) {
 	if (warnedPublicCache) return;
-	const configured = config.get("storage.publicRoot", rootPath("public"));
+	const configured = baseConfig.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;
@@ -139,5 +181,5 @@ function warnIfVariantCacheIsPublic(cacheDirectory) {
 }
 
 //#endregion
-export { isMissingFileError, pruneStaleVariantGenerationsIfCurrent, purgeImageVariantsOfFile, retryOnVanishedDirectory, variantCacheDirectoryFor, warnIfVariantCacheIsPublic };
+export { isMissingFileError, pruneStaleVariantGenerations, pruneStaleVariantGenerationsIfCurrent, purgeImageVariantsOfFile, retryOnVanishedDirectory, variantCacheDirectoryFor, variantSourceDirectoryForFile, warnIfVariantCacheIsPublic };
 //# sourceMappingURL=image-variant-cache.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"image-variant-cache.mjs","names":[],"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 path from \"node:path\";\nimport { rootPath } from \"../../utils/paths\";\nimport { uploadsConfig } from \"../uploads-config\";\nimport { isPathInside } 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 * `storage` import: the local storage 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\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`.\n */\nexport function variantCacheDirectoryFor(diskRoot: string): string {\n  const configured = uploadsConfig(\"images\")?.cacheDirectory;\n\n  return configured\n    ? path.resolve(configured)\n    : path.join(path.resolve(diskRoot), \".cache\", \"image-variants\");\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 a cache directory for the file existed and was 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  try {\n    await fs.access(directory);\n  } catch {\n    return false;\n  }\n\n  await fs.rm(directory, { recursive: true, force: true });\n\n  return true;\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.\n */\nexport async function pruneStaleVariantGenerations(\n  sourceDirectory: string,\n  keep: string,\n): Promise<void> {\n  let entries: string[];\n\n  try {\n    entries = await fs.readdir(sourceDirectory);\n  } catch {\n    return;\n  }\n\n  await Promise.all(\n    entries\n      .filter((entry) => entry !== keep)\n      .map((entry) => fs.rm(path.join(sourceDirectory, entry), { recursive: true, force: true })),\n  );\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":";;;;;;;;;;AAoBA,eAAe,eAAe,QAAiC;CAC7D,IAAI;EACF,OAAO,MAAM,GAAG,SAAS,MAAM;CACjC,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;AASA,SAAgB,yBAAyB,UAA0B;CACjE,MAAM,aAAa,cAAc,QAAQ,CAAC,EAAE;CAE5C,OAAO,aACH,KAAK,QAAQ,UAAU,IACvB,KAAK,KAAK,KAAK,QAAQ,QAAQ,GAAG,UAAU,gBAAgB;AAClE;;;;;;;;AASA,eAAsB,8BACpB,UACA,cAC6B;CAC7B,MAAM,WAAW,MAAM,eAAe,KAAK,QAAQ,QAAQ,CAAC;CAC5D,MAAM,aAAa,MAAM,eAAe,KAAK,QAAQ,KAAK,QAAQ,YAAY,CAAC,CAAC;CAChF,MAAM,WAAW,KAAK,KAAK,YAAY,KAAK,SAAS,YAAY,CAAC;CAElE,IAAI,CAAC,aAAa,UAAU,QAAQ,GAAG,OAAO;CAE9C,MAAM,eAAe,KAAK,SAAS,UAAU,QAAQ,CAAC,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,GAAG;CAE/E,OAAO,uBACL,yBAAyB,QAAQ,GACjC,iBAAiB,UAAU,YAAY,CACzC;AACF;;;;;;AAOA,eAAsB,yBACpB,UACA,cACkB;CAClB,MAAM,YAAY,MAAM,8BAA8B,UAAU,YAAY;CAE5E,IAAI,CAAC,WAAW,OAAO;CAEvB,IAAI;EACF,MAAM,GAAG,OAAO,SAAS;CAC3B,QAAQ;EACN,OAAO;CACT;CAEA,MAAM,GAAG,GAAG,WAAW;EAAE,WAAW;EAAM,OAAO;CAAK,CAAC;CAEvD,OAAO;AACT;;;;;;;AAQA,eAAsB,6BACpB,iBACA,MACe;CACf,IAAI;CAEJ,IAAI;EACF,UAAU,MAAM,GAAG,QAAQ,eAAe;CAC5C,QAAQ;EACN;CACF;CAEA,MAAM,QAAQ,IACZ,QACG,QAAQ,UAAU,UAAU,IAAI,CAAC,CACjC,KAAK,UAAU,GAAG,GAAG,KAAK,KAAK,iBAAiB,KAAK,GAAG;EAAE,WAAW;EAAM,OAAO;CAAK,CAAC,CAAC,CAC9F;AACF;;;;;;;;;;AAWA,eAAsB,sCACpB,oBACA,iBACA,MACe;CACf,IAAI;CAEJ,IAAI;EACF,MAAM,QAAQ,MAAM,GAAG,KAAK,kBAAkB;EAC9C,UAAU,qBAAqB,MAAM,MAAM,MAAM,OAAO;CAC1D,QAAQ;EAEN;CACF;CAEA,IAAI,YAAY,MAAM;CAEtB,MAAM,6BAA6B,iBAAiB,IAAI;AAC1D;;;;AAKA,SAAgB,mBAAmB,OAAyB;CAC1D,OAAQ,OAA6C,SAAS;AAChE;;;;;;AAOA,eAAsB,yBAAyB,OAA2C;CACxF,IAAI;EACF,MAAM,MAAM;CACd,SAAS,OAAO;EACd,IAAI,CAAC,mBAAmB,KAAK,GAAG,MAAM;EAEtC,MAAM,MAAM;CACd;AACF;AAEA,IAAI,oBAAoB;;;;;;;;;;;AAYxB,SAAgB,2BAA2B,gBAA8B;CACvE,IAAI,mBAAmB;CAEvB,MAAM,aAAa,OAAO,IAAI,sBAAsB,SAAS,QAAQ,CAAC;CACtE,MAAM,eAAe,MAAM,QAAQ,UAAU,IAAI,aAAa,CAAC,UAAU,EAAC,CACvE,QAAQ,SAAyB,OAAO,SAAS,YAAY,KAAK,SAAS,CAAC,CAAC,CAC7E,KAAK,SAAS,KAAK,QAAQ,IAAI,CAAC;CACnC,MAAM,WAAW,KAAK,QAAQ,cAAc;CAE5C,IAAI,CAAC,YAAY,MAAM,SAAS,aAAa,QAAQ,aAAa,UAAU,IAAI,CAAC,GAAG;CAEpF,oBAAoB;CACpB,IAAI,KACF,WACA,kBACA,4BAA4B,SAAS,2JACvC;AACF"}
+{"version":3,"file":"image-variant-cache.mjs","names":["config"],"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,32 +1,33 @@
 import { ImageVariantDefinition, ImageVariantOutputFormat } from "../uploads-types.mjs";
-
 //#region ../../packages/core/src/http/uploads/image-variant-types.d.ts
 /**
  * The `uploads.images` config after validation, with every default applied
  */
-type ResolvedImageVariantsConfig = {
+export type ResolvedImageVariantsConfig = {
   variants: Readonly<Record<string, ImageVariantDefinition>>;
   formats: readonly ImageVariantOutputFormat[];
   maxSourceBytes: number;
   maxSourcePixels: number;
   cacheDirectory: string;
+  maxCacheBytes: number;
+  maxCacheAge: number;
 };
 /**
  * Raster formats a variant can be generated from, detected by magic bytes
  */
-type VariantSourceFormat = "jpeg" | "png" | "webp" | "avif";
+export type VariantSourceFormat = "jpeg" | "png" | "webp" | "avif";
 /**
  * Every format `detectImageFormat` can recognise, including the refused ones
  */
-type DetectedImageFormat = VariantSourceFormat | "gif" | "svg";
+export type DetectedImageFormat = VariantSourceFormat | "gif" | "svg";
 /**
  * Format a derivative is written in
  */
-type VariantOutputFormat = VariantSourceFormat;
+export type VariantOutputFormat = VariantSourceFormat;
 /**
  * What the query string of an uploads request asks for
  */
-type UploadedFileQuery = {
+export type UploadedFileQuery = {
   type: "original";
 } | {
   type: "variant";
@@ -44,7 +45,7 @@ type UploadedFileQuery = {
  * passed through loader data as is. Core does not import that type — web
  * depends on core, not the other way around — this is a structural match.
  */
-type GeneratedImageVariant = {
+export type GeneratedImageVariant = {
   /**
    * Actual rendered width, in pixels
    */
@@ -66,7 +67,7 @@ type GeneratedImageVariant = {
  * Serializable descriptor returned by `generateImageVariants`, matching web's
  * `ImageDescriptor` field for field.
  */
-type GeneratedImageDescriptor = {
+export type GeneratedImageDescriptor = {
   /**
    * The original source path: `/uploads/<path>`
    */
@@ -89,5 +90,4 @@ type GeneratedImageDescriptor = {
   formats?: readonly ImageVariantOutputFormat[];
 };
 //#endregion
-export { DetectedImageFormat, GeneratedImageDescriptor, GeneratedImageVariant, ResolvedImageVariantsConfig, UploadedFileQuery, VariantOutputFormat, VariantSourceFormat };
 //# sourceMappingURL=image-variant-types.d.mts.map

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

@@ -1 +1 @@
-{"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;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":";;;;;YAKY;EACV,UAAU,SAAS,eAAe;EAClC,kBAAkB;EAClB;EACA;EACA;EACA;EACA;;;;;YAMU;;;;YAKA,sBAAsB;;;;YAKtB,sBAAsB;;;;YAKtB;EACN;;EACA;EAAiB;EAAiB;;EAClC;EAAiB;;;;;;;;;;YAUX;;;;EAIV;;;;EAKA;;;;EAKA;;;;EAKA,OAAO,QAAQ,OAAO;;;;;;YAOZ;;;;EAIV;;;;EAKA;;;;EAKA;;;;EAKA,UAAU,SAAS,eAAe;;;;EAKlC,mBAAmB"}

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

@@ -5,9 +5,10 @@
  * Raised the first time a variant is requested, so a bad config fails loudly
  * on the first image instead of producing unbounded or surprising derivatives.
  */
-declare class ImageVariantsConfigError extends Error {
-  constructor(message: string);
+export declare class ImageVariantsConfigError extends Error {
+  /** Stable Warlock error code; `warlock explain WL1005` prints the fix. */
+  readonly code = "WL1005";
+  constructor(message: string, options?: ErrorOptions);
 }
 //#endregion
-export { ImageVariantsConfigError };
 //# sourceMappingURL=image-variants-config-error.d.mts.map

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

@@ -1 +1 @@
-{"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;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":";;;;;;;qBAMa,iCAAiC;;WAE5B;EAEhB,YAAmB,iBAAiB,UAAU"}

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

@@ -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":["../../../../../../../../../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  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

@@ -3,4 +3,5 @@ import { GenerateImageVariantsOptions, generateImageVariants } from "./generate-
 import { ImageVariantsConfigError } from "./image-variants-config-error.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";
+import { UploadedFileControllerOptions, createUploadedFileController, uploadedFileController } from "./uploaded-file.controller.mjs";
+export { DetectedImageFormat, GenerateImageVariantsOptions, GeneratedImageDescriptor, GeneratedImageVariant, ImageVariantsConfigError, PurgeImageVariantsOptions, ResolveImageVariantInput, ResolvedImageVariant, ResolvedImageVariantsConfig, UploadedFileControllerOptions, UploadedFileQuery, VariantOutputFormat, VariantSourceFormat, createUploadedFileController, generateImageVariants, purgeImageVariants, resolveImageVariant, uploadedFileController };

package/esm/http/uploads/index.mjs

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

package/esm/http/uploads/load-variant-source.mjs

@@ -21,7 +21,7 @@ import fs from "node:fs/promises";
 * I/O) propagates unchanged.
 */
 async function loadVariantSource(absolutePath, { maxSourceBytes, maxSourcePixels, expectedFormat }) {
-	const buffer = await fs.readFile(absolutePath);
+	const buffer = Buffer.isBuffer(absolutePath) ? absolutePath : await fs.readFile(absolutePath);
 	if (buffer.length > maxSourceBytes) throw new HttpError(413, "The source image is too large.");
 	if (detectImageFormat(buffer) !== expectedFormat) throw new HttpError(415, "The source image changed format while it was read.");
 	const image = new Image(buffer);

package/esm/http/uploads/load-variant-source.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"load-variant-source.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/load-variant-source.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport { Image } from \"../../image\";\nimport { HttpError } from \"../errors\";\nimport { detectImageFormat } from \"./detect-image-format\";\nimport type { VariantSourceFormat } from \"./image-variant-types\";\n\n/**\n * Bounds and the expected format a source must match\n */\nexport type LoadVariantSourceOptions = {\n  maxSourceBytes: number;\n  maxSourcePixels: number;\n  expectedFormat: VariantSourceFormat;\n};\n\n/**\n * Read a variant source in full and check it before it is decoded.\n *\n * The caller has already sniffed the format from the file head; this re-checks\n * the bytes actually read, the same buffer that is then resized, so the file\n * cannot be swapped between the check and the render.\n *\n * - bytes over `maxSourceBytes` → 413\n * - magic bytes that no longer match `expectedFormat` → 415\n * - a header sharp cannot read (e.g. avif without a decoder) → 415\n * - width × height over `maxSourcePixels` → 413, read from the header only\n *\n * @throws HttpError with status 413 or 415. Any other error (sharp missing,\n * I/O) propagates unchanged.\n */\nexport async function loadVariantSource(\n  absolutePath: string,\n  { maxSourceBytes, maxSourcePixels, expectedFormat }: LoadVariantSourceOptions,\n): Promise<Image> {\n  const buffer = await fs.readFile(absolutePath);\n\n  if (buffer.length > maxSourceBytes) {\n    throw new HttpError(413, \"The source image is too large.\");\n  }\n\n  if (detectImageFormat(buffer) !== expectedFormat) {\n    throw new HttpError(415, \"The source image changed format while it was read.\");\n  }\n\n  // Constructed outside the try below: sharp being absent is a server fault\n  // (500 with the install hint), not an unsupported image.\n  const image = new Image(buffer);\n\n  let width: number | undefined;\n  let height: number | undefined;\n\n  try {\n    ({ width, height } = await image.metadata());\n  } catch {\n    throw new HttpError(415, \"The source image cannot be decoded.\");\n  }\n\n  if (!width || !height) {\n    throw new HttpError(415, \"The source image cannot be decoded.\");\n  }\n\n  if (width * height > maxSourcePixels) {\n    throw new HttpError(413, \"The source image has too many pixels.\");\n  }\n\n  return image;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA8BA,eAAsB,kBACpB,cACA,EAAE,gBAAgB,iBAAiB,kBACnB;CAChB,MAAM,SAAS,MAAM,GAAG,SAAS,YAAY;CAE7C,IAAI,OAAO,SAAS,gBAClB,MAAM,IAAI,UAAU,KAAK,gCAAgC;CAG3D,IAAI,kBAAkB,MAAM,MAAM,gBAChC,MAAM,IAAI,UAAU,KAAK,oDAAoD;CAK/E,MAAM,QAAQ,IAAI,MAAM,MAAM;CAE9B,IAAI;CACJ,IAAI;CAEJ,IAAI;EACF,CAAC,CAAE,OAAO,UAAW,MAAM,MAAM,SAAS;CAC5C,QAAQ;EACN,MAAM,IAAI,UAAU,KAAK,qCAAqC;CAChE;CAEA,IAAI,CAAC,SAAS,CAAC,QACb,MAAM,IAAI,UAAU,KAAK,qCAAqC;CAGhE,IAAI,QAAQ,SAAS,iBACnB,MAAM,IAAI,UAAU,KAAK,uCAAuC;CAGlE,OAAO;AACT"}
+{"version":3,"file":"load-variant-source.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/load-variant-source.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport { Image } from \"../../image\";\nimport { HttpError } from \"../errors\";\nimport { detectImageFormat } from \"./detect-image-format\";\nimport type { VariantSourceFormat } from \"./image-variant-types\";\n\n/**\n * Bounds and the expected format a source must match\n */\nexport type LoadVariantSourceOptions = {\n  maxSourceBytes: number;\n  maxSourcePixels: number;\n  expectedFormat: VariantSourceFormat;\n};\n\n/**\n * Read a variant source in full and check it before it is decoded.\n *\n * The caller has already sniffed the format from the file head; this re-checks\n * the bytes actually read, the same buffer that is then resized, so the file\n * cannot be swapped between the check and the render.\n *\n * - bytes over `maxSourceBytes` → 413\n * - magic bytes that no longer match `expectedFormat` → 415\n * - a header sharp cannot read (e.g. avif without a decoder) → 415\n * - width × height over `maxSourcePixels` → 413, read from the header only\n *\n * @throws HttpError with status 413 or 415. Any other error (sharp missing,\n * I/O) propagates unchanged.\n */\nexport async function loadVariantSource(\n  absolutePath: string | Buffer,\n  { maxSourceBytes, maxSourcePixels, expectedFormat }: LoadVariantSourceOptions,\n): Promise<Image> {\n  const buffer = Buffer.isBuffer(absolutePath) ? absolutePath : await fs.readFile(absolutePath);\n\n  if (buffer.length > maxSourceBytes) {\n    throw new HttpError(413, \"The source image is too large.\");\n  }\n\n  if (detectImageFormat(buffer) !== expectedFormat) {\n    throw new HttpError(415, \"The source image changed format while it was read.\");\n  }\n\n  // Constructed outside the try below: sharp being absent is a server fault\n  // (500 with the install hint), not an unsupported image.\n  const image = new Image(buffer);\n\n  let width: number | undefined;\n  let height: number | undefined;\n\n  try {\n    ({ width, height } = await image.metadata());\n  } catch {\n    throw new HttpError(415, \"The source image cannot be decoded.\");\n  }\n\n  if (!width || !height) {\n    throw new HttpError(415, \"The source image cannot be decoded.\");\n  }\n\n  if (width * height > maxSourcePixels) {\n    throw new HttpError(413, \"The source image has too many pixels.\");\n  }\n\n  return image;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA8BA,eAAsB,kBACpB,cACA,EAAE,gBAAgB,iBAAiB,kBACnB;CAChB,MAAM,SAAS,OAAO,SAAS,YAAY,IAAI,eAAe,MAAM,GAAG,SAAS,YAAY;CAE5F,IAAI,OAAO,SAAS,gBAClB,MAAM,IAAI,UAAU,KAAK,gCAAgC;CAG3D,IAAI,kBAAkB,MAAM,MAAM,gBAChC,MAAM,IAAI,UAAU,KAAK,oDAAoD;CAK/E,MAAM,QAAQ,IAAI,MAAM,MAAM;CAE9B,IAAI;CACJ,IAAI;CAEJ,IAAI;EACF,CAAC,CAAE,OAAO,UAAW,MAAM,MAAM,SAAS;CAC5C,QAAQ;EACN,MAAM,IAAI,UAAU,KAAK,qCAAqC;CAChE;CAEA,IAAI,CAAC,SAAS,CAAC,QACb,MAAM,IAAI,UAAU,KAAK,qCAAqC;CAGhE,IAAI,QAAQ,SAAS,iBACnB,MAAM,IAAI,UAAU,KAAK,uCAAuC;CAGlE,OAAO;AACT"}

package/esm/http/uploads/parse-uploaded-file-query.mjs

@@ -1,5 +1,5 @@
 //#region ../../packages/core/src/http/uploads/parse-uploaded-file-query.ts
-const ALLOWED_KEYS = new Set(["variant", "format"]);
+const ALLOWED_KEYS = /* @__PURE__ */ new Set(["variant", "format"]);
 /**
 * Read the query string of an uploads request, strictly.
 *

package/esm/http/uploads/parse-uploaded-file-query.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"parse-uploaded-file-query.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/parse-uploaded-file-query.ts"],"sourcesContent":["import type { UploadedFileQuery } from \"./image-variant-types\";\n\nconst ALLOWED_KEYS = new Set([\"variant\", \"format\"]);\n\n/**\n * Read the query string of an uploads request, strictly.\n *\n * It parses the raw URL rather than the framework's parsed query, because the\n * parsed form folds a repeated key into an array and a lone key into a string,\n * and a strict allowlist has to see both. Only `variant` and `format` are\n * accepted, each at most once, and `format` only next to `variant`.\n *\n * @param url - the raw request URL, path and query\n */\nexport function parseUploadedFileQuery(url: string): UploadedFileQuery {\n  const queryStart = url.indexOf(\"?\");\n  const rawQuery = queryStart === -1 ? \"\" : url.slice(queryStart + 1);\n\n  if (rawQuery === \"\") return { type: \"original\" };\n\n  const values = new Map<string, string>();\n\n  for (const [key, value] of new URLSearchParams(rawQuery)) {\n    if (!ALLOWED_KEYS.has(key)) {\n      return { type: \"invalid\", reason: `Unknown query parameter \"${key}\".` };\n    }\n\n    if (values.has(key)) {\n      return { type: \"invalid\", reason: `Query parameter \"${key}\" is repeated.` };\n    }\n\n    values.set(key, value);\n  }\n\n  const variant = values.get(\"variant\");\n  const format = values.get(\"format\");\n\n  if (variant === undefined) {\n    return values.size === 0\n      ? { type: \"original\" }\n      : { type: \"invalid\", reason: `\"format\" requires \"variant\".` };\n  }\n\n  if (variant === \"\") {\n    return { type: \"invalid\", reason: `\"variant\" must not be empty.` };\n  }\n\n  return format === undefined ? { type: \"variant\", variant } : { type: \"variant\", variant, format };\n}\n"],"mappings":";AAEA,MAAM,eAAe,IAAI,IAAI,CAAC,WAAW,QAAQ,CAAC;;;;;;;;;;;AAYlD,SAAgB,uBAAuB,KAAgC;CACrE,MAAM,aAAa,IAAI,QAAQ,GAAG;CAClC,MAAM,WAAW,eAAe,KAAK,KAAK,IAAI,MAAM,aAAa,CAAC;CAElE,IAAI,aAAa,IAAI,OAAO,EAAE,MAAM,WAAW;CAE/C,MAAM,yBAAS,IAAI,IAAoB;CAEvC,KAAK,MAAM,CAAC,KAAK,UAAU,IAAI,gBAAgB,QAAQ,GAAG;EACxD,IAAI,CAAC,aAAa,IAAI,GAAG,GACvB,OAAO;GAAE,MAAM;GAAW,QAAQ,4BAA4B,IAAI;EAAI;EAGxE,IAAI,OAAO,IAAI,GAAG,GAChB,OAAO;GAAE,MAAM;GAAW,QAAQ,oBAAoB,IAAI;EAAgB;EAG5E,OAAO,IAAI,KAAK,KAAK;CACvB;CAEA,MAAM,UAAU,OAAO,IAAI,SAAS;CACpC,MAAM,SAAS,OAAO,IAAI,QAAQ;CAElC,IAAI,YAAY,QACd,OAAO,OAAO,SAAS,IACnB,EAAE,MAAM,WAAW,IACnB;EAAE,MAAM;EAAW,QAAQ;CAA+B;CAGhE,IAAI,YAAY,IACd,OAAO;EAAE,MAAM;EAAW,QAAQ;CAA+B;CAGnE,OAAO,WAAW,SAAY;EAAE,MAAM;EAAW;CAAQ,IAAI;EAAE,MAAM;EAAW;EAAS;CAAO;AAClG"}
+{"version":3,"file":"parse-uploaded-file-query.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/parse-uploaded-file-query.ts"],"sourcesContent":["import type { UploadedFileQuery } from \"./image-variant-types\";\n\nconst ALLOWED_KEYS = new Set([\"variant\", \"format\"]);\n\n/**\n * Read the query string of an uploads request, strictly.\n *\n * It parses the raw URL rather than the framework's parsed query, because the\n * parsed form folds a repeated key into an array and a lone key into a string,\n * and a strict allowlist has to see both. Only `variant` and `format` are\n * accepted, each at most once, and `format` only next to `variant`.\n *\n * @param url - the raw request URL, path and query\n */\nexport function parseUploadedFileQuery(url: string): UploadedFileQuery {\n  const queryStart = url.indexOf(\"?\");\n  const rawQuery = queryStart === -1 ? \"\" : url.slice(queryStart + 1);\n\n  if (rawQuery === \"\") return { type: \"original\" };\n\n  const values = new Map<string, string>();\n\n  for (const [key, value] of new URLSearchParams(rawQuery)) {\n    if (!ALLOWED_KEYS.has(key)) {\n      return { type: \"invalid\", reason: `Unknown query parameter \"${key}\".` };\n    }\n\n    if (values.has(key)) {\n      return { type: \"invalid\", reason: `Query parameter \"${key}\" is repeated.` };\n    }\n\n    values.set(key, value);\n  }\n\n  const variant = values.get(\"variant\");\n  const format = values.get(\"format\");\n\n  if (variant === undefined) {\n    return values.size === 0\n      ? { type: \"original\" }\n      : { type: \"invalid\", reason: `\"format\" requires \"variant\".` };\n  }\n\n  if (variant === \"\") {\n    return { type: \"invalid\", reason: `\"variant\" must not be empty.` };\n  }\n\n  return format === undefined ? { type: \"variant\", variant } : { type: \"variant\", variant, format };\n}\n"],"mappings":";AAEA,MAAM,+BAAe,IAAI,IAAI,CAAC,WAAW,QAAQ,CAAC;;;;;;;;;;;AAYlD,SAAgB,uBAAuB,KAAgC;CACrE,MAAM,aAAa,IAAI,QAAQ,GAAG;CAClC,MAAM,WAAW,eAAe,KAAK,KAAK,IAAI,MAAM,aAAa,CAAC;CAElE,IAAI,aAAa,IAAI,OAAO,EAAE,MAAM,WAAW;CAE/C,MAAM,yBAAS,IAAI,IAAoB;CAEvC,KAAK,MAAM,CAAC,KAAK,UAAU,IAAI,gBAAgB,QAAQ,GAAG;EACxD,IAAI,CAAC,aAAa,IAAI,GAAG,GACvB,OAAO;GAAE,MAAM;GAAW,QAAQ,4BAA4B,IAAI;EAAI;EAGxE,IAAI,OAAO,IAAI,GAAG,GAChB,OAAO;GAAE,MAAM;GAAW,QAAQ,oBAAoB,IAAI;EAAgB;EAG5E,OAAO,IAAI,KAAK,KAAK;CACvB;CAEA,MAAM,UAAU,OAAO,IAAI,SAAS;CACpC,MAAM,SAAS,OAAO,IAAI,QAAQ;CAElC,IAAI,YAAY,QACd,OAAO,OAAO,SAAS,IACnB,EAAE,MAAM,WAAW,IACnB;EAAE,MAAM;EAAW,QAAQ;CAA+B;CAGhE,IAAI,YAAY,IACd,OAAO;EAAE,MAAM;EAAW,QAAQ;CAA+B;CAGnE,OAAO,WAAW,SAAY;EAAE,MAAM;EAAW;CAAQ,IAAI;EAAE,MAAM;EAAW;EAAS;CAAO;AAClG"}

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

@@ -1,12 +1,11 @@
 import { StorageDriverName } from "../../storage/types.mjs";
-
 //#region ../../packages/core/src/http/uploads/purge-image-variants.d.ts
 /**
  * Options for {@link purgeImageVariants}
  */
-type PurgeImageVariantsOptions = {
+export type PurgeImageVariantsOptions = {
   /**
-   * Local disk the source lives on; the default disk when omitted
+   * Disk the source lives on; the default disk when omitted
    */
   disk?: StorageDriverName;
 };
@@ -19,14 +18,18 @@ type PurgeImageVariantsOptions = {
  *   `uploads.images.cacheDirectory` is set, that directory is shared by every
  *   local disk, so this clears all of them.
  *
+ * Only recognized derivative, source-manifest and temporary files in the
+ * generated cache layout are removed. The cache root, directories, unrelated
+ * files and symlinks stay in place. Use a dedicated folder for derivatives.
+ *
  * Deleting or moving a file through local storage (`storage.delete`,
  * `deleteMany`, `move`) already purges its derivatives; call this for files
  * removed some other way.
  *
+ * @throws ImageVariantsConfigError when the cache equals or contains any
+ * configured local disk root, including through a symlink
  * @returns `true` when something was removed
- * @throws ImageVariantsConfigError when the disk is not a local disk
  */
-declare function purgeImageVariants(relativePath?: string, options?: PurgeImageVariantsOptions): Promise<boolean>;
+export declare function purgeImageVariants(relativePath?: string, options?: PurgeImageVariantsOptions): Promise<boolean>;
 //#endregion
-export { PurgeImageVariantsOptions, purgeImageVariants };
 //# sourceMappingURL=purge-image-variants.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"purge-image-variants.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/purge-image-variants.ts"],"mappings":";;;;;AAUA;KAAY,yBAAA;;;AAIc;EAAxB,IAAA,GAAO,iBAAiB;AAAA;;;;;;;;AAsBhB;;;;;;;;;iBAHY,kBAAA,CACpB,YAAA,WACA,OAAA,GAAS,yBAAA,GACR,OAAO"}
+{"version":3,"file":"purge-image-variants.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/purge-image-variants.ts"],"mappings":";;;;;YAeY;;;;EAIV,OAAO;;;;;;;;;;;;;;;;;;;;;;;wBAwBa,mBACpB,uBACA,UAAS,4BACR"}