@lovrozagar/honey 0.7.3 → 1.0.0-rc.3

package/dist/middleware/middleware.js

@@ -0,0 +1,112 @@
+/**
+ * The middleware primitive: the typed factories, the meta a middleware contributes, and the chain
+ * compiler. A chain compiles once per route; every `next()` boundary is an error boundary, and a
+ * layer whose middleware answered synchronously stays synchronous (no Promise per layer).
+ */
+import { isReservedCtxKey } from "../context/context.js";
+import { isHoneyResponse } from "../response/builder.js";
+/**
+ * Stamp a stable name on a middleware closure. `Function.prototype.name` is inferred by whatever
+ * transpiled the module, and transpilers disagree about a closure returned from a factory; a
+ * shipped middleware names itself so generated artifacts are deterministic.
+ */
+export function namedMiddleware(name, fn) {
+    Object.defineProperty(fn, "name", { configurable: true, value: name });
+    return fn;
+}
+/**
+ * `internal` decides whether a route appears in generated artifacts at all; a middleware that set
+ * it would silently remove routes, so it is the one key middleware may not contribute.
+ */
+function attachMiddlewareMeta(fn, meta) {
+    if ("internal" in meta) {
+        throw new Error('middleware meta cannot set "internal": it controls whether routes appear in generated artifacts; set it on the route with .meta({ internal: true })');
+    }
+    Object.defineProperty(fn, "meta", { value: Object.freeze({ ...meta }) });
+}
+/** A middleware whose error keys are constrained to a factory; `.use()` accumulates them. */
+export function defineMiddleware(opts) {
+    const fn = opts.fn;
+    if (opts.errors) {
+        Object.defineProperty(fn, "errors", { value: opts.errors.slice(1) });
+        /* the factory the keys come from, off the type: a document reads their statuses off it */
+        Object.defineProperty(fn, "errorFactory", { value: opts.errors[0] });
+    }
+    if (opts.meta)
+        attachMiddlewareMeta(fn, opts.meta);
+    return fn;
+}
+/**
+ * A middleware: annotate `ctx` for what it requires; what it adds is inferred from `next({...})`.
+ *   createMiddleware((ctx: { env: { DB: D1Database } }, next) => next({ db }))
+ */
+export function createMiddleware(fn, opts) {
+    if (opts?.meta)
+        attachMiddlewareMeta(fn, opts.meta);
+    return fn;
+}
+/** Merge the meta a chain contributes, in run order (later wins). Resolved once at finalize. */
+export function collectMiddlewareMeta(groups) {
+    let out = null;
+    for (const group of groups) {
+        for (const mw of group) {
+            const meta = mw.meta;
+            if (meta)
+                out = Object.assign(out ?? {}, meta);
+        }
+    }
+    return out;
+}
+const NO_RESPONSE_HANDLER = "handler must return a Response — did you forget 'return ctx.res...()'?";
+const NO_RESPONSE_MIDDLEWARE = "middleware must return a Response — did you forget 'return next(...)'?";
+function mergeAdditions(ctx, additions) {
+    for (const key in additions)
+        if (!isReservedCtxKey(key))
+            ctx[key] = additions[key];
+}
+/** Whether a layer answered: a Response, or honey's own built one. */
+const isAnswer = (value) => isHoneyResponse(value) || value instanceof Response;
+/** Settle one layer's result: anything but a Response (nothing, a string…) and a throw both go to the boundary. */
+function settle(result, ctx, convert, missing) {
+    if (result instanceof Promise) {
+        return result.then((value) => (isAnswer(value) ? value : convert(new Error(missing), ctx)), (thrown) => convert(thrown, ctx));
+    }
+    return isAnswer(result) ? result : convert(new Error(missing), ctx);
+}
+/**
+ * Compile a middleware chain and a handler into one function, once. Whatever the handler or a
+ * middleware throws or rejects with becomes a Response at that layer, so the middleware around it
+ * always gets a Response from `next()` and its post-`next()` code runs on errors too.
+ */
+export function compileChain(middlewares, handler, convert) {
+    const n = middlewares.length;
+    const runHandler = (ctx) => {
+        try {
+            return settle(handler(ctx), ctx, convert, NO_RESPONSE_HANDLER);
+        }
+        catch (thrown) {
+            return convert(thrown, ctx);
+        }
+    };
+    const step = (i, ctx) => {
+        if (i === n)
+            return runHandler(ctx);
+        const mw = middlewares[i];
+        let called = false;
+        const next = (additions) => {
+            if (called)
+                throw new Error("next() called multiple times");
+            called = true;
+            if (additions)
+                mergeAdditions(ctx, additions);
+            return step(i + 1, ctx);
+        };
+        try {
+            return settle(mw(ctx, next), ctx, convert, NO_RESPONSE_MIDDLEWARE);
+        }
+        catch (thrown) {
+            return convert(thrown, ctx);
+        }
+    };
+    return n === 0 ? runHandler : (ctx) => step(0, ctx);
+}

