@zudojs/http 0.1.0 → 1.1.0

package/dist/httpRouter/tree/core/httpTree.helper.js

@@ -0,0 +1,80 @@
+/**
+ * Route tree helper functions.
+ *
+ * @module httpRoute/tree/helpers
+ */
+import { createChildNode } from "./httpTree.nodeCreation.js";
+/**
+ * Gets pattern segments from a path.
+ */
+export function getPatternSegments(path) {
+    return path.split("/").filter(Boolean);
+}
+/**
+ * Inserts a segment into the tree.
+ */
+export function insertSegment(node, segments, handler, methods, metadata) {
+    if (segments.length === 0) {
+        node.handler = handler;
+        for (const method of methods) {
+            node.methods.add(method);
+        }
+        Object.assign(node.metadata, metadata);
+        return;
+    }
+    const [segment, ...rest] = segments;
+    if (segment === undefined) {
+        return;
+    }
+    let child = node.children.get(segment);
+    if (!child) {
+        child = createChildNode(segment);
+        node.children.set(segment, child);
+    }
+    insertSegment(child, rest, handler, methods, metadata);
+}
+/**
+ * Removes a route from the tree.
+ */
+export function removeRouteFromTree(node, segments) {
+    if (segments.length === 0) {
+        if (node.handler) {
+            node.handler = undefined;
+            node.methods.clear();
+            return true;
+        }
+        return false;
+    }
+    const [segment, ...rest] = segments;
+    if (segment === undefined) {
+        return false;
+    }
+    const child = node.children.get(segment);
+    if (!child) {
+        return false;
+    }
+    const removed = removeRouteFromTree(child, rest);
+    if (removed && isEmptyNode(child)) {
+        node.children.delete(segment);
+    }
+    return removed;
+}
+/**
+ * Checks if a node is empty.
+ */
+export function isEmptyNode(node) {
+    return node.children.size === 0 && !node.handler && node.methods.size === 0;
+}
+/**
+ * Checks if a method matches.
+ */
+export function matchesMethod(node, method) {
+    return node.methods.has(method) || node.methods.has("*");
+}
+/**
+ * Splits a path into segments.
+ */
+export function splitPath(path) {
+    return path.split("/").filter(Boolean);
+}
+//# sourceMappingURL=httpTree.helper.js.map

package/dist/httpRouter/tree/core/httpTree.nodeCreation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Route tree node creation utilities.
+ *
+ * @module httpRoute/tree/nodeCreation
+ */
+import type { MutableRouteTreeNode } from "./httpTree.type.js";
+/**
+ * Creates a child node based on the segment.
+ */
+export declare function createChildNode(segment: string): MutableRouteTreeNode;
+//# sourceMappingURL=httpTree.nodeCreation.d.ts.map

package/dist/httpRouter/tree/core/httpTree.nodeCreation.js

@@ -0,0 +1,54 @@
+/**
+ * Route tree node creation utilities.
+ *
+ * @module httpRoute/tree/nodeCreation
+ */
+/**
+ * Creates a child node based on the segment.
+ */
+export function createChildNode(segment) {
+    if (segment.startsWith(":")) {
+        return {
+            name: segment.slice(1),
+            type: "parameter",
+            children: new Map(),
+            methods: new Set(),
+            metadata: {},
+            optional: false,
+            wildcard: false,
+            param: segment.slice(1),
+        };
+    }
+    if (segment === "*") {
+        return {
+            name: "*",
+            type: "wildcard",
+            children: new Map(),
+            methods: new Set(),
+            metadata: {},
+            optional: false,
+            wildcard: true,
+        };
+    }
+    if (segment.endsWith("?")) {
+        return {
+            name: segment.slice(0, -1),
+            type: "optional",
+            children: new Map(),
+            methods: new Set(),
+            metadata: {},
+            optional: true,
+            wildcard: false,
+        };
+    }
+    return {
+        name: segment,
+        type: "static",
+        children: new Map(),
+        methods: new Set(),
+        metadata: {},
+        optional: false,
+        wildcard: false,
+    };
+}
+//# sourceMappingURL=httpTree.nodeCreation.js.map

