image-renditions 0.2.0 → 0.3.0

package/README.md

@@ -8,10 +8,10 @@ Resize and re-encode uploaded images when a page first shows them, store each re
 
 ```html
 <img
-  src="/_renditions/v1/avatar.faf7e221f65dd97945e352a57e805252.avif/avatars/42.jpg"
+  src="/_renditions/v1/avatar.faf7e221f65d.avif/avatars/42.jpg"
   srcset="
-    /_renditions/v1/avatar.faf7e221f65dd97945e352a57e805252.avif/avatars/42.jpg    1x,
-    /_renditions/v1/avatar@2x.b62b90cf6c3ed57e4c1c27da0c36d778.avif/avatars/42.jpg 2x
+    /_renditions/v1/avatar.faf7e221f65d.avif/avatars/42.jpg    1x,
+    /_renditions/v1/avatar@2x.b62b90cf6c3e.avif/avatars/42.jpg 2x
   "
   alt=""
 />
@@ -23,7 +23,13 @@ Resize and re-encode uploaded images when a page first shows them, store each re
 
 With an S3 bucket, or a directory that outlives deploys and is shared by every replica, app servers keep no image files: renditions survive redeploys, and any replica serves any of them.
 
-The h3 handler supports h3 1.15 or newer and h3 2, and the Nuxt module requires Nuxt 4.
+The library is modular, with pluggable parts:
+
+- [HTTP](#h3-and-other-frameworks): an event handler for h3 1.15 or newer and h3 2, and a framework-neutral handler for other servers.
+- [Processing](#processing): a processor built on sharp.
+- [Storage](#storage): an S3 bucket or a file system directory, chosen separately for uploads and renditions.
+- [Nuxt](#quick-start): a Nuxt 4 module that registers the handler and the `<RenditionImg>` component.
+- [Extending](#extending): other storage, image libraries, and state shared between replicas plug in through the interfaces of `image-renditions/server`.
 
 ## When not to use it
 
@@ -232,7 +238,7 @@ export default defineRenditionEventHandler({
 - Map different scopes to different keys even for equal paths.
 - A rendition is stored in the result store at `<sourceKey>/<hash>.<extension>`.
   To keep renditions in the bucket of uploads, also return a `resultPrefix` that no source key starts with, such as `` `renditions/${sourceKey}` ``, to use instead of `sourceKey`.
-- S3 limits a key to 1024 bytes in UTF-8, and a rendition key adds up to 38 bytes to its result prefix.
+- S3 limits a key to 1024 bytes in UTF-8, and the library writes a rendition under a key up to 18 bytes longer than its result prefix.
   If source keys can come that close to the limit, return a shorter `resultPrefix`, or their renditions fail as `invalid-request`.
 
 Derive the context from the URL only, host included, for example from the tenant's domain: browsers and CDNs cache the redirect to a rendition by its URL for a day.
@@ -443,7 +449,7 @@ Build URLs in the app with the catalog, which is safe to import in browsers:
 
 ```ts
 catalog.url("avatar", { path: "avatars/42.jpg" })
