@zudojs/http 0.1.0 → 1.0.0

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

@@ -0,0 +1,7 @@
+/**
+ * Logging middleware barrel.
+ *
+ * @module httpMiddleware/builtin/logging
+ */
+export { createLoggingMiddleware, } from "./httpMiddleware.logging.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,21 @@
+/**
+ * Security middleware factory.
+ *
+ * @module httpMiddleware/builtin/security
+ */
+import type { HttpMiddleware } from "../../httpMiddleware.type.js";
+export interface SecurityMiddlewareOptions {
+    readonly strictTransportSecurity?: string;
+    readonly xContentTypeOptions?: string;
+    readonly xFrameOptions?: string;
+    readonly xXssProtection?: string;
+    readonly contentSecurityPolicy?: string;
+    readonly referrerPolicy?: string;
+    /**
+     * Set to `false` to emit only the headers explicitly configured above.
+     * Defaults to `true`.
+     */
+    readonly useDefaults?: boolean;
+}
+export declare function createSecurityMiddleware(options?: SecurityMiddlewareOptions): HttpMiddleware;
+//# sourceMappingURL=httpMiddleware.security.d.ts.map

package/dist/httpMiddleware/builtin/security/httpMiddleware.security.js

@@ -0,0 +1,50 @@
+/**
+ * Security middleware factory.
+ *
+ * @module httpMiddleware/builtin/security
+ */
+import { isValidHeaderFieldValue } from "../../../httpHeaders/security/index.js";
+import { withResponseHeaders } from "../helpers/index.js";
+/**
+ * Headers applied when the caller does not override them.
+ *
+ * `createSecurityMiddleware()` previously defaulted every option to
+ * `undefined` and therefore set no headers at all — its presence in a
+ * codebase read as evidence that the control existed while shipping nothing.
+ */
+const DEFAULT_SECURITY_HEADERS = Object.freeze({
+    "x-content-type-options": "nosniff",
+    "x-frame-options": "DENY",
+    "referrer-policy": "strict-origin-when-cross-origin",
+});
+export function createSecurityMiddleware(options = {}) {
+    const configured = {
+        "strict-transport-security": options.strictTransportSecurity,
+        "x-content-type-options": options.xContentTypeOptions,
+        "x-frame-options": options.xFrameOptions,
+        "x-xss-protection": options.xXssProtection,
+        "content-security-policy": options.contentSecurityPolicy,
+        "referrer-policy": options.referrerPolicy,
+    };
+    const resolved = {
+        ...(options.useDefaults === false ? {} : DEFAULT_SECURITY_HEADERS),
+    };
+    for (const [name, value] of Object.entries(configured)) {
+        if (value === undefined) {
+            continue;
+        }
+        /*
+         * Values reach here as raw strings from configuration. An unvalidated
+         * CR/LF or control character in one is a response-splitting primitive.
+         */
+        if (!isValidHeaderFieldValue(value)) {
+            throw new TypeError(`Invalid value for security header "${name}": it contains a control character or surrounding whitespace.`);
+        }
+        resolved[name] = value;
+    }
+    return async (_context, next) => {
+        const response = await next();
+        return withResponseHeaders(response, resolved);
+    };
+}
+//# sourceMappingURL=httpMiddleware.security.js.map

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

@@ -0,0 +1,7 @@
+/**
+ * Security middleware barrel.
+ *
+ * @module httpMiddleware/builtin/security
+ */
+export { createSecurityMiddleware, type SecurityMiddlewareOptions, } from "./httpMiddleware.security.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,7 @@
+/**
+ * Security middleware barrel.
+ *
+ * @module httpMiddleware/builtin/security
+ */
+export { createSecurityMiddleware, } from "./httpMiddleware.security.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,22 @@
+/**
+ * Static file serving middleware.
+ *
+ * @module httpMiddleware/builtin/static
+ */
+import type { HttpMiddleware } from "../../httpMiddleware.type.js";
+export interface StaticMiddlewareOptions {
+    readonly root: string;
+    readonly index?: string | string[];
+    readonly maxAge?: number;
+    readonly immutable?: boolean;
+    readonly hidden?: boolean;
+    readonly extensions?: string[];
+    readonly fallback?: string;
+    /**
+     * Maximum file size, in bytes, that will be read into memory and served.
+     * Defaults to 10 MiB.
+     */
+    readonly maxFileSize?: number;
+}
+export declare function createStaticMiddleware(options: StaticMiddlewareOptions): HttpMiddleware;
+//# sourceMappingURL=httpMiddleware.static.d.ts.map

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

