@warlock.js/core 5.29.0 → 5.31.0

package/esm/http/uploads/resolve-inline-image-content-type.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-inline-image-content-type.mjs","names":[],"sources":["../../../../../../../../core/src/http/uploads/resolve-inline-image-content-type.ts"],"sourcesContent":["import path from \"node:path\";\nimport type { DetectedImageFormat, VariantSourceFormat } from \"./image-variant-types\";\n\n/**\n * Extensions an upload original may carry for each raster format that is\n * allowed to render inline. Anything else — including `.gif`, since gif is\n * not a variant source format — is never served inline, regardless of what\n * its bytes sniff as.\n */\nconst EXTENSION_IMAGE_FORMATS: Readonly<Record<string, VariantSourceFormat>> = {\n  \".jpg\": \"jpeg\",\n  \".jpeg\": \"jpeg\",\n  \".png\": \"png\",\n  \".webp\": \"webp\",\n  \".avif\": \"avif\",\n};\n\n/**\n * Content type an inline response must advertise for each raster format,\n * used instead of an extension-derived guess.\n */\nconst INLINE_IMAGE_CONTENT_TYPES: Readonly<Record<VariantSourceFormat, string>> = {\n  jpeg: \"image/jpeg\",\n  png: \"image/png\",\n  webp: \"image/webp\",\n  avif: \"image/avif\",\n};\n\n/**\n * Content type to serve an upload original inline with, or `undefined` when\n * it must go out as an attachment instead.\n *\n * `sendFile` sets `Content-Type` from the file's EXTENSION, not its bytes.\n * The inline branch in `uploaded-file.controller.ts` only sniffs the bytes to\n * decide \"is this raster\" — so a JPEG-signature file named `x.html` sniffed\n * as jpeg (raster, so \"safe\") would still have been sent by `sendFile` as\n * `text/html`: a polyglot JPEG/HTML stored-XSS vector, the reverse of the\n * already-fixed SVG-named-`.png` case.\n *\n * Inline is therefore only safe when the sniffed format AND the\n * extension-derived format agree — the extension maps to the SAME image\n * type the bytes sniffed as. Any mismatch (raster bytes under a non-image or\n * different-image extension) returns `undefined`, sending the caller to the\n * attachment path instead of trusting either signal alone.\n */\nexport function resolveInlineImageContentType(\n  filePath: string,\n  sniffedFormat: DetectedImageFormat | undefined,\n): string | undefined {\n  if (sniffedFormat === undefined) return undefined;\n\n  const extensionFormat = EXTENSION_IMAGE_FORMATS[path.extname(filePath).toLowerCase()];\n\n  if (extensionFormat === undefined || extensionFormat !== sniffedFormat) return undefined;\n\n  return INLINE_IMAGE_CONTENT_TYPES[extensionFormat];\n}\n"],"mappings":";;;;;;;;;AASA,MAAM,0BAAyE;CAC7E,QAAQ;CACR,SAAS;CACT,QAAQ;CACR,SAAS;CACT,SAAS;AACX;;;;;AAMA,MAAM,6BAA4E;CAChF,MAAM;CACN,KAAK;CACL,MAAM;CACN,MAAM;AACR;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,8BACd,UACA,eACoB;CACpB,IAAI,kBAAkB,QAAW,OAAO;CAExC,MAAM,kBAAkB,wBAAwB,KAAK,QAAQ,QAAQ,CAAC,CAAC,YAAY;CAEnF,IAAI,oBAAoB,UAAa,oBAAoB,eAAe,OAAO;CAE/E,OAAO,2BAA2B;AACpC"}
+{"version":3,"file":"resolve-inline-image-content-type.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/resolve-inline-image-content-type.ts"],"sourcesContent":["import path from \"node:path\";\nimport type { DetectedImageFormat, VariantSourceFormat } from \"./image-variant-types\";\n\n/**\n * Extensions an upload original may carry for each raster format that is\n * allowed to render inline. Anything else — including `.gif`, since gif is\n * not a variant source format — is never served inline, regardless of what\n * its bytes sniff as.\n */\nconst EXTENSION_IMAGE_FORMATS: Readonly<Record<string, VariantSourceFormat>> = {\n  \".jpg\": \"jpeg\",\n  \".jpeg\": \"jpeg\",\n  \".png\": \"png\",\n  \".webp\": \"webp\",\n  \".avif\": \"avif\",\n};\n\n/**\n * Content type an inline response must advertise for each raster format,\n * used instead of an extension-derived guess.\n */\nconst INLINE_IMAGE_CONTENT_TYPES: Readonly<Record<VariantSourceFormat, string>> = {\n  jpeg: \"image/jpeg\",\n  png: \"image/png\",\n  webp: \"image/webp\",\n  avif: \"image/avif\",\n};\n\n/**\n * Content type to serve an upload original inline with, or `undefined` when\n * it must go out as an attachment instead.\n *\n * `sendFile` sets `Content-Type` from the file's EXTENSION, not its bytes.\n * The inline branch in `uploaded-file.controller.ts` only sniffs the bytes to\n * decide \"is this raster\" — so a JPEG-signature file named `x.html` sniffed\n * as jpeg (raster, so \"safe\") would still have been sent by `sendFile` as\n * `text/html`: a polyglot JPEG/HTML stored-XSS vector, the reverse of the\n * already-fixed SVG-named-`.png` case.\n *\n * Inline is therefore only safe when the sniffed format AND the\n * extension-derived format agree — the extension maps to the SAME image\n * type the bytes sniffed as. Any mismatch (raster bytes under a non-image or\n * different-image extension) returns `undefined`, sending the caller to the\n * attachment path instead of trusting either signal alone.\n */\nexport function resolveInlineImageContentType(\n  filePath: string,\n  sniffedFormat: DetectedImageFormat | undefined,\n): string | undefined {\n  if (sniffedFormat === undefined) return undefined;\n\n  const extensionFormat = EXTENSION_IMAGE_FORMATS[path.extname(filePath).toLowerCase()];\n\n  if (extensionFormat === undefined || extensionFormat !== sniffedFormat) return undefined;\n\n  return INLINE_IMAGE_CONTENT_TYPES[extensionFormat];\n}\n"],"mappings":";;;;;;;;;AASA,MAAM,0BAAyE;CAC7E,QAAQ;CACR,SAAS;CACT,QAAQ;CACR,SAAS;CACT,SAAS;AACX;;;;;AAMA,MAAM,6BAA4E;CAChF,MAAM;CACN,KAAK;CACL,MAAM;CACN,MAAM;AACR;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,8BACd,UACA,eACoB;CACpB,IAAI,kBAAkB,QAAW,OAAO;CAExC,MAAM,kBAAkB,wBAAwB,KAAK,QAAQ,QAAQ,CAAC,CAAC,YAAY;CAEnF,IAAI,oBAAoB,UAAa,oBAAoB,eAAe,OAAO;CAE/E,OAAO,2BAA2B;AACpC"}

package/esm/http/uploads/resolve-original-content-type.mjs

@@ -1,6 +1,6 @@
 import mime from "mime";
 