package/dist/httpRouter/tree/core/httpTree.traversal.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Route tree traversal functions.
+ *
+ * @module httpRoute/tree/traversal
+ */
+import type { MutableRouteTreeNode } from "./httpTree.type.js";
+/**
+ * Collects candidates from the tree.
+ */
+export declare function collectCandidates(node: MutableRouteTreeNode, segments: readonly string[]): MutableRouteTreeNode[];
+/**
+ * Collects optional routes from the tree.
+ */
+export declare function collectOptionalRoutes(node: MutableRouteTreeNode): MutableRouteTreeNode[];
+/**
+ * Collects all routes from the tree.
+ */
+export declare function collectRoutes(node: MutableRouteTreeNode, path: string): Array<{
+    readonly path: string;
+    readonly node: MutableRouteTreeNode;
+}>;
+/**
+ * Finds a static child node.
+ */
+export declare function findStaticChild(node: MutableRouteTreeNode, name: string): MutableRouteTreeNode | undefined;
+//# sourceMappingURL=httpTree.traversal.d.ts.map

package/dist/httpRouter/tree/core/httpTree.traversal.js

@@ -0,0 +1,73 @@
+/**
+ * Route tree traversal functions.
+ *
+ * @module httpRoute/tree/traversal
+ */
+/**
+ * Collects candidates from the tree.
+ */
+export function collectCandidates(node, segments) {
+    if (segments.length === 0) {
+        return [node];
+    }
+    const [segment, ...rest] = segments;
+    if (segment === undefined) {
+        return [node];
+    }
+    const candidates = [];
+    const staticChild = node.children.get(segment);
+    if (staticChild) {
+        candidates.push(...collectCandidates(staticChild, rest));
+    }
+    for (const child of node.children.values()) {
+        if (child.type === "parameter") {
+            candidates.push(...collectCandidates(child, rest));
+        }
+        if (child.type === "wildcard") {
+            candidates.push(child);
+        }
+        if (child.type === "optional") {
+            candidates.push(...collectCandidates(child, rest));
+            candidates.push(child);
+        }
+    }
+    return candidates;
+}
+/**
+ * Collects optional routes from the tree.
+ */
+export function collectOptionalRoutes(node) {
+    const results = [];
+    for (const child of node.children.values()) {
+        if (child.type === "optional" || child.wildcard) {
+            results.push(child);
+            results.push(...collectOptionalRoutes(child));
+        }
+    }
+    return results;
+}
+/**
+ * Collects all routes from the tree.
+ */
+export function collectRoutes(node, path) {
+    const results = [];
+    if (node.handler) {
+        results.push({ path, node });
+    }
+    for (const [key, child] of node.children) {
+        const childPath = child.type === "parameter"
+            ? `${path}:${key}`
+            : child.type === "wildcard"
+                ? `${path}*`
+                : `${path}/${key}`;
+        results.push(...collectRoutes(child, childPath));
+    }
+    return results;
+}
+/**
+ * Finds a static child node.
+ */
+export function findStaticChild(node, name) {
+    return node.children.get(name);
+}
+//# sourceMappingURL=httpTree.traversal.js.map

