@dunx/http 0.1.0

package/dist/server/application.d.ts

@@ -0,0 +1,84 @@
+import type { BunRequest } from 'bun';
+import { type App, type AppOptions, type Ctor, type InjectionToken, type ShutdownSignal } from '@dunx/core';
+import { type DiscoveredRoute } from '../route/discover.js';
+import type { WebSocketRuntime } from '../ws/adapter.js';
+import type { PubSubRelay } from '../ws/relay.js';
+import type { SocketOptions } from '../ws/socket.js';
+import type { CorsOptions } from './cors.js';
+import { type ErrorMapper } from './errors.js';
+import type { Middleware } from './middleware.js';
+import { type RequestLoggingOptions } from './request-logging.js';
+import { type AppSettings } from './settings.js';
+export interface HttpOptions extends AppOptions {
+    readonly port?: number;
+    /** Resolved from the container, so middleware can inject(). */
+    readonly middleware?: readonly Ctor<Middleware>[];
+    readonly onError?: ErrorMapper;
+    /**
+     * One structured entry per request, on by default. `false` removes it; an
+     * options object tunes what it records. See {@link RequestLoggingMiddleware}.
+     *
+     * It is the **outermost** middleware, ahead of anything `middleware` declares,
+     * so a request rejected by a guard is still logged with the status it got.
+     */
+    readonly requestLogging?: boolean | RequestLoggingOptions;
+    /**
+     * Bun's `websocket` options, plus where a throwing handler goes. Server-wide, so
+     * they live here next to `middleware` rather than on a module: gateways
+     * themselves are declared in `@Module({ providers })`.
+     */
+    readonly websocket?: SocketOptions;
+    /**
+     * Multi-node websocket fan-out. Absent — the default — means `PubSub` publishes
+     * to this process only, which is exactly Bun's native pub/sub and costs nothing.
+     *
+     * `new RedisRelay({ url })` is the batteries-included one. Anything with a
+     * `publish` and a `subscribe` fits, including `@dunx/infra`'s `RedisConnection`,
+     * which has to come out of the container and so goes through
+     * `app.get(PubSub).relayThrough(...)` instead of this option.
+     */
+    readonly relay?: PubSubRelay;
+    /** The broker channel the relay carries frames on. @default 'dunx:ws' */
+    readonly relayChannel?: string;
+}
+/**
+ * Everything below `listen()` configures the route table, which is built exactly
+ * once — when the server binds. Calling any of them afterwards throws rather than
+ * being quietly dropped.
+ */
+export interface HttpApp extends App {
+    /** Prefixes every discovered route. Last call wins. */
+    setGlobalPrefix(prefix: string): this;
+    /** Appends middleware, after anything `HttpOptions.middleware` declared. */
+    use(...middleware: readonly Ctor<Middleware>[]): this;
+    set<K extends keyof AppSettings>(key: K, value: AppSettings[K]): this;
+    setting<K extends keyof AppSettings>(key: K): AppSettings[K];
+    /** Mounts an `OPTIONS` preflight per path. Last call wins. */
+    enableCors(options?: CorsOptions): this;
+    /** The same `inject(ClientAddress)` singleton — honours `'trust proxy'`. */
+    clientIp(req: BunRequest): string | undefined;
+    /** Every gateway path this app upgrades on, exactly as mounted. */
+    readonly gatewayPaths: readonly string[];
+    listen(port?: number): Promise<string>;
+}
+export declare class HttpApplication implements HttpApp {
+    #private;
+    readonly closed: Promise<void>;
+    readonly gatewayPaths: readonly string[];
+    constructor(app: App, discovered: readonly DiscoveredRoute[], options: HttpOptions, websocket?: WebSocketRuntime);
+    get<T>(token: InjectionToken<T>): T;
+    setGlobalPrefix(prefix: string): this;
+    use(...middleware: readonly Ctor<Middleware>[]): this;
+    set<K extends keyof AppSettings>(key: K, value: AppSettings[K]): this;
+    setting<K extends keyof AppSettings>(key: K): AppSettings[K];
+    enableCors(options?: CorsOptions): this;
+    clientIp(req: BunRequest): string | undefined;
+    /**
+     * The one `Bun.serve` call. A gateway's upgrade is a native `GET` route in the
+     * same table, so Bun's router — not a hand-written `fetch` fallback — is what
+     * matches an upgrade, and no `fetch` handler is needed at all.
+     */
+    listen(port?: number): Promise<string>;
+    shutdown(): Promise<void>;
+    enableShutdownHooks(signals?: readonly ShutdownSignal[]): this;
+}

