image-renditions 0.3.0 → 0.4.0

package/README.md

@@ -409,6 +409,18 @@ It renders the first frame of other animated sources, such as APNG and animated
 An animation at the pixel limit may take about 4 bytes of memory per pixel, and its encoder needs more, so plan memory for `limits.concurrency` such renditions at once.
 Changing the limits keeps stored renditions as they are; bump `pipelineVersion` to render them again.
 
+When a preset keeps the animation and a GIF or WebP animation renders its first frame because of its EXIF orientation or a limit, `createRenditionServer()` passes it to `onDegradation` once the rendition is written.
+The reason is `animation-orientation`, `animation-frames` or `animation-pixels`, and the message has the values involved, so you can log such renditions and tune the limits:
+
+```ts
+const server = createRenditionServer({
+  // ...
+  onDegradation({ message, target }) {
+    console.warn(`The rendition of ${target.path} is degraded: ${message}`)
+  },
+})
+```
+
 To process images with another library, implement the [`Processor`](#extending) interface and pass your implementation to `createRenditionServer()` as `processor`.
 
 ## h3 and other frameworks
@@ -576,6 +588,7 @@ Implement an interface from `image-renditions/server` and pass your implementati
 - To use other storage, implement `SourceStore` or `ResultStore` and pass it as `source` or `results`.
 - To process images with another library, implement `Processor` and pass it as `processor`.
   Implement its `assertRecipe()` to reject recipes it cannot render, such as animations, when the server is created.
+  Return `degradation` from its `process()` to report an image that falls short of its recipe to `onDegradation`.
 - To share the index of published renditions between replicas, for example in Redis, implement `ReadinessIndex` and pass it as `readiness.shared`.
   If a call fails or exceeds `indexTimeout`, the server reports the error to `onError` and checks storage instead, while [outdated URLs](#outdated-urls) fail as `unknown-recipe`.
 - To render each rendition once across replicas, implement `Coordinator` as a shared lock and pass it as `coordinator`.

package/dist/h3.d.mts

@@ -1,4 +1,4 @@
-import { r as RenditionHandlerOptions } from "./handler-RAQFWtrg.mjs";
+import { r as RenditionHandlerOptions } from "./handler-P49xsp3S.mjs";
 import { EventHandler, H3Event } from "h3";
 //#region src/h3.d.ts
 /** Source of the application context of a request. */

package/dist/{handler-RAQFWtrg.d.mts → handler-P49xsp3S.d.mts}

@@ -2,7 +2,7 @@ import { r as Recipe, s as RenditionFormat } from "./recipe-BT8D60Qb.mjs";
 import { a as RenditionTarget, t as Catalog } from "./catalog-D11xkViN.mjs";
 import { n as RenditionAddress } from "./url-DoJdUx9J.mjs";
 import { i as StoreCallOptions, n as ResultStore, r as SourceStore } from "./stores-P-TUmax4.mjs";
-import { t as Processor } from "./processor-DvyPs-OZ.mjs";
+import { r as Processor, t as Degradation } from "./processor-Dd3jqaOW.mjs";
 //#region src/server/error.d.ts
 /** Why a rendition could not be served. */
 type RenditionFailureReason =
@@ -124,6 +124,21 @@ interface RenditionServerOptions<Context, Scope extends string = string> {
    * It is not awaited, and its own failures are ignored.
    */
   onError?(error: unknown): void;
+  /**
+   * Receives a degradation the processor reports for a rendition it rendered, such as the first frame of an animation beyond a limit, once the rendition is written.
+   *
+   * Later requests for the rendition do not report it again.
+   * It is not awaited, and its own failures are ignored.
+   */
+  onDegradation?(degradation: RenditionDegradation<Context, Scope>): void;
+}
+/** Degradation a processor reported for a rendition the server wrote. */
+interface RenditionDegradation<Context, Scope extends string = string> extends Degradation {
+  recipe: Recipe;
+  target: RenditionTarget<Scope>;
+  /** Context of the call that rendered the rendition, which may be any of the concurrent calls for it. */
+  context: Context;
+  rendition: Rendition;
 }
 /** Published rendition. */
 interface Rendition {
@@ -224,4 +239,4 @@ type RenditionHandler<Context> = (request: RenditionRequest, getContext: () => C
  */
 declare function createRenditionHandler<Context, Scope extends string = string>({ server, onFailure, redirectCacheControl }: RenditionHandlerOptions<Context, Scope>): RenditionHandler<Context>;
 //#endregion
-export { RenditionFailureReason as _, createRenditionHandler as a, RenditionServerOptions as c, MemoryReadinessIndexOptions as d, ReadinessIndex as f, RenditionError as g, createLocalCoordinator as h, RenditionRequest as i, SourceResolution as l, Coordinator as m, RenditionHandler as n, Rendition as o, createMemoryReadinessIndex as p, RenditionHandlerOptions as r, RenditionServer as s, RenditionFailure as t, createRenditionServer as u };
+export { RenditionError as _, createRenditionHandler as a, RenditionServer as c, createRenditionServer as d, MemoryReadinessIndexOptions as f, createLocalCoordinator as g, Coordinator as h, RenditionRequest as i, RenditionServerOptions as l, createMemoryReadinessIndex as m, RenditionHandler as n, Rendition as o, ReadinessIndex as p, RenditionHandlerOptions as r, RenditionDegradation as s, RenditionFailure as t, SourceResolution as u, RenditionFailureReason as v };

package/dist/{processor-DvyPs-OZ.d.mts → processor-Dd3jqaOW.d.mts}

@@ -1,6 +1,22 @@
 import { r as Recipe } from "./recipe-BT8D60Qb.mjs";
 import { t as EncodedImage } from "./stores-P-TUmax4.mjs";
 //#region src/server/processor.d.ts
+/** Shortfall of a rendered image against its recipe, which a processor reports. */
+interface Degradation {
+  /** Code of the shortfall, such as `animation-frames`. */
+  reason: string;
+  /** Human-readable description with the values involved, such as an exceeded limit. */
+  message: string;
+}
+/** Image a processor renders. */
+interface ProcessedImage extends EncodedImage {
+  /**
+   * Shortfall the processor detected, such as the first frame of an animation beyond a limit.
+   *
+   * Its absence does not promise that the image renders the recipe in full.
+   */
+  degradation?: Degradation;
+}
 /** Renders a source image according to a recipe. */
 interface Processor {
   /**
@@ -8,7 +24,7 @@ interface Processor {
    *
    * Rejects with a `RenditionError` of reason `unsupported-source` when the source cannot be decoded or processed, and of reason `source-too-large` when it exceeds a size limit.
    */
-  process(source: Uint8Array, recipe: Recipe): Promise<EncodedImage>;
+  process(source: Uint8Array, recipe: Recipe): Promise<ProcessedImage>;
   /**
    * Checks that the processor renders a recipe as it describes.
    *
@@ -19,4 +35,4 @@ interface Processor {
   assertRecipe?(recipe: Recipe): void;
 }
 //#endregion
-export { Processor as t };
+export { ProcessedImage as n, Processor as r, Degradation as t };

package/dist/server.d.mts

@@ -1,4 +1,4 @@
-import { _ as RenditionFailureReason, a as createRenditionHandler, c as RenditionServerOptions, d as MemoryReadinessIndexOptions, f as ReadinessIndex, g as RenditionError, h as createLocalCoordinator, i as RenditionRequest, l as SourceResolution, m as Coordinator, n as RenditionHandler, o as Rendition, p as createMemoryReadinessIndex, r as RenditionHandlerOptions, s as RenditionServer, t as RenditionFailure, u as createRenditionServer } from "./handler-RAQFWtrg.mjs";
+import { _ as RenditionError, a as createRenditionHandler, c as RenditionServer, d as createRenditionServer, f as MemoryReadinessIndexOptions, g as createLocalCoordinator, h as Coordinator, i as RenditionRequest, l as RenditionServerOptions, m as createMemoryReadinessIndex, n as RenditionHandler, o as Rendition, p as ReadinessIndex, r as RenditionHandlerOptions, s as RenditionDegradation, t as RenditionFailure, u as SourceResolution, v as RenditionFailureReason } from "./handler-P49xsp3S.mjs";
 import { i as StoreCallOptions, n as ResultStore, r as SourceStore, t as EncodedImage } from "./stores-P-TUmax4.mjs";
-import { t as Processor } from "./processor-DvyPs-OZ.mjs";
-export { Coordinator, EncodedImage, MemoryReadinessIndexOptions, Processor, ReadinessIndex, Rendition, RenditionError, RenditionFailure, RenditionFailureReason, RenditionHandler, RenditionHandlerOptions, RenditionRequest, RenditionServer, RenditionServerOptions, ResultStore, SourceResolution, SourceStore, StoreCallOptions, createLocalCoordinator, createMemoryReadinessIndex, createRenditionHandler, createRenditionServer };
+import { n as ProcessedImage, r as Processor, t as Degradation } from "./processor-Dd3jqaOW.mjs";
+export { Coordinator, Degradation, EncodedImage, MemoryReadinessIndexOptions, ProcessedImage, Processor, ReadinessIndex, Rendition, RenditionDegradation, RenditionError, RenditionFailure, RenditionFailureReason, RenditionHandler, RenditionHandlerOptions, RenditionRequest, RenditionServer, RenditionServerOptions, ResultStore, SourceResolution, SourceStore, StoreCallOptions, createLocalCoordinator, createMemoryReadinessIndex, createRenditionHandler, createRenditionServer };

package/dist/server.mjs

@@ -88,7 +88,7 @@ const MAX_TIMEOUT = 2 ** 31 - 1;
 * @throws {RangeError} When a limit is not an integer in its range, or the processor cannot render a variant of the catalog.
 */
 function createRenditionServer(options) {
-	const { catalog, source, results, processor, resolveSource = resolveUnscoped, onError } = options;
+	const { catalog, source, results, processor, resolveSource = resolveUnscoped, onError, onDegradation } = options;
 	const memory = createMemoryReadinessIndex(options.readiness?.memory);
 	const shared = options.readiness?.shared;
 	const coordinator = options.coordinator ?? createLocalCoordinator();
@@ -148,28 +148,26 @@ function createRenditionServer(options) {
 		try {
 			return await withTimeout(indexTimeout, call);
 		} catch (error) {
-			report(error);
+			notify(onError, error);
 			return;
 		}
 	}
-	/** Passes an error to `onError` without waiting for it, so a failing or hanging callback cannot affect the operation. */
-	function report(error) {
-		try {
-			Promise.resolve(onError?.(error)).catch(() => {});
-		} catch {}
-	}
 	function callStorage(reason, call) {
 		return withTimeout(storageTimeout, call).catch((error) => {
 			throw error instanceof RenditionError ? error : new RenditionError(reason, `Storage call failed: ${error}`, { cause: error });
 		});
 	}
 	async function render(recipe, sourceKey, key) {
-		const data = await callStorage("source-error", (signal) => source.read(sourceKey, { signal }));
-		if (!data) throw new RenditionError("source-not-found", `The source ${sourceKey} does not exist.`);
-		const image = await processor.process(data, recipe).catch((error) => {
+		const input = await callStorage("source-error", (signal) => source.read(sourceKey, { signal }));
+		if (!input) throw new RenditionError("source-not-found", `The source ${sourceKey} does not exist.`);
+		const { data, contentType, degradation } = await processor.process(input, recipe).catch((error) => {
 			throw error instanceof RenditionError ? error : new RenditionError("processing-failed", `Processing failed: ${error}`, { cause: error });
 		});
-		await callStorage("storage-error", (signal) => results.write(key, image, { signal }));
+		await callStorage("storage-error", (signal) => results.write(key, {
+			data,
+			contentType
+		}, { signal }));
+		return degradation;
 	}
 	return {
 		catalog,
@@ -180,7 +178,16 @@ function createRenditionServer(options) {
 			if (await isIndexed(rendition.url)) return rendition;
 			return coordinator.run(rendition.url, async () => {
 				if (!await isIndexed(rendition.url)) {
-					if (!await callStorage("storage-error", (signal) => results.exists(rendition.key, { signal }))) await limiter.run(() => render(recipe, sourceKey, rendition.key));
+					if (!await callStorage("storage-error", (signal) => results.exists(rendition.key, { signal }))) {
+						const degradation = await limiter.run(() => render(recipe, sourceKey, rendition.key));
+						if (degradation) notify(onDegradation, {
+							...degradation,
+							recipe,
+							target,
+							context,
+							rendition: { ...rendition }
+						});
+					}
 					await markPublished(rendition.url);
 				}
 				return rendition;
@@ -193,6 +200,12 @@ function createRenditionServer(options) {
 		resolve
 	};
 }
+/** Calls an optional callback without waiting for it, so a failing or hanging callback cannot affect the operation. */
+function notify(callback, value) {
+	try {
+		Promise.resolve(callback?.(value)).catch(() => {});
+	} catch {}
+}
 /**
 * Runs a call with an abort signal that fires after the timeout.
 *

package/dist/sharp.d.mts

@@ -1,4 +1,4 @@
-import { t as Processor } from "./processor-DvyPs-OZ.mjs";
+import { r as Processor } from "./processor-Dd3jqaOW.mjs";
 //#region src/processors/sharp/processor.d.ts
 /** Options of {@link createSharpProcessor}. */
 export interface SharpProcessorOptions {

package/dist/sharp.mjs

@@ -115,12 +115,13 @@ function createSharpProcessor({ maxInputPixels = 1e8, maxAnimationPixels = 5e7,
 		assertRecipe,
 		async process(source, recipe) {
 			assertRecipe(recipe);
-			const data = await render(source, recipe, maxInputPixels, limits).catch((error) => {
+			const { data, degradation } = await render(source, recipe, maxInputPixels, limits).catch((error) => {
 				throw error instanceof RenditionError ? error : new RenditionError("unsupported-source", "The source cannot be processed.", { cause: error });
 			});
 			return {
 				data: new Uint8Array(data),
-				contentType: formatContentTypes[recipe.format]
+				contentType: formatContentTypes[recipe.format],
+				degradation
 			};
 		}
 	};
@@ -150,7 +151,8 @@ async function render(source, recipe, maxInputPixels, limits) {
 		width = raster.width;
 		height = raster.height;
 	}
-	const frames = keepsAnimation(recipe, metadata, limits) ? {
+	const animation = planAnimation(recipe, metadata, limits);
+	const frames = animation.animated ? {
 		animated: true,
 		limitInputPixels: limits.maxAnimationPixels
 	} : { pages: 1 };
@@ -164,6 +166,12 @@ async function render(source, recipe, maxInputPixels, limits) {
 	if (resize) pipeline = pipeline.resize(resize);
 	if (recipe.format === "jpeg") pipeline = pipeline.flatten({ background: parseColor(recipe.background) });
 	pipeline = pipeline.toColourspace("srgb");
+	return {
+		data: await encode(pipeline, recipe),
+		degradation: animation.degradation
+	};
+}
+function encode(pipeline, recipe) {
 	switch (recipe.format) {
 		case "avif": return pipeline.avif({
 			quality: recipe.quality,
@@ -178,14 +186,26 @@ async function render(source, recipe, maxInputPixels, limits) {
 	}
 }
 /**
-* Whether a rendition keeps the animation of a source, judged by the metadata of its first frame.
+* Plans whether a rendition keeps the animation of a source, judged by the metadata of its first frame.
 *
 * Sharp resizes and crops the frames one by one, so the planned geometry of the first frame applies to every frame.
 */
-function keepsAnimation(recipe, { format, pages = 1, width, height, orientation = 1 }, { maxAnimationPixels, maxFrames }) {
-	if (recipe.animation !== "preserve" || format !== "gif" && format !== "webp" || pages < 2 || orientation !== 1) return false;
+function planAnimation(recipe, { format, pages = 1, width, height, orientation = 1 }, { maxAnimationPixels, maxFrames }) {
+	if (recipe.animation !== "preserve" || format !== "gif" && format !== "webp" || pages < 2) return { animated: false };
+	if (orientation !== 1) return degrade("animation-orientation", `Sharp cannot apply the EXIF orientation ${orientation} to the frames of an animation.`);
+	if (maxFrames > 0 && pages > maxFrames) return degrade("animation-frames", `The animation of ${pages} frames exceeds the frame limit of ${maxFrames}.`);
 	const pixels = Math.max(width * height, estimateRenditionArea(recipe, width, height)) * pages;
-	return (maxFrames === 0 || pages <= maxFrames) && (maxAnimationPixels === 0 || pixels <= maxAnimationPixels);
+	if (maxAnimationPixels > 0 && pixels > maxAnimationPixels) return degrade("animation-pixels", `The animation of ${pixels} pixels exceeds the animation pixel limit of ${maxAnimationPixels}.`);
+	return { animated: true };
+}
+function degrade(reason, message) {
+	return {
+		animated: false,
+		degradation: {
+			reason,
+			message
+		}
+	};
 }
 /**
 * Checks that sharp can keep an animation where a recipe asks for it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-renditions",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "On-demand image transformations that persist every result to durable storage and keep app servers stateless.",
   "homepage": "https://github.com/IlyaSemenov/image-renditions#readme",
   "bugs": "https://github.com/IlyaSemenov/image-renditions/issues",