package/dist/middleware/powered-by.d.ts

@@ -0,0 +1,6 @@
+import { type MiddlewareFn } from "./middleware.ts";
+export type PoweredByOptions = {
+    /** Default `Honey`. */
+    name?: string;
+};
+export declare function poweredBy(options?: PoweredByOptions): MiddlewareFn<{}>;

package/dist/middleware/powered-by.js

@@ -0,0 +1,13 @@
+/**
+ * `poweredBy({ name })`: `X-Powered-By: Honey`, or `name`, on every answer. A value the handler set
+ * itself is kept.
+ */
+import { withHeaders } from "../response/with-headers.js";
+import { namedMiddleware } from "./middleware.js";
+export function poweredBy(options = {}) {
+    const name = options.name ?? "Honey";
+    return namedMiddleware("poweredBy", async (_ctx, next) => withHeaders(await next(), (headers) => {
+        if (!headers.has("x-powered-by"))
+            headers.set("x-powered-by", name);
+    }));
+}

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,40 @@
+import { type MiddlewareFn } from "./middleware.ts";
+/** A key's window after one more request: requests counted so far, and when it ends (epoch ms). */
+export type RateLimitHit = {
+    readonly count: number;
+    readonly resetAt: number;
+};
+/** Counts a request against `key`'s current window, starting a new one when it has ended. */
+export type RateLimitStore = {
+    hit(key: string): Promise<RateLimitHit> | RateLimitHit;
+};
+export type MemoryStore = {
+    hit(key: string): RateLimitHit;
+    readonly size: number;
+};
+export type MemoryStoreOptions = {
+    /** Windows kept at most; past it the least recently used is evicted. Default 10 000. */
+    maxKeys?: number | undefined;
+    windowMs: number;
+};
+type KeyContext = {
+    readonly ip: string | null;
+    readonly req: Request;
+};
+export type RateLimitOptions = {
+    /** The window a request counts against. Default `ctx.ip`; no reported peer shares one window. */
+    key?: (ctx: KeyContext) => string;
+    /** Requests per window. */
+    limit: number;
+} & ({
+    maxKeys?: number;
+    store?: never;
+    windowMs: number;
+} | {
+    maxKeys?: never;
+    store: RateLimitStore;
+    windowMs?: never;
+});
+export declare function memoryStore(options: MemoryStoreOptions): MemoryStore;
+export declare function rateLimit(options: RateLimitOptions): MiddlewareFn<KeyContext, {}, "too_many_requests">;
+export {};

package/dist/middleware/rate-limit.js