package/dist/server/client-address.d.ts

@@ -0,0 +1,15 @@
+import type { BunRequest, Server } from 'bun';
+export interface AddressSource {
+    readonly server: Server<unknown>;
+    readonly trustProxy: boolean;
+}
+/**
+ * The client's address, honouring the `'trust proxy'` setting. Every class is
+ * injectable, so `inject(ClientAddress)` in a middleware or controller needs no
+ * registration; `app.clientIp(req)` is the same instance.
+ */
+export declare class ClientAddress {
+    of(req: BunRequest): string | undefined;
+}
+/** Internal: `listen()` hands the bound server to the resolved singleton. */
+export declare const attachAddressSource: (target: ClientAddress, source: AddressSource) => void;

package/dist/server/context.d.ts

@@ -0,0 +1,21 @@
+import type { DiscoveredRoute } from '../route/discover.js';
+import type { HttpMethod } from '../route/marker.js';
+import type { MetaKey } from '../route/metadata.js';
+/**
+ * Which route the middleware is running for, and what that route's decorators
+ * declared. `get` resolves the handler's metadata first and the controller class's
+ * second — the same override direction as Nest's `getAllAndOverride`.
+ */
+export interface RouteContext {
+    readonly controller: string;
+    readonly handler: string;
+    readonly method: HttpMethod;
+    readonly path: string;
+    get<T>(key: MetaKey<T>): T | undefined;
+}
+/**
+ * One frozen context per route, built when the table is built and closed over by
+ * the chain. The merge already happened at discovery, so `get` is a Map lookup —
+ * not a prototype walk, and nothing is read per request.
+ */
+export declare const buildContext: (route: DiscoveredRoute) => RouteContext;

package/dist/server/cors.d.ts

@@ -0,0 +1,26 @@
+import type { RouteHandler } from './middleware.js';
+export type CorsOrigin = string | readonly string[] | ((origin: string) => boolean);
+export interface CorsOptions {
+    /**
+     * `'*'` by default. A concrete string, a list, or a predicate all answer with the
+     * caller's own origin only when it is allowed — a request from anywhere else gets
+     * no CORS headers at all, which is what makes the browser block it.
+     */
+    readonly origin?: CorsOrigin;
+    /** Defaults to the methods actually declared on the path. */
+    readonly methods?: readonly string[];
+    /** Echoes `Access-Control-Request-Headers` when omitted. */
+    readonly allowedHeaders?: readonly string[];
+    readonly exposedHeaders?: readonly string[];
+    readonly credentials?: boolean;
+    /** Seconds a browser may cache the preflight for. */
+    readonly maxAge?: number;
+}
+/** Adds the response-side CORS headers. One extra closure per route, at boot. */
+export declare const withCors: (options: CorsOptions, handler: RouteHandler) => RouteHandler;
+/**
+ * `Bun.serve({ routes })` answers a method miss with 404, so a preflight cannot be
+ * inferred — every CORS-enabled path gets its own `OPTIONS` handler, built at boot
+ * from the methods that path actually declares.
+ */
+export declare const preflight: (options: CorsOptions, methods: readonly string[]) => RouteHandler;

package/dist/server/errors.d.ts