-// /_renditions/v1/avatar.faf7e221f65dd97945e352a57e805252.avif/avatars/42.jpg
+// /_renditions/v1/avatar.faf7e221f65d.avif/avatars/42.jpg
 
 catalog.srcset("avatar", { scope: "tenant", path: "avatars/42.jpg" })
 ```

package/dist/h3.d.mts

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

package/dist/h3.mjs

@@ -1,4 +1,4 @@
-import { t as createRenditionHandler } from "./handler-CPJllrYi.mjs";
+import { t as createRenditionHandler } from "./handler-D5toFJ55.mjs";
 import { defineEventHandler } from "h3";
 //#region src/h3.ts
 /**

package/dist/{handler-CPJllrYi.mjs → handler-D5toFJ55.mjs}

@@ -1,5 +1,5 @@
-import { a as parseRenditionPath } from "./url-BAU5GYXC.mjs";
 import { r as toDeclaredTarget } from "./scopes-C1kzqQHz.mjs";
+import { i as parseRenditionPath } from "./url-C6PtYIEf.mjs";
 import { t as RenditionError } from "./error-DViVpVmH.mjs";
 //#region src/server/handler.ts
 const failureStatus = {

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

@@ -1,6 +1,6 @@
 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-BVH3ZB0F.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";
 //#region src/server/error.d.ts

package/dist/hash-CHipV1N6.mjs

@@ -0,0 +1,16 @@
+import { o as serializeRecipe } from "./recipe-BavgOq0b.mjs";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
+//#region src/hash.ts
+/**
+* Length of a recipe hash in hex digits, which keeps 48 bits of SHA-256.
+*
+* It tells apart the few thousand recipes an application may have over its lifetime, and a catalog rejects a collision among its own recipes.
+*/
+const RECIPE_HASH_LENGTH = 12;
+/** Identifies a recipe by the truncated SHA-256 of its canonical serialization. */
+function hashRecipe(recipe) {
+	return bytesToHex(sha256(utf8ToBytes(serializeRecipe(recipe)))).slice(0, RECIPE_HASH_LENGTH);
+}
+//#endregion
+export { hashRecipe as t };

package/dist/index.d.mts

@@ -1,9 +1,7 @@
 import { a as RenditionAnimation, c as RenditionOptions, d as formatContentTypes, f as formatExtensions, i as RecipeInput, l as RenditionPosition, m as serializeRecipe, n as RECIPE_ENGINE_VERSION, o as RenditionFit, p as normalizeRecipe, r as Recipe, s as RenditionFormat, t as MAX_DIMENSION, u as SourcePolicy } from "./recipe-BT8D60Qb.mjs";
 import { a as RenditionTarget, c as defineCatalog, i as PresetName, n as CatalogDefinition, o as RenditionVariant, r as PresetDefinition, s as ScopeName, t as Catalog } from "./catalog-D11xkViN.mjs";
-import { a as formatRenditionPath, i as assertBasePath, n as RenditionAddress, o as parseRenditionPath, r as URL_FORMAT_VERSION, t as DEFAULT_BASE_PATH } from "./url-BVH3ZB0F.mjs";
+import { i as parseRenditionPath, n as RenditionAddress, r as formatRenditionPath, t as DEFAULT_BASE_PATH } from "./url-DoJdUx9J.mjs";
 //#region src/hash.d.ts
-/** Length of a recipe hash in hex digits, which keeps 128 bits of SHA-256. */
-export declare const RECIPE_HASH_LENGTH = 32;
 /** Identifies a recipe by the truncated SHA-256 of its canonical serialization. */
 export declare function hashRecipe(recipe: Recipe): string;
 //#endregion
@@ -20,4 +18,4 @@ export declare function encodePath(path: string): string;
 /** Checks that a scope is a short token that needs no URL encoding. */
 export declare function isSafeScope(scope: string): boolean;
 //#endregion
-export { Catalog, CatalogDefinition, DEFAULT_BASE_PATH, MAX_DIMENSION, PresetDefinition, PresetName, RECIPE_ENGINE_VERSION, Recipe, RecipeInput, RenditionAddress, RenditionAnimation, RenditionFit, RenditionFormat, RenditionOptions, RenditionPosition, RenditionTarget, RenditionVariant, ScopeName, SourcePolicy, URL_FORMAT_VERSION, assertBasePath, defineCatalog, formatContentTypes, formatExtensions, formatRenditionPath, normalizeRecipe, parseRenditionPath, serializeRecipe };
+export { Catalog, CatalogDefinition, DEFAULT_BASE_PATH, MAX_DIMENSION, PresetDefinition, PresetName, RECIPE_ENGINE_VERSION, Recipe, RecipeInput, type RenditionAddress, RenditionAnimation, RenditionFit, RenditionFormat, RenditionOptions, RenditionPosition, RenditionTarget, RenditionVariant, ScopeName, SourcePolicy, defineCatalog, formatContentTypes, formatExtensions, formatRenditionPath, normalizeRecipe, parseRenditionPath, serializeRecipe };

package/dist/index.mjs

@@ -1,7 +1,8 @@
 import { a as normalizeRecipe, i as formatExtensions, n as RECIPE_ENGINE_VERSION, o as serializeRecipe, r as formatContentTypes, t as MAX_DIMENSION } from "./recipe-BavgOq0b.mjs";
-import { a as parseRenditionPath, i as formatRenditionPath, n as URL_FORMAT_VERSION, o as RECIPE_HASH_LENGTH, r as assertBasePath, s as hashRecipe, t as DEFAULT_BASE_PATH } from "./url-BAU5GYXC.mjs";
+import { t as hashRecipe } from "./hash-CHipV1N6.mjs";
 import { n as isSafePath, r as isSafeScope, t as encodePath } from "./path-hNFUjCbA.mjs";
 import { t as assertDeclaredScope } from "./scopes-C1kzqQHz.mjs";
+import { i as parseRenditionPath, n as assertBasePath, r as formatRenditionPath, t as DEFAULT_BASE_PATH } from "./url-C6PtYIEf.mjs";
 //#region src/catalog.ts
 /** Extensions of sources that get animated variants, as a path does not tell an animated source from a still one. */
 const ANIMATED_EXTENSIONS = ["gif", "webp"];
@@ -64,7 +65,11 @@ function defineCatalog(definition) {
 			originals: Object.freeze([...originals]),
 			animatedVariants
 		});
-		for (const variant of [...variants, ...animatedVariants ?? []]) if (!variantsByHash.has(variant.hash)) variantsByHash.set(variant.hash, variant);
+		for (const variant of [...variants, ...animatedVariants ?? []]) {
+			const known = variantsByHash.get(variant.hash);
+			if (known && serializeRecipe(known.recipe) !== serializeRecipe(variant.recipe)) throw new RangeError(`Variants "${known.label}" and "${variant.label}" have different recipes of the same hash; change pipelineVersion to change every hash.`);
+			if (!known) variantsByHash.set(variant.hash, variant);
+		}
 	}
 	function getPreset(preset) {
 		const found = presetsByName.get(preset);
@@ -120,4 +125,4 @@ function wrapRangeError(context, fn) {
 	}
 }
 //#endregion
-export { DEFAULT_BASE_PATH, MAX_DIMENSION, RECIPE_ENGINE_VERSION, RECIPE_HASH_LENGTH, URL_FORMAT_VERSION, assertBasePath, defineCatalog, encodePath, formatContentTypes, formatExtensions, formatRenditionPath, hashRecipe, isSafePath, isSafeScope, normalizeRecipe, parseRenditionPath, serializeRecipe };
+export { DEFAULT_BASE_PATH, MAX_DIMENSION, RECIPE_ENGINE_VERSION, defineCatalog, encodePath, formatContentTypes, formatExtensions, formatRenditionPath, hashRecipe, isSafePath, isSafeScope, normalizeRecipe, parseRenditionPath, serializeRecipe };

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-9XP5SZhg.mjs";
+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 { 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 };

package/dist/server.mjs

@@ -1,9 +1,9 @@
 import { i as formatExtensions, s as assertInteger } from "./recipe-BavgOq0b.mjs";
-import { s as hashRecipe } from "./url-BAU5GYXC.mjs";
+import { t as hashRecipe } from "./hash-CHipV1N6.mjs";
 import { n as isSafePath } from "./path-hNFUjCbA.mjs";
 import { n as isDeclaredScope } from "./scopes-C1kzqQHz.mjs";
 import { t as RenditionError } from "./error-DViVpVmH.mjs";
-import { t as createRenditionHandler } from "./handler-CPJllrYi.mjs";
+import { t as createRenditionHandler } from "./handler-D5toFJ55.mjs";
 //#region src/server/coordinator.ts
 /** Creates a coordinator that merges concurrent equal requests within the process. */
 function createLocalCoordinator() {

package/dist/{url-BAU5GYXC.mjs → url-C6PtYIEf.mjs}

@@ -1,15 +1,5 @@
-import { i as formatExtensions, o as serializeRecipe } from "./recipe-BavgOq0b.mjs";
+import { i as formatExtensions } from "./recipe-BavgOq0b.mjs";
 import { n as isSafePath, r as isSafeScope, t as encodePath } from "./path-hNFUjCbA.mjs";
-import { sha256 } from "@noble/hashes/sha2.js";
-import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
-//#region src/hash.ts
-/** Length of a recipe hash in hex digits, which keeps 128 bits of SHA-256. */
-const RECIPE_HASH_LENGTH = 32;
-/** Identifies a recipe by the truncated SHA-256 of its canonical serialization. */
-function hashRecipe(recipe) {
-	return bytesToHex(sha256(utf8ToBytes(serializeRecipe(recipe)))).slice(0, 32);
-}
-//#endregion
 //#region src/url.ts
 /** Version segment of the rendition URL format this library builds and parses. */
 const URL_FORMAT_VERSION = "v1";
@@ -26,7 +16,8 @@ function formatRenditionPath(basePath, { scope, label, hash, format, path }) {
 	const extension = formatExtensions[format];
 	if (!isSafeLabel(label) || !isHash(hash) || !extension) throw new RangeError(`Invalid rendition variant "${label}.${hash}.${extension ?? format}".`);
 	if (!isSafePath(path)) throw new RangeError(`Unsafe rendition source path "${path}".`);
-	return `${basePath}/v1/${scope === void 0 ? "" : `${scope}/`}${label}.${hash}.${extension}/${encodePath(path)}`;
+	const scopePrefix = scope === void 0 ? "" : `${scope}/`;
+	return `${basePath}/${URL_FORMAT_VERSION}/${scopePrefix}${label}.${hash}.${extension}/${encodePath(path)}`;
 }
 /**
 * Parses the path of a rendition URL, ignoring any query string.
@@ -34,7 +25,7 @@ function formatRenditionPath(basePath, { scope, label, hash, format, path }) {
 * Returns `undefined` for a path outside `basePath`, another URL format version, or malformed or unsafe parts.
 */
 function parseRenditionPath(basePath, url) {
-	const prefix = `${basePath}/v1/`;
+	const prefix = `${basePath}/${URL_FORMAT_VERSION}/`;
 	const pathname = url.split("?", 1)[0];
 	if (!pathname.startsWith(prefix)) return;
 	const parts = pathname.slice(prefix.length).split("/");
@@ -67,8 +58,13 @@ const formats = Object.keys(formatExtensions);
 function isSafeLabel(label) {
 	return /^[\w@.-]{1,64}$/.test(label);
 }
+/**
+* Checks that a recipe hash is 1 to 64 ASCII letters, digits, `_` or `-`, which need no encoding in a URL or a storage key.
+*
+* The grammar does not fix the format of hashes, so a hash the catalog cannot produce is looked up as a published rendition instead of making the URL malformed.
+*/
 function isHash(hash) {
-	return hash.length === 32 && /^[\da-f]+$/.test(hash);
+	return /^[\w-]{1,64}$/.test(hash);
 }
 function decodeSegment(segment) {
 	try {
@@ -78,4 +74,4 @@ function decodeSegment(segment) {
 	}
 }
 //#endregion
-export { parseRenditionPath as a, formatRenditionPath as i, URL_FORMAT_VERSION as n, RECIPE_HASH_LENGTH as o, assertBasePath as r, hashRecipe as s, DEFAULT_BASE_PATH as t };
+export { parseRenditionPath as i, assertBasePath as n, formatRenditionPath as r, DEFAULT_BASE_PATH as t };

package/dist/{url-BVH3ZB0F.d.mts → url-DoJdUx9J.d.mts}

@@ -1,7 +1,5 @@
 import { s as RenditionFormat } from "./recipe-BT8D60Qb.mjs";
 //#region src/url.d.ts
-/** Version segment of the rendition URL format this library builds and parses. */
-declare const URL_FORMAT_VERSION = "v1";
 /** Mount path of the rendition handler unless a catalog sets another one. */
 declare const DEFAULT_BASE_PATH = "/_renditions";
 /** Parts of a rendition URL. */
@@ -28,11 +26,5 @@ declare function formatRenditionPath(basePath: string, { scope, label, hash, for
  * Returns `undefined` for a path outside `basePath`, another URL format version, or malformed or unsafe parts.
  */
 declare function parseRenditionPath(basePath: string, url: string): RenditionAddress | undefined;
-/**
- * Checks that a base path is absolute, has no trailing slash and needs no URL encoding.
- *
- * @throws {RangeError} When the base path is invalid.
- */
-declare function assertBasePath(basePath: string): void;
 //#endregion
-export { formatRenditionPath as a, assertBasePath as i, RenditionAddress as n, parseRenditionPath as o, URL_FORMAT_VERSION as r, DEFAULT_BASE_PATH as t };
+export { parseRenditionPath as i, RenditionAddress as n, formatRenditionPath as r, DEFAULT_BASE_PATH as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-renditions",
-  "version": "0.2.0",
+  "version": "0.3.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",