@fishenv/http 0.0.0-stage → 0.0.3

package/dist/sse/index.js

@@ -0,0 +1,40 @@
+/**
+ * Server-Sent Events for `@fishenv/http`.
+ *
+ * An SSE route is an ordinary `GET` route whose handler returns a streaming
+ * `Response`, so middleware, path-param validation, interceptors and the error
+ * chain all work unchanged — no core dispatch branching is required.
+ *
+ * Live connections can be registered in an {@link SseHub} so that any service
+ * can push to a specific client later:
+ *
+ * ```ts
+ * class UserEvents extends SseHub {}
+ *
+ * api.sse("/events").keepalive(30_000).subscribe(UserEvents, ({ ctx }) => ctx.user.id);
+ *
+ * // elsewhere, e.g. inside a use case
+ * userEvents.send(userId, { type: "order.shipped" }, { event: "notification" });
+ * ```
+ *
+ * Module layout:
+ * - `types.ts`         — shared data types
+ * - `encode.ts`        — `text/event-stream` framing
+ * - `connection.ts`    — `SseConnection`, a single live stream
+ * - `response.ts`      — `createSseResponse()`, request → streaming response
+ * - `hub.ts`           — `SseHub`, keyed registry for targeted sends
+ * - `route-builder.ts` — `SseRouteBuilder`
+ * - `router.ts`        — `withSse()` mixin
+ */
+// Connection
+export { SseConnection } from "./connection.js";
+// Framing
+export { encodeSseComment, encodeSseEvent, encodeSseRetry } from "./encode.js";
+// Hub
+export { SseHub } from "./hub.js";
+// Response
+export { createSseResponse } from "./response.js";
+// Route builder
+export { SseRouteBuilder } from "./route-builder.js";
+// Router mixin
+export { withSse } from "./router.js";

package/dist/sse/response.d.ts

@@ -0,0 +1,10 @@
+/** Turning a request into a streaming `text/event-stream` response. */
+import { SseConnection } from "./connection.ts";
+import type { SseCleanupFn, SseConnectionOptions } from "./types.ts";
+export type SseOpenFn = (sse: SseConnection) => void | SseCleanupFn | Promise<void | SseCleanupFn>;
+/**
+ * `onOpen` runs after the response has been handed to the client, so anything
+ * it throws can no longer change the status code — it is logged and the stream
+ * is closed.
+ */
+export declare function createSseResponse(req: Request, options: SseConnectionOptions, onOpen: SseOpenFn): Response;

package/dist/sse/response.js

@@ -0,0 +1,50 @@
+/** Turning a request into a streaming `text/event-stream` response. */
+import { DEFAULT_HIGH_WATER_MARK, SseConnection } from "./connection.js";
+/**
+ * `onOpen` runs after the response has been handed to the client, so anything
+ * it throws can no longer change the status code — it is logged and the stream
+ * is closed.
+ */
+export function createSseResponse(req, options, onOpen) {
+    const highWaterMark = options.highWaterMark ?? DEFAULT_HIGH_WATER_MARK;
+    let connection;
+    const stream = new ReadableStream({
+        start(controller) {
+            const sse = new SseConnection(controller, req, options);
+            connection = sse;
+            if (options.retryMs != null)
+                sse.retry(options.retryMs);
+            if (options.keepaliveMs != null && options.keepaliveMs > 0) {
+                const timer = setInterval(() => sse.comment("ka"), options.keepaliveMs);
+                sse.onClose(() => clearInterval(timer));
+            }
+            // Not awaited: a handler that never resolves must not block the stream.
+            void (async () => {
+                try {
+                    const cleanup = await onOpen(sse);
+                    if (typeof cleanup === "function")
+                        sse.onClose(cleanup);
+                }
+                catch (err) {
+                    console.error("[fishenv.sse] handler error after stream start:", err);
+                    sse.close();
+                }
+            })();
+        },
+        cancel() {
+            // Sole disconnect signal: `req.signal` semantics differ between
+            // runtimes (some abort it on *successful* delivery), which would tear
+            // down healthy streams.
+            connection?.close();
+        },
+    }, new ByteLengthQueuingStrategy({ highWaterMark }));
+    return new Response(stream, {
+        status: 200,
+        headers: {
+            "content-type": "text/event-stream; charset=utf-8",
+            // `no-transform` stops proxies (and server-side compression) from buffering.
+            "cache-control": "no-cache, no-store, no-transform",
+            "x-accel-buffering": "no",
+        },
+    });
+}

package/dist/sse/route-builder.d.ts