@@ -0,0 +1,25 @@
+import { AppError } from '@dunx/core';
+export declare class HttpError extends AppError {
+    readonly status: number;
+    name: string;
+    constructor(status: number, message: string, options?: ErrorOptions);
+}
+/** Which declared schema rejected the request. */
+export type InputSource = 'body' | 'query' | 'params';
+/** A Standard Schema issue, flattened: `path` is dotted, or absent at the root. */
+export interface ValidationIssue {
+    readonly message: string;
+    readonly path?: string;
+}
+/**
+ * A declared schema rejected the input. Always a 400, and the issues survive into
+ * the response body — a caller cannot fix what it cannot see.
+ */
+export declare class ValidationError extends HttpError {
+    readonly source: InputSource;
+    readonly issues: readonly ValidationIssue[];
+    name: string;
+    constructor(source: InputSource, issues: readonly ValidationIssue[]);
+}
+export type ErrorMapper = (error: unknown, req: Request) => Response;
+export declare const defaultErrorMapper: ErrorMapper;

package/dist/server/factory.d.ts

@@ -0,0 +1,12 @@
+import { type ModuleRef } from '@dunx/core';
+import { type HttpApp, type HttpOptions } from './application.js';
+export type { HttpApp, HttpOptions } from './application.js';
+export declare class HttpFactory {
+    /**
+     * Boots the container, discovers every controller's routes and every gateway's
+     * handlers, and rejects a collision in either. The `Bun.serve` route table itself
+     * is built by `listen()`, so `setGlobalPrefix`, `use`, `set` and `enableCors` can
+     * still affect it.
+     */
+    static create(root: ModuleRef, options?: HttpOptions): Promise<HttpApp>;
+}

package/dist/server/input.d.ts

@@ -0,0 +1,17 @@
+import type { BunRequest } from 'bun';
+import type { RouteInput, RouteSchemas } from '../route/schema.js';
+/**
+ * Built once per route at boot. A route that declares nothing gets the identity
+ * reader — no parse, no validation, not even a promise.
+ *
+ * A reader **returns a promise only when it has something to wait for**. A `body`
+ * schema always does; `query` and `params` against a synchronous validator — which
+ * zod, Valibot and ArkType all are — resolve without one.
+ */
+export type InputReader = (req: BunRequest) => RouteInput | Promise<RouteInput>;
+/**
+ * Folds the declared schemas into a single closure, the way `compose` folds
+ * middleware: which parsers and validators run is decided here, at boot, so per
+ * request there is no metadata to read and no branch left to take.
+ */
+export declare const buildInputReader: (options: RouteSchemas | undefined) => InputReader;

package/dist/server/middleware.d.ts

@@ -0,0 +1,20 @@
+import type { BunRequest } from 'bun';
+import type { RouteContext } from './context.js';
+export type Next = () => Promise<Response>;
+/**
+ * The single extension point. A guard is middleware that throws, an interceptor
+ * wraps `next()`, a filter is the error mapper. `ctx` names the route and carries
+ * what its decorators declared, resolved at boot — so a guard costs a Map lookup.
+ */
+export interface Middleware {
+    handle(req: BunRequest, ctx: RouteContext, next: Next): Promise<Response>;
+}
+export type RouteHandler = (req: BunRequest) => Promise<Response>;
+/**
+ * What goes into the `Bun.serve` route table. Wider than `RouteHandler` because
+ * Bun accepts a plain `Response`, which is what lets a route with nothing to
+ * await skip promises altogether — see `buildRoutes`.
+ */
+export type ServedHandler = (req: BunRequest) => Response | Promise<Response>;
+/** Folded into one closure per route at boot — no per-request array iteration. */
+export declare const compose: (middleware: readonly Middleware[], ctx: RouteContext, handler: RouteHandler) => RouteHandler;

package/dist/server/request-logging.d.ts