-//#region ../core/src/http/uploads/resolve-original-content-type.ts
+//#region ../../packages/core/src/http/uploads/resolve-original-content-type.ts
 /**
 * Extension-derived MIME types that are never safe to advertise as-is: a
 * browser that trusts one of these will parse and execute the response body

package/esm/http/uploads/resolve-original-content-type.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-original-content-type.mjs","names":[],"sources":["../../../../../../../../core/src/http/uploads/resolve-original-content-type.ts"],"sourcesContent":["import mime from \"mime\";\n\n/**\n * Extension-derived MIME types that are never safe to advertise as-is: a\n * browser that trusts one of these will parse and execute the response body\n * (inline `<script>` in an svg, markup and script in html/xhtml/xml), so an\n * upload served under its real type is stored XSS the moment it is fetched\n * from the app's own origin.\n */\nconst INLINE_EXECUTABLE_MIME_TYPES = new Set([\n  \"image/svg+xml\",\n  \"text/html\",\n  \"application/xhtml+xml\",\n  \"text/xml\",\n  \"application/xml\",\n]);\n\n/**\n * Content type for an upload original that is being served as an\n * `attachment` (see `uploaded-file.controller.ts`): the extension-derived\n * type, except the svg/html/xml family, which is downgraded to\n * `application/octet-stream` so a browser never sniffs or renders it.\n */\nexport function resolveOriginalContentType(filePath: string): string {\n  const type = mime.getType(filePath) || \"application/octet-stream\";\n\n  return INLINE_EXECUTABLE_MIME_TYPES.has(type) ? \"application/octet-stream\" : type;\n}\n"],"mappings":";;;;;;;;;;AASA,MAAM,+BAA+B,IAAI,IAAI;CAC3C;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;;AAQD,SAAgB,2BAA2B,UAA0B;CACnE,MAAM,OAAO,KAAK,QAAQ,QAAQ,KAAK;CAEvC,OAAO,6BAA6B,IAAI,IAAI,IAAI,6BAA6B;AAC/E"}
+{"version":3,"file":"resolve-original-content-type.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/resolve-original-content-type.ts"],"sourcesContent":["import mime from \"mime\";\n\n/**\n * Extension-derived MIME types that are never safe to advertise as-is: a\n * browser that trusts one of these will parse and execute the response body\n * (inline `<script>` in an svg, markup and script in html/xhtml/xml), so an\n * upload served under its real type is stored XSS the moment it is fetched\n * from the app's own origin.\n */\nconst INLINE_EXECUTABLE_MIME_TYPES = new Set([\n  \"image/svg+xml\",\n  \"text/html\",\n  \"application/xhtml+xml\",\n  \"text/xml\",\n  \"application/xml\",\n]);\n\n/**\n * Content type for an upload original that is being served as an\n * `attachment` (see `uploaded-file.controller.ts`): the extension-derived\n * type, except the svg/html/xml family, which is downgraded to\n * `application/octet-stream` so a browser never sniffs or renders it.\n */\nexport function resolveOriginalContentType(filePath: string): string {\n  const type = mime.getType(filePath) || \"application/octet-stream\";\n\n  return INLINE_EXECUTABLE_MIME_TYPES.has(type) ? \"application/octet-stream\" : type;\n}\n"],"mappings":";;;;;;;;;;AASA,MAAM,+BAA+B,IAAI,IAAI;CAC3C;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;;AAQD,SAAgB,2BAA2B,UAA0B;CACnE,MAAM,OAAO,KAAK,QAAQ,QAAQ,KAAK;CAEvC,OAAO,6BAA6B,IAAI,IAAI,IAAI,6BAA6B;AAC/E"}

package/esm/http/uploads/resolve-remote-image-variant.mjs

@@ -0,0 +1,89 @@
+import { HttpError } from "../errors/errors.mjs";
+import { uploadsConfig } from "../uploads-config.mjs";
+import { variantCacheKey, variantCachePath, variantSourceDirectory, variantSourceKey } from "./variant-cache-key.mjs";
+import { retryOnVanishedDirectory, warnIfVariantCacheIsPublic } from "./image-variant-cache.mjs";
+import { isVariantSourceFormat } from "./detect-image-format.mjs";
+import { remoteVariantDisk, remoteVariantSource } from "./remote-variant-source.mjs";
+import { generateImageVariant } from "./generate-image-variant.mjs";
+import { resolveImageVariantsConfig } from "./resolve-image-variants-config.mjs";
+import { freshImageVariant, scheduleImageVariantCacheTrim } from "./trim-image-variant-cache.mjs";
+import { variantGenerations } from "./variant-generations.mjs";
+import path from "node:path";
+import { atomicWriteAsync } from "@warlock.js/fs";
+import fs from "node:fs/promises";
+
+//#region ../../packages/core/src/http/uploads/resolve-remote-image-variant.ts
+/** Cloud sources are read through their driver; derivatives remain in a local cache. */
+async function resolveRemoteImageVariant(input) {
+	const disk = remoteVariantDisk(input.disk);
+	const images = resolveImageVariantsConfig(uploadsConfig("images"), disk.cacheRoot);
+	if (!images) throw new HttpError(400, "Image variants are not configured.");
+	if (!Object.prototype.hasOwnProperty.call(images.variants, input.variant)) throw new HttpError(400, `Unknown variant "${input.variant}".`);
+	if (input.format !== void 0 && !images.formats.includes(input.format)) throw new HttpError(400, `Format "${input.format}" is not allowed.`);
+	const source = await remoteVariantSource(input.path, disk, images);
+	if (!source) return void 0;
+	try {
+		return await renderRemoteImageVariant(input, disk, images, source);
+	} finally {
+		source.release();
+	}
+}
+/** Ingest rendering reuses one source handle and its memoized bounded download. */
+async function renderRemoteImageVariant(input, disk, images, source) {
+	const variant = Object.prototype.hasOwnProperty.call(images.variants, input.variant) ? images.variants[input.variant] : void 0;
+	if (!variant) throw new HttpError(400, `Unknown variant "${input.variant}".`);
+	if (input.format !== void 0 && !images.formats.includes(input.format)) throw new HttpError(400, `Format "${input.format}" is not allowed.`);
+	const generation = source.metadataGeneration ?? (await source.load()).generation;
+	const sourceKey = variantSourceKey(disk.root, source.sourcePath);
+	const manifestPath = path.join(variantSourceDirectory(images.cacheDirectory, sourceKey), generation, "source.json");
+	let format = input.format;
+	if (!format) {
+		try {
+			const savedFormat = JSON.parse(await fs.readFile(manifestPath, "utf8"))?.format;
+			if (isVariantSourceFormat(savedFormat)) format = savedFormat;
+		} catch (error) {
+			if (error.code !== "ENOENT" && !(error instanceof SyntaxError)) throw error;
+		}
+		format ??= (await source.load()).sourceFormat;
+	}
+	const hash = variantCacheKey({
+		relativePath: JSON.stringify([
+			disk.root,
+			source.sourcePath,
+			generation
+		]),
+		sourceSize: 0,
+		sourceMtimeMs: 0,
+		variant,
+		format
+	});
+	const target = variantCachePath(images.cacheDirectory, {
+		sourceKey,
+		generation
+	}, hash, format);
+	warnIfVariantCacheIsPublic(images.cacheDirectory);
+	if (!await freshImageVariant(target, images.maxCacheAge)) await variantGenerations.run(target, async () => {
+		if (await freshImageVariant(target, images.maxCacheAge)) return;
+		const loaded = await source.load();
+		await retryOnVanishedDirectory(async () => {
+			await generateImageVariant({
+				image: loaded.image.clone(),
+				variant,
+				format,
+				targetPath: target
+			});
+			await atomicWriteAsync(manifestPath, JSON.stringify({ format: loaded.sourceFormat }));
+		});
+		scheduleImageVariantCacheTrim(images, target);
+	});
+	return {
+		absolutePath: target,
+		hash,
+		format,
+		contentType: `image/${format}`
+	};
+}
+
+//#endregion
+export { renderRemoteImageVariant, resolveRemoteImageVariant };
+//# sourceMappingURL=resolve-remote-image-variant.mjs.map

