@db3.ai/app 0.1.0-beta.1

package/src/media/image/ImageVariantRenderer.ts

@@ -0,0 +1,386 @@
+import { randomUUID } from 'node:crypto';
+import { pipeline } from 'node:stream/promises';
+
+import type { Storage, StorageDisk, StorageEntry } from '../../storage';
+import { normalizeStoragePath } from '../../storage/path';
+import type { ImageProcessor, ImageVariant, ImageVariantCacheOptions, ImageVariantOptions } from './contracts';
+import { MAX_IMAGE_VARIANT_WIDTH } from './contracts';
+import type { MediaFile } from '../MediaFile';
+import { SharpImageProcessor } from './processors/SharpImageProcessor';
+
+const IMAGE_VARIANT_CACHE_VERSION = 'v1';
+const DEFAULT_IMAGE_VARIANT_CACHE_PREFIX = 'image-cache';
+const IMAGE_VARIANT_OUTPUT_MIME_TYPE = 'image/webp';
+const MAX_CONCURRENT_IMAGE_RENDERS = 2;
+const PASSTHROUGH_IMAGE_MIME_TYPES = new Set([
+	'image/gif',
+	'image/svg+xml',
+]);
+const SUPPORTED_IMAGE_MIME_TYPES = new Set([
+	'image/avif',
+	'image/jpeg',
+	'image/png',
+	'image/webp',
+]);
+
+/**
+ * Renders responsive variants of managed images into disposable storage.
+ */
+export class ImageVariantRenderer {
+	#activeRenders = 0;
+	readonly #cacheDiskName: string | null;
+	readonly #cachePrefix: string;
+	readonly #pendingRenders = new Map<string, Promise<void>>();
+	readonly #renderWaiters: Array<() => void> = [];
+
+	/**
+	 * Creates an image renderer backed by application storage.
+	 *
+	 * @param storage - Storage service used to read source bytes and cache variants.
+	 * @param options - Disposable cache disk and directory configuration.
+	 * @param processor - Image processing engine used for cache misses.
+	 */
+	constructor(
+		private readonly storage: Storage,
+		options: ImageVariantCacheOptions = {},
+		private readonly processor: ImageProcessor = new SharpImageProcessor(),
+	) {
+		this.#cacheDiskName = optionalNonEmptyString(
+			options.cacheDisk,
+			'Image variant cache disk',
+		);
+		this.#cachePrefix = normalizeStoragePath(
+			options.cachePrefix ?? DEFAULT_IMAGE_VARIANT_CACHE_PREFIX,
+		);
+	}
+
+	/**
+	 * Returns a width-constrained image, using the disposable cache when available.
+	 *
+	 * SVG and animated GIF sources are returned unchanged because they either
+	 * scale natively or must preserve animation. Raster variants emit compressed
+	 * WebP while preserving aspect ratio and orientation without enlargement.
+	 * Failed renders settle source and cache streams before removing partial files.
+	 *
+	 * @param file - Managed source image.
+	 * @param options - Variant dimensions that form the cache identity.
+	 * @returns Rendered or cached image variant.
+	 *
+	 * @example
+	 * const image = await app.media.renderImage(file, {
+	 * 	width: 640,
+	 * });
+	 */
+	async render(file: MediaFile, options: ImageVariantOptions): Promise<ImageVariant> {
+		const width = imageVariantWidth(options.width);
+		const sourceMimeType = normalizedImageMimeType(file.mimeType);
+		const sourceDiskName = requiredMediaFileValue(file.disk, 'Managed image disk is required.');
+		const sourcePath = requiredMediaFileValue(file.path, 'Managed image path is required.');
+		const sourceDisk = this.storage.disk(sourceDiskName);
+
+		if (PASSTHROUGH_IMAGE_MIME_TYPES.has(sourceMimeType)) {
+			return {
+				stream: await sourceDisk.readStream(sourcePath),
+				mimeType: sourceMimeType,
+				path: null,
+				cached: false,
+			};
+		}
+
+		if (!SUPPORTED_IMAGE_MIME_TYPES.has(sourceMimeType)) {
+			throw new Error(`Managed media type "${sourceMimeType}" cannot be rendered as a responsive image.`);
+		}
+
+		const mimeType = IMAGE_VARIANT_OUTPUT_MIME_TYPE;
+		const fileId = requiredMediaFileValue(file.id, 'Managed image id is required.');
+		const cacheDiskName = this.#cacheDiskName ?? sourceDiskName;
+		const cacheDisk = this.storage.disk(cacheDiskName);
+		const path = imageVariantPath(this.#cachePrefix, fileId, width, mimeType);
+
+		if (await cacheDisk.exists(path)) {
+			return {
+				stream: await cacheDisk.readStream(path),
+				mimeType,
+				path,
+				cached: true,
+			};
+		}
+
+		let cached = false;
+		const renderKey = `${cacheDiskName}:${path}`;
+		const pendingRender = this.#pendingRenders.get(renderKey);
+
+		if (pendingRender) {
+			await pendingRender;
+			cached = true;
+		} else {
+			const render = this.#withRenderSlot(async () => {
+				if (await cacheDisk.exists(path)) {
+					cached = true;
+					return;
+				}
+
+				const source = await sourceDisk.readStream(sourcePath);
+				const renderer = this.processor.transform({
+					sourceMimeType,
+					outputMimeType: mimeType,
+					width,
+				});
+				const temporaryPath = `${path}.tmp-${randomUUID()}`;
+				const processing = pipeline(source, renderer);
+				const writing = cacheDisk.writeStream(temporaryPath, renderer, {
+					mimeType,
+					visibility: 'private',
+				});
+
+				try {
+					await Promise.all([processing, writing]);
+					await cacheDisk.move(temporaryPath, path);
+				} catch (error) {
+					// Stop both streams and finish storage work before removing partial bytes.
+					source.destroy();
+					renderer.destroy();
+					await Promise.allSettled([processing, writing]);
+					await deleteVariantQuietly(cacheDisk, temporaryPath);
+					throw error;
+				}
+			});
+
+			this.#pendingRenders.set(renderKey, render);
+
+			try {
+				await render;
+			} finally {
+				if (this.#pendingRenders.get(renderKey) === render) {
+					this.#pendingRenders.delete(renderKey);
+				}
+			}
+		}
+
+		return {
+			stream: await cacheDisk.readStream(path),
+			mimeType,
+			path,
+			cached,
+		};
+	}
+
+	/**
+	 * Deletes every disposable responsive variant derived from a managed image.
+	 *
+	 * @param file - Managed source image whose cached variants should be removed.
+	 * @returns Number of cached variant files deleted from storage.
+	 */
+	async deleteCachedVariants(file: MediaFile): Promise<number> {
+		const fileId = requiredMediaFileValue(file.id, 'Managed image id is required.');
+		const sourceDiskName = requiredMediaFileValue(file.disk, 'Managed image disk is required.');
+			const cacheDiskName = this.#cacheDiskName ?? sourceDiskName;
+			const cacheDisk = this.storage.disk(cacheDiskName);
+			const path = imageVariantDirectoryPath(this.#cachePrefix, fileId);
+			let entries: StorageEntry[];
+
+			try {
+				entries = await cacheDisk.list(path, {
+					deep: true,
+				}).toArray(false);
+			} catch (error) {
+				if (isMissingStorageDirectory(error)) return 0;
+
+				throw error;
+			}
+			let deleted = 0;
+
+		for (const entry of entries) {
+			if (!entry.isFile) continue;
+
+			if (await cacheDisk.delete(entry.path)) {
+				deleted += 1;
+			}
+		}
+
+		return deleted;
+	}
+
+	/**
+	 * Runs one cache-generating render within the per-process concurrency bound.
+	 *
+	 * @param task - Render operation that writes one disposable cache entry.
+	 * @returns Task result after a render slot becomes available.
+	 */
+	async #withRenderSlot<TResult>(task: () => Promise<TResult>): Promise<TResult> {
+		if (this.#activeRenders >= MAX_CONCURRENT_IMAGE_RENDERS) {
+			await new Promise<void>(resolve => {
+				this.#renderWaiters.push(resolve);
+			});
+		} else {
+			this.#activeRenders += 1;
+		}
+
+		try {
+			return await task();
+		} finally {
+			const next = this.#renderWaiters.shift();
+
+			if (next) {
+				next();
+			} else {
+				this.#activeRenders -= 1;
+			}
+		}
+	}
+}
+
+/**
+ * Builds the disposable cache path for one image variant.
+ *
+ * @param cachePrefix - Relative cache directory on the configured disk.
+ * @param fileId - Immutable managed source-file ULID.
+ * @param width - Validated requested width, or null for original dimensions.
+ * @param mimeType - Normalized output MIME type.
+ * @returns Storage path beneath the disposable image-cache directory.
+ */
+function imageVariantPath(
+	cachePrefix: string,
+	fileId: string,
+	width: number | null,
+	mimeType: string,
+): string {
+	const extension = imageExtension(mimeType);
+	const variantName = width === null ? 'original' : `w-${width}`;
+
+	return normalizeStoragePath(
+		`${cachePrefix}/${IMAGE_VARIANT_CACHE_VERSION}/${fileId}/${variantName}.${extension}`,
+	);
+}
+
+/**
+ * Builds the storage directory containing every cached variant for one image.
+ *
+ * @param cachePrefix - Relative cache directory on the configured disk.
+ * @param fileId - Immutable managed source-file ULID.
+ * @returns Directory path containing all cached variants for the image.
+ */
+function imageVariantDirectoryPath(cachePrefix: string, fileId: string): string {
+	return normalizeStoragePath(
+		`${cachePrefix}/${IMAGE_VARIANT_CACHE_VERSION}/${fileId}`,
+	);
+}
+
+/**
+ * Returns whether a storage listing failed because its directory is absent.
+ *
+ * Flystorage wraps provider errors, so the native missing-path code can appear
+ * on any cause in the chain. Other listing failures remain visible to callers.
+ *
+ * @param error - Unknown storage listing failure.
+ * @returns True when an underlying provider reports a missing directory.
+ */
+function isMissingStorageDirectory(error: unknown): boolean {
+	let current = error;
+
+	while (current && typeof current === 'object') {
+		if ((current as { code?: unknown }).code === 'ENOENT') return true;
+
+		current = (current as { cause?: unknown }).cause;
+	}
+
+	return false;
+}
+
+/**
+ * Returns the conventional extension for a supported image MIME type.
+ *
+ * @param mimeType - Normalized image MIME type.
+ * @returns Filename extension without a leading dot.
+ */
+function imageExtension(mimeType: string): string {
+	switch (mimeType) {
+		case 'image/avif':
+			return 'avif';
+		case 'image/jpeg':
+			return 'jpg';
+		case 'image/png':
+			return 'png';
+		case 'image/webp':
+			return 'webp';
+		default:
+			throw new Error(`Unsupported responsive image MIME type "${mimeType}".`);
+	}
+}
+
+/**
+ * Validates one requested responsive image width.
+ *
+ * @param value - Optional requested pixel width.
+ * @returns Validated integer width, or null to preserve source dimensions.
+ */
+function imageVariantWidth(value: number | undefined): number | null {
+	if (value === undefined) return null;
+
+	if (!Number.isInteger(value) || value < 1 || value > MAX_IMAGE_VARIANT_WIDTH) {
+		throw new RangeError(`Image width must be an integer between 1 and ${MAX_IMAGE_VARIANT_WIDTH}.`);
+	}
+
+	return value;
+}
+
+/**
+ * Normalizes common image MIME aliases.
+ *
+ * @param value - MIME type recorded on the managed file.
+ * @returns Normalized lower-case MIME type.
+ */
+function normalizedImageMimeType(value: string | null): string {
+	const mimeType = String(value || '').trim().toLowerCase();
+
+	return mimeType === 'image/jpg' ? 'image/jpeg' : mimeType;
+}
+
+/**
+ * Requires a non-empty managed file field.
+ *
+ * @param value - Nullable model field value.
+ * @param message - Error message used when the field is empty.
+ * @returns Non-empty string value.
+ */
+function requiredMediaFileValue(value: string | null, message: string): string {
+	const normalized = String(value || '').trim();
+
+	if (!normalized) throw new Error(message);
+
+	return normalized;
+}
+
+/**
+ * Validates one optional configuration string.
+ *
+ * @param value - Optional string configuration.
+ * @param label - Human-readable configuration label.
+ * @returns Trimmed string, or null when the option is omitted.
+ */
+function optionalNonEmptyString(value: string | undefined, label: string): string | null {
+	if (value === undefined) return null;
+
+	const normalized = value.trim();
+
+	if (!normalized) {
+		throw new Error(`${label} must be a non-empty string.`);
+	}
+
+	return normalized;
+}
+
+/**
+ * Removes an incomplete variant without masking the render failure.
+ *
+ * @param disk - Storage disk containing the temporary variant.
+ * @param path - Temporary storage path to remove.
+ * @returns Promise that resolves after the best-effort cleanup.
+ */
+async function deleteVariantQuietly(disk: StorageDisk, path: string): Promise<void> {
+	try {
+		await disk.delete(path);
+	} catch {
+		// The original render or storage error is more actionable than cleanup failure.
+	}
+}