@@ -0,0 +1,55 @@
+import { Logger, RequestContext } from '@dunx/core';
+import type { BunRequest } from 'bun';
+import type { RouteContext } from './context.js';
+import type { Middleware, Next } from './middleware.js';
+export declare const REQUEST_ID_HEADER = "x-request-id";
+export interface RequestLoggingOptions {
+    /** Bodies past this many characters are logged as a size. Default 2048. `0` omits them. */
+    readonly maxBodyLength?: number;
+    /**
+     * Log the request body. Default **`false`**.
+     *
+     * Reading it means `req.clone().text()` — a second copy of every payload,
+     * buffered and parsed, on the hot path. Measured on the `validate` scenario in
+     * `tools/bench`, turning both body options on costs roughly two thirds of the
+     * throughput. It is also the field most likely to contain a password.
+     *
+     * Turn it on in development, where seeing the payload is the point.
+     */
+    readonly requestBody?: boolean;
+    /** Log the response body. Default **`false`** — same clone-and-buffer cost. */
+    readonly responseBody?: boolean;
+    /** Paths to skip entirely — a health check polled every second, say. */
+    readonly ignore?: readonly string[];
+}
+/**
+ * One structured entry per request, carrying the request and its response.
+ *
+ * Installed by `HttpFactory.create` unless `requestLogging: false`. It injects
+ * `Logger` and `RequestContext` — both `@dunx/core` contracts, both bound by
+ * default — so it works with no logging module imported, and picks up
+ * `@arkv/logger` automatically once `@dunx/infra/logger` is.
+ *
+ * **One entry, not two.** Nest needs a middleware for the inbound half and an
+ * interceptor for the outbound one, because they are different classes and the
+ * interceptor cannot see what the middleware saw. Here they are the same
+ * closure, so there is no pair to correlate by `requestId` to find out how a
+ * call ended. A 4xx is the same line at `warn`, a 5xx at `error`.
+ *
+ * Everything the handler logs in between carries `requestId`, `method`, `event`
+ * and `context` without being passed anything, because the whole call runs
+ * inside `runWithContext`.
+ *
+ * **Nothing here is `async`.** Reading the request or the response body are the
+ * only steps that can ever wait, both are off by default, and both are adopted
+ * with `.then` rather than awaited — the same rule `input.ts` follows, for the
+ * same measured reason. An `async` scope callback alone cost 0.44 µs/request
+ * against a synchronous one on raw `Bun.serve`.
+ */
+export declare class RequestLoggingMiddleware implements Middleware {
+    #private;
+    private readonly logger;
+    private readonly context;
+    constructor(logger: Logger, context: RequestContext, options?: RequestLoggingOptions);
+    handle(req: BunRequest, ctx: RouteContext, next: Next): Promise<Response>;
+}

package/dist/server/routes.d.ts