package/esm/http/uploads/resolve-remote-image-variant.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-remote-image-variant.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/resolve-remote-image-variant.ts"],"sourcesContent":["import { atomicWriteAsync } from \"@warlock.js/fs\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { HttpError } from \"../errors\";\nimport { uploadsConfig } from \"../uploads-config\";\nimport { isVariantSourceFormat } from \"./detect-image-format\";\nimport { generateImageVariant } from \"./generate-image-variant\";\nimport { retryOnVanishedDirectory, warnIfVariantCacheIsPublic } from \"./image-variant-cache\";\nimport type { ResolvedImageVariantsConfig, VariantOutputFormat } from \"./image-variant-types\";\nimport {\n  remoteVariantDisk,\n  remoteVariantSource,\n  type RemoteVariantSource,\n} from \"./remote-variant-source\";\nimport { resolveImageVariantsConfig } from \"./resolve-image-variants-config\";\nimport type { ResolveImageVariantInput, ResolvedImageVariant } from \"./resolve-image-variant\";\nimport { freshImageVariant, scheduleImageVariantCacheTrim } from \"./trim-image-variant-cache\";\nimport {\n  variantCacheKey,\n  variantCachePath,\n  variantSourceDirectory,\n  variantSourceKey,\n} from \"./variant-cache-key\";\nimport { variantGenerations } from \"./variant-generations\";\n\n/** Cloud sources are read through their driver; derivatives remain in a local cache. */\nexport async function resolveRemoteImageVariant(\n  input: ResolveImageVariantInput,\n): Promise<ResolvedImageVariant | undefined> {\n  const disk = remoteVariantDisk(input.disk);\n  const images = resolveImageVariantsConfig(uploadsConfig(\"images\"), disk.cacheRoot);\n  if (!images) throw new HttpError(400, \"Image variants are not configured.\");\n  if (!Object.prototype.hasOwnProperty.call(images.variants, input.variant))\n    throw new HttpError(400, `Unknown variant \"${input.variant}\".`);\n  if (input.format !== undefined && !images.formats.includes(input.format as never))\n    throw new HttpError(400, `Format \"${input.format}\" is not allowed.`);\n  const source = await remoteVariantSource(input.path, disk, images);\n  if (!source) return undefined;\n  try {\n    return await renderRemoteImageVariant(input, disk, images, source);\n  } finally {\n    source.release();\n  }\n}\n\n/** Ingest rendering reuses one source handle and its memoized bounded download. */\nexport async function renderRemoteImageVariant(\n  input: ResolveImageVariantInput,\n  disk: ReturnType<typeof remoteVariantDisk>,\n  images: ResolvedImageVariantsConfig,\n  source: RemoteVariantSource,\n): Promise<ResolvedImageVariant> {\n  const variant = Object.prototype.hasOwnProperty.call(images.variants, input.variant)\n    ? images.variants[input.variant]\n    : undefined;\n  if (!variant) throw new HttpError(400, `Unknown variant \"${input.variant}\".`);\n  if (input.format !== undefined && !images.formats.includes(input.format as never))\n    throw new HttpError(400, `Format \"${input.format}\" is not allowed.`);\n  const generation = source.metadataGeneration ?? (await source.load()).generation;\n  const sourceKey = variantSourceKey(disk.root, source.sourcePath);\n  const manifestPath = path.join(\n    variantSourceDirectory(images.cacheDirectory, sourceKey),\n    generation,\n    \"source.json\",\n  );\n  let format: VariantOutputFormat | undefined = input.format;\n  if (!format) {\n    try {\n      const saved: unknown = JSON.parse(await fs.readFile(manifestPath, \"utf8\"));\n      const savedFormat = (saved as { format?: unknown } | null)?.format;\n      if (isVariantSourceFormat(savedFormat as never)) format = savedFormat as VariantOutputFormat;\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code !== \"ENOENT\" && !(error instanceof SyntaxError))\n        throw error;\n    }\n    format ??= (await source.load()).sourceFormat;\n  }\n  const hash = variantCacheKey({\n    relativePath: JSON.stringify([disk.root, source.sourcePath, generation]),\n    sourceSize: 0,\n    sourceMtimeMs: 0,\n    variant,\n    format,\n  });\n  const target = variantCachePath(images.cacheDirectory, { sourceKey, generation }, hash, format);\n  warnIfVariantCacheIsPublic(images.cacheDirectory);\n  if (!(await freshImageVariant(target, images.maxCacheAge))) {\n    await variantGenerations.run(target, async () => {\n      if (await freshImageVariant(target, images.maxCacheAge)) return;\n      const loaded = await source.load();\n      await retryOnVanishedDirectory(async () => {\n        await generateImageVariant({\n          image: loaded.image.clone(),\n          variant,\n          format,\n          targetPath: target,\n        });\n        await atomicWriteAsync(manifestPath, JSON.stringify({ format: loaded.sourceFormat }));\n      });\n      scheduleImageVariantCacheTrim(images, target);\n      // Retain other generations: an older concurrent download must not prune\n      // a newer object's derivatives. Background eviction reclaims them.\n    });\n  }\n  return { absolutePath: target, hash, format, contentType: `image/${format}` };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA0BA,eAAsB,0BACpB,OAC2C;CAC3C,MAAM,OAAO,kBAAkB,MAAM,IAAI;CACzC,MAAM,SAAS,2BAA2B,cAAc,QAAQ,GAAG,KAAK,SAAS;CACjF,IAAI,CAAC,QAAQ,MAAM,IAAI,UAAU,KAAK,oCAAoC;CAC1E,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,OAAO,UAAU,MAAM,OAAO,GACtE,MAAM,IAAI,UAAU,KAAK,oBAAoB,MAAM,QAAQ,GAAG;CAChE,IAAI,MAAM,WAAW,UAAa,CAAC,OAAO,QAAQ,SAAS,MAAM,MAAe,GAC9E,MAAM,IAAI,UAAU,KAAK,WAAW,MAAM,OAAO,kBAAkB;CACrE,MAAM,SAAS,MAAM,oBAAoB,MAAM,MAAM,MAAM,MAAM;CACjE,IAAI,CAAC,QAAQ,OAAO;CACpB,IAAI;EACF,OAAO,MAAM,yBAAyB,OAAO,MAAM,QAAQ,MAAM;CACnE,UAAU;EACR,OAAO,QAAQ;CACjB;AACF;;AAGA,eAAsB,yBACpB,OACA,MACA,QACA,QAC+B;CAC/B,MAAM,UAAU,OAAO,UAAU,eAAe,KAAK,OAAO,UAAU,MAAM,OAAO,IAC/E,OAAO,SAAS,MAAM,WACtB;CACJ,IAAI,CAAC,SAAS,MAAM,IAAI,UAAU,KAAK,oBAAoB,MAAM,QAAQ,GAAG;CAC5E,IAAI,MAAM,WAAW,UAAa,CAAC,OAAO,QAAQ,SAAS,MAAM,MAAe,GAC9E,MAAM,IAAI,UAAU,KAAK,WAAW,MAAM,OAAO,kBAAkB;CACrE,MAAM,aAAa,OAAO,uBAAuB,MAAM,OAAO,KAAK,EAAC,CAAE;CACtE,MAAM,YAAY,iBAAiB,KAAK,MAAM,OAAO,UAAU;CAC/D,MAAM,eAAe,KAAK,KACxB,uBAAuB,OAAO,gBAAgB,SAAS,GACvD,YACA,aACF;CACA,IAAI,SAA0C,MAAM;CACpD,IAAI,CAAC,QAAQ;EACX,IAAI;GAEF,MAAM,cADiB,KAAK,MAAM,MAAM,GAAG,SAAS,cAAc,MAAM,CAC/C,CAAC,EAAkC;GAC5D,IAAI,sBAAsB,WAAoB,GAAG,SAAS;EAC5D,SAAS,OAAO;GACd,IAAK,MAAgC,SAAS,YAAY,EAAE,iBAAiB,cAC3E,MAAM;EACV;EACA,YAAY,MAAM,OAAO,KAAK,EAAC,CAAE;CACnC;CACA,MAAM,OAAO,gBAAgB;EAC3B,cAAc,KAAK,UAAU;GAAC,KAAK;GAAM,OAAO;GAAY;EAAU,CAAC;EACvE,YAAY;EACZ,eAAe;EACf;EACA;CACF,CAAC;CACD,MAAM,SAAS,iBAAiB,OAAO,gBAAgB;EAAE;EAAW;CAAW,GAAG,MAAM,MAAM;CAC9F,2BAA2B,OAAO,cAAc;CAChD,IAAI,CAAE,MAAM,kBAAkB,QAAQ,OAAO,WAAW,GACtD,MAAM,mBAAmB,IAAI,QAAQ,YAAY;EAC/C,IAAI,MAAM,kBAAkB,QAAQ,OAAO,WAAW,GAAG;EACzD,MAAM,SAAS,MAAM,OAAO,KAAK;EACjC,MAAM,yBAAyB,YAAY;GACzC,MAAM,qBAAqB;IACzB,OAAO,OAAO,MAAM,MAAM;IAC1B;IACA;IACA,YAAY;GACd,CAAC;GACD,MAAM,iBAAiB,cAAc,KAAK,UAAU,EAAE,QAAQ,OAAO,aAAa,CAAC,CAAC;EACtF,CAAC;EACD,8BAA8B,QAAQ,MAAM;CAG9C,CAAC;CAEH,OAAO;EAAE,cAAc;EAAQ;EAAM;EAAQ,aAAa,SAAS;CAAS;AAC9E"}

package/esm/http/uploads/resolve-upload-path.mjs

@@ -2,7 +2,7 @@ import { isPathInside, isPathWithin } from "./is-path-inside.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
 