@@ -0,0 +1,198 @@
+/**
+ * Static file serving middleware.
+ *
+ * @module httpMiddleware/builtin/static
+ */
+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";
+const DEFAULT_INDEX = "index.html";
+const DEFAULT_MAX_AGE = 3600;
+const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
+const MIME_TYPES = {
+    ".html": "text/html",
+    ".css": "text/css",
+    ".js": "application/javascript",
+    ".mjs": "application/javascript",
+    ".json": "application/json",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".ico": "image/x-icon",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".eot": "application/vnd.ms-fontobject",
+    ".txt": "text/plain",
+    ".xml": "application/xml",
+    ".pdf": "application/pdf",
+    ".zip": "application/zip",
+    ".gz": "application/gzip",
+};
+function getContentType(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    return MIME_TYPES[ext] ?? "application/octet-stream";
+}
+function generateETag(data) {
+    return `"${createHash("md5").update(data).digest("hex")}"`;
+}
+/**
+ * Decodes a request pathname without letting a traversal payload through.
+ *
+ * `new URL()` does not decode `%2e`, so `/%2e%2e/%2e%2e/etc/passwd` reaches
+ * this function intact and only becomes `../../etc/passwd` once decoded —
+ * after which `path.join` happily resolves it outside the root. Decoding per
+ * segment and rejecting `.`/`..` closes that before any path is built.
+ *
+ * @returns The decoded pathname, or `undefined` if it must not be served.
+ */
+function decodePathname(pathname) {
+    const parts = pathname.split("/");
+    const decoded = [];
+    for (const part of parts) {
+        let value;
+        try {
+            value = decodeURIComponent(part);
+        }
+        catch {
+            /* Malformed percent-encoding. */
+            return undefined;
+        }
+        if (value === "." || value === "..") {
+            return undefined;
+        }
+        if (value.includes("/") ||
+            value.includes("\\") ||
+            value.includes("\u0000")) {
+            return undefined;
+        }
+        decoded.push(value);
+    }
+    return decoded.join("/");
+}
+/**
+ * Resolves a candidate path and confirms it stays inside the served root.
+ *
+ * This is the containment check, and it is deliberately independent of the
+ * dotfile filter: relying on `pathname.includes("/.")` to stop `/..` is
+ * accidental, and it is switched off entirely by `hidden: true`.
+ *
+ * @returns The resolved absolute path, or `undefined` if it escapes the root.
+ */
+function containedPath(resolvedRoot, candidate) {
+    const resolved = resolve(candidate);
+    if (resolved !== resolvedRoot &&
+        !resolved.startsWith(`${resolvedRoot}${sep}`)) {
+        return undefined;
+    }
+    return resolved;
+}
+export function createStaticMiddleware(options) {
+    const root = options.root;
+    const resolvedRoot = resolve(root);
+    const maxFileSize = options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+    /**
+     * Reads a candidate path, but only if it is inside the root and within the
+     * size cap.
+     */
+    const readContained = async (candidate) => {
+        const resolved = containedPath(resolvedRoot, candidate);
+        if (resolved === undefined) {
+            return undefined;
+        }
+        try {
+            const stats = await stat(resolved);
+            if (!stats.isFile() || stats.size > maxFileSize) {
+                return undefined;
+            }
+            return {
+                path: resolved,
+                data: await readFile(resolved),
+                mtime: stats.mtime,
+            };
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const indexFiles = Array.isArray(options.index)
+        ? options.index
+        : [options.index ?? DEFAULT_INDEX];
+    const maxAge = options.maxAge ?? DEFAULT_MAX_AGE;
+    const immutable = options.immutable ?? false;
+    const hidden = options.hidden ?? false;
+    const extensions = options.extensions ?? [];
+    const fallback = options.fallback;
+    return async (context, next) => {
+        const method = context.request.method?.toUpperCase();
+        if (method !== undefined && method !== "GET" && method !== "HEAD") {
+            return next();
+        }
+        const url = new URL(context.request.url);
+        const decodedPathname = decodePathname(url.pathname);
+        if (decodedPathname === undefined) {
+            return next();
+        }
+        let pathname = decodedPathname;
+        if (pathname.endsWith("/")) {
+            pathname = pathname.slice(0, -1);
+        }
+        if (!hidden && pathname.includes("/.")) {
+            return next();
+        }
+        const filePaths = [
+            join(root, pathname),
+            ...extensions.map((ext) => join(root, `${pathname}.${ext}`)),
+        ];
+        let found;
+        for (const candidate of filePaths) {
+            found = await readContained(candidate);
+            if (found) {
+                break;
+            }
+        }
+        if (!found) {
+            for (const indexFile of indexFiles) {
+                found = await readContained(join(root, `${pathname}/${indexFile}`));
+                if (found) {
+                    break;
+                }
+            }
+        }
+        if (!found && fallback) {
+            found = await readContained(join(root, fallback));
+        }
+        if (!found) {
+            return next();
+        }
+        const filePath = found.path;
+        const fileData = found.data;
+        const etag = generateETag(fileData);
+        const lastModified = found.mtime.toUTCString();
+        const contentType = getContentType(filePath);
+        const cacheControl = immutable
+            ? `public, max-age=${maxAge}, immutable`
+            : `public, max-age=${maxAge}`;
+        const responseHeaders = new Headers(context.response.headers);
+        responseHeaders.set("content-type", contentType);
+        responseHeaders.set("etag", etag);
+        responseHeaders.set("last-modified", lastModified);
+        responseHeaders.set("cache-control", cacheControl);
+        /*
+         * `Accept-Ranges: bytes` is deliberately NOT set: this middleware always
+         * 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);
+        }
+        return applyHeadersToResponse(context.response, responseHeaders).setBody(fileData);
+    };
+}
+//# sourceMappingURL=httpMiddleware.static.js.map

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

@@ -0,0 +1,8 @@
+/**
+ * Timing middleware factory.
+ *
+ * @module httpMiddleware/builtin/timing
+ */
+import type { HttpMiddleware } from "../../httpMiddleware.type.js";
+export declare function createTimingMiddleware(): HttpMiddleware;
+//# sourceMappingURL=httpMiddleware.timing.d.ts.map

package/dist/httpMiddleware/builtin/timing/httpMiddleware.timing.js

@@ -0,0 +1,18 @@
+/**
+ * Timing middleware factory.
+ *
+ * @module httpMiddleware/builtin/timing
+ */
+import { performanceNow, withResponseHeaders } from "../helpers/index.js";
+export function createTimingMiddleware() {
+    return async (context, next) => {
+        const start = performanceNow();
+        const response = await next();
+        const duration = performanceNow() - start;
+        return withResponseHeaders(response, {
+            "server-timing": `total;dur=${duration.toFixed(2)}`,
+            "x-response-time": `${duration.toFixed(2)}ms`,
+        });
+    };
+}
+//# sourceMappingURL=httpMiddleware.timing.js.map

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

@@ -0,0 +1,7 @@
+/**
+ * Timing middleware barrel.
+ *
+ * @module httpMiddleware/builtin/timing
+ */
+export { createTimingMiddleware } from "./httpMiddleware.timing.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,7 @@
+/**
+ * Timing middleware barrel.
+ *
+ * @module httpMiddleware/builtin/timing
+ */
+export { createTimingMiddleware } from "./httpMiddleware.timing.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * Video compression utilities using FFmpeg.
+ *
+ * @module httpMiddleware/builtin/video
+ *
+ * Requires: npm install fluent-ffmpeg
+ */
+import type { HttpMiddleware } from "../../httpMiddleware.type.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";
+    readonly scale?: {
+        readonly width?: number;
+        readonly height?: number;
+    };
+}
+export interface VideoCompressionMiddlewareOptions {
+    readonly enabled?: boolean;
+    readonly contentTypeMap?: Record<string, VideoCompressionOptions>;
+    readonly tempDir?: string;
+}
+export declare function compressVideo(inputBuffer: Buffer, options?: VideoCompressionOptions): Promise<Buffer>;
+export declare function createVideoCompressionMiddleware(options?: VideoCompressionMiddlewareOptions): HttpMiddleware;
+//# sourceMappingURL=httpMiddleware.video.d.ts.map

package/dist/httpMiddleware/builtin/video/httpMiddleware.video.js

@@ -0,0 +1,83 @@
+/**
+ * Video compression utilities using FFmpeg.
+ *
+ * @module httpMiddleware/builtin/video
+ *
+ * Requires: npm install fluent-ffmpeg
+ */
+import { applyHeadersToResponse } from "../helpers/index.js";
+const DEFAULT_CRF = 28;
+const DEFAULT_PRESET = "medium";
+const DEFAULT_FORMAT = "mp4";
+async function getFfmpeg() {
+    try {
+        const mod = await import("fluent-ffmpeg");
+        return mod.default ?? mod;
+    }
+    catch {
+        throw new Error("fluent-ffmpeg is not installed. Run: npm install fluent-ffmpeg");
+    }
+}
+export async function compressVideo(inputBuffer, options = {}) {
+    const ffmpegInstance = await getFfmpeg();
+    const crf = options.crf ?? DEFAULT_CRF;
+    const preset = options.preset ?? DEFAULT_PRESET;
+    const format = options.format ?? DEFAULT_FORMAT;
+    return new Promise((resolve, reject) => {
+        const outputBuffer = [];
+        ffmpegInstance
+            .input(inputBuffer)
+            .inputFormat("mp4")
+            .outputOptions([
+            `-crf ${crf}`,
+            `-preset ${preset}`,
+            "-movflags +faststart",
+        ])
+            .format(format)
+            .on("end", () => {
+            resolve(Buffer.concat(outputBuffer));
+        })
+            .on("error", (err) => {
+            reject(err);
+        })
+            .pipe((err, stdout) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            stdout.on("data", (chunk) => {
+                outputBuffer.push(chunk);
+            });
+        });
+    });
+}
+export function createVideoCompressionMiddleware(options = {}) {
+    const enabled = options.enabled ?? true;
+    return async (context, next) => {
+        if (!enabled) {
+            return next();
+        }
+        const response = await next();
+        const contentType = context.response.headers["content-type"];
+        if (!contentType || !contentType.startsWith("video/")) {
+            return response;
+        }
+        const body = context.response.body;
+        if (!Buffer.isBuffer(body)) {
+            return response;
+        }
+        const compressionOptions = options.contentTypeMap?.[contentType] ?? {};
+        try {
+            const compressed = await compressVideo(body, compressionOptions);
+            const newContentType = "video/mp4";
+            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);
+        }
+        catch {
+            return response;
+        }
+    };
+}
+//# sourceMappingURL=httpMiddleware.video.js.map

package/dist/httpMiddleware/httpMiddleware.state.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Default HTTP middleware state implementation.
+ *
+ * @module httpMiddleware/state
+ */
+import type { HttpMiddlewareState } from "./httpMiddleware.type.js";
+export declare class DefaultHttpMiddlewareState implements HttpMiddlewareState {
+    private readonly store;
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    entries(): IterableIterator<readonly [string, unknown]>;
+}
+//# sourceMappingURL=httpMiddleware.state.d.ts.map

package/dist/httpMiddleware/httpMiddleware.state.js

@@ -0,0 +1,30 @@
+/**
+ * Default HTTP middleware state implementation.
+ *
+ * @module httpMiddleware/state
+ */
+/* -------------------------------------------------------------------------- */
+/* Default State                                                              */
+/* -------------------------------------------------------------------------- */
+export class DefaultHttpMiddlewareState {
+    store = new Map();
+    get(key) {
+        return this.store.get(key);
+    }
+    set(key, value) {
+        this.store.set(key, value);
+    }
+    has(key) {
+        return this.store.has(key);
+    }
+    delete(key) {
+        return this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+    entries() {
+        return this.store.entries();
+    }
+}
+//# sourceMappingURL=httpMiddleware.state.js.map

package/dist/httpMiddleware/httpMiddleware.type.d.ts

@@ -0,0 +1,54 @@
+/**
+ * HTTP middleware type definitions.
+ *
+ * @module httpMiddleware/types
+ */
+import type { HttpRequestContext as RequestContext } from "../httpRequest/httpRequest.context.js";
+import type { HttpResponseContext as ResponseContext } from "../httpResponse/httpResponse.context.js";
+export type HttpMiddlewareResult = void | Response | RequestContext | ResponseContext | Promise<void | Response | RequestContext | ResponseContext>;
+export type HttpNext = () => Promise<ResponseContext>;
+export type HttpMiddleware = (context: HttpMiddlewareContext, next: HttpNext) => HttpMiddlewareResult;
+export interface HttpMiddlewareContext {
+    readonly request: RequestContext;
+    readonly response: ResponseContext;
+    readonly state: HttpMiddlewareState;
+    readonly signal: AbortSignal;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+export interface HttpMiddlewareState {
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    entries(): IterableIterator<readonly [string, unknown]>;
+}
+export interface HttpMiddlewareOptions {
+    readonly name?: string;
+    readonly priority?: number;
+    readonly enabled?: boolean;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface RegisteredMiddleware {
+    readonly id: string;
+    readonly name: string;
+    readonly priority: number;
+    readonly enabled: boolean;
+    readonly middleware: HttpMiddleware;
+}
+export interface HttpMiddlewarePipelineOptions {
+    readonly middlewares?: readonly (HttpMiddleware | RegisteredMiddleware)[];
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly onError?: HttpMiddlewareErrorHandler;
+}
+export type HttpMiddlewareErrorHandler = (error: unknown, context: HttpMiddlewareContext) => void | Response | ResponseContext | Promise<void | Response | ResponseContext>;
+export interface InternalMiddleware {
+    readonly id: string;
+    readonly middleware: HttpMiddleware;
+    readonly name: string;
+    readonly priority: number;
+    readonly sequence?: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    enabled: boolean;
+}
+//# sourceMappingURL=httpMiddleware.type.d.ts.map

package/dist/httpMiddleware/httpMiddleware.type.js

@@ -0,0 +1,7 @@
+/**
+ * HTTP middleware type definitions.
+ *
+ * @module httpMiddleware/types
+ */
+export {};
+//# sourceMappingURL=httpMiddleware.type.js.map

package/dist/httpMiddleware/pipeline/httpMiddleware.pipeline.d.ts

@@ -0,0 +1,35 @@
+/**
+ * HTTP middleware pipeline implementation.
+ *
+ * @module httpMiddleware/pipeline
+ */
+import type { HttpMiddleware, HttpMiddlewarePipelineOptions, HttpMiddlewareState, RegisteredMiddleware } from "../httpMiddleware.type.js";
+import type { HttpRequestContext as RequestContext } from "../../httpRequest/httpRequest.context.js";
+import type { HttpResponseContext as ResponseContext } from "../../httpResponse/httpResponse.context.js";
+export declare class HttpMiddlewarePipeline {
+    private readonly entries;
+    private readonly metadata;
+    private readonly onError;
+    private sequence;
+    constructor(options?: HttpMiddlewarePipelineOptions);
+    use(middleware: HttpMiddleware, options?: {
+        readonly name?: string;
+        readonly priority?: number;
+        readonly enabled?: boolean;
+        readonly metadata?: Readonly<Record<string, unknown>>;
+    }): () => void;
+    remove(id: string): boolean;
+    enable(id: string): boolean;
+    disable(id: string): boolean;
+    has(id: string): boolean;
+    clear(): void;
+    count(): number;
+    get(id: string): RegisteredMiddleware | undefined;
+    list(): readonly RegisteredMiddleware[];
+    execute(request: RequestContext, response: ResponseContext, options?: {
+        readonly state?: HttpMiddlewareState;
+        readonly signal?: AbortSignal;
+        readonly metadata?: Readonly<Record<string, unknown>>;
+    }): Promise<ResponseContext>;
+}
+//# sourceMappingURL=httpMiddleware.pipeline.d.ts.map