@@ -0,0 +1,47 @@
+import { type Ctor } from '@dunx/core';
+import type { DiscoveredRoute } from '../route/discover.js';
+import type { HttpMethod } from '../route/marker.js';
+import type { UpgradeHandler } from '../ws/adapter.js';
+import { type CorsOptions } from './cors.js';
+import { type ErrorMapper } from './errors.js';
+import { type Middleware, type RouteHandler, type ServedHandler } from './middleware.js';
+/** How a `@UseGuards` class becomes an instance. `listen()` passes `app.get`. */
+export type GuardResolver = (guard: Ctor<Middleware>) => Middleware;
+/** `OPTIONS` is never a `@Get`-style route — only CORS mounts one. */
+export type RouteMethod = HttpMethod | 'OPTIONS';
+export type BunRoutes = Record<string, Partial<Record<RouteMethod, ServedHandler>>>;
+/**
+ * What `listen()` hands `Bun.serve`: the HTTP table plus one `GET` per gateway,
+ * whose handler may answer `undefined` because the socket was upgraded.
+ */
+export type ServeRoutes = Record<string, Partial<Record<RouteMethod, ServedHandler | UpgradeHandler>>>;
+/**
+ * Bun silently lets one route win on a collision, so a duplicate method+path is a
+ * boot error naming both handlers. Run twice: once at `create()` on the discovered
+ * paths, and again from `buildRoutes` at `listen()` on the final, prefixed ones.
+ */
+export declare const assertNoCollisions: (discovered: readonly DiscoveredRoute[]) => void;
+/**
+ * A gateway's upgrade is a native route like any other, so a path claimed by both a
+ * controller and a gateway would lose one of them when the two tables merge.
+ */
+export declare const assertNoGatewayCollisions: (discovered: readonly DiscoveredRoute[], gatewayPaths: readonly string[]) => void;
+/**
+ * The two tables in one. A gateway's `GET` is what Bun's router matches on an
+ * upgrade — the reason no `fetch` handler is needed for a socket to connect.
+ */
+export declare const withUpgradeRoutes: (routes: BunRoutes, gateways: ReadonlyMap<string, UpgradeHandler>) => ServeRoutes;
+/**
+ * Bun answers an unmatched path itself, so nothing in the middleware chain ever
+ * sees it — which makes a 404 invisible to request logging, metrics and tracing.
+ *
+ * This is the only `fetch` handler dunx installs, and it is not a router: Bun
+ * still does all the matching, and this runs only once Bun has decided nothing
+ * matched. It puts the global middleware in front of a 404 in the framework's
+ * own error shape.
+ *
+ * Composed per request rather than at boot, because the context names the path
+ * that missed. That allocation is on the 404 path only.
+ */
+export declare const buildFallback: (middleware?: readonly Middleware[], onError?: ErrorMapper, cors?: CorsOptions) => RouteHandler;
+export declare const buildRoutes: (discovered: readonly DiscoveredRoute[], middleware?: readonly Middleware[], onError?: ErrorMapper, cors?: CorsOptions, resolve?: GuardResolver) => BunRoutes;

package/dist/server/settings.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The settings `app.set()` accepts. A key has to be declared here to be settable,
+ * so the map is checked at compile time instead of being a string bag — a typo is
+ * a type error, not a setting that silently never applies.
+ */
+export interface AppSettings {
+    /**
+     * Resolve the client address from `X-Forwarded-For` rather than the socket. Only
+     * turn it on behind a proxy that rewrites the header: a direct client can send
+     * whatever it likes.
+     */
+    'trust proxy': boolean;
+}
+export declare const defaultSettings: () => AppSettings;

package/dist/server/status.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Frozen object plus an indexed-access union, not an `enum`. An enum emits a
+ * runtime object that no other syntax can produce, which is why the repo bans it —
+ * see CLAUDE.md. This gives the same `HttpStatusCode.NOT_FOUND` ergonomics, a
+ * narrower type, and erases cleanly.
+ */
+export declare const HttpStatusCode: Readonly<{
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly ACCEPTED: 202;
+    readonly NO_CONTENT: 204;
+    readonly MOVED_PERMANENTLY: 301;
+    readonly FOUND: 302;
+    readonly NOT_MODIFIED: 304;
+    readonly TEMPORARY_REDIRECT: 307;
+    readonly PERMANENT_REDIRECT: 308;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly PAYMENT_REQUIRED: 402;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly METHOD_NOT_ALLOWED: 405;
+    readonly NOT_ACCEPTABLE: 406;
+    readonly REQUEST_TIMEOUT: 408;
+    readonly CONFLICT: 409;
+    readonly GONE: 410;
+    readonly PRECONDITION_FAILED: 412;
+    readonly PAYLOAD_TOO_LARGE: 413;
+    readonly URI_TOO_LONG: 414;
+    readonly UNSUPPORTED_MEDIA_TYPE: 415;
+    readonly IM_A_TEAPOT: 418;
+    readonly UNPROCESSABLE_ENTITY: 422;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly NOT_IMPLEMENTED: 501;
+    readonly BAD_GATEWAY: 502;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly GATEWAY_TIMEOUT: 504;
+}>;
+/** The status numbers: `200 | 201 | ...`. */
+export type HttpStatusCode = (typeof HttpStatusCode)[keyof typeof HttpStatusCode];
+/** The names: `'OK' | 'CREATED' | ...`. */
+export type HttpStatusName = keyof typeof HttpStatusCode;