-//#region ../core/src/http/uploads/resolve-upload-path.ts
+//#region ../../packages/core/src/http/uploads/resolve-upload-path.ts
 async function realpathOrSelf(target) {
 	try {
 		return await fs.realpath(target);
@@ -47,7 +47,8 @@ async function resolveUploadPath(wildcard, storageRoot, excludedDirectories = []
 	}
 	return {
 		absolutePath: realPath,
-		relativePath: path.relative(realRoot, realPath).split(path.sep).join("/")
+		relativePath: path.relative(realRoot, realPath).split(path.sep).join("/"),
+		root: realRoot
 	};
 }
 

package/esm/http/uploads/resolve-upload-path.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-upload-path.mjs","names":[],"sources":["../../../../../../../../core/src/http/uploads/resolve-upload-path.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { isPathInside, isPathWithin } from \"./is-path-inside\";\n\n/**\n * A request path that resolved to a regular file inside the storage root\n */\nexport type ResolvedUploadPath = {\n  /**\n   * Real (symlink-free) absolute path of the file\n   */\n  absolutePath: string;\n\n  /**\n   * Path of the file relative to the real storage root, `/`-separated\n   */\n  relativePath: string;\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 * Resolve the wildcard of an uploads route to a file inside the storage root.\n *\n * The wildcard arrives already decoded once by the router and is NOT decoded\n * again: a second decode would turn `%252e%252e%252f` into `../`.\n *\n * Returns `undefined` — the caller answers 404 for every case, so the response\n * is no existence oracle — when the path:\n * - is empty, carries a NUL byte, or is absolute\n * - resolves outside the root, or to the root itself\n * - lies in one of the `excludedDirectories` (the variant cache)\n * - does not exist, or is not a regular file\n * - is (or passes through) a symlink whose target leaves the root\n */\nexport async function resolveUploadPath(\n  wildcard: unknown,\n  storageRoot: string,\n  excludedDirectories: readonly string[] = [],\n): Promise<ResolvedUploadPath | undefined> {\n  if (typeof wildcard !== \"string\" || wildcard === \"\" || wildcard.includes(\"\\0\")) {\n    return undefined;\n  }\n\n  if (path.isAbsolute(wildcard) || path.win32.isAbsolute(wildcard) || /^[A-Za-z]:/.test(wildcard)) {\n    return undefined;\n  }\n\n  const root = path.resolve(storageRoot);\n  const resolved = path.resolve(root, wildcard);\n\n  if (!isPathInside(resolved, root)) return undefined;\n\n  for (const excluded of excludedDirectories) {\n    if (isPathWithin(resolved, path.resolve(excluded))) return undefined;\n  }\n\n  let realPath: string;\n\n  try {\n    realPath = await fs.realpath(resolved);\n  } catch {\n    return undefined;\n  }\n\n  const realRoot = await realpathOrSelf(root);\n\n  if (!isPathInside(realPath, realRoot)) return undefined;\n\n  for (const excluded of excludedDirectories) {\n    if (isPathWithin(realPath, await realpathOrSelf(path.resolve(excluded)))) return undefined;\n  }\n\n  try {\n    const stats = await fs.stat(realPath);\n\n    if (!stats.isFile()) return undefined;\n  } catch {\n    return undefined;\n  }\n\n  return {\n    absolutePath: realPath,\n    relativePath: path.relative(realRoot, realPath).split(path.sep).join(\"/\"),\n  };\n}\n"],"mappings":";;;;;AAmBA,eAAe,eAAe,QAAiC;CAC7D,IAAI;EACF,OAAO,MAAM,GAAG,SAAS,MAAM;CACjC,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;;;;;;;;AAgBA,eAAsB,kBACpB,UACA,aACA,sBAAyC,CAAC,GACD;CACzC,IAAI,OAAO,aAAa,YAAY,aAAa,MAAM,SAAS,SAAS,IAAI,GAC3E;CAGF,IAAI,KAAK,WAAW,QAAQ,KAAK,KAAK,MAAM,WAAW,QAAQ,KAAK,aAAa,KAAK,QAAQ,GAC5F;CAGF,MAAM,OAAO,KAAK,QAAQ,WAAW;CACrC,MAAM,WAAW,KAAK,QAAQ,MAAM,QAAQ;CAE5C,IAAI,CAAC,aAAa,UAAU,IAAI,GAAG,OAAO;CAE1C,KAAK,MAAM,YAAY,qBACrB,IAAI,aAAa,UAAU,KAAK,QAAQ,QAAQ,CAAC,GAAG,OAAO;CAG7D,IAAI;CAEJ,IAAI;EACF,WAAW,MAAM,GAAG,SAAS,QAAQ;CACvC,QAAQ;EACN;CACF;CAEA,MAAM,WAAW,MAAM,eAAe,IAAI;CAE1C,IAAI,CAAC,aAAa,UAAU,QAAQ,GAAG,OAAO;CAE9C,KAAK,MAAM,YAAY,qBACrB,IAAI,aAAa,UAAU,MAAM,eAAe,KAAK,QAAQ,QAAQ,CAAC,CAAC,GAAG,OAAO;CAGnF,IAAI;EAGF,IAAI,EAAC,MAFe,GAAG,KAAK,QAAQ,EAE1B,CAAC,OAAO,GAAG,OAAO;CAC9B,QAAQ;EACN;CACF;CAEA,OAAO;EACL,cAAc;EACd,cAAc,KAAK,SAAS,UAAU,QAAQ,CAAC,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,GAAG;CAC1E;AACF"}
+{"version":3,"file":"resolve-upload-path.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/resolve-upload-path.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { isPathInside, isPathWithin } from \"./is-path-inside\";\n\n/**\n * A request path that resolved to a regular file inside the storage root\n */\nexport type ResolvedUploadPath = {\n  /**\n   * Real (symlink-free) absolute path of the file\n   */\n  absolutePath: string;\n\n  /**\n   * Path of the file relative to the real storage root, `/`-separated\n   */\n  relativePath: string;\n\n  /**\n   * Real (symlink-free) absolute path of the storage root\n   */\n  root: string;\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 * Resolve the wildcard of an uploads route to a file inside the storage root.\n *\n * The wildcard arrives already decoded once by the router and is NOT decoded\n * again: a second decode would turn `%252e%252e%252f` into `../`.\n *\n * Returns `undefined` — the caller answers 404 for every case, so the response\n * is no existence oracle — when the path:\n * - is empty, carries a NUL byte, or is absolute\n * - resolves outside the root, or to the root itself\n * - lies in one of the `excludedDirectories` (the variant cache)\n * - does not exist, or is not a regular file\n * - is (or passes through) a symlink whose target leaves the root\n */\nexport async function resolveUploadPath(\n  wildcard: unknown,\n  storageRoot: string,\n  excludedDirectories: readonly string[] = [],\n): Promise<ResolvedUploadPath | undefined> {\n  if (typeof wildcard !== \"string\" || wildcard === \"\" || wildcard.includes(\"\\0\")) {\n    return undefined;\n  }\n\n  if (path.isAbsolute(wildcard) || path.win32.isAbsolute(wildcard) || /^[A-Za-z]:/.test(wildcard)) {\n    return undefined;\n  }\n\n  const root = path.resolve(storageRoot);\n  const resolved = path.resolve(root, wildcard);\n\n  if (!isPathInside(resolved, root)) return undefined;\n\n  for (const excluded of excludedDirectories) {\n    if (isPathWithin(resolved, path.resolve(excluded))) return undefined;\n  }\n\n  let realPath: string;\n\n  try {\n    realPath = await fs.realpath(resolved);\n  } catch {\n    return undefined;\n  }\n\n  const realRoot = await realpathOrSelf(root);\n\n  if (!isPathInside(realPath, realRoot)) return undefined;\n\n  for (const excluded of excludedDirectories) {\n    if (isPathWithin(realPath, await realpathOrSelf(path.resolve(excluded)))) return undefined;\n  }\n\n  try {\n    const stats = await fs.stat(realPath);\n\n    if (!stats.isFile()) return undefined;\n  } catch {\n    return undefined;\n  }\n\n  return {\n    absolutePath: realPath,\n    relativePath: path.relative(realRoot, realPath).split(path.sep).join(\"/\"),\n    root: realRoot,\n  };\n}\n"],"mappings":";;;;;AAwBA,eAAe,eAAe,QAAiC;CAC7D,IAAI;EACF,OAAO,MAAM,GAAG,SAAS,MAAM;CACjC,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;;;;;;;;AAgBA,eAAsB,kBACpB,UACA,aACA,sBAAyC,CAAC,GACD;CACzC,IAAI,OAAO,aAAa,YAAY,aAAa,MAAM,SAAS,SAAS,IAAI,GAC3E;CAGF,IAAI,KAAK,WAAW,QAAQ,KAAK,KAAK,MAAM,WAAW,QAAQ,KAAK,aAAa,KAAK,QAAQ,GAC5F;CAGF,MAAM,OAAO,KAAK,QAAQ,WAAW;CACrC,MAAM,WAAW,KAAK,QAAQ,MAAM,QAAQ;CAE5C,IAAI,CAAC,aAAa,UAAU,IAAI,GAAG,OAAO;CAE1C,KAAK,MAAM,YAAY,qBACrB,IAAI,aAAa,UAAU,KAAK,QAAQ,QAAQ,CAAC,GAAG,OAAO;CAG7D,IAAI;CAEJ,IAAI;EACF,WAAW,MAAM,GAAG,SAAS,QAAQ;CACvC,QAAQ;EACN;CACF;CAEA,MAAM,WAAW,MAAM,eAAe,IAAI;CAE1C,IAAI,CAAC,aAAa,UAAU,QAAQ,GAAG,OAAO;CAE9C,KAAK,MAAM,YAAY,qBACrB,IAAI,aAAa,UAAU,MAAM,eAAe,KAAK,QAAQ,QAAQ,CAAC,CAAC,GAAG,OAAO;CAGnF,IAAI;EAGF,IAAI,EAAC,MAFe,GAAG,KAAK,QAAQ,EAE1B,CAAC,OAAO,GAAG,OAAO;CAC9B,QAAQ;EACN;CACF;CAEA,OAAO;EACL,cAAc;EACd,cAAc,KAAK,SAAS,UAAU,QAAQ,CAAC,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,GAAG;EACxE,MAAM;CACR;AACF"}