package/src/media/image/ImageVariantRequest.ts

@@ -0,0 +1,65 @@
+import type { ImageVariantOptions } from './contracts';
+import { MAX_IMAGE_VARIANT_WIDTH } from './contracts';
+
+/**
+ * Error raised when an untrusted image variant request cannot be translated
+ * into an allowlisted framework command.
+ */
+export class ImageVariantRequestError extends RangeError {
+	/**
+	 * Creates an invalid image request error.
+	 *
+	 * @param message - Safe explanation suitable for an HTTP error response.
+	 * @param code - Stable application error code for HTTP adapters.
+	 */
+	constructor(message: string, readonly code: 'invalid_image_width') {
+		super(message);
+		this.name = 'ImageVariantRequestError';
+	}
+}
+
+/**
+ * Translates URL query parameters into a safe image variant command.
+ *
+ * Only documented parameters are interpreted. Unknown parameters are ignored
+ * and no processor option is accepted directly from the request.
+ *
+ * @param searchParams - URL query parameters supplied by an HTTP adapter.
+ * @returns Validated variant options, or null when the original is requested.
+ *
+ * @example
+ * const options = imageVariantOptionsFromSearchParams(requestUrl.searchParams);
+ */
+export function imageVariantOptionsFromSearchParams(searchParams: URLSearchParams): ImageVariantOptions | null {
+	const requestedWidth = searchParams.get('w');
+
+	if (requestedWidth === null) {
+		return null;
+	}
+
+	if (!/^[1-9]\d*$/.test(requestedWidth)) {
+		throw invalidImageWidth();
+	}
+
+	const width = Number(requestedWidth);
+
+	if (!Number.isSafeInteger(width) || width > MAX_IMAGE_VARIANT_WIDTH) {
+		throw invalidImageWidth();
+	}
+
+	return {
+		width,
+	};
+}
+
+/**
+ * Creates the canonical invalid-width error.
+ *
+ * @returns Safe image request error.
+ */
+function invalidImageWidth(): ImageVariantRequestError {
+	return new ImageVariantRequestError(
+		`Image width must be an integer between 1 and ${MAX_IMAGE_VARIANT_WIDTH}.`,
+		'invalid_image_width',
+	);
+}