package/dist/ws/adapter.d.ts

@@ -0,0 +1,21 @@
+import type { BunRequest, Server, WebSocketHandler } from 'bun';
+import type { DiscoveredGateway } from './discover.js';
+import type { SocketData, SocketOptions } from './socket.js';
+/**
+ * A gateway's entry in the server's route table. Returning `undefined` is how Bun
+ * is told the socket was upgraded; a `Response` is `426` for a request that was not
+ * an upgrade, or whatever `@OnUpgrade` refused with.
+ */
+export type UpgradeHandler = (req: BunRequest, server: Server<SocketData>) => Response | undefined | Promise<Response | undefined>;
+/**
+ * Everything the one `Bun.serve` call needs from the websocket side, built once at
+ * boot: the handler object, and one native route per gateway path. Nothing here
+ * calls `Bun.serve` itself.
+ */
+export interface WebSocketRuntime {
+    readonly websocket: WebSocketHandler<SocketData>;
+    /** Merged into the HTTP route table by `listen()`, keyed by gateway path. */
+    readonly routes: ReadonlyMap<string, UpgradeHandler>;
+    readonly paths: readonly string[];
+}
+export declare const buildWebSocket: (discovered: readonly DiscoveredGateway[], options?: SocketOptions) => WebSocketRuntime;

package/dist/ws/decorators.d.ts

@@ -0,0 +1,17 @@
+type GatewayTarget = abstract new (...args: never[]) => object;
+type HandlerMethod = (...args: never[]) => unknown;
+export declare const Gateway: (path?: string) => <T extends GatewayTarget>(target: T) => T;
+/** Runs before the socket exists. Return a `Response` to refuse the upgrade. */
+export declare const OnUpgrade: () => <T extends HandlerMethod>(value: T) => T;
+export declare const OnOpen: () => <T extends HandlerMethod>(value: T) => T;
+export declare const OnClose: () => <T extends HandlerMethod>(value: T) => T;
+export declare const OnDrain: () => <T extends HandlerMethod>(value: T) => T;
+export declare const OnPing: () => <T extends HandlerMethod>(value: T) => T;
+export declare const OnPong: () => <T extends HandlerMethod>(value: T) => T;
+/**
+ * With an event name, the handler is routed the `data` of any
+ * `{"event":"<name>","data":...}` frame. With none, it is the raw catch-all and
+ * receives every frame no named handler claimed.
+ */
+export declare const OnMessage: (event?: string) => <T extends HandlerMethod>(value: T) => T;
+export {};

package/dist/ws/discover.d.ts

@@ -0,0 +1,40 @@
+import { type Ctor, type InjectionToken, type ResolvedModule } from '@dunx/core';
+import { type HandlerKind } from './marker.js';
+/**
+ * A discovered handler, already bound to its instance. Every kind has a different
+ * signature, so the runtime holds them loosely and the decorators are what keep
+ * the declared shapes honest.
+ */
+export type Invoke = (...args: readonly unknown[]) => unknown;
+export interface DiscoveredHandler {
+    readonly kind: HandlerKind;
+    readonly event: string | undefined;
+    readonly method: string;
+    readonly invoke: Invoke;
+}
+export interface DiscoveredGateway {
+    readonly name: string;
+    readonly path: string;
+    readonly handlers: readonly DiscoveredHandler[];
+}
+/** `chat` and `/chat/` both become `/chat`; an empty path becomes `/`. */
+export declare const normalizePath: (path: string) => string;
+/**
+ * Walks the prototype chain of a constructed gateway and collects every marked
+ * method. Most-derived wins on a repeated name; an undecorated override does not
+ * shadow its decorated base, and dispatch still lands on the override because the
+ * handler is bound off the instance.
+ */
+export declare const discoverGateway: (instance: object) => DiscoveredGateway;
+/**
+ * The name of the first handler a class declares, without constructing it. A
+ * provider that declares one but is not a gateway would silently never receive a
+ * frame, so that becomes a boot error naming the method.
+ */
+export declare const findHandlerMethod: (ctor: Ctor<unknown>) => string | undefined;
+/**
+ * Gateways are declared in `@Module({ providers })` like any other injectable and
+ * found here by their marker — the same discovery-by-inspection controllers get,
+ * with no second registration key to keep in step.
+ */
+export declare const discoverGateways: (modules: readonly ResolvedModule[], resolve: (token: InjectionToken<unknown>) => unknown) => readonly DiscoveredGateway[];

