@warlock.js/core 5.30.0 → 5.31.0

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

@@ -1,30 +1,88 @@
 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 { log } from "@warlock.js/logger";
 import path from "node:path";
-import fs from "node:fs/promises";
+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.realpath(target);
+		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`.
+* `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
@@ -90,7 +132,7 @@ async function pruneStaleVariantGenerations(sourceDirectory, keep) {
 async function pruneStaleVariantGenerationsIfCurrent(sourceAbsolutePath, sourceDirectory, keep) {
 	let current;
 	try {
-		const stats = await fs.stat(sourceAbsolutePath);
+		const stats = await fs$1.stat(sourceAbsolutePath);
 		current = variantGenerationTag(stats.size, stats.mtimeMs);
 	} catch {
 		return;

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":["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

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

@@ -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":["../../../../../../../../../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":";;AAMA;;;;;cAAa,wBAAA,SAAiC,KAAK;;WAEjC,IAAA;cAEG,OAAA,UAAiB,OAAA,GAAU,YAAA;AAAA"}

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/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/purge-image-variants.d.mts

@@ -6,7 +6,7 @@ import { StorageDriverName } from "../../storage/types.mjs";
  */
 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,12 +19,17 @@ 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>;
 //#endregion

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":";;;;;AAeA;KAAY,yBAAA;;;AAIc;EAAxB,IAAA,GAAO,iBAAiB;AAAA;;;;;;;;AA2BhB;;;;;;;;;;;;;;iBAHY,kBAAA,CACpB,YAAA,WACA,OAAA,GAAS,yBAAA,GACR,OAAO"}

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

@@ -1,8 +1,9 @@
+import { purgeVariantCacheEntries, variantCacheEntries, variantSourceCacheEntries } from "./image-variant-cache-entries.mjs";
+import { variantSourceDirectory, variantSourceKey } from "./variant-cache-key.mjs";
 import { purgeImageVariantsOfFile, variantCacheDirectoryFor } from "./image-variant-cache.mjs";
-import { ImageVariantsConfigError } from "./image-variants-config-error.mjs";
 import { localDiskRoot } from "./local-disk-root.mjs";
+import { remoteVariantDisk, remoteVariantPath } from "./remote-variant-source.mjs";
 import path from "node:path";
-import fs from "node:fs/promises";
 
 //#region ../../packages/core/src/http/uploads/purge-image-variants.ts
 /**
@@ -14,29 +15,28 @@ import fs from "node:fs/promises";
 *   `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
 */
 async function purgeImageVariants(relativePath, options = {}) {
 	const diskRoot = localDiskRoot(options.disk);
-	if (!diskRoot) throw new ImageVariantsConfigError(options.disk === void 0 ? "purgeImageVariants needs a local storage driver with a root." : `purgeImageVariants needs a local disk; "${options.disk}" is not one.`);
-	if (relativePath === void 0) {
-		const directory = variantCacheDirectoryFor(diskRoot);
-		try {
-			await fs.access(directory);
-		} catch {
-			return false;
-		}
-		await fs.rm(directory, {
-			recursive: true,
-			force: true
-		});
-		return true;
+	if (!diskRoot) {
+		const disk = remoteVariantDisk(options.disk);
+		const location = relativePath === void 0 ? void 0 : remoteVariantPath(relativePath);
+		if (relativePath !== void 0 && location === void 0) return false;
+		const cache = variantCacheDirectoryFor(disk.cacheRoot);
+		return purgeVariantCacheEntries(location === void 0 ? variantCacheEntries(cache) : variantSourceCacheEntries(variantSourceDirectory(cache, variantSourceKey(disk.root, disk.driver.applyPrefix(location)))));
 	}
+	if (relativePath === void 0) return purgeVariantCacheEntries(variantCacheEntries(variantCacheDirectoryFor(diskRoot)));
 	const location = relativePath.replace(/\\/g, "/").replace(/^\/+/, "");
 	return purgeImageVariantsOfFile(diskRoot, path.resolve(diskRoot, location));
 }

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

@@ -1 +1 @@
-{"version":3,"file":"purge-image-variants.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/purge-image-variants.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport type { StorageDriverName } from \"../../storage/types\";\nimport { purgeImageVariantsOfFile, variantCacheDirectoryFor } from \"./image-variant-cache\";\nimport { ImageVariantsConfigError } from \"./image-variants-config-error\";\nimport { localDiskRoot } from \"./local-disk-root\";\n\n/**\n * Options for {@link purgeImageVariants}\n */\nexport type PurgeImageVariantsOptions = {\n  /**\n   * Local disk the source lives on; the default disk when omitted\n   */\n  disk?: StorageDriverName;\n};\n\n/**\n * Remove cached image derivatives.\n *\n * - With a path: every derivative of that file, in every variant and format.\n *   The file itself is untouched and does not need to exist.\n * - Without a path: the whole derivative cache of the disk. When\n *   `uploads.images.cacheDirectory` is set, that directory is shared by every\n *   local disk, so this clears all of them.\n *\n * Deleting or moving a file through local storage (`storage.delete`,\n * `deleteMany`, `move`) already purges its derivatives; call this for files\n * removed some other way.\n *\n * @returns `true` when something was removed\n * @throws ImageVariantsConfigError when the disk is not a local disk\n */\nexport async function purgeImageVariants(\n  relativePath?: string,\n  options: PurgeImageVariantsOptions = {},\n): Promise<boolean> {\n  const diskRoot = localDiskRoot(options.disk);\n\n  if (!diskRoot) {\n    throw new ImageVariantsConfigError(\n      options.disk === undefined\n        ? \"purgeImageVariants needs a local storage driver with a root.\"\n        : `purgeImageVariants needs a local disk; \"${options.disk}\" is not one.`,\n    );\n  }\n\n  if (relativePath === undefined) {\n    const directory = variantCacheDirectoryFor(diskRoot);\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  const location = relativePath.replace(/\\\\/g, \"/\").replace(/^\\/+/, \"\");\n\n  return purgeImageVariantsOfFile(diskRoot, path.resolve(diskRoot, location));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAiCA,eAAsB,mBACpB,cACA,UAAqC,CAAC,GACpB;CAClB,MAAM,WAAW,cAAc,QAAQ,IAAI;CAE3C,IAAI,CAAC,UACH,MAAM,IAAI,yBACR,QAAQ,SAAS,SACb,iEACA,2CAA2C,QAAQ,KAAK,cAC9D;CAGF,IAAI,iBAAiB,QAAW;EAC9B,MAAM,YAAY,yBAAyB,QAAQ;EAEnD,IAAI;GACF,MAAM,GAAG,OAAO,SAAS;EAC3B,QAAQ;GACN,OAAO;EACT;EAEA,MAAM,GAAG,GAAG,WAAW;GAAE,WAAW;GAAM,OAAO;EAAK,CAAC;EAEvD,OAAO;CACT;CAEA,MAAM,WAAW,aAAa,QAAQ,OAAO,GAAG,CAAC,CAAC,QAAQ,QAAQ,EAAE;CAEpE,OAAO,yBAAyB,UAAU,KAAK,QAAQ,UAAU,QAAQ,CAAC;AAC5E"}
+{"version":3,"file":"purge-image-variants.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/purge-image-variants.ts"],"sourcesContent":["import path from \"node:path\";\nimport type { StorageDriverName } from \"../../storage/types\";\nimport { purgeImageVariantsOfFile, variantCacheDirectoryFor } from \"./image-variant-cache\";\nimport { remoteVariantDisk, remoteVariantPath } from \"./remote-variant-source\";\nimport { variantSourceDirectory, variantSourceKey } from \"./variant-cache-key\";\nimport { localDiskRoot } from \"./local-disk-root\";\nimport {\n  purgeVariantCacheEntries,\n  variantCacheEntries,\n  variantSourceCacheEntries,\n} from \"./image-variant-cache-entries\";\n\n/**\n * Options for {@link purgeImageVariants}\n */\nexport type PurgeImageVariantsOptions = {\n  /**\n   * Disk the source lives on; the default disk when omitted\n   */\n  disk?: StorageDriverName;\n};\n\n/**\n * Remove cached image derivatives.\n *\n * - With a path: every derivative of that file, in every variant and format.\n *   The file itself is untouched and does not need to exist.\n * - Without a path: the whole derivative cache of the disk. When\n *   `uploads.images.cacheDirectory` is set, that directory is shared by every\n *   local disk, so this clears all of them.\n *\n * Only recognized derivative, source-manifest and temporary files in the\n * generated cache layout are removed. The cache root, directories, unrelated\n * files and symlinks stay in place. Use a dedicated folder for derivatives.\n *\n * Deleting or moving a file through local storage (`storage.delete`,\n * `deleteMany`, `move`) already purges its derivatives; call this for files\n * removed some other way.\n *\n * @throws ImageVariantsConfigError when the cache equals or contains any\n * configured local disk root, including through a symlink\n * @returns `true` when something was removed\n */\nexport async function purgeImageVariants(\n  relativePath?: string,\n  options: PurgeImageVariantsOptions = {},\n): Promise<boolean> {\n  const diskRoot = localDiskRoot(options.disk);\n\n  if (!diskRoot) {\n    const disk = remoteVariantDisk(options.disk);\n    const location = relativePath === undefined ? undefined : remoteVariantPath(relativePath);\n    if (relativePath !== undefined && location === undefined) return false;\n    const cache = variantCacheDirectoryFor(disk.cacheRoot);\n    return purgeVariantCacheEntries(\n      location === undefined\n        ? variantCacheEntries(cache)\n        : variantSourceCacheEntries(\n            variantSourceDirectory(\n              cache,\n              variantSourceKey(disk.root, disk.driver.applyPrefix(location)),\n            ),\n          ),\n    );\n  }\n\n  if (relativePath === undefined) {\n    return purgeVariantCacheEntries(variantCacheEntries(variantCacheDirectoryFor(diskRoot)));\n  }\n\n  const location = relativePath.replace(/\\\\/g, \"/\").replace(/^\\/+/, \"\");\n\n  return purgeImageVariantsOfFile(diskRoot, path.resolve(diskRoot, location));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,eAAsB,mBACpB,cACA,UAAqC,CAAC,GACpB;CAClB,MAAM,WAAW,cAAc,QAAQ,IAAI;CAE3C,IAAI,CAAC,UAAU;EACb,MAAM,OAAO,kBAAkB,QAAQ,IAAI;EAC3C,MAAM,WAAW,iBAAiB,SAAY,SAAY,kBAAkB,YAAY;EACxF,IAAI,iBAAiB,UAAa,aAAa,QAAW,OAAO;EACjE,MAAM,QAAQ,yBAAyB,KAAK,SAAS;EACrD,OAAO,yBACL,aAAa,SACT,oBAAoB,KAAK,IACzB,0BACE,uBACE,OACA,iBAAiB,KAAK,MAAM,KAAK,OAAO,YAAY,QAAQ,CAAC,CAC/D,CACF,CACN;CACF;CAEA,IAAI,iBAAiB,QACnB,OAAO,yBAAyB,oBAAoB,yBAAyB,QAAQ,CAAC,CAAC;CAGzF,MAAM,WAAW,aAAa,QAAQ,OAAO,GAAG,CAAC,CAAC,QAAQ,QAAQ,EAAE;CAEpE,OAAO,yBAAyB,UAAU,KAAK,QAAQ,UAAU,QAAQ,CAAC;AAC5E"}

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

@@ -0,0 +1,115 @@
+import { storagePath } from "../../utils/paths.mjs";
+import { HttpError } from "../errors/errors.mjs";
+import { storage } from "../../storage/storage.mjs";
+import "../../storage/index.mjs";
+import { detectImageFormat, isVariantSourceFormat } from "./detect-image-format.mjs";
+import { loadVariantSource } from "./load-variant-source.mjs";
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+//#region ../../packages/core/src/http/uploads/remote-variant-source.ts
+const activeSources = /* @__PURE__ */ new Map();
+function remoteVariantDisk(disk) {
+	const driver = disk === void 0 ? storage.activeDriver : storage.getDriver(disk);
+	const { bucket, endpoint, region } = driver.options;
+	return {
+		driver,
+		root: JSON.stringify([
+			driver.name,
+			bucket,
+			endpoint,
+			region
+		]),
+		cacheRoot: storagePath()
+	};
+}
+/** Object keys are normalized once, without URL decoding, before prefixing. */
+function remoteVariantPath(location) {
+	if (!location || location.includes("\0") || location.includes("\\") || path.posix.isAbsolute(location) || path.win32.isAbsolute(location) || /^[A-Za-z]:/.test(location) || location.split("/").includes("..")) return void 0;
+	const normalized = path.posix.normalize(location);
+	return normalized === "." ? void 0 : normalized;
+}
+async function remoteVariantSource(location, disk, images) {
+	const relativePath = remoteVariantPath(location);
+	if (!relativePath) return void 0;
+	const objectPath = relativePath;
+	let metadata;
+	try {
+		metadata = await disk.driver.metadata(relativePath);
+	} catch (error) {
+		const detail = error;
+		if ([
+			"ENOENT",
+			"NoSuchKey",
+			"NotFound"
+		].includes(detail.code ?? detail.name ?? "") || detail.$metadata?.httpStatusCode === 404) return void 0;
+		throw error;
+	}
+	if (metadata.isDirectory) return void 0;
+	if (metadata.size > images.maxSourceBytes) throw new HttpError(413, "The source image is too large.");
+	const sourcePath = disk.driver.applyPrefix(relativePath);
+	const metadataGeneration = metadata.etag ? createHash("sha256").update(JSON.stringify([
+		metadata.etag,
+		metadata.size,
+		metadata.lastModified?.getTime()
+	])).digest("hex") : void 0;
+	const activeKey = JSON.stringify([
+		disk.root,
+		sourcePath,
+		metadataGeneration,
+		images.maxSourceBytes,
+		images.maxSourcePixels
+	]);
+	const existing = activeSources.get(activeKey);
+	if (existing) {
+		existing.references++;
+		return existing.source;
+	}
+	let loaded;
+	async function load() {
+		const stream = await disk.driver.getStream(objectPath);
+		const chunks = [];
+		let size = 0;
+		try {
+			for await (const chunk of stream) {
+				const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+				size += bytes.length;
+				if (size > images.maxSourceBytes) throw new HttpError(413, "The source image is too large.");
+				chunks.push(bytes);
+			}
+		} finally {
+			stream.destroy();
+		}
+		const buffer = Buffer.concat(chunks);
+		const sourceFormat = detectImageFormat(buffer);
+		if (!isVariantSourceFormat(sourceFormat)) throw new HttpError(415, "Variants are only available for jpeg, png, webp and avif images.");
+		return {
+			image: await loadVariantSource(buffer, {
+				maxSourceBytes: images.maxSourceBytes,
+				maxSourcePixels: images.maxSourcePixels,
+				expectedFormat: sourceFormat
+			}),
+			sourceFormat,
+			generation: metadataGeneration ?? createHash("sha256").update(buffer).digest("hex")
+		};
+	}
+	const source = {
+		relativePath,
+		sourcePath,
+		metadataGeneration,
+		load: () => loaded ??= load(),
+		release() {
+			const active = activeSources.get(activeKey);
+			if (active && --active.references === 0) activeSources.delete(activeKey);
+		}
+	};
+	activeSources.set(activeKey, {
+		source,
+		references: 1
+	});
+	return source;
+}
+
+//#endregion
+export { remoteVariantDisk, remoteVariantPath, remoteVariantSource };
+//# sourceMappingURL=remote-variant-source.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote-variant-source.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/remote-variant-source.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport path from \"node:path\";\nimport type { StorageDriverContract, StorageDriverName } from \"../../storage/types\";\nimport { storage } from \"../../storage\";\nimport { storagePath } from \"../../utils/paths\";\nimport { HttpError } from \"../errors\";\nimport { detectImageFormat, isVariantSourceFormat } from \"./detect-image-format\";\nimport type { ResolvedImageVariantsConfig } from \"./image-variant-types\";\nimport { loadVariantSource } from \"./load-variant-source\";\nimport type { Image } from \"../../image\";\nimport type { VariantSourceFormat } from \"./image-variant-types\";\n\ntype LoadedRemoteSource = { image: Image; sourceFormat: VariantSourceFormat; generation: string };\nexport type RemoteVariantSource = {\n  relativePath: string;\n  sourcePath: string;\n  metadataGeneration?: string;\n  load(): Promise<LoadedRemoteSource>;\n  release(): void;\n};\nconst activeSources = new Map<string, { references: number; source: RemoteVariantSource }>();\n\nexport function remoteVariantDisk(disk?: StorageDriverName): {\n  driver: StorageDriverContract;\n  root: string;\n  cacheRoot: string;\n} {\n  const driver = disk === undefined ? storage.activeDriver : storage.getDriver(disk);\n  const { bucket, endpoint, region } = driver.options;\n  return {\n    driver,\n    root: JSON.stringify([driver.name, bucket, endpoint, region]),\n    cacheRoot: storagePath(),\n  };\n}\n\n/** Object keys are normalized once, without URL decoding, before prefixing. */\nexport function remoteVariantPath(location: string): string | undefined {\n  if (\n    !location ||\n    location.includes(\"\\0\") ||\n    location.includes(\"\\\\\") ||\n    path.posix.isAbsolute(location) ||\n    path.win32.isAbsolute(location) ||\n    /^[A-Za-z]:/.test(location) ||\n    location.split(\"/\").includes(\"..\")\n  )\n    return undefined;\n  const normalized = path.posix.normalize(location);\n  return normalized === \".\" ? undefined : normalized;\n}\n\nexport async function remoteVariantSource(\n  location: string,\n  disk: ReturnType<typeof remoteVariantDisk>,\n  images: ResolvedImageVariantsConfig,\n): Promise<RemoteVariantSource | undefined> {\n  const relativePath = remoteVariantPath(location);\n  if (!relativePath) return undefined;\n  const objectPath = relativePath;\n  let metadata;\n  try {\n    metadata = await disk.driver.metadata(relativePath);\n  } catch (error) {\n    const detail = error as {\n      code?: string;\n      name?: string;\n      $metadata?: { httpStatusCode?: number };\n    };\n    if (\n      [\"ENOENT\", \"NoSuchKey\", \"NotFound\"].includes(detail.code ?? detail.name ?? \"\") ||\n      detail.$metadata?.httpStatusCode === 404\n    )\n      return undefined;\n    throw error;\n  }\n  if (metadata.isDirectory) return undefined;\n  if (metadata.size > images.maxSourceBytes)\n    throw new HttpError(413, \"The source image is too large.\");\n  // The identity includes the effective prefix, including tenant context.\n  const sourcePath = disk.driver.applyPrefix(relativePath);\n  const metadataGeneration = metadata.etag\n    ? createHash(\"sha256\")\n        .update(JSON.stringify([metadata.etag, metadata.size, metadata.lastModified?.getTime()]))\n        .digest(\"hex\")\n    : undefined;\n  const activeKey = JSON.stringify([\n    disk.root,\n    sourcePath,\n    metadataGeneration,\n    images.maxSourceBytes,\n    images.maxSourcePixels,\n  ]);\n  const existing = activeSources.get(activeKey);\n  if (existing) {\n    existing.references++;\n    return existing.source;\n  }\n  let loaded: Promise<LoadedRemoteSource> | undefined;\n  async function load() {\n    const stream = await disk.driver.getStream(objectPath);\n    const chunks: Buffer[] = [];\n    let size = 0;\n    try {\n      for await (const chunk of stream) {\n        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);\n        size += bytes.length;\n        if (size > images.maxSourceBytes)\n          throw new HttpError(413, \"The source image is too large.\");\n        chunks.push(bytes);\n      }\n    } finally {\n      stream.destroy();\n    }\n    const buffer = Buffer.concat(chunks);\n    const sourceFormat = detectImageFormat(buffer);\n    if (!isVariantSourceFormat(sourceFormat))\n      throw new HttpError(415, \"Variants are only available for jpeg, png, webp and avif images.\");\n    const image = await loadVariantSource(buffer, {\n      maxSourceBytes: images.maxSourceBytes,\n      maxSourcePixels: images.maxSourcePixels,\n      expectedFormat: sourceFormat,\n    });\n    return {\n      image,\n      sourceFormat,\n      generation: metadataGeneration ?? createHash(\"sha256\").update(buffer).digest(\"hex\"),\n    };\n  }\n  const source: RemoteVariantSource = {\n    relativePath,\n    sourcePath,\n    metadataGeneration,\n    load: () => (loaded ??= load()),\n    release() {\n      const active = activeSources.get(activeKey);\n      if (active && --active.references === 0) activeSources.delete(activeKey);\n    },\n  };\n  activeSources.set(activeKey, { source, references: 1 });\n  return source;\n}\n"],"mappings":"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"}