package/src/media/image/contracts/ImageProcessor.ts

@@ -0,0 +1,53 @@
+import type { Duplex } from 'node:stream';
+
+/**
+ * Allowlisted image transformation passed to a concrete processing engine.
+ */
+export interface ImageProcessorCommand {
+	/** Normalized MIME type of the encoded source stream. */
+	sourceMimeType: string;
+
+	/** Normalized MIME type the processor must emit. */
+	outputMimeType: string;
+
+	/** Maximum output width in pixels, or null to preserve source dimensions. */
+	width: number | null;
+}
+
+/**
+ * Canonical image reconstruction passed to a concrete processing engine.
+ *
+ * Reconstruction decodes the complete untrusted input and emits a new image
+ * without preserving source metadata or trailing source bytes.
+ */
+export interface ImageProcessorReconstructionCommand {
+	/** Normalized MIME type already identified from the encoded source stream. */
+	sourceMimeType: string;
+
+	/** Normalized MIME type the processor must use for the reconstructed image. */
+	outputMimeType: string;
+}
+
+/**
+ * Adapter implemented by a concrete image processing engine.
+ *
+ * The framework owns request parsing, cache identity, storage, and concurrency.
+ * Processors only translate a trusted command into a bounded transform stream.
+ */
+export interface ImageProcessor {
+	/**
+	 * Creates a stream that transforms encoded source bytes into an image variant.
+	 *
+	 * @param command - Validated transformation command.
+	 * @returns Duplex stream that accepts source bytes and emits encoded output.
+	 */
+	transform(command: ImageProcessorCommand): Duplex;
+
+	/**
+	 * Creates a stream that fully decodes and reconstructs an untrusted image.
+	 *
+	 * @param command - Validated canonical reconstruction command.
+	 * @returns Duplex stream that accepts source bytes and emits reconstructed bytes.
+	 */
+	reconstruct(command: ImageProcessorReconstructionCommand): Duplex;
+}