package/dist/ws/envelope.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The whole wire protocol: one JSON object, an event name, and a payload. It is
+ * only ever read for a gateway that declares at least one `@OnMessage(event)`
+ * handler — a gateway with only a raw `@OnMessage()` never parses anything.
+ */
+export interface Envelope {
+    readonly event: string;
+    readonly data?: unknown;
+}
+export declare const encode: (event: string, data: unknown) => string;
+/**
+ * `undefined` for anything that is not an envelope — binary frames, invalid JSON,
+ * a non-object, or a missing `event`. Those fall through to the raw handler
+ * instead of being rejected here.
+ */
+export declare const decode: (message: string | Buffer) => Envelope | undefined;

package/dist/ws/marker.d.ts

@@ -0,0 +1,27 @@
+export declare const HandlerKind: Readonly<{
+    readonly UPGRADE: 'upgrade';
+    readonly OPEN: 'open';
+    readonly MESSAGE: 'message';
+    readonly CLOSE: 'close';
+    readonly DRAIN: 'drain';
+    readonly PING: 'ping';
+    readonly PONG: 'pong';
+}>;
+export type HandlerKind = (typeof HandlerKind)[keyof typeof HandlerKind];
+export interface HandlerMeta {
+    readonly kind: HandlerKind;
+    /**
+     * Only meaningful for a message handler: the envelope event it claims.
+     * `undefined` is the raw catch-all that sees every unrouted frame.
+     */
+    readonly event: string | undefined;
+}
+export declare const markHandler: (target: object, meta: HandlerMeta) => void;
+export declare const handlerMetaOf: (value: unknown) => HandlerMeta | undefined;
+export declare const markGateway: (target: object, path: string) => void;
+export declare const gatewayPathOf: (target: object) => string;
+/**
+ * `@Gateway` is what separates a gateway from every other provider in the same
+ * module, so unlike `@Controller` it is required rather than decorative.
+ */
+export declare const isGateway: (target: object) => boolean;

package/dist/ws/pubsub.d.ts