package/dist/httpRouter/tree/core/httpTree.type.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Route tree types.
+ *
+ * @module httpRoute/tree/types
+ */
+export interface RouteTreeNode {
+    readonly name: string;
+    readonly type: RouteTreeNodeType;
+    readonly children: ReadonlyMap<string, RouteTreeNode>;
+    readonly handler?: unknown;
+    readonly methods: ReadonlySet<string>;
+    readonly metadata: Record<string, unknown>;
+    readonly optional: boolean;
+    readonly wildcard: boolean;
+    readonly param?: string;
+}
+export type RouteTreeNodeType = "static" | "parameter" | "wildcard" | "optional";
+/**
+ * Options for {@link RouteTree}.
+ *
+ * Deliberately empty. `caseSensitive` and `strict` were declared here and never
+ * read — case sensitivity and trailing-slash handling are owned by
+ * `RouterOptions` and applied by `RouteMatcher`, which is the path requests
+ * actually take. Declaring them here again promised behaviour this structure
+ * never implemented.
+ */
+export interface RouteTreeOptions {
+}
+export interface RouteTreeMatch {
+    readonly params: Record<string, string>;
+    readonly path: string;
+    readonly handler: unknown;
+    readonly methods: readonly string[];
+    readonly metadata: Record<string, unknown>;
+}
+export interface RouteTreeSnapshot {
+    readonly root: RouteTreeNode;
+    readonly timestamp: number;
+    readonly nodeCount: number;
+}
+export interface MutableRouteTreeNode {
+    name: string;
+    type: RouteTreeNodeType;
+    children: Map<string, MutableRouteTreeNode>;
+    handler?: unknown;
+    methods: Set<string>;
+    metadata: Record<string, unknown>;
+    optional: boolean;
+    wildcard: boolean;
+    param?: string;
+}
+//# sourceMappingURL=httpTree.type.d.ts.map

package/dist/httpRouter/tree/core/httpTree.type.js

@@ -0,0 +1,7 @@
+/**
+ * Route tree types.
+ *
+ * @module httpRoute/tree/types
+ */
+export {};
+//# sourceMappingURL=httpTree.type.js.map

package/dist/httpRouter/tree/core/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Core tree utilities.
+ *
+ * @module httpRoute/tree/core
+ */
+export * from "./httpTree.type.js";
+export * from "./httpTree.helper.js";
+export * from "./httpTree.nodeCreation.js";
+export * from "./httpTree.traversal.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpRouter/tree/core/index.js

@@ -0,0 +1,10 @@
+/**
+ * Core tree utilities.
+ *
+ * @module httpRoute/tree/core
+ */
+export * from "./httpTree.type.js";
+export * from "./httpTree.helper.js";
+export * from "./httpTree.nodeCreation.js";
+export * from "./httpTree.traversal.js";
+//# sourceMappingURL=index.js.map

package/dist/httpRouter/tree/httpTree.core.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Route tree implementation.
+ *
+ * @module httpRoute/tree/tree
+ */
+import type { RouteTreeOptions, RouteTreeMatch, RouteTreeSnapshot } from "./core/httpTree.type.js";
+export declare class RouteTree {
+    private readonly root;
+    private nodeCount;
+    constructor(_options?: RouteTreeOptions);
+    insert(path: string, handler: unknown, methods?: readonly string[], metadata?: Record<string, unknown>): void;
+    remove(path: string): boolean;
+    lookup(path: string, method?: string): RouteTreeMatch | undefined;
+    has(path: string, method?: string): boolean;
+    clear(): void;
+    snapshot(): RouteTreeSnapshot;
+    get size(): number;
+    private extractParams;
+    private freezeNode;
+}
+//# sourceMappingURL=httpTree.core.d.ts.map

package/dist/httpRouter/tree/httpTree.core.js

