@fishenv/http 0.0.0-stage → 0.0.3

package/dist/core/router.js

@@ -0,0 +1,327 @@
+import { dispatch } from "./compose.js";
+import { buildCors } from "./cors.js";
+import { defaultMethodNotAllowedHandler, defaultNotFoundHandler, } from "./error.js";
+import { Matcher } from "./matcher.js";
+import { createRouteBuilder, createRouteBuilderFromContract, } from "./route-builder.js";
+import { completeUpgrade, createWebSocketRuntime, } from "./upgrade.js";
+const stubContainer = {
+    get() {
+        throw new Error("No DI container configured. Pass one via serve() options.");
+    },
+};
+/**
+ * Router — immutable middleware chain, mutable route registration.
+ *
+ * `.use()` returns a new Router with the extended Ctx type but the same
+ * backing store — routes registered on either instance are collected together.
+ * Route methods (.get, .post, etc.) return a RouteBuilder chain.
+ * Call `.build()` before `.fetch` or `serve()`.
+ *
+ * `Requires` is the context this router expects a parent to provide when it
+ * is mounted via `.add()`. Create one with `r<AppCtx>()`; `.add()` only
+ * accepts it on a parent whose `Ctx` satisfies `AppCtx`, and `serve()` only
+ * accepts routers with no outstanding requirements.
+ */
+export class Router {
+    #prefix;
+    #middlewares;
+    #store;
+    #errorHandler;
+    #notFoundHandler;
+    #cors = null;
+    #corsOptions = null;
+    #env = {
+        development: false,
+        logger: console,
+        websocket: {},
+    };
+    #built = false;
+    #matcher = null;
+    #container = stubContainer;
+    constructor(opts, middlewares, errorHandler, notFoundHandler, store) {
+        this.#prefix = opts?.prefix ?? "";
+        this.#middlewares = middlewares ?? [];
+        this.#errorHandler = errorHandler;
+        this.#notFoundHandler = notFoundHandler;
+        this.#store = store ?? { routes: [], children: [], locked: false };
+    }
+    // ── RouterRef implementation ─────────────────────────────────────────
+    _registerRoute(def) {
+        if (this.#store.locked) {
+            throw new Error("Cannot add routes after build()");
+        }
+        this.#store.routes.push(def);
+    }
+    _getMiddlewares() {
+        return [...this.#middlewares];
+    }
+    _getPrefix() {
+        return this.#prefix;
+    }
+    // ── Middleware ────────────────────────────────────────────────────────
+    use(mw) {
+        return new Router({ prefix: this.#prefix }, [
+            ...this.#middlewares,
+            mw,
+        ], this.#errorHandler, this.#notFoundHandler, this.#store);
+    }
+    // ── Sub-router ───────────────────────────────────────────────────────
+    /** Create a child router and mount it on this one — shorthand for `r<Ctx>(opts)` + `.add()`. */
+    extend(opts) {
+        const child = new Router(opts);
+        this.add(child);
+        return child;
+    }
+    add(...args) {
+        if (this.#store.locked) {
+            throw new Error("Cannot add routers after build()");
+        }
+        const extra = typeof args[0] === "string" ? args.shift() : "";
+        for (const child of args) {
+            this.#store.children.push({
+                router: child,
+                prefix: this.#prefix + extra,
+                middlewares: [...this.#middlewares],
+            });
+        }
+        return this;
+    }
+    // ── Route methods ────────────────────────────────────────────────────
+    get(path) {
+        return createRouteBuilder(this, "GET", path);
+    }
+    post(path) {
+        return createRouteBuilder(this, "POST", path);
+    }
+    put(path) {
+        return createRouteBuilder(this, "PUT", path);
+    }
+    patch(path) {
+        return createRouteBuilder(this, "PATCH", path);
+    }
+    delete(path) {
+        return createRouteBuilder(this, "DELETE", path);
+    }
+    options(path) {
+        return createRouteBuilder(this, "OPTIONS", path);
+    }
+    // ── Contract-driven route ────────────────────────────────────────────
+    /**
+     * Register a route from a `@fishenv/http-contract` endpoint definition, e.g.:
+     *
+     * ```ts
+     * router.contract(contract.users.create).handle(({ body }) => { ... });
+     * ```
+     *
+     * `.handle()` gets exactly the same type safety (body/query/params/output)
+     * as chaining `.input().output().param()` manually, because the contract
+     * endpoint and the route builder share the same shape types.
+     */
+    contract(endpoint) {
+        return createRouteBuilderFromContract(this, endpoint);
+    }
+    // ── Error / not-found ────────────────────────────────────────────────
+    // ── CORS ─────────────────────────────────────────────────────────────
+    cors(options) {
+        this.#cors = buildCors(options);
+        this.#corsOptions = options;
+        return this;
+    }
+    // ── Error / not-found ────────────────────────────────────────────────
+    onError(handler) {
+        this.#errorHandler = handler;
+        return this;
+    }
+    notFound(handler) {
+        this.#notFoundHandler = handler;
+        return this;
+    }
+    // ── Container ────────────────────────────────────────────────────────
+    /** @internal Set by serve(). For testing, call before build(). */
+    _setContainer(container) {
+        this.#container = container;
+    }
+    /** @internal Set by serve() before build(); forwarded to route `onBuild` hooks. */
+    _setEnv(env) {
+        this.#env = { ...this.#env, ...env };
+    }
+    // ── Build ────────────────────────────────────────────────────────────
+    build() {
+        if (this.#built)
+            return; // idempotent
+        const matcher = new Matcher();
+        const allRoutes = this.#collectRoutes();
+        const env = { ...this.#env, cors: this.#corsOptions };
+        for (const route of allRoutes) {
+            route.onBuild?.(env);
+            matcher.add(route.method, route.path, route);
+        }
+        matcher.compile();
+        this.#matcher = matcher;
+        this.#built = true;
+        this.#store.locked = true;
+    }
+    // ── Fetch ────────────────────────────────────────────────────────────
+    /**
+     * Entry point for request handling — available after build().
+     * Use directly for testing without binding a port.
+     */
+    fetch = (req) => this.#handle(req, true);
+    /**
+     * @internal Used by serve(): HEAD responses keep their body so Bun can
+     * derive `Content-Length` from it before dropping it (it does not drain
+     * streams to do so).
+     */
+    _serverFetch = (req) => this.#handle(req, false);
+    async #handle(req, stripHeadBody) {
+        if (!this.#built || !this.#matcher) {
+            throw new Error("Router not built. Call .build() first.");
+        }
+        const url = new URL(req.url);
+        const method = req.method.toUpperCase();
+        const isHead = method === "HEAD";
+        // CORS preflight — short-circuit before route matching
+        if (method === "OPTIONS" && this.#cors) {
+            return this.#cors.preflight(req);
+        }
+        // Try exact method match, then HEAD→GET fallback
+        let matched = this.#matcher.match(method, url.pathname);
+        if (isHead && (!matched || matched.allowedMethods)) {
+            const getMatch = this.#matcher.match("GET", url.pathname);
+            if (getMatch && !getMatch.allowedMethods) {
+                matched = getMatch;
+            }
+        }
+        if (!matched) {
+            const notFound = this.#notFoundHandler ?? defaultNotFoundHandler;
+            return notFound(req);
+        }
+        // 405 — path matched but method didn't
+        if (matched.allowedMethods) {
+            const allowed = isHead && !matched.allowedMethods.includes("HEAD")
+                ? [...matched.allowedMethods, "HEAD"]
+                : matched.allowedMethods;
+            return defaultMethodNotAllowedHandler(req, allowed);
+        }
+        // Build error handler chain: route catch → router onError → default
+        const errorHandlers = [];
+        if (matched.definition.errorHandler) {
+            errorHandlers.push(matched.definition.errorHandler);
+        }
+        if (matched.definition.routerErrorHandlers) {
+            errorHandlers.push(...matched.definition.routerErrorHandlers);
+        }
+        if (this.#errorHandler) {
+            errorHandlers.push(this.#errorHandler);
+        }
+        let response = await dispatch(req, matched.definition, matched.params, this.#container, errorHandlers);
+        // Inject CORS headers on every response
+        if (this.#cors) {
+            response = this.#cors.applyTo(req, response);
+        }
+        // HEAD: strip body. Cancel it so a stream (e.g. SSE) is not left open.
+        if (isHead && stripHeadBody) {
+            response.body?.cancel().catch(() => { });
+            return new Response(null, {
+                status: response.status,
+                headers: response.headers,
+            });
+        }
+        return response;
+    }
+    // ── Internal ─────────────────────────────────────────────────────────
+    /**
+     * Flatten this router's routes plus all mounted children. Child routes are
+     * copied (a child may be mounted more than once) with the mount prefix and
+     * middleware prepended and the child's onError appended to the chain.
+     * Locks every visited store.
+     */
+    #collectRoutes(visiting = new Set()) {
+        if (visiting.has(this.#store)) {
+            throw new Error("Router mount cycle detected");
+        }
+        visiting.add(this.#store);
+        this.#store.locked = true;
+        const routes = [...this.#store.routes];
+        for (const { router: child, prefix, middlewares } of this.#store.children) {
+            if (child.#cors || child.#notFoundHandler) {
+                throw new Error("cors() and notFound() are only supported on the root router");
+            }
+            for (const def of child.#collectRoutes(visiting)) {
+                routes.push({
+                    ...def,
+                    path: prefix + def.path,
+                    middlewares: [...middlewares, ...def.middlewares],
+                    routerErrorHandlers: child.#errorHandler
+                        ? [...(def.routerErrorHandlers ?? []), child.#errorHandler]
+                        : def.routerErrorHandlers,
+                });
+            }
+        }
+        visiting.delete(this.#store);
+        return routes;
+    }
+}
+// ── Factories ────────────────────────────────────────────────────────────
+/**
+ * Create a router. Pass a context type to declare what a parent must provide
+ * when this router is mounted with `.add()`:
+ *
+ * ```ts
+ * // context.ts
+ * export const base = r().use(auth);
+ * export type AppCtx = CtxOf<typeof base>;
+ *
+ * // users.ts — type-only import, no runtime cycle
+ * export const users = r<AppCtx>({ prefix: "/users" });
+ *
+ * // main.ts
+ * serve(base.add(users));
+ * ```
+ */
+export function r(opts) {
+    return new Router(opts);
+}
+export const router = r;
+export function serve(
+// biome-ignore lint/suspicious/noExplicitAny: accepts routers of any context
+app, options) {
+    if (options?.container) {
+        app._setContainer(options.container);
+    }
+    app._setEnv({
+        development: options?.development ?? false,
+        logger: options?.logger ?? console,
+        websocket: options?.websocket ?? {},
+    });
+    app.build(); // idempotent
+    const sockets = createWebSocketRuntime(options?.websocket, options?.logger);
+    const server = Bun.serve({
+        port: options?.port ?? 8000,
+        hostname: options?.hostname ?? "0.0.0.0",
+        development: options?.development ?? false,
+        idleTimeout: options?.idleTimeout ?? 0,
+        fetch: async (req, server) => completeUpgrade(req, await app._serverFetch(req), server),
+        websocket: sockets.websocket,
+        // Errors outside the router's error chain (e.g. a `Bun.file` body that
+        // fails to open while the response is sent) would otherwise reach Bun's
+        // default error page, which exposes messages and paths in development.
+        error: (err) => {
+            options?.logger?.error("Unhandled error while serving request", err);
+            return new Response(null, { status: 500 });
+        },
+    });
+    const handle = {
+        hostname: server.hostname ?? options?.hostname ?? "0.0.0.0",
+        port: server.port ?? options?.port ?? 8000,
+        stop: (force) => {
+            sockets.closeAll();
+            return server.stop(force);
+        },
+    };
+    options?.signal?.addEventListener("abort", () => void handle.stop(), {
+        once: true,
+    });
+    options?.onListen?.({ hostname: handle.hostname, port: handle.port });
+    return handle;
+}

package/dist/core/transport.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Cross-process fan-out seam shared by `@fishenv/http/sse` and
+ * `@fishenv/http/ws`. One adapter (Redis pub/sub, NATS, Postgres LISTEN…)
+ * serves both.
+ */
+import type { Logger } from "./router.ts";
+/** Every message carries the node that published it, for echo suppression. */
+export interface TransportEnvelope {
+    origin: string;
+}
+/** Messages must be JSON-serializable. */
+export interface Transport<M extends TransportEnvelope = TransportEnvelope> {
+    publish(message: M): void | Promise<void>;
+    subscribe(onMessage: (message: M) => void): () => void;
+}
+/** `Omit` that preserves discriminated unions. */
+export type WithoutOrigin<M> = M extends unknown ? Omit<M, "origin"> : never;
+export interface TransportBridge<M extends TransportEnvelope> {
+    /** Random per-process id stamped into `origin`. */
+    readonly nodeId: string;
+    /** Stamp `origin` and publish; failures are logged, never thrown. */
+    publish(message: WithoutOrigin<M>): void;
+    /** Detach from the transport. Idempotent. */
+    close(): void;
+}
+/**
+ * Wrap a (possibly absent) transport with the bookkeeping every hub needs:
+ * a node id, dropping our own echoes, and logging publish failures so a
+ * flaky broker can never break a local send.
+ */
+export declare function createTransportBridge<M extends TransportEnvelope>(transport: Transport<M> | undefined, onRemote: (message: M) => void, opts?: {
+    label?: string;
+    logger?: Pick<Logger, "error">;
+}): TransportBridge<M>;
+/**
+ * In-process transport: every subscriber sees every message. Useful for
+ * tests and for wiring several hubs together in one process.
+ */
+export declare function createMemoryTransport<M extends TransportEnvelope = TransportEnvelope>(): Transport<M>;

package/dist/core/transport.js

@@ -0,0 +1,68 @@
+/**
+ * Cross-process fan-out seam shared by `@fishenv/http/sse` and
+ * `@fishenv/http/ws`. One adapter (Redis pub/sub, NATS, Postgres LISTEN…)
+ * serves both.
+ */
+/**
+ * Wrap a (possibly absent) transport with the bookkeeping every hub needs:
+ * a node id, dropping our own echoes, and logging publish failures so a
+ * flaky broker can never break a local send.
+ */
+export function createTransportBridge(transport, onRemote, opts = {}) {
+    const nodeId = crypto.randomUUID();
+    const label = opts.label ?? "[fishenv.http]";
+    const logger = opts.logger ?? console;
+    const fail = (err) => logger.error(`${label} transport publish failed:`, err);
+    let unsubscribe = transport?.subscribe((message) => {
+        if (message.origin === nodeId)
+            return;
+        try {
+            onRemote(message);
+        }
+        catch (err) {
+            logger.error(`${label} transport message handler failed:`, err);
+        }
+    });
+    return {
+        nodeId,
+        publish(message) {
+            if (transport == null)
+                return;
+            try {
+                const result = transport.publish({
+                    ...message,
+                    origin: nodeId,
+                });
+                if (result instanceof Promise)
+                    result.catch(fail);
+            }
+            catch (err) {
+                fail(err);
+            }
+        },
+        close() {
+            unsubscribe?.();
+            unsubscribe = undefined;
+        },
+    };
+}
+/**
+ * In-process transport: every subscriber sees every message. Useful for
+ * tests and for wiring several hubs together in one process.
+ */
+export function createMemoryTransport() {
+    const subscribers = new Set();
+    return {
+        publish(message) {
+            // Clone through JSON to catch non-serializable payloads early, like a
+            // real broker would.
+            const copy = JSON.parse(JSON.stringify(message));
+            for (const fn of [...subscribers])
+                fn(copy);
+        },
+        subscribe(fn) {
+            subscribers.add(fn);
+            return () => subscribers.delete(fn);
+        },
+    };
+}

package/dist/core/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The "shape" types (schemas, input/output, params, HTTP method, route meta)
+ * live in `@fishenv/http-contract` so that a `ContractBuilder` and a `RouteBuilder`
+ * are built from exactly the same type definitions — no structural-typing
+ * gap between `router.contract(endpoint).handle(...)` and
+ * `router.post(path).input(...).output(...).handle(...)`.
+ */
+export type { AnySchema, BasePathParams, ExtractParams, HttpMethod, InferBody, InferCookies, InferHeaders, InferOutput, InferQuery, InputKind, InputOptions, MergeParam, RouteMeta, ValibotSchema, } from "../contract/index.ts";
+import type { AnySchema, ErrorTypes, HttpMethod, InferBody, InferCookies, InferHeaders, InferQuery, InputKind, InputOptions, RouteMeta } from "../contract/index.ts";
+import type { CorsOptions } from "./cors.ts";
+import type { Logger } from "./router.ts";
+import type { WsServerOptions } from "./upgrade.ts";
+export interface ResolvedInput<K extends InputKind, O extends InputOptions<K>> {
+    kind: K;
+    options: O;
+}
+export type MiddlewareFn<In extends object, Out extends object> = (ctx: In & {
+    req: Request;
+}) => Promise<Out> | Out;
+export type MergeCtx<A extends Record<string, unknown>, B extends Record<string, unknown>> = A & B;
+export type InterceptorState = Record<string, unknown>;
+export type BeforeInterceptorFn<Ctx extends Record<string, unknown>> = (args: {
+    req: Request;
+    ctx: Ctx;
+    state: InterceptorState;
+}) => Promise<void> | void;
+export type AfterInterceptorFn<Ctx extends Record<string, unknown>> = (args: {
+    response: Response;
+    ctx: Ctx;
+    state: InterceptorState;
+}) => Promise<Response> | Response;
+export interface InterceptorPair<Ctx extends Record<string, unknown>> {
+    before?: BeforeInterceptorFn<Ctx>;
+    after?: AfterInterceptorFn<Ctx>;
+}
+export interface HandlerArgs<Ctx extends Record<string, unknown>, K extends InputKind, O extends InputOptions<K>, Params extends Record<string, unknown>> {
+    req: Request;
+    path: Params;
+    ctx: Ctx;
+    body: InferBody<K, O>;
+    headers: InferHeaders<O>;
+    query: InferQuery<O>;
+    cookies: InferCookies<O>;
+    container: DIContainer;
+}
+export type HandlerFn<Ctx extends Record<string, unknown>, K extends InputKind, O extends InputOptions<K>, Params extends Record<string, unknown>, Output> = (args: HandlerArgs<Ctx, K, O, Params>) => [Output] extends [undefined] ? Response | Promise<Response> : Response | Output | Promise<Response | Output>;
+export type ErrorHandlerFn = (err: unknown, args: {
+    req: Request;
+}) => Response | Promise<Response> | null | undefined | void;
+export interface RouteDefinition {
+    method: HttpMethod;
+    path: string;
+    middlewares: MiddlewareFn<Record<string, unknown>, Record<string, unknown>>[];
+    paramSchemas: Map<string, AnySchema>;
+    inputKind: InputKind;
+    inputOptions: InputOptions<InputKind>;
+    outputSchema?: AnySchema;
+    errorTypes?: ErrorTypes;
+    meta?: RouteMeta;
+    interceptors: InterceptorPair<Record<string, unknown>>[];
+    handler: HandlerFn<Record<string, unknown>, InputKind, InputOptions<InputKind>, Record<string, unknown>, unknown>;
+    errorHandler?: ErrorHandlerFn;
+    /** onError handlers of mounted routers, innermost first. Set at build(). */
+    routerErrorHandlers?: ErrorHandlerFn[];
+    /**
+     * Run before *any* middleware (router-level included); throw to reject.
+     * Errors go through the normal error chain.
+     */
+    guards?: RouteGuardFn[];
+    /** Called once per route at `build()` with root-level configuration. */
+    onBuild?: (env: BuildEnv) => void;
+    kind: "http" | "ws" | "sse";
+}
+export type RouteGuardFn = (req: Request) => void | Promise<void>;
+/** Root-level configuration handed to {@link RouteDefinition.onBuild}. */
+export interface BuildEnv {
+    /** The root router's `cors()` options, if configured. */
+    cors: CorsOptions | null;
+    development: boolean;
+    logger: Logger;
+    websocket: WsServerOptions;
+}
+export interface DIContainer {
+    get<T>(token: abstract new (...args: any[]) => T): T;
+}
+export type NotFoundHandler = (req: Request) => Response | Promise<Response>;

package/dist/core/upgrade.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Generic WebSocket upgrade plumbing for Bun — deliberately protocol-agnostic
+ * so core never depends on `@fishenv/http/ws`.
+ *
+ * Bun upgrades from inside `fetch(req, server)`, but route handlers only see
+ * `req` and must return a `Response`. A handler therefore *requests* an
+ * upgrade (keyed by the `Request`, which survives CORS/HEAD response cloning)
+ * and returns a placeholder; `serve()` — or {@link completeUpgrade} for a
+ * hand-rolled `Bun.serve` — performs the actual upgrade.
+ */
+import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
+import type { Logger } from "./router.ts";
+export type UpgradedSocket = ServerWebSocket<SocketData>;
+/** Per-socket lifecycle callbacks, dispatched through `ws.data`. */
+export interface SocketHandlers {
+    open?(ws: UpgradedSocket): void | Promise<void>;
+    message?(ws: UpgradedSocket, message: string | Buffer): void | Promise<void>;
+    close?(ws: UpgradedSocket, code: number, reason: string): void | Promise<void>;
+    drain?(ws: UpgradedSocket): void;
+}
+export interface SocketData {
+    readonly handlers: SocketHandlers;
+    /** The server that owns this socket — needed for native `publish()`. */
+    readonly server: Server<SocketData>;
+    /** Owned by whoever requested the upgrade. */
+    state: unknown;
+}
+export interface UpgradeIntent {
+    handlers: SocketHandlers;
+    state?: unknown;
+    /** Extra handshake response headers, e.g. `Sec-WebSocket-Protocol`. */
+    headers?: HeadersInit;
+}
+/**
+ * Ask the server to upgrade `req` once the response pipeline finishes.
+ *
+ * The returned `426` is only ever seen when no server performs the upgrade —
+ * e.g. when calling `router.fetch()` directly in a unit test.
+ */
+export declare function requestUpgrade(req: Request, intent: UpgradeIntent): Response;
+/** Remove and return the pending upgrade for `req`, if any. */
+export declare function takeUpgrade(req: Request): UpgradeIntent | undefined;
+/**
+ * Finish a request inside Bun's `fetch(req, server)`: performs a pending
+ * upgrade (returning `undefined`, as Bun requires) or passes `res` through.
+ */
+export declare function completeUpgrade(req: Request, res: Response, server: Server<SocketData>): Response | undefined;
+/**
+ * Server-global socket settings. Bun's own defaults are permissive (16 MB
+ * frames and send buffers, slow consumers never dropped); these are not.
+ */
+export interface WsServerOptions {
+    /** Max inbound message size in bytes. Default 64 KiB. */
+    maxPayloadLength?: number;
+    /** Max bytes buffered per socket before backpressure. Default 1 MiB. */
+    backpressureLimit?: number;
+    /** Close sockets that exceed `backpressureLimit`. Default `true`. */
+    closeOnBackpressureLimit?: boolean;
+    /** Seconds without traffic before a socket is closed. Default 120. */
+    idleTimeout?: number;
+    /** Send protocol pings so idle-but-alive sockets stay open. Default `true`. */
+    sendPings?: boolean;
+    /** `permessage-deflate`. Default `false` (decompression-bomb surface). */
+    perMessageDeflate?: boolean;
+}
+export declare const DEFAULT_MAX_PAYLOAD_LENGTH: number;
+export declare const DEFAULT_BACKPRESSURE_LIMIT: number;
+/** `1001 Going Away` — sent to every socket on graceful shutdown. */
+export declare const CLOSE_GOING_AWAY = 1001;
+/** `1011 Internal Error`. */
+export declare const CLOSE_INTERNAL_ERROR = 1011;
+export interface WebSocketRuntime {
+    /** Pass as `websocket` to `Bun.serve`. */
+    readonly websocket: WebSocketHandler<SocketData>;
+    /** Number of sockets currently open on this server. */
+    readonly size: number;
+    /** Close every open socket, e.g. before `server.stop()`. */
+    closeAll(code?: number, reason?: string): void;
+}
+/**
+ * Build the single Bun `websocket` handler that dispatches every event to the
+ * per-socket {@link SocketHandlers}. Also a last-resort guard: a handler that
+ * throws or rejects is logged and its socket closed with `1011`.
+ */
+export declare function createWebSocketRuntime(options?: WsServerOptions, logger?: Pick<Logger, "error">): WebSocketRuntime;