@@ -0,0 +1,52 @@
+import type { Server } from 'bun';
+import { type PubSubRelay, type RelayOptions } from './relay.js';
+import type { SocketData } from './socket.js';
+/**
+ * Server-wide publish, delegating to Bun's own pub/sub. Topics live in the
+ * runtime, not in a JavaScript registry: `socket.subscribe(topic)` is what joins
+ * one, and Bun does the fan-out.
+ *
+ * Injectable — `HttpFactory` binds it, so a service can publish without holding a
+ * socket and without registering anything.
+ *
+ * With a {@link PubSubRelay} attached the same publish also reaches the other
+ * nodes. Without one — the default — nothing here touches a broker and the cost is
+ * exactly Bun's.
+ */
+export declare class PubSub {
+    #private;
+    /** Called with the live server by `listen()`; also usable directly. */
+    attach(server: Server<SocketData>): void;
+    get attached(): boolean;
+    /** This process's id on the relay channel. Stable for the process's lifetime. */
+    get origin(): string;
+    get relaying(): boolean;
+    /**
+     * Opt into multi-node fan-out: every `publish` from here on also goes to
+     * `relay`, and everything other nodes put on the channel is fanned out locally.
+     *
+     * `HttpFactory.create(root, { relay })` is the shorthand — `listen()` calls this.
+     * Call it directly when the relay has to come out of the container, which is the
+     * case for an app reusing its own `@dunx/infra/redis` connection:
+     * `app.get(PubSub).relayThrough(app.get(RedisConnection))` before `listen()`.
+     *
+     * A broker that cannot be reached is reported through `onError` and left alone —
+     * local fan-out is unaffected, and the app boots either way.
+     */
+    relayThrough(relay: PubSubRelay, options?: RelayOptions): Promise<void>;
+    /** Bytes sent locally, `0` if the message was dropped, `-1` under backpressure. */
+    publish(topic: string, data: string | Bun.BufferSource, compress?: boolean): number;
+    /** The same envelope `@OnMessage(event)` reads, published to a topic. */
+    publishEvent(topic: string, event: string, data?: unknown): number;
+    /** Subscribers on **this** node. Bun counts its own sockets and nothing else. */
+    subscriberCount(topic: string): number;
+    /**
+     * Releases a relay this `PubSub` was given, if the relay owns connections.
+     *
+     * The server reference goes too, which is what makes a relay the *app* owns safe
+     * to leave subscribed: `PubSubRelay` has no unsubscribe, so a frame may still
+     * arrive on a shared connection after this node stopped, and with no server
+     * there is nothing for it to fan out to.
+     */
+    close(): Promise<void>;
+}

package/dist/ws/redis-relay.d.ts

@@ -0,0 +1,52 @@
+import type { PubSubRelay } from './relay.js';
+/** The same fallback chain `Bun.RedisClient` uses when given no URL. */
+export declare const defaultRelayUrl: () => string;
+export interface RedisRelayOptions {
+    /** @default `$VALKEY_URL`, `$REDIS_URL`, then `redis://localhost:6379` */
+    readonly url?: string;
+    /**
+     * Bun's reconnection budget.
+     *
+     * `0` by default, and that default is not a preference: a `Bun.RedisClient` that
+     * never connects keeps an internal retry timer alive past `close()`, and the
+     * process then never exits. A relay is exactly the connection most likely to be
+     * absent — a single-node deployment with `REDIS_URL` left over from staging —
+     * so the default has to be the one that lets the app boot, degrade, and still
+     * exit. Raise it when Redis is a hard requirement and you want Bun to reconnect
+     * for you.
+     *
+     * @default 0
+     */
+    readonly maxRetries?: number;
+    /** @default 10000 */
+    readonly connectionTimeout?: number;
+    readonly tls?: boolean | Bun.TLSOptions;
+}
+/**
+ * A {@link PubSubRelay} on `Bun.RedisClient` — a Bun global, so this costs
+ * `@dunx/http` no dependency at all.
+ *
+ * **Two connections, not one.** A client in subscriber mode rejects every data
+ * command, and throws synchronously doing it, so the subscription cannot share the
+ * socket that publishes. This is the same split the socket.io Redis adapter makes
+ * with its `pubClient` / `subClient`.
+ *
+ * Both are opened lazily, on the first call that needs them, and a failed one is
+ * discarded so the next call builds a fresh connection rather than reusing a dead
+ * one.
+ */
+export declare class RedisRelay implements PubSubRelay {
+    #private;
+    constructor(options?: RedisRelayOptions);
+    /** The URL with any password removed, for logs and error messages. */
+    get url(): string;
+    publish(channel: string, message: string): Promise<number>;
+    subscribe(channel: string, listener: (message: string) => void): Promise<void>;
+    /**
+     * `UNSUBSCRIBE` before `close()`, and that order is load-bearing: measured on
+     * Bun 1.3.14, a `Bun.RedisClient` left in subscriber mode keeps the process
+     * alive after `close()`, so an app that shut down cleanly would never exit.
+     * Leaving subscriber mode first fixes it. Recorded in docs/bun-apis.md.
+     */
+    close(): Promise<void>;
+}