@@ -0,0 +1,90 @@
+/**
+ * `rateLimit({ limit, windowMs })`: a fixed-window limiter. Each key (default `ctx.ip`, the platform
+ * peer, so a forwarded header cannot rotate it) gets `limit` requests per window; past that the
+ * answer is 429 `too_many_requests` with `Retry-After`, and the handler never runs. Every answer
+ * carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (epoch seconds).
+ *
+ * The default store is in-process and per middleware: bounded to `maxKeys` windows, the least
+ * recently used evicted first, so a key spray cannot grow it (H18.8). Behind several instances,
+ * pass a shared `store`.
+ */
+import { HoneyError } from "../errors/error.js";
+import { withHeaders } from "../response/with-headers.js";
+import { namedMiddleware } from "./middleware.js";
+class WindowStore {
+    #maxKeys;
+    #windowMs;
+    /* insertion order is recency: a hit re-inserts its key last, so the first key is the LRU */
+    #windows = new Map();
+    constructor(windowMs, maxKeys) {
+        this.#windowMs = windowMs;
+        this.#maxKeys = maxKeys;
+    }
+    get size() {
+        return this.#windows.size;
+    }
+    hit(key) {
+        const windows = this.#windows;
+        const now = Date.now();
+        const current = windows.get(key);
+        if (current !== undefined)
+            windows.delete(key);
+        else if (windows.size >= this.#maxKeys)
+            windows.delete(windows.keys().next().value);
+        const hit = current !== undefined && current.resetAt > now
+            ? { count: current.count + 1, resetAt: current.resetAt }
+            : { count: 1, resetAt: now + this.#windowMs };
+        windows.set(key, hit);
+        return hit;
+    }
+}
+export function memoryStore(options) {
+    const { maxKeys = 10_000, windowMs } = options;
+    if (!(Number.isFinite(windowMs) && windowMs > 0)) {
+        throw new TypeError("rateLimit: windowMs must be a positive finite number");
+    }
+    if (!(Number.isInteger(maxKeys) && maxKeys > 0))
+        throw new TypeError("rateLimit: maxKeys must be a positive integer");
+    return new WindowStore(windowMs, maxKeys);
+}
+function peerKey(ctx) {
+    return ctx.ip ?? "";
+}
+export function rateLimit(options) {
+    const { limit } = options;
+    if (!(Number.isInteger(limit) && limit > 0))
+        throw new TypeError("rateLimit: limit must be a positive integer");
+    const store = options.store ?? memoryStore(options);
+    const keyOf = options.key ?? peerKey;
+    const limitText = String(limit);
+    /** The answer for a counted request: 429 past the limit, else the chain's with the headers. */
+    const answer = async (hit, next) => {
+        const remaining = String(Math.max(0, limit - hit.count));
+        const reset = String(Math.ceil(hit.resetAt / 1000));
+        if (hit.count > limit) {
+            const retryAfter = String(Math.max(0, Math.ceil((hit.resetAt - Date.now()) / 1000)));
+            throw new HoneyError({
+                errorKey: "too_many_requests",
+                headers: {
+                    "retry-after": retryAfter,
+                    "x-ratelimit-limit": limitText,
+                    "x-ratelimit-remaining": remaining,
+                    "x-ratelimit-reset": reset,
+                },
+                status: "too_many_requests",
+            });
+        }
+        return withHeaders(await next(), (out) => {
+            out.set("x-ratelimit-limit", limitText);
+            out.set("x-ratelimit-remaining", remaining);
+            out.set("x-ratelimit-reset", reset);
+        });
+    };
+    /* a sync store (the memory default) is answered without an extra await */
+    const mw = (ctx, next) => {
+        const hit = store.hit(keyOf(ctx));
+        return hit instanceof Promise ? hit.then((counted) => answer(counted, next)) : answer(hit, next);
+    };
+    mw.errors = ["too_many_requests"];
+    return namedMiddleware("rateLimit", mw);
+}

package/dist/middleware/request-id.d.ts

@@ -0,0 +1,25 @@
+import { type MiddlewareFn } from "./middleware.ts";
+/**
+ * May the hop that sent this request decide a value it carries (a request id, a trace)? `false`
+ * (the default) never; `true` always; a function decides per request.
+ */
+export type InboundTrust = boolean | ((ctx: {
+    readonly ip: string | null;
+    readonly req: Request;
+}) => boolean);
+export type RequestIdOptions = {
+    /** Default `crypto.randomUUID()`. */
+    generate?: () => string;
+    /** Default `x-request-id`. */
+    header?: string;
+    /** Reuse a valid inbound id when the hop is trusted. Default `false`: always a fresh id. */
+    trustInbound?: InboundTrust;
+    /** Which inbound ids are safe to reuse. Default: 1–128 of `A-Z a-z 0-9 . _ : + / = -` (UUIDs, ULIDs, base64, trace ids). */
+    validate?: (id: string) => boolean;
+};
+export declare function requestId(options?: RequestIdOptions): MiddlewareFn<{
+    readonly ip: string | null;
+    readonly req: Request;
+}, {
+    requestId: string;
+}>;

package/dist/middleware/request-id.js

@@ -0,0 +1,30 @@
+/**
+ * `requestId(options)`: one id per request, on `ctx.requestId`, echoed on the answer (errors
+ * included), and bound into `ctx.log` and the request log. An inbound id is never trusted by
+ * default: a client could pick it. `trustInbound` opts in, always or per request (a gateway's peer,
+ * a shared secret), and the id must still pass `validate` (H23: trust is plain code, never a
+ * proxy count). With telemetry on, the id is the root span's `honey.request_id`.
+ */
+import { TRACE } from "../context/context.js";
+import { withHeaders } from "../response/with-headers.js";
+import { namedMiddleware } from "./middleware.js";
+const SAFE_ID = /^[\w.:+/=-]{1,128}$/;
+function safeId(id) {
+    return SAFE_ID.test(id);
+}
+function freshId() {
+    return crypto.randomUUID();
+}
+export function requestId(options = {}) {
+    const header = options.header ?? "x-request-id";
+    const generate = options.generate ?? freshId;
+    const validate = options.validate ?? safeId;
+    const trust = options.trustInbound ?? false;
+    return namedMiddleware("requestId", async (ctx, next) => {
+        const inbound = trust === false ? null : ctx.req.headers.get(header);
+        const reused = inbound !== null && validate(inbound) && (typeof trust === "function" ? trust(ctx) : trust);
+        const id = reused ? inbound : generate();
+        ctx[TRACE]?.annotate("honey.request_id", id);
+        return withHeaders(await next({ requestId: id }), (headers) => headers.set(header, id));
+    });
+}

package/dist/middleware/secure-headers.d.ts

@@ -0,0 +1,18 @@
+import { type MiddlewareFn } from "./middleware.ts";
+export type SecureHeadersOptions = {
+    contentSecurityPolicy?: string;
+    crossOriginEmbedderPolicy?: string;
+    crossOriginOpenerPolicy?: string;
+    crossOriginResourcePolicy?: string;
+    permissionsPolicy?: string;
+    /** Default `strict-origin-when-cross-origin`; `false` leaves it out. */
+    referrerPolicy?: false | string;
+    strictTransportSecurity?: string;
+    /** Default `nosniff`; `false` leaves it out. */
+    xContentTypeOptions?: false | string;
+    /** Default `SAMEORIGIN`; `false` leaves it out. */
+    xFrameOptions?: false | string;
+    /** Default `0` (the legacy auditor off); `false` leaves it out. */
+    xXssProtection?: false | string;
+};
+export declare function secureHeaders(options?: SecureHeadersOptions): MiddlewareFn<{}>;

package/dist/middleware/secure-headers.js

@@ -0,0 +1,36 @@
+/**
+ * `secureHeaders(options)`: the browser security headers every answer should carry. The defaults
+ * (nosniff, SAMEORIGIN, a strict referrer policy, the legacy XSS auditor off) are on unless set to
+ * `false`; CSP, HSTS, permissions and the cross-origin policies are set only when configured. A
+ * header the handler set itself wins: an app-wide default never loosens a stricter route.
+ */
+import { withHeaders } from "../response/with-headers.js";
+import { namedMiddleware } from "./middleware.js";
+/** A default header's value: `false` leaves it out, unset takes the default. */
+function withDefault(value, fallback) {
+    return value === false ? null : (value ?? fallback);
+}
+/** The headers `options` asks for, computed once. */
+function headersFor(options) {
+    const entries = [
+        ["x-content-type-options", withDefault(options.xContentTypeOptions, "nosniff")],
+        ["x-frame-options", withDefault(options.xFrameOptions, "SAMEORIGIN")],
+        ["referrer-policy", withDefault(options.referrerPolicy, "strict-origin-when-cross-origin")],
+        ["x-xss-protection", withDefault(options.xXssProtection, "0")],
+        ["content-security-policy", options.contentSecurityPolicy],
+        ["strict-transport-security", options.strictTransportSecurity],
+        ["permissions-policy", options.permissionsPolicy],
+        ["cross-origin-opener-policy", options.crossOriginOpenerPolicy],
+        ["cross-origin-resource-policy", options.crossOriginResourcePolicy],
+        ["cross-origin-embedder-policy", options.crossOriginEmbedderPolicy],
+    ];
+    return entries.filter((entry) => typeof entry[1] === "string" && entry[1] !== "");
+}
+export function secureHeaders(options = {}) {
+    const headers = headersFor(options);
+    return namedMiddleware("secureHeaders", async (_ctx, next) => withHeaders(await next(), (out) => {
+        for (const [name, value] of headers)
+            if (!out.has(name))
+                out.set(name, value);
+    }));
+}

package/dist/middleware/server-timing.d.ts

@@ -0,0 +1,8 @@
+import { type MiddlewareFn } from "./middleware.ts";
+export type Timing = {
+    end(name: string): void;
+    start(name: string, description?: string): void;
+};
+export declare function serverTiming(): MiddlewareFn<{}, {
+    timing: Timing;
+}>;

package/dist/middleware/server-timing.js

@@ -0,0 +1,52 @@
+/**
+ * `serverTiming()`: `ctx.timing.start(name, description?)` and `end(name)` time the work a request
+ * does, and the answer carries them as `Server-Timing`, a `total` last. A timing left open closes at
+ * the answer; an `end` with no `start` is ignored. Names become tokens and descriptions quoted
+ * strings, so no value can break the header. A `Server-Timing` set below (a handler, an upstream) is
+ * kept, with these added after it.
+ */
+import { withHeaders } from "../response/with-headers.js";
+import { namedMiddleware } from "./middleware.js";
+/* metric names are RFC 9110 tokens; anything else becomes `_` */
+const NON_TOKEN = /[^!#$%&'*+.^`|~\w-]/g;
+/* descriptions are quoted strings: latin1 only, no controls, `\` and `"` escaped */
+const NON_QUOTABLE = /[^\t\x20-\x7e\x80-\xff]/g;
+function tokenOf(name) {
+    return name.replace(NON_TOKEN, "_") || "_";
+}
+function quoted(description) {
+    return `"${description.replace(NON_QUOTABLE, "?").replace(/[\\"]/g, "\\$&")}"`;
+}
+/** The header value: each timing, then the total since `started`, all closed at `now`. */
+function metrics(entries, started, now) {
+    const parts = [];
+    for (const [name, entry] of entries) {
+        const desc = entry.description ? `;desc=${quoted(entry.description)}` : "";
+        parts.push(`${tokenOf(name)}${desc};dur=${((entry.end ?? now) - entry.start).toFixed(2)}`);
+    }
+    parts.push(`total;dur=${(now - started).toFixed(2)}`);
+    return parts.join(", ");
+}
+export function serverTiming() {
+    return namedMiddleware("serverTiming", async (_ctx, next) => {
+        const started = performance.now();
+        const entries = new Map();
+        const timing = {
+            end(name) {
+                const entry = entries.get(name);
+                if (entry)
+                    entry.end = performance.now();
+            },
+            start(name, description) {
+                entries.set(name, { description, end: undefined, start: performance.now() });
+            },
+        };
+        const response = await next({ timing });
+        const value = metrics(entries, started, performance.now());
+        /* get-then-set, not append: append would build native Headers on the plain path */
+        return withHeaders(response, (headers) => {
+            const upstream = headers.get("server-timing");
+            headers.set("server-timing", upstream ? `${upstream}, ${value}` : value);
+        });
+    });
+}

package/dist/middleware/timeout.d.ts

@@ -0,0 +1,6 @@
+import { type MiddlewareFn } from "./middleware.ts";
+export type TimeoutOptions = {
+    /** Milliseconds the chain below may take; 0 answers anything that waits a turn. */
+    duration: number;
+};
+export declare function timeout(options: TimeoutOptions): MiddlewareFn<{}, {}, "request_timeout">;

package/dist/middleware/timeout.js

@@ -0,0 +1,29 @@
+/**
+ * `timeout({ duration })`: answer 504 `request_timeout` when the rest of the chain has not answered
+ * within `duration` ms, and abort `ctx.signal`, so a fetch, query or stream that takes it stops
+ * instead of running on after the 504. Work that ignores the signal still runs; its answer is
+ * dropped. An answer or an error in time goes through untouched.
+ */
+import { ABORT_CONTEXT } from "../context/context.js";
+import { HoneyError } from "../errors/error.js";
+import { namedMiddleware } from "./middleware.js";
+export function timeout(options) {
+    const { duration } = options;
+    if (!(Number.isFinite(duration) && duration >= 0)) {
+        throw new TypeError("timeout: duration must be a finite number of ms, 0 or more");
+    }
+    const mw = (ctx, next) => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new HoneyError({ errorKey: "request_timeout", status: "gateway_timeout" }));
+            ctx[ABORT_CONTEXT](new DOMException("request timed out", "TimeoutError"));
+        }, duration);
+        /* next() never rejects: the boundary turns a throw below into its answer. Whichever comes
+         * first answers; a late answer is dropped, since the promise has settled */
+        void Promise.resolve(next()).then((response) => {
+            clearTimeout(timer);
+            resolve(response);
+        });
+    });
+    mw.errors = ["request_timeout"];
+    return namedMiddleware("timeout", mw);
+}