@@ -0,0 +1,96 @@
+/**
+ * Route tree implementation.
+ *
+ * @module httpRoute/tree/tree
+ */
+import { insertSegment, removeRouteFromTree, matchesMethod, splitPath, } from "./core/httpTree.helper.js";
+import { collectCandidates } from "./core/httpTree.traversal.js";
+export class RouteTree {
+    root;
+    nodeCount = 0;
+    constructor(_options = {}) {
+        this.root = {
+            name: "",
+            type: "static",
+            children: new Map(),
+            methods: new Set(),
+            metadata: {},
+            optional: false,
+            wildcard: false,
+        };
+    }
+    insert(path, handler, methods = ["GET"], metadata = {}) {
+        const segments = splitPath(path);
+        insertSegment(this.root, segments, handler, methods, metadata);
+        this.nodeCount++;
+    }
+    remove(path) {
+        const segments = splitPath(path);
+        const removed = removeRouteFromTree(this.root, segments);
+        if (removed) {
+            this.nodeCount--;
+        }
+        return removed;
+    }
+    lookup(path, method) {
+        const segments = splitPath(path);
+        const candidates = collectCandidates(this.root, segments);
+        for (const candidate of candidates) {
+            if (candidate.handler && (!method || matchesMethod(candidate, method))) {
+                return {
+                    params: this.extractParams(segments, candidate),
+                    path,
+                    handler: candidate.handler,
+                    methods: Array.from(candidate.methods),
+                    metadata: { ...candidate.metadata },
+                };
+            }
+        }
+        return undefined;
+    }
+    has(path, method) {
+        return this.lookup(path, method) !== undefined;
+    }
+    clear() {
+        this.root.children.clear();
+        this.root.handler = undefined;
+        this.root.methods.clear();
+        this.root.metadata = {};
+        this.nodeCount = 0;
+    }
+    snapshot() {
+        return {
+            root: this.freezeNode(this.root),
+            timestamp: Date.now(),
+            nodeCount: this.nodeCount,
+        };
+    }
+    get size() {
+        return this.nodeCount;
+    }
+    extractParams(segments, node) {
+        const params = {};
+        if (node.type === "parameter" && node.param) {
+            params[node.param] = segments[segments.length - 1] ?? "";
+        }
+        return params;
+    }
+    freezeNode(node) {
+        const children = new Map();
+        for (const [key, child] of node.children) {
+            children.set(key, this.freezeNode(child));
+        }
+        return {
+            name: node.name,
+            type: node.type,
+            children,
+            handler: node.handler,
+            methods: new Set(node.methods),
+            metadata: { ...node.metadata },
+            optional: node.optional,
+            wildcard: node.wildcard,
+            param: node.param,
+        };
+    }
+}
+//# sourceMappingURL=httpTree.core.js.map

package/dist/httpRouter/tree/httpTree.factory.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Route tree factory.
+ *
+ * @module httpRoute/tree/factory
+ */
+import type { RouteTreeOptions } from "./core/httpTree.type.js";
+import { RouteTree } from "./httpTree.core.js";
+/**
+ * Creates a new route tree.
+ */
+export declare function createRouteTree(options?: RouteTreeOptions): RouteTree;
+//# sourceMappingURL=httpTree.factory.d.ts.map

package/dist/httpRouter/tree/httpTree.factory.js

@@ -0,0 +1,13 @@
+/**
+ * Route tree factory.
+ *
+ * @module httpRoute/tree/factory
+ */
+import { RouteTree } from "./httpTree.core.js";
+/**
+ * Creates a new route tree.
+ */
+export function createRouteTree(options = {}) {
+    return new RouteTree(options);
+}
+//# sourceMappingURL=httpTree.factory.js.map

package/dist/httpRouter/tree/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * HTTP route tree (radix tree).
+ */
+export type { RouteTreeNode, RouteTreeNodeType, RouteTreeOptions, RouteTreeMatch, RouteTreeSnapshot, MutableRouteTreeNode, } from "./core/httpTree.type.js";
+export { RouteTree } from "./httpTree.core.js";
+export { createRouteTree } from "./httpTree.factory.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpRouter/tree/index.js

@@ -0,0 +1,6 @@
+/**
+ * HTTP route tree (radix tree).
+ */
+export { RouteTree } from "./httpTree.core.js";
+export { createRouteTree } from "./httpTree.factory.js";
+//# sourceMappingURL=index.js.map

package/dist/httpSecurity/httpSecurity.config.d.ts

@@ -2,8 +2,15 @@
  * @zudojs/http — Security configuration types.
  *
  * Defines the configuration for HTTP security features:
- * body limits, header validation, host validation, proxy trust,
- * timeouts, and abort propagation.
+ * body limits, header validation, host validation and proxy trust.
+ *
+ * Every field here is read by `guardRequest` or by the trust-proxy layer.
+ * `trustedProxyCount`, `requestTimeout`, `headersTimeout` and
+ * `keepAliveTimeout` were removed: nothing in the package read them, and their
+ * JSDoc made an explicit and false promise ("default: 30000") that an operator
+ * setting `requestTimeout: 5000` was protected against slowloris. The Node
+ * adapter has its own, separately named timeout options, and those are the
+ * ones that take effect.
  */
 /** Configuration for HTTP request security guards. */
 export interface HTTPSecurityConfig {
@@ -19,16 +26,15 @@ export interface HTTPSecurityConfig {
     readonly maxQueryLength?: number;
     /** Allowed Host header values. Empty = allow all. */
     readonly allowedHosts?: readonly string[];
-    /** Whether to trust X-Forwarded-* headers (default: false). */
+    /**
+     * Whether `X-Forwarded-*` headers may be trusted (default: `false`).
+     *
+     * Consumed by `httpTrustProxy` and the adapter, not by `guardRequest`. For a
+     * real proxy set — CIDR ranges, named presets, a predicate — pass a
+     * `TrustProxy` value to the adapter directly; this flag is only the
+     * on/off signal.
+     */
     readonly trustProxy?: boolean;
-    /** Number of trusted proxy hops (default: 0). */
-    readonly trustedProxyCount?: number;
-    /** Request timeout in milliseconds (default: 30000). */
-    readonly requestTimeout?: number;
-    /** Headers timeout in milliseconds (default: 10000). */
-    readonly headersTimeout?: number;
-    /** Keep-alive timeout in milliseconds (default: 5000). */
-    readonly keepAliveTimeout?: number;
     /** Maximum request ID length (default: 128). */
     readonly maxRequestIdLength?: number;
     /** Characters allowed in request IDs (default: alphanumeric + hyphens + underscores). */

package/dist/httpSecurity/httpSecurity.config.js

@@ -2,8 +2,15 @@
  * @zudojs/http — Security configuration types.
  *
  * Defines the configuration for HTTP security features:
- * body limits, header validation, host validation, proxy trust,
- * timeouts, and abort propagation.
+ * body limits, header validation, host validation and proxy trust.
+ *
+ * Every field here is read by `guardRequest` or by the trust-proxy layer.
+ * `trustedProxyCount`, `requestTimeout`, `headersTimeout` and
+ * `keepAliveTimeout` were removed: nothing in the package read them, and their
+ * JSDoc made an explicit and false promise ("default: 30000") that an operator
+ * setting `requestTimeout: 5000` was protected against slowloris. The Node
+ * adapter has its own, separately named timeout options, and those are the
+ * ones that take effect.
  */
 /** Default security configuration. */
 export const DEFAULT_SECURITY_CONFIG = Object.freeze({
@@ -14,10 +21,6 @@ export const DEFAULT_SECURITY_CONFIG = Object.freeze({
     maxQueryLength: 4096,
     allowedHosts: [],
     trustProxy: false,
-    trustedProxyCount: 0,
-    requestTimeout: 30_000, // 30s
-    headersTimeout: 10_000, // 10s
-    keepAliveTimeout: 5_000, // 5s
     maxRequestIdLength: 128,
     requestIdPattern: /^[a-zA-Z0-9_-]+$/,
     enableCrlfProtection: true,

package/dist/httpSecurity/httpSecurity.guard.d.ts

@@ -26,4 +26,32 @@ export interface GuardResult {
  * @returns A GuardResult indicating whether the request is allowed.
  */
 export declare function guardRequest(request: GuardableRequest, config?: Partial<HTTPSecurityConfig>): GuardResult;
+/**
+ * Binds a configuration to {@link guardRequest} so a server or adapter can
+ * hold a single ready-to-call guard.
+ *
+ * `guardRequest` describes itself as "the first security boundary" and had no
+ * call site anywhere in `src/`, which left the header-count limit, URL-length
+ * limit, Host validation, request-ID validation and the
+ * `Transfer-Encoding`/`Content-Length` smuggling check all inert. This is the
+ * shape the request path should call; see `assertRequestAllowed` for the
+ * throwing variant.
+ */
+export declare function createRequestGuard(config?: Partial<HTTPSecurityConfig>): (request: GuardableRequest) => GuardResult;
+/**
+ * Error thrown by {@link assertRequestAllowed}.
+ *
+ * Carries the status the response should use and the individual validation
+ * failures, so a caller can log the detail without returning it to the client.
+ */
+export declare class HttpRequestGuardError extends Error {
+    readonly statusCode: number;
+    readonly errors: readonly string[];
+    constructor(result: GuardResult);
+}
+/**
+ * Runs the guard and throws {@link HttpRequestGuardError} when the request is
+ * rejected.
+ */
+export declare function assertRequestAllowed(request: GuardableRequest, config?: Partial<HTTPSecurityConfig>): void;
 //# sourceMappingURL=httpSecurity.guard.d.ts.map

package/dist/httpSecurity/httpSecurity.guard.js

@@ -37,4 +37,44 @@ export function guardRequest(request, config) {
     }
     return { allowed: true, errors: [], statusCode: 200 };
 }
+/**
+ * Binds a configuration to {@link guardRequest} so a server or adapter can
+ * hold a single ready-to-call guard.
+ *
+ * `guardRequest` describes itself as "the first security boundary" and had no
+ * call site anywhere in `src/`, which left the header-count limit, URL-length
+ * limit, Host validation, request-ID validation and the
+ * `Transfer-Encoding`/`Content-Length` smuggling check all inert. This is the
+ * shape the request path should call; see `assertRequestAllowed` for the
+ * throwing variant.
+ */
+export function createRequestGuard(config) {
+    return (request) => guardRequest(request, config);
+}
+/**
+ * Error thrown by {@link assertRequestAllowed}.
+ *
+ * Carries the status the response should use and the individual validation
+ * failures, so a caller can log the detail without returning it to the client.
+ */
+export class HttpRequestGuardError extends Error {
+    statusCode;
+    errors;
+    constructor(result) {
+        super(`Request rejected by security guard: ${result.errors.join("; ")}`);
+        this.name = "HttpRequestGuardError";
+        this.statusCode = result.statusCode;
+        this.errors = result.errors;
+    }
+}
+/**
+ * Runs the guard and throws {@link HttpRequestGuardError} when the request is
+ * rejected.
+ */
+export function assertRequestAllowed(request, config) {
+    const result = guardRequest(request, config);
+    if (!result.allowed) {
+        throw new HttpRequestGuardError(result);
+    }
+}
 //# sourceMappingURL=httpSecurity.guard.js.map

package/dist/httpSecurity/index.d.ts

@@ -10,5 +10,5 @@ export { DEFAULT_SECURITY_CONFIG } from "./httpSecurity.config.js";
 export type { SecurityValidationResult } from "./httpSecurity.validator.js";
 export { validateHeaders, validateHost, validateUrl, validateQuery, validateContentLength, validateRequestId, validateTransferEncoding, } from "./httpSecurity.validator.js";
 export type { GuardableRequest, GuardResult } from "./httpSecurity.guard.js";
-export { guardRequest } from "./httpSecurity.guard.js";
+export { guardRequest, createRequestGuard, assertRequestAllowed, HttpRequestGuardError, } from "./httpSecurity.guard.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpSecurity/index.js

@@ -7,5 +7,5 @@
  */
 export { DEFAULT_SECURITY_CONFIG } from "./httpSecurity.config.js";
 export { validateHeaders, validateHost, validateUrl, validateQuery, validateContentLength, validateRequestId, validateTransferEncoding, } from "./httpSecurity.validator.js";
-export { guardRequest } from "./httpSecurity.guard.js";
+export { guardRequest, createRequestGuard, assertRequestAllowed, HttpRequestGuardError, } from "./httpSecurity.guard.js";
 //# sourceMappingURL=index.js.map