@@ -0,0 +1,44 @@
+/** Fluent builder for SSE routes, layered on the core `RouteBuilder`. */
+import type { AnySchema, DIContainer, FinishedRoute, InputOptions, MergeParam, MiddlewareFn, RouteBuilder, RouteMeta } from "../core/index.ts";
+import type { SseConnection } from "./connection.ts";
+import type { SseHub } from "./hub.ts";
+import type { SseCleanupFn, SseConnectionOptions, SseOverflowPolicy } from "./types.ts";
+export interface SseHandlerArgs<Ctx extends Record<string, unknown>, Params extends Record<string, unknown>> {
+    sse: SseConnection;
+    path: Params;
+    ctx: Ctx;
+    req: Request;
+    container: DIContainer;
+}
+export type SseHandlerFn<Ctx extends Record<string, unknown>, Params extends Record<string, unknown>> = (args: SseHandlerArgs<Ctx, Params>) => void | SseCleanupFn | Promise<void | SseCleanupFn>;
+/**
+ * Delegates to the core `RouteBuilder`, so `.param()` / `.with()` carry exactly
+ * the same generics as HTTP routes.
+ */
+export declare class SseRouteBuilder<RouterCtx extends Record<string, unknown>, RouteCtx extends Record<string, unknown>, Params extends Record<string, unknown>> {
+    #private;
+    constructor(inner: RouteBuilder<RouterCtx, RouteCtx, "none", InputOptions<"none">, Params, undefined>, options?: SseConnectionOptions);
+    meta(data: RouteMeta): this;
+    /** Heartbeat interval. Also how the server notices a socket died. */
+    keepalive(intervalMs: number): this;
+    /** Reconnection delay hint sent to the client on connect. */
+    retry(ms: number): this;
+    backpressure(opts: {
+        highWaterMark?: number;
+        onOverflow?: SseOverflowPolicy;
+    }): this;
+    param<Name extends string & keyof Params, S extends AnySchema>(name: Name, schema: S): SseRouteBuilder<RouterCtx, RouteCtx, MergeParam<Params, Name, S>>;
+    with<NewCtx extends Record<string, unknown>>(mw: MiddlewareFn<RouterCtx & RouteCtx, NewCtx>): SseRouteBuilder<RouterCtx, RouteCtx & NewCtx, Params>;
+    /**
+     * Terminal. The returned function (if any) runs when the connection closes.
+     *
+     * `.catch()` on the result only covers failures raised *before* the stream
+     * opens (middleware, param validation) — after that the status is already sent.
+     */
+    handle(fn: SseHandlerFn<RouterCtx & RouteCtx, Params>): FinishedRoute;
+    /**
+     * Terminal shorthand: resolve a hub from the container and register the
+     * connection under the key derived from the request.
+     */
+    subscribe<H extends SseHub>(token: abstract new (...args: any[]) => H, key: (args: SseHandlerArgs<RouterCtx & RouteCtx, Params>) => string): FinishedRoute;
+}

package/dist/sse/route-builder.js