package/esm/http/uploads/resolve-variant-candidate.mjs

@@ -4,7 +4,7 @@ import { readFileHead } from "./read-file-head.mjs";
 import { resolveUploadPath } from "./resolve-upload-path.mjs";
 import fs from "node:fs/promises";
 
-//#region ../core/src/http/uploads/resolve-variant-candidate.ts
+//#region ../../packages/core/src/http/uploads/resolve-variant-candidate.ts
 /**
 * Resolve a path to a variant source, applying the guards both the on-demand
 * route and the `generateImageVariants` ingest helper need: containment

package/esm/http/uploads/resolve-variant-candidate.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-variant-candidate.mjs","names":[],"sources":["../../../../../../../../core/src/http/uploads/resolve-variant-candidate.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport { HttpError } from \"../errors\";\nimport {\n  detectImageFormat,\n  IMAGE_SIGNATURE_BYTES,\n  isVariantSourceFormat,\n} from \"./detect-image-format\";\nimport type { ResolvedImageVariantsConfig, VariantSourceFormat } from \"./image-variant-types\";\nimport { readFileHead } from \"./read-file-head\";\nimport { resolveUploadPath, type ResolvedUploadPath } from \"./resolve-upload-path\";\n\n/**\n * A request path resolved to a usable variant source\n */\nexport type VariantCandidate = {\n  source: ResolvedUploadPath;\n  stats: { size: number; mtimeMs: number };\n  sourceFormat: VariantSourceFormat;\n};\n\n/**\n * Resolve a path to a variant source, applying the guards both the on-demand\n * route and the `generateImageVariants` ingest helper need: containment\n * (via `resolveUploadPath`), the byte-size limit, and the source format,\n * detected from magic bytes rather than the file extension.\n *\n * @returns `undefined` when the path does not resolve to a file inside the\n * storage root — the caller answers 404, the same as a missing file, so the\n * response is no existence oracle\n * @throws HttpError(413) when the source is over `images.maxSourceBytes`\n * @throws HttpError(415) when the source is not jpeg, png, webp or avif\n */\nexport async function resolveVariantCandidate(\n  wildcard: unknown,\n  storageRoot: string,\n  images: ResolvedImageVariantsConfig,\n): Promise<VariantCandidate | undefined> {\n  const source = await resolveUploadPath(wildcard, storageRoot, [images.cacheDirectory]);\n\n  if (!source) return undefined;\n\n  const stats = await fs.stat(source.absolutePath);\n\n  if (stats.size > images.maxSourceBytes) {\n    throw new HttpError(413, \"The source image is too large.\");\n  }\n\n  const sourceFormat = detectImageFormat(\n    await readFileHead(source.absolutePath, IMAGE_SIGNATURE_BYTES),\n  );\n\n  if (!isVariantSourceFormat(sourceFormat)) {\n    throw new HttpError(415, \"Variants are only available for jpeg, png, webp and avif images.\");\n  }\n\n  return {\n    source,\n    stats: { size: stats.size, mtimeMs: stats.mtimeMs },\n    sourceFormat,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAgCA,eAAsB,wBACpB,UACA,aACA,QACuC;CACvC,MAAM,SAAS,MAAM,kBAAkB,UAAU,aAAa,CAAC,OAAO,cAAc,CAAC;CAErF,IAAI,CAAC,QAAQ,OAAO;CAEpB,MAAM,QAAQ,MAAM,GAAG,KAAK,OAAO,YAAY;CAE/C,IAAI,MAAM,OAAO,OAAO,gBACtB,MAAM,IAAI,UAAU,KAAK,gCAAgC;CAG3D,MAAM,eAAe,kBACnB,MAAM,aAAa,OAAO,iBAAmC,CAC/D;CAEA,IAAI,CAAC,sBAAsB,YAAY,GACrC,MAAM,IAAI,UAAU,KAAK,kEAAkE;CAG7F,OAAO;EACL;EACA,OAAO;GAAE,MAAM,MAAM;GAAM,SAAS,MAAM;EAAQ;EAClD;CACF;AACF"}
+{"version":3,"file":"resolve-variant-candidate.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/resolve-variant-candidate.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport { HttpError } from \"../errors\";\nimport {\n  detectImageFormat,\n  IMAGE_SIGNATURE_BYTES,\n  isVariantSourceFormat,\n} from \"./detect-image-format\";\nimport type { ResolvedImageVariantsConfig, VariantSourceFormat } from \"./image-variant-types\";\nimport { readFileHead } from \"./read-file-head\";\nimport { resolveUploadPath, type ResolvedUploadPath } from \"./resolve-upload-path\";\n\n/**\n * A request path resolved to a usable variant source\n */\nexport type VariantCandidate = {\n  source: ResolvedUploadPath;\n  stats: { size: number; mtimeMs: number };\n  sourceFormat: VariantSourceFormat;\n};\n\n/**\n * Resolve a path to a variant source, applying the guards both the on-demand\n * route and the `generateImageVariants` ingest helper need: containment\n * (via `resolveUploadPath`), the byte-size limit, and the source format,\n * detected from magic bytes rather than the file extension.\n *\n * @returns `undefined` when the path does not resolve to a file inside the\n * storage root — the caller answers 404, the same as a missing file, so the\n * response is no existence oracle\n * @throws HttpError(413) when the source is over `images.maxSourceBytes`\n * @throws HttpError(415) when the source is not jpeg, png, webp or avif\n */\nexport async function resolveVariantCandidate(\n  wildcard: unknown,\n  storageRoot: string,\n  images: ResolvedImageVariantsConfig,\n): Promise<VariantCandidate | undefined> {\n  const source = await resolveUploadPath(wildcard, storageRoot, [images.cacheDirectory]);\n\n  if (!source) return undefined;\n\n  const stats = await fs.stat(source.absolutePath);\n\n  if (stats.size > images.maxSourceBytes) {\n    throw new HttpError(413, \"The source image is too large.\");\n  }\n\n  const sourceFormat = detectImageFormat(\n    await readFileHead(source.absolutePath, IMAGE_SIGNATURE_BYTES),\n  );\n\n  if (!isVariantSourceFormat(sourceFormat)) {\n    throw new HttpError(415, \"Variants are only available for jpeg, png, webp and avif images.\");\n  }\n\n  return {\n    source,\n    stats: { size: stats.size, mtimeMs: stats.mtimeMs },\n    sourceFormat,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAgCA,eAAsB,wBACpB,UACA,aACA,QACuC;CACvC,MAAM,SAAS,MAAM,kBAAkB,UAAU,aAAa,CAAC,OAAO,cAAc,CAAC;CAErF,IAAI,CAAC,QAAQ,OAAO;CAEpB,MAAM,QAAQ,MAAM,GAAG,KAAK,OAAO,YAAY;CAE/C,IAAI,MAAM,OAAO,OAAO,gBACtB,MAAM,IAAI,UAAU,KAAK,gCAAgC;CAG3D,MAAM,eAAe,kBACnB,MAAM,aAAa,OAAO,iBAAmC,CAC/D;CAEA,IAAI,CAAC,sBAAsB,YAAY,GACrC,MAAM,IAAI,UAAU,KAAK,kEAAkE;CAG7F,OAAO;EACL;EACA,OAAO;GAAE,MAAM,MAAM;GAAM,SAAS,MAAM;EAAQ;EAClD;CACF;AACF"}

package/esm/http/uploads/single-flight.mjs

@@ -1,4 +1,4 @@
-//#region ../core/src/http/uploads/single-flight.ts
+//#region ../../packages/core/src/http/uploads/single-flight.ts
 /**
 * Runs a task once per key at a time.
 *

package/esm/http/uploads/single-flight.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"single-flight.mjs","names":[],"sources":["../../../../../../../../core/src/http/uploads/single-flight.ts"],"sourcesContent":["/**\n * Runs a task once per key at a time.\n *\n * A caller that arrives while the task for its key is still running gets the\n * same promise instead of starting a second run, so N concurrent cache misses\n * for one derivative generate it once. The entry is dropped when the task\n * settles, success or failure, so a failed run is retried by the next request.\n */\nexport class SingleFlight<T> {\n  protected readonly inflight = new Map<string, Promise<T>>();\n\n  /**\n   * Run `task` for `key`, or join the run already in flight\n   */\n  public run(key: string, task: () => Promise<T>): Promise<T> {\n    const existing = this.inflight.get(key);\n\n    if (existing) return existing;\n\n    const promise = (async () => {\n      try {\n        return await task();\n      } finally {\n        this.inflight.delete(key);\n      }\n    })();\n\n    this.inflight.set(key, promise);\n\n    return promise;\n  }\n\n  /**\n   * Number of keys currently in flight\n   */\n  public get size(): number {\n    return this.inflight.size;\n  }\n}\n"],"mappings":";;;;;;;;;AAQA,IAAa,eAAb,MAA6B;;kCACG,IAAI,IAAwB;;;;;CAK1D,AAAO,IAAI,KAAa,MAAoC;EAC1D,MAAM,WAAW,KAAK,SAAS,IAAI,GAAG;EAEtC,IAAI,UAAU,OAAO;EAErB,MAAM,WAAW,YAAY;GAC3B,IAAI;IACF,OAAO,MAAM,KAAK;GACpB,UAAU;IACR,KAAK,SAAS,OAAO,GAAG;GAC1B;EACF,EAAC,CAAE;EAEH,KAAK,SAAS,IAAI,KAAK,OAAO;EAE9B,OAAO;CACT;;;;CAKA,IAAW,OAAe;EACxB,OAAO,KAAK,SAAS;CACvB;AACF"}
+{"version":3,"file":"single-flight.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/single-flight.ts"],"sourcesContent":["/**\n * Runs a task once per key at a time.\n *\n * A caller that arrives while the task for its key is still running gets the\n * same promise instead of starting a second run, so N concurrent cache misses\n * for one derivative generate it once. The entry is dropped when the task\n * settles, success or failure, so a failed run is retried by the next request.\n */\nexport class SingleFlight<T> {\n  protected readonly inflight = new Map<string, Promise<T>>();\n\n  /**\n   * Run `task` for `key`, or join the run already in flight\n   */\n  public run(key: string, task: () => Promise<T>): Promise<T> {\n    const existing = this.inflight.get(key);\n\n    if (existing) return existing;\n\n    const promise = (async () => {\n      try {\n        return await task();\n      } finally {\n        this.inflight.delete(key);\n      }\n    })();\n\n    this.inflight.set(key, promise);\n\n    return promise;\n  }\n\n  /**\n   * Number of keys currently in flight\n   */\n  public get size(): number {\n    return this.inflight.size;\n  }\n}\n"],"mappings":";;;;;;;;;AAQA,IAAa,eAAb,MAA6B;;kCACG,IAAI,IAAwB;;;;;CAK1D,AAAO,IAAI,KAAa,MAAoC;EAC1D,MAAM,WAAW,KAAK,SAAS,IAAI,GAAG;EAEtC,IAAI,UAAU,OAAO;EAErB,MAAM,WAAW,YAAY;GAC3B,IAAI;IACF,OAAO,MAAM,KAAK;GACpB,UAAU;IACR,KAAK,SAAS,OAAO,GAAG;GAC1B;EACF,EAAC,CAAE;EAEH,KAAK,SAAS,IAAI,KAAK,OAAO;EAE9B,OAAO;CACT;;;;CAKA,IAAW,OAAe;EACxB,OAAO,KAAK,SAAS;CACvB;AACF"}

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

@@ -0,0 +1,193 @@
+import { variantCacheGenerations } from "./image-variant-cache-entries.mjs";
+import { log } from "@warlock.js/logger";
+import fs from "node:fs/promises";
+
+//#region ../../packages/core/src/http/uploads/trim-image-variant-cache.ts
+const SWEEP_INTERVAL_MS = 6e4;
+/**
+* A writer's temporary file older than this is an orphan left by a crashed
+* write and is removed by the sweep. Younger ones are never touched: a writer
+* may still be renaming them into place.
+*/
+const ORPHAN_TEMP_AGE_MS = 60 * 6e4;
+/**
+* A generation directory left without derivatives is removed only when it
+* was last changed longer ago than this, so a directory a writer has just
+* created for its first derivative survives. The writers also retry once when
+* their directory vanishes between `mkdir` and the rename.
+*/
+const EMPTY_GENERATION_GRACE_MS = 5 * 6e4;
+const caches = /* @__PURE__ */ new Map();
+function cacheState(directory) {
+	let state = caches.get(directory);
+	if (!state) {
+		state = {
+			lastSweep: 0,
+			lastWalk: 0,
+			bytes: 0,
+			sizes: /* @__PURE__ */ new Map(),
+			keep: /* @__PURE__ */ new Set(),
+			reconciled: false
+		};
+		caches.set(directory, state);
+	}
+	return state;
+}
+function errorCode(error) {
+	return error?.code;
+}
+/** Age is measured from generation; hits do not extend a derivative's life. */
+async function freshImageVariant(target, maxAgeSeconds) {
+	try {
+		const stats = await fs.stat(target);
+		return stats.isFile() && Date.now() - stats.mtimeMs < maxAgeSeconds * 1e3;
+	} catch (error) {
+		if (errorCode(error) === "ENOENT") return false;
+		throw error;
+	}
+}
+/**
+* Whether a scheduled check must walk the cache. It may skip only when a walk
+* has already reconciled the byte estimate, the cache is within its byte
+* budget, nothing retained has expired (new writes are always younger than
+* the oldest retained derivative), and a walk ran within the last
+* `maxCacheAge`, which also bounds how long an orphaned temporary can linger.
+*/
+function sweepIsDue(state, images) {
+	const maxAgeMs = images.maxCacheAge * 1e3;
+	const now = Date.now();
+	return !state.reconciled || state.bytes > images.maxCacheBytes || state.oldestMtimeMs !== void 0 && state.oldestMtimeMs <= now - maxAgeMs || now - state.lastWalk >= maxAgeMs;
+}
+/**
+* Schedule housekeeping only after a write. Hits do no cache-directory I/O.
+* Writes update a running byte estimate; at most one background check per
+* minute walks the cache, and only when it may have something to reclaim
+* (see {@link sweepIsDue}).
+*/
+function scheduleImageVariantCacheTrim(images, target) {
+	const state = cacheState(images.cacheDirectory);
+	fs.stat(target).then((stats) => {
+		state.bytes += stats.size - (state.sizes.get(target) ?? 0);
+		state.sizes.set(target, stats.size);
+		state.oldestMtimeMs = Math.min(state.oldestMtimeMs ?? stats.mtimeMs, stats.mtimeMs);
+		if (state.timer) return;
+		const delay = Math.max(0, state.lastSweep + SWEEP_INTERVAL_MS - Date.now());
+		state.timer = setTimeout(() => {
+			state.timer = void 0;
+			if (!sweepIsDue(state, images)) {
+				state.lastSweep = Date.now();
+				return;
+			}
+			trimImageVariantCache(images, target).catch((error) => {
+				log.warn("uploads", "image-variants", error);
+			});
+		}, delay);
+		state.timer.unref();
+	}).catch((error) => {
+		if (errorCode(error) !== "ENOENT") log.warn("uploads", "image-variants", error);
+	});
+}
+/** Remove a temporary only when it is a regular file older than {@link ORPHAN_TEMP_AGE_MS}. */
+async function removeOrphanTemporary(target) {
+	try {
+		const stats = await fs.lstat(target);
+		if (stats.isFile() && Date.now() - stats.mtimeMs > 36e5) await fs.rm(target, { force: true });
+	} catch (error) {
+		if (errorCode(error) !== "ENOENT") throw error;
+	}
+}
+/**
+* Remove a generation left without derivatives: its manifest, then the
+* directory itself with a non-recursive `rmdir`, so anything a writer has put
+* there since the walk keeps the directory in place.
+*/
+async function removeEmptyGeneration(generation) {
+	if (generation.derivatives > 0) return;
+	if (Date.now() - generation.mtimeMs <= 3e5) return;
+	if (generation.manifest) await fs.rm(generation.manifest, { force: true });
+	try {
+		if (!(await fs.lstat(generation.directory)).isDirectory()) return;
+		await fs.rmdir(generation.directory);
+	} catch (error) {
+		const code = errorCode(error);
+		if (code !== "ENOENT" && code !== "ENOTEMPTY" && code !== "EEXIST") throw error;
+	}
+}
+/**
+* Join an in-flight sweep rather than queueing another walk. Retain the file
+* about to be served, even if it alone exceeds the byte budget. Only paths in
+* the generated cache layout are touched and symlinks are never followed:
+* expired and oldest derivatives are evicted, writer temporaries older than
+* {@link ORPHAN_TEMP_AGE_MS} are removed, and a generation directory left
+* without derivatives loses its manifest and the directory itself once it is
+* older than {@link EMPTY_GENERATION_GRACE_MS}. The cache root, shard and
+* source directories, user folders and unrelated files stay in place.
+*/
+async function trimImageVariantCache(images, keep) {
+	const state = cacheState(images.cacheDirectory);
+	state.keep.add(keep);
+	if (state.sweep) return state.sweep;
+	state.lastSweep = Date.now();
+	state.lastWalk = state.lastSweep;
+	const sweep = (async () => {
+		const files = [];
+		const generations = [];
+		for await (const found of variantCacheGenerations(images.cacheDirectory)) {
+			let mtimeMs;
+			try {
+				mtimeMs = (await fs.lstat(found.directory)).mtimeMs;
+			} catch (error) {
+				if (errorCode(error) === "ENOENT") continue;
+				throw error;
+			}
+			const generation = {
+				directory: found.directory,
+				mtimeMs,
+				derivatives: 0
+			};
+			generations.push(generation);
+			for (const entry of found.entries) if (entry.type === "manifest") generation.manifest = entry.target;
+			else if (entry.type === "temporary") await removeOrphanTemporary(entry.target);
+			else try {
+				const stats = await fs.stat(entry.target);
+				files.push({
+					target: entry.target,
+					size: stats.size,
+					mtimeMs: stats.mtimeMs,
+					generation
+				});
+				generation.derivatives += 1;
+			} catch (error) {
+				if (errorCode(error) !== "ENOENT") throw error;
+			}
+		}
+		state.sizes = new Map(files.map((file) => [file.target, file.size]));
+		state.bytes = files.reduce((sum, file) => sum + file.size, 0);
+		const cutoff = Date.now() - images.maxCacheAge * 1e3;
+		let oldestMtimeMs;
+		for (const file of files.sort((a, b) => a.mtimeMs - b.mtimeMs)) {
+			if (!state.keep.has(file.target) && (file.mtimeMs <= cutoff || state.bytes > images.maxCacheBytes)) {
+				await fs.rm(file.target, { force: true });
+				state.bytes -= file.size;
+				state.sizes.delete(file.target);
+				file.generation.derivatives -= 1;
+				continue;
+			}
+			oldestMtimeMs = Math.min(oldestMtimeMs ?? file.mtimeMs, file.mtimeMs);
+		}
+		for (const generation of generations) await removeEmptyGeneration(generation);
+		state.oldestMtimeMs = oldestMtimeMs;
+		state.reconciled = true;
+	})();
+	state.sweep = sweep;
+	try {
+		await sweep;
+	} finally {
+		state.sweep = void 0;
+		state.keep.clear();
+	}
+}
+
+//#endregion
+export { freshImageVariant, scheduleImageVariantCacheTrim };
+//# sourceMappingURL=trim-image-variant-cache.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trim-image-variant-cache.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/trim-image-variant-cache.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\nimport fs from \"node:fs/promises\";\nimport type { ResolvedImageVariantsConfig } from \"./image-variant-types\";\nimport { variantCacheGenerations } from \"./image-variant-cache-entries\";\n\nconst SWEEP_INTERVAL_MS = 60_000;\n\n/**\n * A writer's temporary file older than this is an orphan left by a crashed\n * write and is removed by the sweep. Younger ones are never touched: a writer\n * may still be renaming them into place.\n */\nexport const ORPHAN_TEMP_AGE_MS = 60 * 60_000;\n\n/**\n * A generation directory left without derivatives is removed only when it\n * was last changed longer ago than this, so a directory a writer has just\n * created for its first derivative survives. The writers also retry once when\n * their directory vanishes between `mkdir` and the rename.\n */\nexport const EMPTY_GENERATION_GRACE_MS = 5 * 60_000;\n\ntype CacheState = {\n  sweep?: Promise<void>;\n  timer?: ReturnType<typeof setTimeout>;\n  /** When the last scheduled check ran, whether or not it walked the cache. */\n  lastSweep: number;\n  /** When the cache was last walked. */\n  lastWalk: number;\n  bytes: number;\n  sizes: Map<string, number>;\n  keep: Set<string>;\n  /** True once a walk has reconciled `bytes` with the disk. */\n  reconciled: boolean;\n  /** The oldest retained derivative's mtime; undefined when none is known. */\n  oldestMtimeMs?: number;\n};\nconst caches = new Map<string, CacheState>();\nfunction cacheState(directory: string): CacheState {\n  let state = caches.get(directory);\n  if (!state) {\n    state = {\n      lastSweep: 0,\n      lastWalk: 0,\n      bytes: 0,\n      sizes: new Map(),\n      keep: new Set(),\n      reconciled: false,\n    };\n    caches.set(directory, state);\n  }\n  return state;\n}\n\nfunction errorCode(error: unknown): string | undefined {\n  return (error as NodeJS.ErrnoException | undefined)?.code;\n}\n\n/** Age is measured from generation; hits do not extend a derivative's life. */\nexport async function freshImageVariant(target: string, maxAgeSeconds: number): Promise<boolean> {\n  try {\n    const stats = await fs.stat(target);\n    return stats.isFile() && Date.now() - stats.mtimeMs < maxAgeSeconds * 1000;\n  } catch (error) {\n    if (errorCode(error) === \"ENOENT\") return false;\n    throw error;\n  }\n}\n\n/**\n * Whether a scheduled check must walk the cache. It may skip only when a walk\n * has already reconciled the byte estimate, the cache is within its byte\n * budget, nothing retained has expired (new writes are always younger than\n * the oldest retained derivative), and a walk ran within the last\n * `maxCacheAge`, which also bounds how long an orphaned temporary can linger.\n */\nfunction sweepIsDue(state: CacheState, images: ResolvedImageVariantsConfig): boolean {\n  const maxAgeMs = images.maxCacheAge * 1000;\n  const now = Date.now();\n  return (\n    !state.reconciled ||\n    state.bytes > images.maxCacheBytes ||\n    (state.oldestMtimeMs !== undefined && state.oldestMtimeMs <= now - maxAgeMs) ||\n    now - state.lastWalk >= maxAgeMs\n  );\n}\n\n/**\n * Schedule housekeeping only after a write. Hits do no cache-directory I/O.\n * Writes update a running byte estimate; at most one background check per\n * minute walks the cache, and only when it may have something to reclaim\n * (see {@link sweepIsDue}).\n */\nexport function scheduleImageVariantCacheTrim(\n  images: ResolvedImageVariantsConfig,\n  target: string,\n): void {\n  const state = cacheState(images.cacheDirectory);\n  void fs\n    .stat(target)\n    .then((stats) => {\n      state.bytes += stats.size - (state.sizes.get(target) ?? 0);\n      state.sizes.set(target, stats.size);\n      state.oldestMtimeMs = Math.min(state.oldestMtimeMs ?? stats.mtimeMs, stats.mtimeMs);\n      if (state.timer) return;\n      const delay = Math.max(0, state.lastSweep + SWEEP_INTERVAL_MS - Date.now());\n      state.timer = setTimeout(() => {\n        state.timer = undefined;\n        if (!sweepIsDue(state, images)) {\n          state.lastSweep = Date.now();\n          return;\n        }\n        void trimImageVariantCache(images, target).catch((error: unknown) => {\n          log.warn(\"uploads\", \"image-variants\", error);\n        });\n      }, delay);\n      state.timer.unref();\n    })\n    .catch((error: unknown) => {\n      if (errorCode(error) !== \"ENOENT\") log.warn(\"uploads\", \"image-variants\", error);\n    });\n}\n\ntype Derivative = { target: string; size: number; mtimeMs: number; generation: Generation };\ntype Generation = {\n  directory: string;\n  /** The directory's mtime before this sweep removed anything from it. */\n  mtimeMs: number;\n  derivatives: number;\n  manifest?: string;\n};\n\n/** Remove a temporary only when it is a regular file older than {@link ORPHAN_TEMP_AGE_MS}. */\nasync function removeOrphanTemporary(target: string): Promise<void> {\n  try {\n    const stats = await fs.lstat(target);\n    if (stats.isFile() && Date.now() - stats.mtimeMs > ORPHAN_TEMP_AGE_MS) {\n      await fs.rm(target, { force: true });\n    }\n  } catch (error) {\n    if (errorCode(error) !== \"ENOENT\") throw error;\n  }\n}\n\n/**\n * Remove a generation left without derivatives: its manifest, then the\n * directory itself with a non-recursive `rmdir`, so anything a writer has put\n * there since the walk keeps the directory in place.\n */\nasync function removeEmptyGeneration(generation: Generation): Promise<void> {\n  if (generation.derivatives > 0) return;\n  if (Date.now() - generation.mtimeMs <= EMPTY_GENERATION_GRACE_MS) return;\n  if (generation.manifest) await fs.rm(generation.manifest, { force: true });\n  try {\n    if (!(await fs.lstat(generation.directory)).isDirectory()) return;\n    await fs.rmdir(generation.directory);\n  } catch (error) {\n    const code = errorCode(error);\n    if (code !== \"ENOENT\" && code !== \"ENOTEMPTY\" && code !== \"EEXIST\") throw error;\n  }\n}\n\n/**\n * Join an in-flight sweep rather than queueing another walk. Retain the file\n * about to be served, even if it alone exceeds the byte budget. Only paths in\n * the generated cache layout are touched and symlinks are never followed:\n * expired and oldest derivatives are evicted, writer temporaries older than\n * {@link ORPHAN_TEMP_AGE_MS} are removed, and a generation directory left\n * without derivatives loses its manifest and the directory itself once it is\n * older than {@link EMPTY_GENERATION_GRACE_MS}. The cache root, shard and\n * source directories, user folders and unrelated files stay in place.\n */\nexport async function trimImageVariantCache(\n  images: ResolvedImageVariantsConfig,\n  keep: string,\n): Promise<void> {\n  const state = cacheState(images.cacheDirectory);\n  state.keep.add(keep);\n  if (state.sweep) return state.sweep;\n  state.lastSweep = Date.now();\n  state.lastWalk = state.lastSweep;\n  const sweep = (async () => {\n    const files: Derivative[] = [];\n    const generations: Generation[] = [];\n    for await (const found of variantCacheGenerations(images.cacheDirectory)) {\n      let mtimeMs: number;\n      try {\n        mtimeMs = (await fs.lstat(found.directory)).mtimeMs;\n      } catch (error) {\n        if (errorCode(error) === \"ENOENT\") continue;\n        throw error;\n      }\n      const generation: Generation = { directory: found.directory, mtimeMs, derivatives: 0 };\n      generations.push(generation);\n      for (const entry of found.entries) {\n        if (entry.type === \"manifest\") {\n          generation.manifest = entry.target;\n        } else if (entry.type === \"temporary\") {\n          await removeOrphanTemporary(entry.target);\n        } else {\n          try {\n            const stats = await fs.stat(entry.target);\n            files.push({\n              target: entry.target,\n              size: stats.size,\n              mtimeMs: stats.mtimeMs,\n              generation,\n            });\n            generation.derivatives += 1;\n          } catch (error) {\n            if (errorCode(error) !== \"ENOENT\") throw error;\n          }\n        }\n      }\n    }\n    state.sizes = new Map(files.map((file) => [file.target, file.size]));\n    state.bytes = files.reduce((sum, file) => sum + file.size, 0);\n    const cutoff = Date.now() - images.maxCacheAge * 1000;\n    let oldestMtimeMs: number | undefined;\n    for (const file of files.sort((a, b) => a.mtimeMs - b.mtimeMs)) {\n      if (\n        !state.keep.has(file.target) &&\n        (file.mtimeMs <= cutoff || state.bytes > images.maxCacheBytes)\n      ) {\n        await fs.rm(file.target, { force: true });\n        state.bytes -= file.size;\n        state.sizes.delete(file.target);\n        file.generation.derivatives -= 1;\n        continue;\n      }\n      oldestMtimeMs = Math.min(oldestMtimeMs ?? file.mtimeMs, file.mtimeMs);\n    }\n    for (const generation of generations) await removeEmptyGeneration(generation);\n    state.oldestMtimeMs = oldestMtimeMs;\n    state.reconciled = true;\n  })();\n  state.sweep = sweep;\n  try {\n    await sweep;\n  } finally {\n    state.sweep = undefined;\n    state.keep.clear();\n  }\n}\n"],"mappings":"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"}

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

@@ -1,10 +1,26 @@
+import { StorageDriverName } from "../../storage/types.mjs";
 import { RequestHandler } from "../../router/types.mjs";
-//#region ../core/src/http/uploads/uploaded-file.controller.d.ts
+//#region ../../packages/core/src/http/uploads/uploaded-file.controller.d.ts
 /**
- * Serves local uploads, and bounded on-demand variants of the images among them.
+ * Options for {@link createUploadedFileController}
+ */
+type UploadedFileControllerOptions = {
+  /**
+   * Disk to serve from; remote disks support variants only. Uses the default
+   * disk when omitted. A private disk
+   * should be served from a route that checks access first.
+   */
+  disk?: StorageDriverName; /** Allow derivatives from the default cloud disk. Explicit disk selection also opts in. */
+  remote?: boolean;
+};
+/**
+ * Serves local uploads and bounded on-demand image variants from any disk.
  *
  * ```ts
  * router.get("/uploads/*", uploadedFileController);
+ * router.get("/invoices/*", createUploadedFileController({ disk: "private" }), {
+ *   middleware: [authMiddleware()],
+ * });
  * ```
  *
  * - `GET /uploads/<path>` sends the original file with a one-year cache.
@@ -12,13 +28,17 @@ import { RequestHandler } from "../../router/types.mjs";
  *   rendered from a variant named in `uploads.images.variants`. No other query
  *   key is accepted, so a client can never ask for an arbitrary size.
  *
- * The path must stay inside the storage root (after symlinks are resolved) and
+ * The path must stay inside the disk root (after symlinks are resolved) and
  * outside the variant cache; anything else is a 404, the same answer a missing
- * file gets. Derivatives are cached on disk under a sha256 of the source path,
- * size, mtime, variant and format, written atomically, generated once per key
- * even under concurrent requests, and sent with an immutable cache and an ETag.
+ * file gets. Derivatives are cached on disk under a directory per source
+ * (see `resolveImageVariant`), written atomically, generated once per key even
+ * under concurrent requests, and sent with an immutable cache and an ETag.
+ */
+declare function createUploadedFileController(options?: UploadedFileControllerOptions): RequestHandler;
+/**
+ * Serves the default disk's uploads; see {@link createUploadedFileController}
  */
 declare const uploadedFileController: RequestHandler;
 //#endregion
-export { uploadedFileController };
+export { UploadedFileControllerOptions, createUploadedFileController, uploadedFileController };
 //# sourceMappingURL=uploaded-file.controller.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"uploaded-file.controller.d.mts","names":[],"sources":["../../../../../../../../core/src/http/uploads/uploaded-file.controller.ts"],"mappings":";;;;;AA0HA;;;;AAsIC;;;;;;;;;;;cAtIY,sBAAA,EAAwB,cAsIpC"}
+{"version":3,"file":"uploaded-file.controller.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/uploaded-file.controller.ts"],"mappings":";;;;;;KA6FY,6BAAA;EAA6B;;;;;EAMvC,IAAA,GAAO,iBAAiB,EAGlB;EAAN,MAAA;AAAA;;;;;;;;AA0Be;AA+HjB;;;;AAAoF;;;;;;;;;iBAjIpE,4BAAA,CACd,OAAA,GAAS,6BAAA,GACR,cAAc;;;;cA+HJ,sBAAA,EAAwB,cAA+C"}