@warlock.js/core 5.16.0 → 5.17.1

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

@@ -0,0 +1,53 @@
+import path from "node:path";
+
+//#region ../core/src/http/uploads/resolve-inline-image-content-type.ts
+/**
+* Extensions an upload original may carry for each raster format that is
+* allowed to render inline. Anything else — including `.gif`, since gif is
+* not a variant source format — is never served inline, regardless of what
+* its bytes sniff as.
+*/
+const EXTENSION_IMAGE_FORMATS = {
+	".jpg": "jpeg",
+	".jpeg": "jpeg",
+	".png": "png",
+	".webp": "webp",
+	".avif": "avif"
+};
+/**
+* Content type an inline response must advertise for each raster format,
+* used instead of an extension-derived guess.
+*/
+const INLINE_IMAGE_CONTENT_TYPES = {
+	jpeg: "image/jpeg",
+	png: "image/png",
+	webp: "image/webp",
+	avif: "image/avif"
+};
+/**
+* Content type to serve an upload original inline with, or `undefined` when
+* it must go out as an attachment instead.
+*
+* `sendFile` sets `Content-Type` from the file's EXTENSION, not its bytes.
+* The inline branch in `uploaded-file.controller.ts` only sniffs the bytes to
+* decide "is this raster" — so a JPEG-signature file named `x.html` sniffed
+* as jpeg (raster, so "safe") would still have been sent by `sendFile` as
+* `text/html`: a polyglot JPEG/HTML stored-XSS vector, the reverse of the
+* already-fixed SVG-named-`.png` case.
+*
+* Inline is therefore only safe when the sniffed format AND the
+* extension-derived format agree — the extension maps to the SAME image
+* type the bytes sniffed as. Any mismatch (raster bytes under a non-image or
+* different-image extension) returns `undefined`, sending the caller to the
+* attachment path instead of trusting either signal alone.
+*/
+function resolveInlineImageContentType(filePath, sniffedFormat) {
+	if (sniffedFormat === void 0) return void 0;
+	const extensionFormat = EXTENSION_IMAGE_FORMATS[path.extname(filePath).toLowerCase()];
+	if (extensionFormat === void 0 || extensionFormat !== sniffedFormat) return void 0;
+	return INLINE_IMAGE_CONTENT_TYPES[extensionFormat];
+}
+
+//#endregion
+export { resolveInlineImageContentType };
+//# sourceMappingURL=resolve-inline-image-content-type.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,31 @@
+import mime from "mime";
+
+//#region ../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
+* (inline `<script>` in an svg, markup and script in html/xhtml/xml), so an
+* upload served under its real type is stored XSS the moment it is fetched
+* from the app's own origin.
+*/
+const INLINE_EXECUTABLE_MIME_TYPES = new Set([
+	"image/svg+xml",
+	"text/html",
+	"application/xhtml+xml",
+	"text/xml",
+	"application/xml"
+]);
+/**
+* Content type for an upload original that is being served as an
+* `attachment` (see `uploaded-file.controller.ts`): the extension-derived
+* type, except the svg/html/xml family, which is downgraded to
+* `application/octet-stream` so a browser never sniffs or renders it.
+*/
+function resolveOriginalContentType(filePath) {
+	const type = mime.getType(filePath) || "application/octet-stream";
+	return INLINE_EXECUTABLE_MIME_TYPES.has(type) ? "application/octet-stream" : type;
+}
+
+//#endregion
+export { resolveOriginalContentType };
+//# sourceMappingURL=resolve-original-content-type.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,56 @@
+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
+async function realpathOrSelf(target) {
+	try {
+		return await fs.realpath(target);
+	} catch {
+		return target;
+	}
+}
+/**
+* Resolve the wildcard of an uploads route to a file inside the storage root.
+*
+* The wildcard arrives already decoded once by the router and is NOT decoded
+* again: a second decode would turn `%252e%252e%252f` into `../`.
+*
+* Returns `undefined` — the caller answers 404 for every case, so the response
+* is no existence oracle — when the path:
+* - is empty, carries a NUL byte, or is absolute
+* - resolves outside the root, or to the root itself
+* - lies in one of the `excludedDirectories` (the variant cache)
+* - does not exist, or is not a regular file
+* - is (or passes through) a symlink whose target leaves the root
+*/
+async function resolveUploadPath(wildcard, storageRoot, excludedDirectories = []) {
+	if (typeof wildcard !== "string" || wildcard === "" || wildcard.includes("\0")) return;
+	if (path.isAbsolute(wildcard) || path.win32.isAbsolute(wildcard) || /^[A-Za-z]:/.test(wildcard)) return;
+	const root = path.resolve(storageRoot);
+	const resolved = path.resolve(root, wildcard);
+	if (!isPathInside(resolved, root)) return void 0;
+	for (const excluded of excludedDirectories) if (isPathWithin(resolved, path.resolve(excluded))) return void 0;
+	let realPath;
+	try {
+		realPath = await fs.realpath(resolved);
+	} catch {
+		return;
+	}
+	const realRoot = await realpathOrSelf(root);
+	if (!isPathInside(realPath, realRoot)) return void 0;
+	for (const excluded of excludedDirectories) if (isPathWithin(realPath, await realpathOrSelf(path.resolve(excluded)))) return void 0;
+	try {
+		if (!(await fs.stat(realPath)).isFile()) return void 0;
+	} catch {
+		return;
+	}
+	return {
+		absolutePath: realPath,
+		relativePath: path.relative(realRoot, realPath).split(path.sep).join("/")
+	};
+}
+
+//#endregion
+export { resolveUploadPath };
+//# sourceMappingURL=resolve-upload-path.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,39 @@
+import { HttpError } from "../errors/errors.mjs";
+import { detectImageFormat, isVariantSourceFormat } from "./detect-image-format.mjs";
+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
+/**
+* Resolve a path to a variant source, applying the guards both the on-demand
+* route and the `generateImageVariants` ingest helper need: containment
+* (via `resolveUploadPath`), the byte-size limit, and the source format,
+* detected from magic bytes rather than the file extension.
+*
+* @returns `undefined` when the path does not resolve to a file inside the
+* storage root — the caller answers 404, the same as a missing file, so the
+* response is no existence oracle
+* @throws HttpError(413) when the source is over `images.maxSourceBytes`
+* @throws HttpError(415) when the source is not jpeg, png, webp or avif
+*/
+async function resolveVariantCandidate(wildcard, storageRoot, images) {
+	const source = await resolveUploadPath(wildcard, storageRoot, [images.cacheDirectory]);
+	if (!source) return void 0;
+	const stats = await fs.stat(source.absolutePath);
+	if (stats.size > images.maxSourceBytes) throw new HttpError(413, "The source image is too large.");
+	const sourceFormat = detectImageFormat(await readFileHead(source.absolutePath, 512));
+	if (!isVariantSourceFormat(sourceFormat)) throw new HttpError(415, "Variants are only available for jpeg, png, webp and avif images.");
+	return {
+		source,
+		stats: {
+			size: stats.size,
+			mtimeMs: stats.mtimeMs
+		},
+		sourceFormat
+	};
+}
+
+//#endregion
+export { resolveVariantCandidate };
+//# sourceMappingURL=resolve-variant-candidate.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,40 @@
+//#region ../core/src/http/uploads/single-flight.ts
+/**
+* Runs a task once per key at a time.
+*
+* A caller that arrives while the task for its key is still running gets the
+* same promise instead of starting a second run, so N concurrent cache misses
+* for one derivative generate it once. The entry is dropped when the task
+* settles, success or failure, so a failed run is retried by the next request.
+*/
+var SingleFlight = class {
+	constructor() {
+		this.inflight = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Run `task` for `key`, or join the run already in flight
+	*/
+	run(key, task) {
+		const existing = this.inflight.get(key);
+		if (existing) return existing;
+		const promise = (async () => {
+			try {
+				return await task();
+			} finally {
+				this.inflight.delete(key);
+			}
+		})();
+		this.inflight.set(key, promise);
+		return promise;
+	}
+	/**
+	* Number of keys currently in flight
+	*/
+	get size() {
+		return this.inflight.size;
+	}
+};
+
+//#endregion
+export { SingleFlight };
+//# sourceMappingURL=single-flight.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,24 @@
+import { RequestHandler } from "../../router/types.mjs";
+//#region ../core/src/http/uploads/uploaded-file.controller.d.ts
+/**
+ * Serves local uploads, and bounded on-demand variants of the images among them.
+ *
+ * ```ts
+ * router.get("/uploads/*", uploadedFileController);
+ * ```
+ *
+ * - `GET /uploads/<path>` sends the original file with a one-year cache.
+ * - `GET /uploads/<path>?variant=<name>[&format=webp|avif]` sends a derivative
+ *   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
+ * 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.
+ */
+declare const uploadedFileController: RequestHandler;
+//#endregion
+export { uploadedFileController };
+//# sourceMappingURL=uploaded-file.controller.d.mts.map

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

@@ -0,0 +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"}

package/esm/http/uploads/uploaded-file.controller.mjs

@@ -0,0 +1,174 @@
+import { HttpError } from "../errors/errors.mjs";
+import { storage } from "../../storage/storage.mjs";
+import "../../storage/index.mjs";
+import { uploadsConfig } from "../uploads-config.mjs";
+import { generateImageVariant } from "./generate-image-variant.mjs";
+import { detectImageFormat, isVariantSourceFormat } from "./detect-image-format.mjs";
+import { loadVariantSource } from "./load-variant-source.mjs";
+import { resolveImageVariantsConfig } from "./resolve-image-variants-config.mjs";
+import { readFileHead } from "./read-file-head.mjs";
+import { resolveUploadPath } from "./resolve-upload-path.mjs";
+import { resolveVariantCandidate } from "./resolve-variant-candidate.mjs";
+import { variantCacheKey, variantCachePath } from "./variant-cache-key.mjs";
+import { variantGenerations } from "./variant-generations.mjs";
+import { matchesIfNoneMatch } from "./matches-if-none-match.mjs";
+import { parseUploadedFileQuery } from "./parse-uploaded-file-query.mjs";
+import { resolveInlineImageContentType } from "./resolve-inline-image-content-type.mjs";
+import { resolveOriginalContentType } from "./resolve-original-content-type.mjs";
+import { log } from "@warlock.js/logger";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+//#region ../core/src/http/uploads/uploaded-file.controller.ts
+/**
+* One year, in seconds: originals and derivatives are both long-lived
+*/
+const ONE_YEAR = 31536e3;
+const CONTENT_TYPES = {
+	jpeg: "image/jpeg",
+	png: "image/png",
+	webp: "image/webp",
+	avif: "image/avif"
+};
+async function exists(target) {
+	try {
+		await fs.access(target);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function notFound(response) {
+	return response.notFound({ error: "File Not Found" });
+}
+async function sendVariant(response, target, hash, format) {
+	return response.sendBuffer(await fs.readFile(target), {
+		contentType: CONTENT_TYPES[format],
+		cacheTime: ONE_YEAR,
+		immutable: true,
+		etag: `"${hash}"`
+	});
+}
+/**
+* Serve an upload original that isn't safe to render inline: a non-raster
+* format (html, xml, the svg family, anything unrecognised) is markup a
+* browser will parse and execute, and a raster-sniffed file whose extension
+* doesn't back that format up (see `resolveInlineImageContentType`) is a
+* polyglot — so both go out as a download instead of a rendered response.
+* `Content-Type` stays extension-derived, except the svg/html/xml family,
+* which is downgraded to `application/octet-stream` so the browser never
+* renders it even if it ignores the disposition.
+*/
+async function sendOriginalAsAttachment(response, absolutePath) {
+	response.header("Content-Security-Policy", "sandbox");
+	return response.sendBuffer(await fs.readFile(absolutePath), {
+		contentType: resolveOriginalContentType(absolutePath),
+		cacheTime: ONE_YEAR,
+		immutable: true,
+		inline: false,
+		filename: path.basename(absolutePath)
+	});
+}
+/**
+* Serve an upload original inline, once the sniffed raster format and the
+* extension-derived format have been confirmed to agree. The content type is
+* always the SNIFFED image type, passed explicitly — never `sendFile`'s
+* extension-derived guess, which is exactly what let a JPEG named `.html`
+* out as `text/html` before this existed.
+*/
+async function sendOriginalInline(response, absolutePath, contentType) {
+	return response.sendBuffer(await fs.readFile(absolutePath), {
+		contentType,
+		cacheTime: ONE_YEAR,
+		immutable: true
+	});
+}
+/**
+* Serves local uploads, and bounded on-demand variants of the images among them.
+*
+* ```ts
+* router.get("/uploads/*", uploadedFileController);
+* ```
+*
+* - `GET /uploads/<path>` sends the original file with a one-year cache.
+* - `GET /uploads/<path>?variant=<name>[&format=webp|avif]` sends a derivative
+*   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
+* 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.
+*/
+const uploadedFileController = async ({ request, response }) => {
+	const storageRoot = storage.root();
+	if (!storageRoot || storageRoot === ".") {
+		log.error("uploads", "serve", "uploadedFileController needs a local storage driver with a root.");
+		return notFound(response);
+	}
+	const query = parseUploadedFileQuery(request.url);
+	if (query.type === "invalid") return response.badRequest({ error: query.reason });
+	response.header("X-Content-Type-Options", "nosniff");
+	if (query.type === "original") {
+		const images = uploadsConfig("images");
+		const cacheDirectory = images?.cacheDirectory ? [images.cacheDirectory] : [];
+		const source = await resolveUploadPath(request.params["*"], storageRoot, [storage.root(".cache/image-variants"), ...cacheDirectory]);
+		if (!source) return notFound(response);
+		const sniffedFormat = detectImageFormat(await readFileHead(source.absolutePath, 512));
+		if (!isVariantSourceFormat(sniffedFormat)) return sendOriginalAsAttachment(response, source.absolutePath);
+		const inlineContentType = resolveInlineImageContentType(source.absolutePath, sniffedFormat);
+		if (!inlineContentType) return sendOriginalAsAttachment(response, source.absolutePath);
+		return sendOriginalInline(response, source.absolutePath, inlineContentType);
+	}
+	const images = resolveImageVariantsConfig(uploadsConfig("images"), storageRoot);
+	if (!images) return response.badRequest({ error: "Image variants are not configured." });
+	if (!Object.prototype.hasOwnProperty.call(images.variants, query.variant)) return response.badRequest({ error: `Unknown variant "${query.variant}".` });
+	const requestedFormat = query.format;
+	if (requestedFormat !== void 0 && !images.formats.includes(requestedFormat)) return response.badRequest({ error: `Format "${query.format}" is not allowed.` });
+	const variant = images.variants[query.variant];
+	if (variant === void 0) return response.badRequest({ error: `Unknown variant "${query.variant}".` });
+	let source;
+	try {
+		const candidate = await resolveVariantCandidate(request.params["*"], storageRoot, images);
+		if (!candidate) return notFound(response);
+		const resolvedSource = candidate.source;
+		source = resolvedSource;
+		const { stats, sourceFormat } = candidate;
+		const format = requestedFormat ?? sourceFormat;
+		const hash = variantCacheKey({
+			relativePath: resolvedSource.relativePath,
+			sourceSize: stats.size,
+			sourceMtimeMs: stats.mtimeMs,
+			variant,
+			format
+		});
+		const target = variantCachePath(images.cacheDirectory, hash, format);
+		if (await exists(target)) {
+			if (matchesIfNoneMatch(request.header("if-none-match"), `"${hash}"`)) return response.baseResponse.status(304).send();
+			return sendVariant(response, target, hash, format);
+		}
+		await variantGenerations.run(hash, async () => {
+			if (await exists(target)) return;
+			await generateImageVariant({
+				image: await loadVariantSource(resolvedSource.absolutePath, {
+					maxSourceBytes: images.maxSourceBytes,
+					maxSourcePixels: images.maxSourcePixels,
+					expectedFormat: sourceFormat
+				}),
+				variant,
+				format,
+				targetPath: target
+			});
+		});
+		return sendVariant(response, target, hash, format);
+	} catch (error) {
+		if (error instanceof HttpError) return response.send({ error: error.message }, error.status);
+		log.error("uploads", "variant", `Could not generate variant "${query.variant}" of ${source?.relativePath ?? request.params["*"]}: ${error instanceof Error ? error.message : String(error)}`);
+		return response.serverError({ error: "Could not generate the image variant." });
+	}
+};
+
+//#endregion
+export { uploadedFileController };
+//# sourceMappingURL=uploaded-file.controller.mjs.map

package/esm/http/uploads/uploaded-file.controller.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploaded-file.controller.mjs","names":[],"sources":["../../../../../../../../core/src/http/uploads/uploaded-file.controller.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport type { RequestHandler } from \"../../router\";\nimport { storage } from \"../../storage\";\nimport { HttpError } from \"../errors\";\nimport type { Response } from \"../response\";\nimport { uploadsConfig } from \"../uploads-config\";\nimport {\n  detectImageFormat,\n  IMAGE_SIGNATURE_BYTES,\n  isVariantSourceFormat,\n} from \"./detect-image-format\";\nimport { generateImageVariant } from \"./generate-image-variant\";\nimport type { VariantOutputFormat } from \"./image-variant-types\";\nimport { loadVariantSource } from \"./load-variant-source\";\nimport { matchesIfNoneMatch } from \"./matches-if-none-match\";\nimport { parseUploadedFileQuery } from \"./parse-uploaded-file-query\";\nimport { readFileHead } from \"./read-file-head\";\nimport { resolveImageVariantsConfig } from \"./resolve-image-variants-config\";\nimport { resolveInlineImageContentType } from \"./resolve-inline-image-content-type\";\nimport { resolveOriginalContentType } from \"./resolve-original-content-type\";\nimport { resolveUploadPath, type ResolvedUploadPath } from \"./resolve-upload-path\";\nimport { resolveVariantCandidate } from \"./resolve-variant-candidate\";\nimport { variantCacheKey, variantCachePath } from \"./variant-cache-key\";\nimport { variantGenerations } from \"./variant-generations\";\n\n/**\n * One year, in seconds: originals and derivatives are both long-lived\n */\nconst ONE_YEAR = 31_536_000;\n\nconst CONTENT_TYPES: Record<VariantOutputFormat, string> = {\n  jpeg: \"image/jpeg\",\n  png: \"image/png\",\n  webp: \"image/webp\",\n  avif: \"image/avif\",\n};\n\nasync function exists(target: string): Promise<boolean> {\n  try {\n    await fs.access(target);\n\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nfunction notFound(response: Response) {\n  return response.notFound({ error: \"File Not Found\" });\n}\n\nasync function sendVariant(\n  response: Response,\n  target: string,\n  hash: string,\n  format: VariantOutputFormat,\n) {\n  return response.sendBuffer(await fs.readFile(target), {\n    contentType: CONTENT_TYPES[format],\n    cacheTime: ONE_YEAR,\n    immutable: true,\n    etag: `\"${hash}\"`,\n  });\n}\n\n/**\n * Serve an upload original that isn't safe to render inline: a non-raster\n * format (html, xml, the svg family, anything unrecognised) is markup a\n * browser will parse and execute, and a raster-sniffed file whose extension\n * doesn't back that format up (see `resolveInlineImageContentType`) is a\n * polyglot — so both go out as a download instead of a rendered response.\n * `Content-Type` stays extension-derived, except the svg/html/xml family,\n * which is downgraded to `application/octet-stream` so the browser never\n * renders it even if it ignores the disposition.\n */\nasync function sendOriginalAsAttachment(response: Response, absolutePath: string) {\n  response.header(\"Content-Security-Policy\", \"sandbox\");\n\n  return response.sendBuffer(await fs.readFile(absolutePath), {\n    contentType: resolveOriginalContentType(absolutePath),\n    cacheTime: ONE_YEAR,\n    immutable: true,\n    inline: false,\n    filename: path.basename(absolutePath),\n  });\n}\n\n/**\n * Serve an upload original inline, once the sniffed raster format and the\n * extension-derived format have been confirmed to agree. The content type is\n * always the SNIFFED image type, passed explicitly — never `sendFile`'s\n * extension-derived guess, which is exactly what let a JPEG named `.html`\n * out as `text/html` before this existed.\n */\nasync function sendOriginalInline(response: Response, absolutePath: string, contentType: string) {\n  return response.sendBuffer(await fs.readFile(absolutePath), {\n    contentType,\n    cacheTime: ONE_YEAR,\n    immutable: true,\n  });\n}\n\n/**\n * Serves local uploads, and bounded on-demand variants of the images among them.\n *\n * ```ts\n * router.get(\"/uploads/*\", uploadedFileController);\n * ```\n *\n * - `GET /uploads/<path>` sends the original file with a one-year cache.\n * - `GET /uploads/<path>?variant=<name>[&format=webp|avif]` sends a derivative\n *   rendered from a variant named in `uploads.images.variants`. No other query\n *   key is accepted, so a client can never ask for an arbitrary size.\n *\n * The path must stay inside the storage root (after symlinks are resolved) and\n * outside the variant cache; anything else is a 404, the same answer a missing\n * file gets. Derivatives are cached on disk under a sha256 of the source path,\n * size, mtime, variant and format, written atomically, generated once per key\n * even under concurrent requests, and sent with an immutable cache and an ETag.\n */\nexport const uploadedFileController: RequestHandler = async ({ request, response }) => {\n  const storageRoot = storage.root();\n\n  if (!storageRoot || storageRoot === \".\") {\n    log.error(\n      \"uploads\",\n      \"serve\",\n      \"uploadedFileController needs a local storage driver with a root.\",\n    );\n\n    return notFound(response);\n  }\n\n  const query = parseUploadedFileQuery(request.url);\n\n  if (query.type === \"invalid\") {\n    return response.badRequest({ error: query.reason });\n  }\n\n  // Every uploads response — originals and variants — tells the browser not\n  // to guess a content type from the bytes, so a mislabeled body can never be\n  // sniffed into something executable.\n  response.header(\"X-Content-Type-Options\", \"nosniff\");\n\n  if (query.type === \"original\") {\n    const images = uploadsConfig(\"images\");\n    const cacheDirectory = images?.cacheDirectory ? [images.cacheDirectory] : [];\n    const source = await resolveUploadPath(request.params[\"*\"], storageRoot, [\n      storage.root(\".cache/image-variants\"),\n      ...cacheDirectory,\n    ]);\n\n    if (!source) return notFound(response);\n\n    // Inline is decided by SNIFFED bytes, never by extension: an svg (or any\n    // other non-raster file) named `.png` must still download, not render.\n    const head = await readFileHead(source.absolutePath, IMAGE_SIGNATURE_BYTES);\n    const sniffedFormat = detectImageFormat(head);\n\n    if (!isVariantSourceFormat(sniffedFormat)) {\n      return sendOriginalAsAttachment(response, source.absolutePath);\n    }\n\n    // Inline is only safe when the extension-derived type agrees with the\n    // sniffed bytes too — otherwise `sendFile` would advertise the\n    // extension's type (e.g. text/html for JPEG bytes named `.html`).\n    const inlineContentType = resolveInlineImageContentType(source.absolutePath, sniffedFormat);\n\n    if (!inlineContentType) {\n      return sendOriginalAsAttachment(response, source.absolutePath);\n    }\n\n    return sendOriginalInline(response, source.absolutePath, inlineContentType);\n  }\n\n  const images = resolveImageVariantsConfig(uploadsConfig(\"images\"), storageRoot);\n\n  if (!images) {\n    return response.badRequest({ error: \"Image variants are not configured.\" });\n  }\n\n  if (!Object.prototype.hasOwnProperty.call(images.variants, query.variant)) {\n    return response.badRequest({ error: `Unknown variant \"${query.variant}\".` });\n  }\n\n  const requestedFormat = query.format as VariantOutputFormat | undefined;\n\n  if (requestedFormat !== undefined && !images.formats.includes(requestedFormat as never)) {\n    return response.badRequest({ error: `Format \"${query.format}\" is not allowed.` });\n  }\n\n  const variant = images.variants[query.variant];\n  if (variant === undefined) {\n    return response.badRequest({ error: `Unknown variant \"${query.variant}\".` });\n  }\n\n  let source: ResolvedUploadPath | undefined;\n\n  try {\n    const candidate = await resolveVariantCandidate(request.params[\"*\"], storageRoot, images);\n\n    if (!candidate) return notFound(response);\n\n    const resolvedSource = candidate.source;\n\n    source = resolvedSource;\n\n    const { stats, sourceFormat } = candidate;\n    const format: VariantOutputFormat = requestedFormat ?? sourceFormat;\n    const hash = variantCacheKey({\n      relativePath: resolvedSource.relativePath,\n      sourceSize: stats.size,\n      sourceMtimeMs: stats.mtimeMs,\n      variant,\n      format,\n    });\n    const target = variantCachePath(images.cacheDirectory, hash, format);\n\n    if (await exists(target)) {\n      if (matchesIfNoneMatch(request.header(\"if-none-match\"), `\"${hash}\"`)) {\n        return response.baseResponse.status(304).send();\n      }\n\n      return sendVariant(response, target, hash, format);\n    }\n\n    await variantGenerations.run(hash, async () => {\n      if (await exists(target)) return;\n\n      const image = await loadVariantSource(resolvedSource.absolutePath, {\n        maxSourceBytes: images.maxSourceBytes,\n        maxSourcePixels: images.maxSourcePixels,\n        expectedFormat: sourceFormat,\n      });\n\n      await generateImageVariant({ image, variant, format, targetPath: target });\n    });\n\n    return sendVariant(response, target, hash, format);\n  } catch (error) {\n    if (error instanceof HttpError) {\n      return response.send({ error: error.message }, error.status);\n    }\n\n    log.error(\n      \"uploads\",\n      \"variant\",\n      `Could not generate variant \"${query.variant}\" of ${source?.relativePath ?? request.params[\"*\"]}: ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n    );\n\n    return response.serverError({ error: \"Could not generate the image variant.\" });\n  }\n};\n"],"mappings":"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"}

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

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+//#region ../core/src/http/uploads/variant-cache-key.ts
+/**
+* JSON of the variant with its keys sorted, so key order in the app config
+* never changes the hash
+*/
+function normalizedVariantJson(variant) {
+	const sorted = Object.fromEntries(Object.entries(variant).filter(([, value]) => value !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+	return JSON.stringify(sorted);
+}
+/**
+* The sha256 cache key of a derivative.
+*
+* The source size and mtime are part of the key, so rewriting the source moves
+* every request to a new key and a fresh derivative. The parts are hashed as a
+* JSON array, so no two different inputs can concatenate to the same string.
+*/
+function variantCacheKey(input) {
+	const material = JSON.stringify([
+		input.relativePath,
+		input.sourceSize,
+		input.sourceMtimeMs,
+		normalizedVariantJson(input.variant),
+		input.format
+	]);
+	return createHash("sha256").update(material).digest("hex");
+}
+/**
+* File extension of a derivative
+*/
+function variantExtension(format) {
+	return format === "jpeg" ? "jpg" : format;
+}
+/**
+* Where a derivative lives: `<cacheDirectory>/<first 2 hex>/<hash>.<ext>`
+*/
+function variantCachePath(cacheDirectory, hash, format) {
+	return path.join(cacheDirectory, hash.slice(0, 2), `${hash}.${variantExtension(format)}`);
+}
+
+//#endregion
+export { variantCacheKey, variantCachePath };
+//# sourceMappingURL=variant-cache-key.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"variant-cache-key.mjs","names":[],"sources":["../../../../../../../../core/src/http/uploads/variant-cache-key.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport path from \"node:path\";\nimport type { ImageVariantDefinition } from \"../uploads-types\";\nimport type { VariantOutputFormat } from \"./image-variant-types\";\n\n/**\n * Everything a derivative depends on\n */\nexport type VariantCacheKeyInput = {\n  relativePath: string;\n  sourceSize: number;\n  sourceMtimeMs: number;\n  variant: ImageVariantDefinition;\n  format: VariantOutputFormat;\n};\n\n/**\n * JSON of the variant with its keys sorted, so key order in the app config\n * never changes the hash\n */\nfunction normalizedVariantJson(variant: ImageVariantDefinition): string {\n  const sorted = Object.fromEntries(\n    Object.entries(variant)\n      .filter(([, value]) => value !== undefined)\n      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),\n  );\n\n  return JSON.stringify(sorted);\n}\n\n/**\n * The sha256 cache key of a derivative.\n *\n * The source size and mtime are part of the key, so rewriting the source moves\n * every request to a new key and a fresh derivative. The parts are hashed as a\n * JSON array, so no two different inputs can concatenate to the same string.\n */\nexport function variantCacheKey(input: VariantCacheKeyInput): string {\n  const material = JSON.stringify([\n    input.relativePath,\n    input.sourceSize,\n    input.sourceMtimeMs,\n    normalizedVariantJson(input.variant),\n    input.format,\n  ]);\n\n  return createHash(\"sha256\").update(material).digest(\"hex\");\n}\n\n/**\n * File extension of a derivative\n */\nexport function variantExtension(format: VariantOutputFormat): string {\n  return format === \"jpeg\" ? \"jpg\" : format;\n}\n\n/**\n * Where a derivative lives: `<cacheDirectory>/<first 2 hex>/<hash>.<ext>`\n */\nexport function variantCachePath(\n  cacheDirectory: string,\n  hash: string,\n  format: VariantOutputFormat,\n): string {\n  return path.join(cacheDirectory, hash.slice(0, 2), `${hash}.${variantExtension(format)}`);\n}\n"],"mappings":";;;;;;;;AAoBA,SAAS,sBAAsB,SAAyC;CACtE,MAAM,SAAS,OAAO,YACpB,OAAO,QAAQ,OAAO,CAAC,CACpB,QAAQ,GAAG,WAAW,UAAU,MAAS,CAAC,CAC1C,MAAM,CAAC,IAAI,CAAC,OAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAE,CACpD;CAEA,OAAO,KAAK,UAAU,MAAM;AAC9B;;;;;;;;AASA,SAAgB,gBAAgB,OAAqC;CACnE,MAAM,WAAW,KAAK,UAAU;EAC9B,MAAM;EACN,MAAM;EACN,MAAM;EACN,sBAAsB,MAAM,OAAO;EACnC,MAAM;CACR,CAAC;CAED,OAAO,WAAW,QAAQ,CAAC,CAAC,OAAO,QAAQ,CAAC,CAAC,OAAO,KAAK;AAC3D;;;;AAKA,SAAgB,iBAAiB,QAAqC;CACpE,OAAO,WAAW,SAAS,QAAQ;AACrC;;;;AAKA,SAAgB,iBACd,gBACA,MACA,QACQ;CACR,OAAO,KAAK,KAAK,gBAAgB,KAAK,MAAM,GAAG,CAAC,GAAG,GAAG,KAAK,GAAG,iBAAiB,MAAM,GAAG;AAC1F"}

package/esm/http/uploads/variant-generations.mjs

@@ -0,0 +1,16 @@
+import { SingleFlight } from "./single-flight.mjs";
+
+//#region ../core/src/http/uploads/variant-generations.ts
+/**
+* Shared in-process single-flight for derivative generation.
+*
+* Both `uploadedFileController` and `generateImageVariants` run generations
+* through this one instance, so concurrent misses for the same cache key —
+* whether they arrive from the on-demand route or from an ingest call —
+* render the derivative once.
+*/
+const variantGenerations = new SingleFlight();
+
+//#endregion
+export { variantGenerations };
+//# sourceMappingURL=variant-generations.mjs.map

package/esm/http/uploads/variant-generations.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"variant-generations.mjs","names":[],"sources":["../../../../../../../../core/src/http/uploads/variant-generations.ts"],"sourcesContent":["import { SingleFlight } from \"./single-flight\";\n\n/**\n * Shared in-process single-flight for derivative generation.\n *\n * Both `uploadedFileController` and `generateImageVariants` run generations\n * through this one instance, so concurrent misses for the same cache key —\n * whether they arrive from the on-demand route or from an ingest call —\n * render the derivative once.\n */\nexport const variantGenerations = new SingleFlight<void>();\n"],"mappings":";;;;;;;;;;;AAUA,MAAa,qBAAqB,IAAI,aAAmB"}