package/src/media/image/contracts/ImageVariant.ts

@@ -0,0 +1,37 @@
+import type { Readable } from 'node:stream';
+
+/**
+ * Maximum rendered image width accepted by the framework.
+ *
+ * Bounding width protects the application from accidental or malicious
+ * requests that would create excessively large decoded images.
+ */
+export const MAX_IMAGE_VARIANT_WIDTH = 4096;
+
+/**
+ * Options that identify one cached responsive image variant.
+ */
+export interface ImageVariantOptions {
+	/**
+	 * Requested pixel width. Aspect ratio is preserved and images are never
+	 * enlarged. Omit the width to compress the source at its original dimensions.
+	 */
+	width?: number;
+}
+
+/**
+ * Storage-backed responsive image returned by the media service.
+ */
+export interface ImageVariant {
+	/** Rendered image stream loaded from durable storage. */
+	stream: Readable;
+
+	/** MIME type of the rendered bytes. */
+	mimeType: string;
+
+	/** Storage path used on the configured disposable cache disk, or null for passthrough images. */
+	path: string | null;
+
+	/** Whether the bytes were loaded from an existing generated variant. */
+	cached: boolean;
+}

package/src/media/image/contracts/ImageVariantCacheOptions.ts

@@ -0,0 +1,21 @@
+/**
+ * Storage configuration for disposable responsive-image variants.
+ *
+ * Generated variants are derived from durable managed files and may be removed
+ * at any time. A missing variant is regenerated on the next image request.
+ */
+export interface ImageVariantCacheOptions {
+	/**
+	 * Named storage disk used for generated variants.
+	 *
+	 * Omit this value to use the managed source file's disk.
+	 */
+	cacheDisk?: string;
+
+	/**
+	 * Relative directory containing generated variants on the cache disk.
+	 *
+	 * Defaults to `image-cache`.
+	 */
+	cachePrefix?: string;
+}