@@ -0,0 +1,65 @@
+/** Fluent builder for SSE routes, layered on the core `RouteBuilder`. */
+import { createSseResponse } from "./response.js";
+/**
+ * Delegates to the core `RouteBuilder`, so `.param()` / `.with()` carry exactly
+ * the same generics as HTTP routes.
+ */
+export class SseRouteBuilder {
+    #inner;
+    #options;
+    constructor(inner, options = {}) {
+        this.#inner = inner;
+        this.#options = options;
+    }
+    meta(data) {
+        this.#inner.meta(data);
+        return this;
+    }
+    /** Heartbeat interval. Also how the server notices a socket died. */
+    keepalive(intervalMs) {
+        this.#options.keepaliveMs = intervalMs;
+        return this;
+    }
+    /** Reconnection delay hint sent to the client on connect. */
+    retry(ms) {
+        this.#options.retryMs = ms;
+        return this;
+    }
+    backpressure(opts) {
+        if (opts.highWaterMark != null) {
+            this.#options.highWaterMark = opts.highWaterMark;
+        }
+        if (opts.onOverflow != null)
+            this.#options.onOverflow = opts.onOverflow;
+        return this;
+    }
+    param(name, schema) {
+        return new SseRouteBuilder(this.#inner.param(name, schema), {
+            ...this.#options,
+        });
+    }
+    with(mw) {
+        return new SseRouteBuilder(this.#inner.with(mw), { ...this.#options });
+    }
+    /**
+     * Terminal. The returned function (if any) runs when the connection closes.
+     *
+     * `.catch()` on the result only covers failures raised *before* the stream
+     * opens (middleware, param validation) — after that the status is already sent.
+     */
+    handle(fn) {
+        const options = { ...this.#options };
+        const route = this.#inner.handle(({ req, path, ctx, container }) => createSseResponse(req, options, (sse) => fn({ sse, path, ctx, req, container })));
+        route.definition.kind = "sse";
+        return route;
+    }
+    /**
+     * Terminal shorthand: resolve a hub from the container and register the
+     * connection under the key derived from the request.
+     */
+    subscribe(
+    // biome-ignore lint/suspicious/noExplicitAny: intentional any
+    token, key) {
+        return this.handle((args) => args.container.get(token).add(key(args), args.sse));
+    }
+}

package/dist/sse/router.d.ts

@@ -0,0 +1,11 @@
+/** The `withSse()` mixin that adds `.sse()` to a core `Router`. */
+import type { BasePathParams, Router } from "../core/index.ts";
+import { SseRouteBuilder } from "./route-builder.ts";
+export interface SseRouter<Ctx extends Record<string, unknown>> {
+    sse<P extends string>(path: P): SseRouteBuilder<Ctx, Record<never, never>, BasePathParams<P>>;
+}
+/**
+ * `.use()` returns a *new* router, so apply `withSse` last:
+ * `withSse(r({ prefix: "/api" }).use(auth))`.
+ */
+export declare function withSse<Ctx extends Record<string, unknown>, Req extends Record<string, unknown> = Record<never, never>>(router: Router<Ctx, Req>): Router<Ctx, Req> & SseRouter<Ctx>;

package/dist/sse/router.js

@@ -0,0 +1,16 @@
+/** The `withSse()` mixin that adds `.sse()` to a core `Router`. */
+import { createRouteBuilder } from "../core/index.js";
+import { SseRouteBuilder } from "./route-builder.js";
+/**
+ * `.use()` returns a *new* router, so apply `withSse` last:
+ * `withSse(r({ prefix: "/api" }).use(auth))`.
+ */
+export function withSse(router) {
+    const target = router;
+    Object.defineProperty(target, "sse", {
+        value: (path) => new SseRouteBuilder(createRouteBuilder(router, "GET", path), {}),
+        enumerable: false,
+        configurable: true,
+    });
+    return target;
+}

package/dist/sse/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared SSE data types. Deliberately free of class references so every other
+ * module in this package can import from here without a cycle.
+ */
+import type { Transport, TransportEnvelope } from "../core/transport.ts";
+export interface SseEventOptions {
+    /** `event:` field — the client-side listener name. Defaults to `message`. */
+    event?: string;
+    /** `id:` field — echoed back by the browser as `Last-Event-ID` on reconnect. */
+    id?: string;
+    /** `retry:` field — reconnection delay in milliseconds. */
+    retry?: number;
+}
+/** Return value is ignored; a returned promise is awaited only for error logging. */
+export type SseCleanupFn = () => unknown;
+/** What to do when a client is too slow to drain the send buffer. */
+export type SseOverflowPolicy = "close" | "drop";
+export interface SseConnectionOptions {
+    /** Send a `:` comment every N ms. Also how dead sockets get detected. */
+    keepaliveMs?: number;
+    /** Initial `retry:` hint sent as soon as the stream opens. */
+    retryMs?: number;
+    /** Send-buffer size in bytes before the overflow policy kicks in. */
+    highWaterMark?: number;
+    /** Default `"close"` — a stalled client is dropped and reconnects on its own. */
+    onOverflow?: SseOverflowPolicy;
+}
+/** Cross-process fan-out envelope. Must be JSON-serializable. */
+export interface SseTransportMessage extends TransportEnvelope {
+    /** `null` means broadcast to every connection. */
+    key: string | null;
+    data: unknown;
+    event?: string;
+    id?: string;
+    retry?: number;
+    /** Node that published it — used to suppress echo back to the sender. */
+    origin: string;
+}
+/** Seam for multi-instance deployments (Redis pub/sub, NATS, Postgres LISTEN…). */
+export type SseTransport = Transport<SseTransportMessage>;
+export interface SseHubOptions {
+    transport?: SseTransport;
+}

package/dist/sse/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared SSE data types. Deliberately free of class references so every other
+ * module in this package can import from here without a cycle.
+ */

package/dist/static/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Static file serving for `@fishenv/http`.
+ *
+ * `staticFiles()` returns an ordinary router, so it is mounted, prefixed and
+ * wrapped in middleware like any other:
+ *
+ * ```ts
+ * app.add("/assets", staticFiles({ root: "./public" }));
+ * app.add(api).add(spa({ root: "./dist", exclude: ["api/**"] }));
+ * ```
+ *
+ * Requests are decoded and validated per segment, confined to the real root
+ * (symlinks included), dotfiles are hidden and every rejection is a plain 404.
+ *
+ * Module layout:
+ * - `types.ts`     — option and rule types
+ * - `options.ts`   — validation and normalization at creation (throws)
+ * - `resolve.ts`   — request path → file on disk (the security core)
+ * - `rules.ts`     — route-style globs for rules and `exclude`
+ * - `negotiate.ts` — Accept-Encoding, Accept and conditional requests
+ * - `response.ts`  — headers and body; `serveFile()`
+ * - `router.ts`    — `staticFiles()`, `spa()`, `withStatic()`
+ */
+export { serveFile } from "./response.ts";
+export type { StaticRouter } from "./router.ts";
+export { spa, staticFiles, withStatic } from "./router.ts";
+export type { SetHeadersFn, StaticCacheOptions, StaticEncoding, StaticFileInfo, StaticOptions, StaticResponseOptions, StaticRule, } from "./types.ts";

package/dist/static/index.js

@@ -0,0 +1,25 @@
+/**
+ * Static file serving for `@fishenv/http`.
+ *
+ * `staticFiles()` returns an ordinary router, so it is mounted, prefixed and
+ * wrapped in middleware like any other:
+ *
+ * ```ts
+ * app.add("/assets", staticFiles({ root: "./public" }));
+ * app.add(api).add(spa({ root: "./dist", exclude: ["api/**"] }));
+ * ```
+ *
+ * Requests are decoded and validated per segment, confined to the real root
+ * (symlinks included), dotfiles are hidden and every rejection is a plain 404.
+ *
+ * Module layout:
+ * - `types.ts`     — option and rule types
+ * - `options.ts`   — validation and normalization at creation (throws)
+ * - `resolve.ts`   — request path → file on disk (the security core)
+ * - `rules.ts`     — route-style globs for rules and `exclude`
+ * - `negotiate.ts` — Accept-Encoding, Accept and conditional requests
+ * - `response.ts`  — headers and body; `serveFile()`
+ * - `router.ts`    — `staticFiles()`, `spa()`, `withStatic()`
+ */
+export { serveFile } from "./response.js";
+export { spa, staticFiles, withStatic } from "./router.js";

package/dist/static/negotiate.d.ts

@@ -0,0 +1,23 @@
+import type { StaticEncoding } from "./types.ts";
+interface QItem {
+    value: string;
+    q: number;
+}
+/** Parse a `token;q=0.5, other` header into lowercase values with weights. */
+export declare function parseQList(header: string): QItem[];
+/**
+ * Pick the best available encoding for an `Accept-Encoding` header. Highest
+ * q wins; ties go to `available` order (server preference). `q=0` refuses a
+ * coding, `*` covers codings not listed. No header means identity only.
+ */
+export declare function chooseEncoding(header: string | null, available: StaticEncoding[]): StaticEncoding | undefined;
+/** True when the client accepts an HTML document (used for SPA fallback). */
+export declare function acceptsHtml(header: string | null): boolean;
+/** Weak ETag from size + mtime (no inode), suffixed per encoding. */
+export declare function makeEtag(size: number, mtimeMs: number, encoding?: StaticEncoding): string;
+/**
+ * Evaluate `If-None-Match` (weak comparison, `*`, lists), falling back to
+ * `If-Modified-Since` only when `If-None-Match` is absent (RFC 9110 §13.2.2).
+ */
+export declare function isNotModified(req: Request, etag: string | undefined, mtimeMs: number | undefined): boolean;
+export {};

package/dist/static/negotiate.js

@@ -0,0 +1,85 @@
+/** Parse a `token;q=0.5, other` header into lowercase values with weights. */
+export function parseQList(header) {
+    const items = [];
+    for (const part of header.split(",")) {
+        const [rawValue, ...params] = part.split(";");
+        const value = rawValue.trim().toLowerCase();
+        if (!value)
+            continue;
+        let q = 1;
+        for (const param of params) {
+            const [k, v] = param.split("=").map((s) => s.trim());
+            if (k.toLowerCase() === "q") {
+                const n = Number(v);
+                q = Number.isFinite(n) ? Math.min(Math.max(n, 0), 1) : 0;
+            }
+        }
+        items.push({ value, q });
+    }
+    return items;
+}
+const CODING_NAMES = {
+    br: ["br"],
+    gzip: ["gzip", "x-gzip"],
+};
+/**
+ * Pick the best available encoding for an `Accept-Encoding` header. Highest
+ * q wins; ties go to `available` order (server preference). `q=0` refuses a
+ * coding, `*` covers codings not listed. No header means identity only.
+ */
+export function chooseEncoding(header, available) {
+    if (!header || available.length === 0)
+        return undefined;
+    const items = parseQList(header);
+    const star = items.find((i) => i.value === "*")?.q;
+    let best;
+    let bestQ = 0;
+    for (const enc of available) {
+        const explicit = items.find((i) => CODING_NAMES[enc].includes(i.value));
+        const q = explicit?.q ?? star ?? 0;
+        if (q > bestQ) {
+            best = enc;
+            bestQ = q;
+        }
+    }
+    return best;
+}
+/** True when the client accepts an HTML document (used for SPA fallback). */
+export function acceptsHtml(header) {
+    if (!header)
+        return true;
+    return parseQList(header).some((i) => i.q > 0 &&
+        (i.value === "text/html" || i.value === "text/*" || i.value === "*/*"));
+}
+/** Weak ETag from size + mtime (no inode), suffixed per encoding. */
+export function makeEtag(size, mtimeMs, encoding) {
+    const suffix = encoding ? `-${encoding}` : "";
+    return `W/"${size.toString(16)}-${Math.floor(mtimeMs).toString(16)}${suffix}"`;
+}
+function opaqueTag(tag) {
+    return tag.trim().replace(/^W\//, "");
+}
+/**
+ * Evaluate `If-None-Match` (weak comparison, `*`, lists), falling back to
+ * `If-Modified-Since` only when `If-None-Match` is absent (RFC 9110 §13.2.2).
+ */
+export function isNotModified(req, etag, mtimeMs) {
+    const inm = req.headers.get("if-none-match");
+    if (inm !== null) {
+        if (!etag)
+            return false;
+        if (inm.trim() === "*")
+            return true;
+        const ours = opaqueTag(etag);
+        return inm.split(",").some((t) => opaqueTag(t) === ours);
+    }
+    const ims = req.headers.get("if-modified-since");
+    if (ims !== null && mtimeMs !== undefined) {
+        const since = Date.parse(ims);
+        if (Number.isNaN(since))
+            return false;
+        // HTTP dates have second precision.
+        return Math.floor(mtimeMs / 1000) * 1000 <= since;
+    }
+    return false;
+}

package/dist/static/options.d.ts

@@ -0,0 +1,44 @@
+import { type CanonicalCheck, type SymlinkPolicy } from "./resolve.ts";
+import { type CompiledRule } from "./rules.ts";
+import type { SetHeadersFn, StaticEncoding, StaticOptions, StaticResponseOptions } from "./types.ts";
+/** Normalized response options. */
+export interface ResponseConfig {
+    precompressed: StaticEncoding[];
+    etag: boolean;
+    lastModified: boolean;
+    cacheControl: string;
+    headers: Record<string, string>;
+    untrusted: boolean;
+    setHeaders?: SetHeadersFn;
+}
+export interface StaticConfig extends ResponseConfig {
+    root: string;
+    index: string[];
+    extensions: string[];
+    dotfiles: "hide" | "allow";
+    allowDotfiles: Set<string>;
+    symlinks: SymlinkPolicy;
+    rules: CompiledRule[];
+    exclude: RegExp[];
+    fallback?: string[];
+    cache?: {
+        ttlMs: number;
+        maxEntries: number;
+    };
+    windows: boolean;
+    /** `passesFilePolicy` bound to this config, for `locate()`. */
+    allowCanonical: CanonicalCheck;
+}
+/** Validate and normalize the options shared with `serveFile()`. */
+export declare function compileResponseOptions(opts: StaticResponseOptions): ResponseConfig;
+export declare function compileServeFileOptions(opts: StaticResponseOptions): ResponseConfig;
+/** True when `segments` may be served at all (dotfiles, deny, exclude). */
+export declare function isServable(cfg: StaticConfig, segments: string[]): boolean;
+/**
+ * Dotfile and deny rules. Unlike `exclude`, which carves out URL space,
+ * these protect files, so they are also applied to the canonical on-disk
+ * name of whatever a request resolves to.
+ */
+export declare function passesFilePolicy(cfg: StaticConfig, segments: string[]): boolean;
+/** Validate options and resolve the root. Throws on any misconfiguration. */
+export declare function compileStaticOptions(opts: StaticOptions): StaticConfig;