package/dist/observability/curl-logger.d.ts

@@ -0,0 +1,46 @@
+import { type MiddlewareFn } from "../middleware/middleware.ts";
+import type { Logger } from "../telemetry/logger.ts";
+export type BodyOmittedReason = "content-type" | "disabled" | "missing" | "read-error" | "too-large";
+export type CurlLogData = {
+    bodyIncluded: boolean;
+    bodyOmittedReason: BodyOmittedReason | null;
+    curl: string;
+    duration: number;
+    method: string;
+    path: string;
+    requestId: string | null;
+    status: number;
+};
+/** What `skip` sees: everything known before the command is built. */
+export type CurlSkipData = Pick<CurlLogData, "duration" | "method" | "path" | "requestId" | "status">;
+export type CurlLoggerBodyOptions = {
+    /** Content types whose body is logged: an entry ending in `/` takes the whole family. */
+    allowContentTypes?: readonly string[];
+    /** Default 16 KiB; a longer body is left out, read no further than this. */
+    maxBytes?: number;
+};
+type Redact = (name: string, value: string) => string | null;
+export type CurlLoggerOptions = {
+    body?: boolean | CurlLoggerBodyOptions;
+    /** Take each record instead of the app's logger. */
+    log?: ((data: CurlLogData) => void) | undefined;
+    /** The value to log for a header, or `null` to leave it out. Default `defaultRedactHeader`. */
+    redactHeader?: Redact;
+    /** The same for a query parameter. Default `defaultRedactQueryParam`. */
+    redactQueryParam?: Redact;
+    /** Return true to log nothing for this request; runs before any formatting. */
+    skip?: (data: CurlSkipData) => boolean;
+};
+/** The request log's own sensitive headers, masked. */
+export declare function defaultRedactHeader(name: string, value: string): string | null;
+/** Token-, key-, secret- and password-like query parameters, masked. */
+export declare function defaultRedactQueryParam(name: string, value: string): string | null;
+/** The command and the body's fate for one request, outside the middleware. */
+export declare function buildCurlLogData(request: Request, options?: Pick<CurlLoggerOptions, "body" | "redactHeader" | "redactQueryParam">): Promise<Pick<CurlLogData, "bodyIncluded" | "bodyOmittedReason" | "curl">>;
+type CurlCtx = {
+    readonly log: Logger;
+    readonly path: string;
+    readonly req: Request;
+};
+export declare function curlLogger(options?: CurlLoggerOptions): MiddlewareFn<CurlCtx>;
+export {};