@zudojs/http 1.0.0 → 1.2.0

package/dist/httpMiddleware/builtin/cors/httpMiddleware.cors.d.ts

@@ -24,5 +24,13 @@ export interface CorsMiddlewareOptions {
      */
     readonly optionsSuccessStatus?: number;
 }
+/**
+ * Creates the CORS middleware.
+ *
+ * @throws {ConfigurationError} At construction when a wildcard origin
+ *   (including the default `"*"`) is combined with `credentials: true`.
+ *   This used to be accepted and then fail every cross-origin request with a
+ *   500, which tests that send no `Origin` never noticed.
+ */
 export declare function createCorsMiddleware(options?: CorsMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.cors.d.ts.map

package/dist/httpMiddleware/builtin/cors/httpMiddleware.cors.js

@@ -3,6 +3,7 @@
  *
  * @module httpMiddleware/builtin/cors
  */
+import { isOriginAllowed } from "@zudojs/security";
 import { applyHeadersToResponse } from "../helpers/index.js";
 function getRequestHeader(context, name) {
     const headers = context.request.headers;
@@ -13,30 +14,23 @@ function getRequestMethod(context) {
     return (context.request.method ?? "GET").toUpperCase();
 }
 /**
- * Decides whether an origin is allowed.
- *
- * The previous implementation ignored the request origin entirely and wrote
- * `Access-Control-Allow-Origin: *` on every response, so the documented
- * "reflect the origin" pattern allowed every origin on the internet.
+ * The `@zudojs/security` CORS configuration for this middleware's origin
+ * policy. `allowOrigin` defaults to `"*"`; a predicate is bound to the
+ * request context because `@zudojs/security` predicates take the origin only.
  */
-function resolveAllowedOrigin(origin, context, options) {
+function toSecurityCorsConfig(options, context) {
     const configured = options.allowOrigin ?? "*";
-    if (typeof configured === "function") {
-        return configured(origin, context) ? origin : undefined;
-    }
-    const list = typeof configured === "string" ? [configured] : configured;
-    if (list.includes("*")) {
-        if (options.credentials) {
-            /*
-             * A wildcard origin with credentials is forbidden by the spec, and
-             * reflecting the request origin instead would authorise every origin
-             * to read authenticated responses.
-             */
-            throw new TypeError("CORS: a wildcard allowOrigin cannot be combined with credentials.");
-        }
-        return "*";
-    }
-    return list.includes(origin) ? origin : undefined;
+    const origin = typeof configured === "function"
+        ? (value) => context !== undefined && configured(value, context)
+        : configured;
+    return { origin, credentials: options.credentials === true };
+}
+/**
+ * Decides whether an origin is allowed, delegating to `@zudojs/security`'s
+ * `isOriginAllowed` so origin matching has one implementation.
+ */
+function resolveAllowedOrigin(origin, context, options) {
+    return isOriginAllowed(origin, toSecurityCorsConfig(options, context));
 }
 function appendVary(headers, value) {
     const existing = headers.get("vary");
@@ -51,7 +45,16 @@ function appendVary(headers, value) {
         headers.set("vary", `${existing}, ${value}`);
     }
 }
+/**
+ * Creates the CORS middleware.
+ *
+ * @throws {ConfigurationError} At construction when a wildcard origin
+ *   (including the default `"*"`) is combined with `credentials: true`.
+ *   This used to be accepted and then fail every cross-origin request with a
+ *   500, which tests that send no `Origin` never noticed.
+ */
 export function createCorsMiddleware(options = {}) {
+    isOriginAllowed(undefined, toSecurityCorsConfig(options));
     return async (context, next) => {
         const origin = getRequestHeader(context, "origin");
         /*

package/dist/httpMiddleware/builtin/helpers/httpMiddleware.accessor.js

@@ -3,6 +3,7 @@
  *
  * @module httpMiddleware/builtin/helpers/accessors
  */
+import { getCanonicalPath } from "../../../httpRequest/target/httpRequest.target.js";
 export function getRequestMethod(request) {
     const value = request.method;
     return value ?? "GET";
@@ -32,12 +33,7 @@ export function getContextSignal(request) {
     return value;
 }
 export function extractPathname(value) {
-    try {
-        return new URL(value, "http://zudojs.local").pathname;
-    }
-    catch {
-        return value.split("?")[0] ?? value;
-    }
+    return getCanonicalPath(value);
 }
 export function performanceNow() {
     if (typeof performance !== "undefined" &&

package/dist/httpMiddleware/builtin/helpers/httpMiddleware.media.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared helpers for the media (image / video) compression middleware.
+ *
+ * Both middleware used to read the stale `context.response` instead of the
+ * response `next()` returned, so a handler that returned a fresh response
+ * context (the documented style) was never compressed. These helpers read
+ * everything from the returned response.
+ *
+ * @module httpMiddleware/builtin/helpers/media
+ */
+import type { HttpResponseContext as ResponseContext } from "../../../httpResponse/httpResponse.context.js";
+/**
+ * Reports a compression failure. The uncompressed response is still served.
+ */
+export type MediaCompressionErrorHandler = (error: unknown, response: ResponseContext) => void;
+/**
+ * The media type of a response (`image/png; q=1` → `image/png`), lowercased.
+ */
+export declare function getResponseMediaType(response: ResponseContext): string | undefined;
+/**
+ * The response body as a Buffer, or `undefined` for a body that is not held
+ * in memory (streams, JSON values).
+ */
+export declare function getResponseBytes(response: ResponseContext): Buffer | undefined;
+/**
+ * Loads an optional peer module's callable default export.
+ */
+export declare function loadOptionalModule<T>(specifier: string, install: string): Promise<T>;
+/**
+ * Replaces the body and content type of a compressed response.
+ */
+export declare function applyCompressedBody(response: ResponseContext, body: Buffer, contentType: string): ResponseContext;
+//# sourceMappingURL=httpMiddleware.media.d.ts.map

package/dist/httpMiddleware/builtin/helpers/httpMiddleware.media.js

@@ -0,0 +1,59 @@
+/**
+ * Shared helpers for the media (image / video) compression middleware.
+ *
+ * Both middleware used to read the stale `context.response` instead of the
+ * response `next()` returned, so a handler that returned a fresh response
+ * context (the documented style) was never compressed. These helpers read
+ * everything from the returned response.
+ *
+ * @module httpMiddleware/builtin/helpers/media
+ */
+/**
+ * The media type of a response (`image/png; q=1` → `image/png`), lowercased.
+ */
+export function getResponseMediaType(response) {
+    const raw = response.headers["content-type"];
+    if (typeof raw !== "string") {
+        return undefined;
+    }
+    const mediaType = raw.split(";", 1)[0]?.trim().toLowerCase();
+    return mediaType ? mediaType : undefined;
+}
+/**
+ * The response body as a Buffer, or `undefined` for a body that is not held
+ * in memory (streams, JSON values).
+ */
+export function getResponseBytes(response) {
+    const body = response.body;
+    if (Buffer.isBuffer(body)) {
+        return body;
+    }
+    if (body instanceof Uint8Array) {
+        return Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+    }
+    return undefined;
+}
+/**
+ * Loads an optional peer module's callable default export.
+ */
+export async function loadOptionalModule(specifier, install) {
+    try {
+        const mod = (await import(specifier));
+        return (mod.default ?? mod);
+    }
+    catch {
+        throw new Error(`${specifier} is not installed. Run: ${install}`);
+    }
+}
+/**
+ * Replaces the body and content type of a compressed response.
+ */
+export function applyCompressedBody(response, body, contentType) {
+    response.setHeader("content-type", contentType);
+    if (response.headers["cache-control"] === undefined) {
+        response.setHeader("cache-control", "public, max-age=86400");
+    }
+    response.removeHeader("content-length");
+    return response.setBody(body);
+}
+//# sourceMappingURL=httpMiddleware.media.js.map

package/dist/httpMiddleware/builtin/helpers/index.d.ts

@@ -6,4 +6,5 @@
 export * from "./httpMiddleware.contextHelper.js";
 export * from "./httpMiddleware.accessor.js";
 export * from "./httpMiddleware.response.js";
+export * from "./httpMiddleware.media.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpMiddleware/builtin/helpers/index.js

@@ -6,4 +6,5 @@
 export * from "./httpMiddleware.contextHelper.js";
 export * from "./httpMiddleware.accessor.js";
 export * from "./httpMiddleware.response.js";
+export * from "./httpMiddleware.media.js";
 //# sourceMappingURL=index.js.map

package/dist/httpMiddleware/builtin/image/httpMiddleware.image.d.ts

@@ -6,6 +6,7 @@
  * Requires: npm install sharp
  */
 import type { HttpMiddleware } from "../../httpMiddleware.type.js";
+import { type MediaCompressionErrorHandler } from "../helpers/index.js";
 export interface ImageCompressionOptions {
     readonly quality?: number;
     readonly format?: "jpeg" | "png" | "webp" | "avif";
@@ -17,10 +18,22 @@ export interface ImageCompressionMiddlewareOptions {
     readonly enabled?: boolean;
     readonly defaultQuality?: number;
     readonly defaultFormat?: "jpeg" | "png" | "webp" | "avif";
+    /** Upper bound on the output width; applied to every image. */
     readonly maxWidth?: number;
+    /** Upper bound on the output height; applied to every image. */
     readonly maxHeight?: number;
     readonly contentTypeMap?: Record<string, ImageCompressionOptions>;
+    /**
+     * Called when compression fails. The original response is still served.
+     * Defaults to a no-op.
+     */
+    readonly onError?: MediaCompressionErrorHandler;
 }
 export declare function compressImage(buffer: Buffer, options?: ImageCompressionOptions): Promise<Buffer>;
+/**
+ * Compresses `image/*` responses. Status, headers and body are read from the
+ * response returned by `next()`, and `maxWidth` / `maxHeight` cap every
+ * output.
+ */
 export declare function createImageCompressionMiddleware(options?: ImageCompressionMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.image.d.ts.map

package/dist/httpMiddleware/builtin/image/httpMiddleware.image.js

@@ -5,23 +5,14 @@
  *
  * Requires: npm install sharp
  */
-import { applyHeadersToResponse } from "../helpers/index.js";
+import { applyCompressedBody, getResponseBytes, getResponseMediaType, loadOptionalModule, } from "../helpers/index.js";
 const DEFAULT_QUALITY = 80;
 const DEFAULT_FORMAT = "jpeg";
-async function getSharp() {
-    try {
-        const mod = await import("sharp");
-        return mod.default ?? mod;
-    }
-    catch {
-        throw new Error("Sharp is not installed. Run: npm install sharp");
-    }
-}
 export async function compressImage(buffer, options = {}) {
-    const sharpInstance = await getSharp();
+    const sharp = await loadOptionalModule("sharp", "npm install sharp");
     const quality = options.quality ?? DEFAULT_QUALITY;
     const format = options.format ?? DEFAULT_FORMAT;
-    let pipeline = sharpInstance(buffer);
+    let pipeline = sharp(buffer);
     if (options.width || options.height) {
         pipeline = pipeline.resize({
             width: options.width,
@@ -30,59 +21,46 @@ export async function compressImage(buffer, options = {}) {
             withoutEnlargement: true,
         });
     }
-    switch (format) {
-        case "jpeg":
-            return pipeline.jpeg({ quality }).toBuffer();
-        case "png":
-            return pipeline.png({ quality }).toBuffer();
-        case "webp":
-            return pipeline.webp({ quality }).toBuffer();
-        case "avif":
-            return pipeline.avif({ quality }).toBuffer();
-        default:
-            return pipeline.toBuffer();
+    return pipeline[format]({ quality }).toBuffer();
+}
+function capDimension(requested, max) {
+    if (max === undefined) {
+        return requested;
     }
+    return requested === undefined ? max : Math.min(requested, max);
 }
+/**
+ * Compresses `image/*` responses. Status, headers and body are read from the
+ * response returned by `next()`, and `maxWidth` / `maxHeight` cap every
+ * output.
+ */
 export function createImageCompressionMiddleware(options = {}) {
     const enabled = options.enabled ?? true;
-    const defaultQuality = options.defaultQuality ?? DEFAULT_QUALITY;
-    const defaultFormat = options.defaultFormat ?? DEFAULT_FORMAT;
     const contentTypeMap = options.contentTypeMap ?? {};
-    return async (context, next) => {
-        if (!enabled) {
-            return next();
-        }
+    return async (_context, next) => {
         const response = await next();
-        const contentType = context.response.headers["content-type"];
-        if (!contentType || !contentType.startsWith("image/")) {
+        const mediaType = getResponseMediaType(response);
+        if (!enabled || !mediaType?.startsWith("image/")) {
             return response;
         }
-        const body = context.response.body;
-        if (!Buffer.isBuffer(body) && typeof body !== "string") {
+        const buffer = getResponseBytes(response);
+        if (!buffer || buffer.length === 0) {
             return response;
         }
-        const buffer = Buffer.isBuffer(body) ? body : Buffer.from(body);
-        const compressionOptions = contentTypeMap[contentType] ?? {
-            quality: defaultQuality,
-            format: defaultFormat,
-        };
+        const mapped = contentTypeMap[mediaType] ?? {};
+        const format = mapped.format ?? options.defaultFormat ?? DEFAULT_FORMAT;
         try {
-            const compressed = await compressImage(buffer, compressionOptions);
-            const newContentType = compressionOptions.format === "jpeg"
-                ? "image/jpeg"
-                : compressionOptions.format === "png"
-                    ? "image/png"
-                    : compressionOptions.format === "webp"
-                        ? "image/webp"
-                        : compressionOptions.format === "avif"
-                            ? "image/avif"
-                            : contentType;
-            const headers = new Headers(response.headers);
-            headers.set("content-type", newContentType);
-            headers.set("cache-control", headers.get("cache-control") ?? "public, max-age=86400");
-            return applyHeadersToResponse(response, headers).setBody(compressed);
+            const compressed = await compressImage(buffer, {
+                ...mapped,
+                quality: mapped.quality ?? options.defaultQuality ?? DEFAULT_QUALITY,
+                format,
+                width: capDimension(mapped.width, options.maxWidth),
+                height: capDimension(mapped.height, options.maxHeight),
+            });
+            return applyCompressedBody(response, compressed, `image/${format}`);
         }
-        catch {
+        catch (error) {
+            options.onError?.(error, response);
             return response;
         }
     };

package/dist/httpMiddleware/builtin/index.d.ts

@@ -13,6 +13,7 @@ export * from "./helpers/index.js";
 export * from "./static/index.js";
 export * from "./image/index.js";
 export * from "./video/index.js";
+export * from "./rateLimit/index.js";
 /** State middleware — identity pass-through. */
 export declare function createStateMiddleware(): import("../httpMiddleware.type.js").HttpMiddleware;
 //# sourceMappingURL=index.d.ts.map

package/dist/httpMiddleware/builtin/index.js

@@ -13,6 +13,7 @@ export * from "./helpers/index.js";
 export * from "./static/index.js";
 export * from "./image/index.js";
 export * from "./video/index.js";
+export * from "./rateLimit/index.js";
 /** State middleware — identity pass-through. */
 export function createStateMiddleware() {
     return async (_context, next) => {

package/dist/httpMiddleware/builtin/rateLimit/httpMiddleware.rateLimit.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Rate limiting middleware built on `@zudojs/security`.
+ *
+ * AGENTS.md requires public endpoints to be rate limited with
+ * `createRateLimiter` from `@zudojs/security`, and `@zudojs/http` offered no
+ * way to do that. This wraps the shared limiter; it does not re-implement it.
+ *
+ * The client key is `request.remoteAddress`, which the Node adapter has
+ * already resolved through its `trustProxy` setting, so forwarded headers
+ * only count when the adapter trusts the peer that sent them.
+ *
+ * A request with no usable client address (a Unix-socket peer, a context
+ * built without `remoteAddress`, a destroyed socket) is counted in one
+ * shared bucket, {@link UNKNOWN_CLIENT_RATE_LIMIT_IP}. The `@zudojs/security`
+ * default key generator refuses such a request with a `ConfigurationError`,
+ * which would otherwise surface as a 500, and skipping the limiter for it
+ * would give it unlimited requests.
+ *
+ * @module httpMiddleware/builtin/rateLimit
+ */
+import { createRateLimiter, type RateLimiterOptions } from "@zudojs/security";
+import type { HttpMiddleware } from "../../httpMiddleware.type.js";
+/**
+ * The `ip` given to the limiter for a request whose `remoteAddress` is
+ * missing or is not an IP address. `0.0.0.0` is never a real peer address,
+ * so these requests share one bucket without colliding with a client.
+ */
+export declare const UNKNOWN_CLIENT_RATE_LIMIT_IP = "0.0.0.0";
+/**
+ * The limiter instance returned by `@zudojs/security`'s `createRateLimiter`.
+ */
+export type HttpRateLimiter = ReturnType<typeof createRateLimiter>;
+/**
+ * Options for {@link createRateLimitMiddleware}: either the
+ * `@zudojs/security` limiter options, or an existing `limiter` to share
+ * between routes.
+ */
+export type RateLimitMiddlewareOptions = RateLimiterOptions | {
+    readonly limiter: HttpRateLimiter;
+};
+/**
+ * Creates middleware that answers `429 Too Many Requests` (with
+ * `Retry-After`, from the `@zudojs/security` handler) once a client exceeds
+ * its allowance, and otherwise passes the request on.
+ */
+export declare function createRateLimitMiddleware(options: RateLimitMiddlewareOptions): HttpMiddleware;
+//# sourceMappingURL=httpMiddleware.rateLimit.d.ts.map

package/dist/httpMiddleware/builtin/rateLimit/httpMiddleware.rateLimit.js

@@ -0,0 +1,61 @@
+/**
+ * Rate limiting middleware built on `@zudojs/security`.
+ *
+ * AGENTS.md requires public endpoints to be rate limited with
+ * `createRateLimiter` from `@zudojs/security`, and `@zudojs/http` offered no
+ * way to do that. This wraps the shared limiter; it does not re-implement it.
+ *
+ * The client key is `request.remoteAddress`, which the Node adapter has
+ * already resolved through its `trustProxy` setting, so forwarded headers
+ * only count when the adapter trusts the peer that sent them.
+ *
+ * A request with no usable client address (a Unix-socket peer, a context
+ * built without `remoteAddress`, a destroyed socket) is counted in one
+ * shared bucket, {@link UNKNOWN_CLIENT_RATE_LIMIT_IP}. The `@zudojs/security`
+ * default key generator refuses such a request with a `ConfigurationError`,
+ * which would otherwise surface as a 500, and skipping the limiter for it
+ * would give it unlimited requests.
+ *
+ * @module httpMiddleware/builtin/rateLimit
+ */
+import { createRateLimiter, parseClientIp, } from "@zudojs/security";
+import { createResponseContext } from "../../../httpResponse/httpResponse.context.js";
+/**
+ * The `ip` given to the limiter for a request whose `remoteAddress` is
+ * missing or is not an IP address. `0.0.0.0` is never a real peer address,
+ * so these requests share one bucket without colliding with a client.
+ */
+export const UNKNOWN_CLIENT_RATE_LIMIT_IP = "0.0.0.0";
+/**
+ * Creates middleware that answers `429 Too Many Requests` (with
+ * `Retry-After`, from the `@zudojs/security` handler) once a client exceeds
+ * its allowance, and otherwise passes the request on.
+ */
+export function createRateLimitMiddleware(options) {
+    const limiter = "limiter" in options ? options.limiter : createRateLimiter(options);
+    return async (context, next) => {
+        const request = context.request;
+        const limitRequest = {
+            ip: clientIpOf(request.remoteAddress),
+            method: request.method,
+            path: request.path,
+            headers: request.headers,
+        };
+        const rejection = { statusCode: 429, headers: {} };
+        if (limiter.middleware(limitRequest, rejection).allowed) {
+            return next();
+        }
+        const response = createResponseContext().setStatus(rejection.statusCode);
+        for (const [name, value] of Object.entries(rejection.headers)) {
+            response.setHeader(name.toLowerCase(), value);
+        }
+        return response.setBody(rejection.body ?? "Too Many Requests");
+    };
+}
+function clientIpOf(remoteAddress) {
+    return typeof remoteAddress === "string" &&
+        parseClientIp(remoteAddress) !== undefined
+        ? remoteAddress
+        : UNKNOWN_CLIENT_RATE_LIMIT_IP;
+}
+//# sourceMappingURL=httpMiddleware.rateLimit.js.map

package/dist/httpMiddleware/builtin/rateLimit/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @zudojs/http/httpMiddleware/builtin/rateLimit
+ *
+ * Rate limiting middleware wrapping `@zudojs/security`'s `createRateLimiter`.
+ */
+export { createRateLimitMiddleware, UNKNOWN_CLIENT_RATE_LIMIT_IP, type HttpRateLimiter, type RateLimitMiddlewareOptions, } from "./httpMiddleware.rateLimit.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpMiddleware/builtin/rateLimit/index.js

@@ -0,0 +1,7 @@
+/**
+ * @zudojs/http/httpMiddleware/builtin/rateLimit
+ *
+ * Rate limiting middleware wrapping `@zudojs/security`'s `createRateLimiter`.
+ */
+export { createRateLimitMiddleware, UNKNOWN_CLIENT_RATE_LIMIT_IP, } from "./httpMiddleware.rateLimit.js";
+//# sourceMappingURL=index.js.map

package/dist/httpMiddleware/builtin/static/httpMiddleware.static.js

@@ -7,6 +7,8 @@ import { readFile, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { extname, join, resolve, sep } from "node:path";
 import { applyHeadersToResponse } from "../helpers/index.js";
+import { parseRequestTarget } from "../../../httpRequest/target/httpRequest.target.js";
+import { evaluateConditionalRequest } from "../../../httpConditional/httpConditional.core.js";
 const DEFAULT_INDEX = "index.html";
 const DEFAULT_MAX_AGE = 3600;
 const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
@@ -133,7 +135,19 @@ export function createStaticMiddleware(options) {
         if (method !== undefined && method !== "GET" && method !== "HEAD") {
             return next();
         }
-        const url = new URL(context.request.url);
+        /*
+         * `context.request.url` is the request-target as the adapter received
+         * it — `/pub/app.js`, not an absolute URL — so it must be parsed against
+         * a base. `new URL(url)` alone threw `Invalid URL` for every request the
+         * Node adapter delivered, and the middleware answered 500 to all of them.
+         */
+        let url;
+        try {
+            url = parseRequestTarget(context.request.url);
+        }
+        catch {
+            return next();
+        }
         const decodedPathname = decodePathname(url.pathname);
         if (decodedPathname === undefined) {
             return next();
@@ -188,9 +202,21 @@ export function createStaticMiddleware(options) {
          * returns the whole body and has no 206 path, so advertising range
          * support makes range-aware clients misbehave.
          */
-        const ifNoneMatch = context.request.headers["if-none-match"];
-        if (ifNoneMatch === etag) {
-            return applyHeadersToResponse(context.response, responseHeaders).setStatus(304);
+        /*
+         * RFC 9110 section 13.2.2 evaluation: `If-None-Match` lists, weak tags
+         * and `*`, then `If-Modified-Since`, plus `If-Match` /
+         * `If-Unmodified-Since` (412). An exact string compare missed all of
+         * those and re-sent the whole file.
+         */
+        const headers = context.request.headers;
+        const conditional = evaluateConditionalRequest(context.request.method, {
+            ifMatch: headers["if-match"],
+            ifNoneMatch: headers["if-none-match"],
+            ifModifiedSince: headers["if-modified-since"],
+            ifUnmodifiedSince: headers["if-unmodified-since"],
+        }, { etag, lastModified });
+        if (conditional.statusCode !== undefined) {
+            return applyHeadersToResponse(context.response, responseHeaders).setStatus(conditional.statusCode);
         }
         return applyHeadersToResponse(context.response, responseHeaders).setBody(fileData);
     };

package/dist/httpMiddleware/builtin/video/httpMiddleware.video.d.ts

@@ -3,14 +3,17 @@
  *
  * @module httpMiddleware/builtin/video
  *
- * Requires: npm install fluent-ffmpeg
+ * Requires: npm install fluent-ffmpeg (and an ffmpeg binary)
  */
 import type { HttpMiddleware } from "../../httpMiddleware.type.js";
+import { type MediaCompressionErrorHandler } from "../helpers/index.js";
 export interface VideoCompressionOptions {
     readonly bitrate?: string;
     readonly preset?: "ultrafast" | "superfast" | "veryfast" | "faster" | "fast" | "medium" | "slow" | "slower" | "veryslow";
     readonly crf?: number;
     readonly format?: "mp4" | "webm" | "mov";
+    /** Input container; defaults to `mp4`. */
+    readonly inputFormat?: string;
     readonly scale?: {
         readonly width?: number;
         readonly height?: number;
@@ -20,7 +23,22 @@ export interface VideoCompressionMiddlewareOptions {
     readonly enabled?: boolean;
     readonly contentTypeMap?: Record<string, VideoCompressionOptions>;
     readonly tempDir?: string;
+    /**
+     * Called when compression fails. The original response is still served.
+     */
+    readonly onError?: MediaCompressionErrorHandler;
 }
+/**
+ * Transcodes a video held in memory.
+ *
+ * `fluent-ffmpeg`'s export is a factory: `input()` exists only on the
+ * command it returns. Calling it on the module (as this did) threw
+ * `ffmpegInstance.input is not a function` on every call.
+ */
 export declare function compressVideo(inputBuffer: Buffer, options?: VideoCompressionOptions): Promise<Buffer>;
+/**
+ * Compresses `video/*` responses, reading status, headers and body from the
+ * response returned by `next()`.
+ */
 export declare function createVideoCompressionMiddleware(options?: VideoCompressionMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.video.d.ts.map