package/src/media/image/contracts/index.ts

@@ -0,0 +1,3 @@
+export * from './ImageVariant';
+export * from './ImageVariantCacheOptions';
+export * from './ImageProcessor';

package/src/media/image/index.ts

@@ -0,0 +1,5 @@
+export * from './contracts';
+export * from './ImageReconstructionError';
+export * from './ImageVariantRenderer';
+export * from './ImageVariantRequest';
+export * from './processors';

package/src/media/image/processors/SharpImageProcessor.ts

@@ -0,0 +1,121 @@
+import sharp, { type Sharp } from 'sharp';
+import type { ImageProcessor, ImageProcessorCommand, ImageProcessorReconstructionCommand } from '../contracts';
+
+const IMAGE_VARIANT_INPUT_PIXEL_LIMIT = 40_000_000;
+const IMAGE_VARIANT_PROCESSING_TIMEOUT_SECONDS = 20;
+const CANONICAL_JPEG_QUALITY = 90;
+const CANONICAL_WEBP_QUALITY = 90;
+
+/**
+ * Sharp/libvips image processor used by the framework's default media service.
+ */
+export class SharpImageProcessor implements ImageProcessor {
+	/**
+	 * Creates a bounded Sharp transform for one validated framework command.
+	 *
+	 * @param command - Trusted image transformation command.
+	 * @returns Sharp duplex stream for encoded source and output bytes.
+	 */
+	transform(command: ImageProcessorCommand): Sharp {
+		let image = this.#source(false);
+
+		if (command.width !== null) {
+			image = image.resize({
+				width: command.width,
+				withoutEnlargement: true,
+			});
+		}
+
+		switch (command.outputMimeType) {
+			case 'image/avif':
+				return image.avif({
+					quality: 50,
+				});
+			case 'image/jpeg':
+				return image.jpeg({
+					progressive: true,
+					quality: 82,
+				});
+			case 'image/png':
+				return image.png({
+					compressionLevel: 9,
+				});
+			case 'image/webp':
+				return image.webp({
+					quality: 82,
+				});
+			default:
+				throw new Error(`Sharp cannot encode responsive image MIME type "${command.outputMimeType}".`);
+		}
+	}
+
+	/**
+	 * Creates a bounded full-resolution reconstruction of untrusted image bytes.
+	 *
+	 * Reconstruction preserves animated GIF and WebP frames, applies source
+	 * orientation, and relies on Sharp's default metadata removal.
+	 *
+	 * @param command - Validated canonical reconstruction command.
+	 * @returns Sharp duplex stream for complete decoding and canonical encoding.
+	 */
+	reconstruct(command: ImageProcessorReconstructionCommand): Sharp {
+		const image = this.#source(isAnimatedImageMimeType(command.sourceMimeType));
+
+		switch (command.outputMimeType) {
+			case 'image/avif':
+				return image.avif({
+					quality: 65,
+				});
+			case 'image/gif':
+				return image.gif({
+					effort: 7,
+					interFrameMaxError: 0,
+				});
+			case 'image/jpeg':
+				return image.jpeg({
+					progressive: true,
+					quality: CANONICAL_JPEG_QUALITY,
+				});
+			case 'image/png':
+				return image.png({
+					compressionLevel: 9,
+				});
+			case 'image/webp':
+				return image.webp({
+					effort: 5,
+					quality: CANONICAL_WEBP_QUALITY,
+				});
+			default:
+				throw new Error(`Sharp cannot reconstruct image MIME type "${command.outputMimeType}".`);
+		}
+	}
+
+	/**
+	 * Creates one security-bounded Sharp input pipeline.
+	 *
+	 * @param animated - Whether all frames from a supported animated source are decoded.
+	 * @returns Sharp input stream with decode limits, orientation, and timeout configured.
+	 */
+	#source(animated: boolean): Sharp {
+		return sharp({
+			animated,
+			failOn: 'warning',
+			limitInputPixels: IMAGE_VARIANT_INPUT_PIXEL_LIMIT,
+			sequentialRead: true,
+		})
+			.autoOrient()
+			.timeout({
+				seconds: IMAGE_VARIANT_PROCESSING_TIMEOUT_SECONDS,
+			});
+	}
+}
+
+/**
+ * Returns whether reconstruction must decode every source animation frame.
+ *
+ * @param mimeType - Normalized source image MIME type.
+ * @returns True for supported animated container formats.
+ */
+function isAnimatedImageMimeType(mimeType: string): boolean {
+	return mimeType === 'image/gif' || mimeType === 'image/webp';
+}

package/src/media/image/processors/index.ts

@@ -0,0 +1 @@
+export * from './SharpImageProcessor';