@dunx/http 3.5.1 → 3.7.0

package/dist/internal.js

@@ -7,11 +7,14 @@ import {
   HIDDEN2,
   joinPath2,
   discoverRoutes2,
-  RoutePrefix2,
+  RoutePrefix2
+} from "./chunk-1jt27yka.js";
+import {
   isGateway2,
   discoverGateway,
-  buildContext2
-} from "./chunk-p9hdmkm6.js";
+  buildContext2,
+  IMMUTABLE_CACHE_CONTROL2
+} from "./chunk-3eecdh6d.js";
 // src/inspect.ts
 import {
   classOf,
@@ -72,6 +75,7 @@ var gatewaysOf = (root) => collectModules(root).flatMap((module) => (module.opti
 // src/server/html.ts
 var embedJson = (value) => JSON.stringify(value).replaceAll("<", "\\u003c");
 export {
+  IMMUTABLE_CACHE_CONTROL2 as IMMUTABLE_CACHE_CONTROL,
   RoutePrefix2 as RoutePrefix,
   buildContext2 as buildContext,
   defaultStatusFor2 as defaultStatusFor,

package/dist/route/claims.d.ts

@@ -0,0 +1,11 @@
+/**
+ * What has claimed each path, so a second claim is a boot error naming both
+ * rather than a silent overwrite. Routes and RPCs share it because the failure
+ * is the same one: a table keyed by path keeps whichever registered last.
+ */
+export declare class PathClaims {
+    #private;
+    constructor(noun: string, remedy: string);
+    /** Records `owner` against `key`, or throws naming the one already there. */
+    claim(key: string, owner: string): void;
+}

package/dist/route/metadata.d.ts

@@ -1,3 +1,4 @@
+import type { Server } from 'bun';
 import type { Ctor } from '@dunx/core';
 import type { Middleware } from '../server/middleware.js';
 /** What a route's decorators resolved to, keyed by `MetaKey.id`. */
@@ -28,6 +29,16 @@ export declare const HIDDEN: MetaKey<boolean>;
  * genuinely public route from one that matched nothing.
  */
 export declare const UNMATCHED: MetaKey<boolean>;
+/** This route idles by design, so `buildRoutes` clears Bun's idle deadline for
+ * it with the server it is handed. `@Sse` sets it; a raw stream can too. */
+export declare const STREAMS: MetaKey<boolean>;
+/**
+ * The server that received the request, on the unmatched path only, where the
+ * context is built per request. A matched route's is built once at boot and
+ * carries none: those clear their deadline through {@link STREAMS}. Not exported
+ * from the barrel - `ConnectMiddleware` is the only reader.
+ */
+export declare const REQUEST_SERVER: MetaKey<Server<unknown>>;
 export declare const Roles: (...roles: readonly string[]) => <F extends object>(target: F) => F;
 export declare const Public: () => <F extends object>(target: F) => F;
 /**

package/dist/route/prefix.d.ts

@@ -1,3 +1,9 @@
+/**
+ * A leading slash and no trailing one, so `${path}/x` is never `//x`. `/` is
+ * what an empty prefix normalises to; a caller that wants `''` there maps it
+ * itself, which is the only difference between the two users.
+ */
+export declare const normalizePrefix: (path: string) => string;
 /**
  * The global prefix, as `listen()` resolved it.
  *

package/dist/server/application.d.ts

@@ -3,7 +3,7 @@ import { ShutdownAware, type App, type Ctor, type InjectionToken, type ModuleRef
 import type { DiscoveredRoute } from '../route/discover.js';
 import type { WebSocketRuntime } from '../ws/adapter.js';
 import type { CorsOptions } from './cors.js';
-import type { Middleware } from './middleware.js';
+import { type Middleware } from './middleware.js';
 import { type AppSettings } from './settings.js';
 import type { HttpOptions } from './options.js';
 /**

package/dist/server/binding.d.ts

@@ -1,13 +1,13 @@
 import type { Server } from 'bun';
 import type { SocketData } from '../ws/socket.js';
 import type { WebSocketRuntime } from '../ws/adapter.js';
-import type { RouteHandler } from './middleware.js';
+import type { ServedHandler } from './middleware.js';
 import { type BunRoutes } from './routes.js';
 /** What `listen()` computes and hands the binding, once the table is final. */
 export interface BindingPlan {
     readonly port: number;
     readonly routes: BunRoutes;
-    readonly fetch: RouteHandler;
+    readonly fetch: ServedHandler;
     readonly websocket: WebSocketRuntime | undefined;
 }
 /** The protocol settings, fixed at construction. `undefined` leaves Bun's own
@@ -20,6 +20,8 @@ export interface BindingProtocols {
      * merged into the main table and a second `Bun.serve` takes them.
      */
     readonly gatewayPort?: number | undefined;
+    /** Seconds a request may idle before Bun severs it. `undefined` leaves Bun's 10. */
+    readonly idleTimeout?: number | undefined;
 }
 /**
  * The two per-server counters a metrics reader wants, summed across however

package/dist/server/claimed-routes.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The paths a path-claiming middleware serves off the unmatched fallback.
+ *
+ * `ThrottleGuard` skips unmatched paths so a burst of 404s cannot spend a real
+ * caller's budget. A claimed path is not a 404: something answers it, and it
+ * costs whatever that costs, so it is rate limited like any route.
+ *
+ * Attached by `listen()`, for the reason `RoutePrefix` is: the set is not known
+ * until every middleware has been resolved.
+ */
+export declare class ClaimedRoutes {
+    #private;
+    attach(paths: Iterable<string>): void;
+    has(path: string): boolean;
+}

package/dist/server/cors.d.ts

@@ -1,4 +1,4 @@
-import type { RouteHandler } from './middleware.js';
+import type { RouteHandler, ServedHandler } from './middleware.js';
 export type CorsOrigin = string | readonly string[] | ((origin: string) => boolean);
 export interface CorsOptions {
     /**
@@ -17,7 +17,7 @@ export interface CorsOptions {
     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;
+export declare const withCors: (options: CorsOptions, handler: ServedHandler) => ServedHandler;
 /**
  * `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

package/dist/server/middleware.d.ts

@@ -1,4 +1,4 @@
-import type { BunRequest } from 'bun';
+import type { BunRequest, Server } from 'bun';
 import type { RouteContext } from './context.js';
 export type Next = () => Promise<Response>;
 /**
@@ -15,6 +15,18 @@ export type RouteHandler = (req: BunRequest) => Promise<Response>;
  * 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>;
+export type ServedHandler = (req: BunRequest, 
+/** The server that received the request. Bun always passes it; optional so a
+ * test can call a handler with the request alone. See `STREAMS`. */
+server?: Server<unknown>) => 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;
+/**
+ * Middleware that answers a fixed set of paths itself, on the unmatched path.
+ * `buildRoutes` cross-checks them against the route table: Bun matches a route
+ * first, so a controller on one of these would shadow it with nothing said.
+ */
+export interface ClaimsPaths {
+    claimedPaths(): readonly string[];
+}
+export declare const hasClaimedPaths: (value: object) => value is ClaimsPaths;

package/dist/server/options-provider.d.ts

@@ -104,6 +104,9 @@ export declare abstract class HttpOptionsProvider {
      * usable with one. See {@link HttpOptions.gatewayPort}.
      */
     get gatewayPort(): number | undefined;
+    /** Seconds a request may idle before Bun severs it. See
+     * {@link HttpOptions.idleTimeout}. */
+    get idleTimeout(): number | undefined;
 }
 /**
  * The base itself, bound when no module bound a subclass. Concrete because the

package/dist/server/options.d.ts

@@ -146,7 +146,15 @@ export interface HttpOptions extends AppOptions {
      * and never both. The pair without a `gatewayPort` is a boot error.
      *
      * `0` takes any free port and is the one value that does not warn when no
-     * gateway is declared. See docs/guide/19-deployment.md.
+     * gateway is declared. See docs/guide/20-deployment.md.
      */
     readonly gatewayPort?: number;
+    /**
+     * Seconds a request may go without traffic before `Bun.serve` severs it. `0`
+     * removes the limit for every request, which is what a slowloris counts on;
+     * a route that idles declares `meta(STREAMS, true)` instead, as `@Sse` does.
+     *
+     * @default 10, which is Bun's
+     */
+    readonly idleTimeout?: number;
 }

package/dist/server/routes.d.ts

@@ -4,7 +4,7 @@ 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';
+import { type Middleware, type ServedHandler } from './middleware.js';
 /** How a `@UseGuards` class becomes an instance. `listen()` passes `app.get`. */
 /**
  * How a guard or a module's middleware becomes an instance.
@@ -58,7 +58,12 @@ export declare const withUpgradeRoutes: (routes: BunRoutes, gateways: ReadonlyMa
  * `ctx.get(UNMATCHED)` is the cheaper half: set here and by no real route, so a
  * middleware can tell a miss from a handler's own 404 before calling `next()`.
  */
-export declare const buildFallback: (middleware?: readonly Middleware[], onError?: ErrorMapper, cors?: CorsOptions, notFound?: 'guarded' | 'public') => RouteHandler;
+/**
+ * A route and a path-claiming middleware cannot share a path: Bun matches the
+ * route, the fallback never runs, and the claim is silently dead.
+ */
+export declare const assertNoShadowedClaims: (discovered: readonly DiscoveredRoute[], middleware: readonly Middleware[]) => void;
+export declare const buildFallback: (middleware?: readonly Middleware[], onError?: ErrorMapper, cors?: CorsOptions, notFound?: 'guarded' | 'public') => ServedHandler;
 export declare const buildRoutes: (discovered: readonly DiscoveredRoute[], middleware?: readonly Middleware[], onError?: ErrorMapper, cors?: CorsOptions, resolve?: GuardResolver) => BunRoutes;
 /**
  * A second key per route ending in `/`, holding the handlers the first one has.

package/dist/sse/decorators.d.ts

@@ -0,0 +1,28 @@
+import { type RoutePath } from '../route/marker.js';
+import type { Input, RouteSchemas } from '../route/schema.js';
+import type { SseEvent } from './event.js';
+import { SseStream } from './stream.js';
+/** The request half of {@link RouteSchemas}: no body, and always 200. */
+export type SseSchemas = Pick<RouteSchemas, 'params' | 'query'>;
+/** What a `@Sse` handler may answer with. */
+export type SseResult = SseStream | AsyncIterable<SseEvent>;
+/** {@link Input} plus the resume header. */
+export type SseInput<O extends SseSchemas> = Input<O> & {
+    /** The `id` this client last saw, from `Last-Event-ID`. Absent on a first connection. */
+    readonly lastEventId: string | undefined;
+};
+/**
+ * A `GET` route answering `text/event-stream`, from a handler returning an
+ * `AsyncIterable<SseEvent>` or an {@link SseStream}.
+ *
+ * ```ts
+ * @Sse('/progress')
+ * async *progress(input: SseInput<RouteSchemas>): AsyncGenerator<SseEvent> {
+ *   yield { data: { step: 10 }, id: '10' };
+ * }
+ * ```
+ *
+ * The parameter is annotated for the reason `@Get`'s is: a standard decorator
+ * can check a parameter's type but not supply one.
+ */
+export declare const Sse: <const O extends SseSchemas>(path?: RoutePath, options?: O) => <H extends (input: SseInput<O>) => SseResult | Promise<SseResult>>(value: H, _context: ClassMethodDecoratorContext) => H;

package/dist/sse/event.d.ts

@@ -0,0 +1,19 @@
+/**
+ * One server-sent event. Every field is optional: `retry` alone changes the
+ * reconnection delay, `event` alone fires a named event with no payload.
+ */
+export interface SseEvent {
+    /** A string as it is, anything else through `JSON.stringify`. Each line of it
+     * becomes its own `data:` line. */
+    readonly data?: unknown;
+    /** The `event:` name the client listens for. Absent dispatches `message`. */
+    readonly event?: string;
+    /** Sent back as `Last-Event-ID` on the client's next connection. */
+    readonly id?: string;
+    /** Milliseconds the client waits before reconnecting, truncated to an integer. */
+    readonly retry?: number;
+}
+/** `event`, framed, ending with the blank line that dispatches it. */
+export declare const frameEvent: (event: SseEvent) => string;
+/** A comment line: bytes on the wire that dispatch nothing, which is a heartbeat. */
+export declare const frameComment: (text: string) => string;

package/dist/sse/stream.d.ts

@@ -0,0 +1,35 @@
+import { type SseEvent } from './event.js';
+export interface SseStreamOptions {
+    /**
+     * Milliseconds between the comment lines that stop a proxy seeing no bytes
+     * from reaping the connection. `0` sends none. @default 15000
+     */
+    readonly heartbeatMs?: number;
+}
+/**
+ * A server-sent-events response, held open by a `ReadableStream` in a `Response`.
+ * `@Sse` builds one for a handler returning an `AsyncIterable` and takes one a
+ * handler built itself; outside a route it is a `Response` a `@Get` can return.
+ */
+export declare class SseStream {
+    #private;
+    constructor(options?: SseStreamOptions);
+    /**
+     * Pumps `events` into a new stream, closing it when the iterable ends. A throw
+     * once the headers are out cannot become a status, so the body ends without its
+     * terminal chunk and an `EventSource` reconnects.
+     */
+    static from(events: AsyncIterable<SseEvent>, options?: SseStreamOptions): SseStream;
+    /** The `id` of the last event sent, or `undefined` if none carried one. */
+    get lastEventId(): string | undefined;
+    get closed(): boolean;
+    /** Frames and enqueues one event. A send after the stream closed is dropped. */
+    send(event: SseEvent): void;
+    /** A comment line, which is what the heartbeat sends. */
+    comment(text?: string): void;
+    close(): void;
+    /**
+     * `headers` merge under the three this sets. No status: an event stream is a
+     * 200 or it is not one. */
+    toResponse(headers?: Readonly<Record<string, string>>): Response;
+}

package/dist/static/files.d.ts

@@ -2,6 +2,13 @@ import type { BunRequest } from 'bun';
 import type { Middleware, Next } from '../server/middleware.js';
 import type { RouteContext } from '../server/context.js';
 import { StaticOptions } from './options.js';
+/**
+ * One year, and `immutable`, which is only honest for a name that changes with
+ * the bytes: a content-addressed file, or a URL carrying the installed version.
+ * `@dunx/openapi` serves a renderer's assets under the second rule and takes this
+ * through `@dunx/http/internal`, so the two cannot drift.
+ */
+export declare const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
 /**
  * Static files, on `Bun.file`. A `Bun.file` handed to a `Response` already
  * streams, sets `content-type`, answers a `Range` request and uses `sendfile(2)`,

package/dist/static/options.d.ts

@@ -1,3 +1,4 @@
+import { normalizePrefix } from '../route/prefix.js';
 export interface StaticOptionsInit {
     /**
      * The directory served. Resolved once, at construction, and every request is
@@ -42,5 +43,4 @@ export declare class StaticOptions {
     readonly immutable: (pathname: string) => boolean;
     constructor(init: StaticOptionsInit);
 }
-/** A leading slash and no trailing one, so `${path}/x` is never `//x`. */
-export declare const normalizePrefix: (path: string) => string;
+export { normalizePrefix };

package/dist/throttle/guard.d.ts

@@ -1,5 +1,6 @@
 import { Logger } from '@dunx/core';
 import type { BunRequest } from 'bun';
+import { ClaimedRoutes } from '../server/claimed-routes.js';
 import { ClientAddress } from '../server/client-address.js';
 import type { RouteContext } from '../server/context.js';
 import type { Middleware, Next } from '../server/middleware.js';
@@ -23,6 +24,7 @@ export declare class ThrottleGuard implements Middleware {
     private readonly store;
     private readonly address;
     private readonly logger;
-    constructor(options: ThrottleOptions, store: ThrottleStore, address: ClientAddress, logger: Logger);
+    private readonly claimed;
+    constructor(options: ThrottleOptions, store: ThrottleStore, address: ClientAddress, logger: Logger, claimed: ClaimedRoutes);
     handle(req: BunRequest, ctx: RouteContext, next: Next): Promise<Response>;
 }

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@dunx/http",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "description": "Bun.serve adapter for the dunx framework: controllers, middleware and WebSocket gateways",
   "keywords": [
     "bun",
+    "connect-rpc",
     "controller",
     "dunx",
+    "grpc-web",
     "http",
     "pubsub",
     "realtime",
@@ -41,6 +43,10 @@
       "types": "./dist/client.d.ts",
       "import": "./dist/client.js"
     },
+    "./connect": {
+      "types": "./dist/connect.d.ts",
+      "import": "./dist/connect.js"
+    },
     "./internal": {
       "types": "./dist/internal.d.ts",
       "import": "./dist/internal.js"
@@ -59,16 +65,27 @@
     "@arkv/shared": "0.8.0"
   },
   "devDependencies": {
+    "@bufbuild/protobuf": "2.15.0",
+    "@connectrpc/connect": "2.2.0",
+    "@connectrpc/connect-web": "2.2.0",
     "@dunx/core": "workspace:*",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/core": "2.11.0",
     "@opentelemetry/sdk-trace-node": "2.11.0"
   },
   "peerDependencies": {
-    "@dunx/core": "^3.5.1",
+    "@bufbuild/protobuf": "^2.15.0",
+    "@connectrpc/connect": "^2.2.0",
+    "@dunx/core": "^3.7.0",
     "@types/bun": ">=1.4.1"
   },
   "peerDependenciesMeta": {
+    "@bufbuild/protobuf": {
+      "optional": true
+    },
+    "@connectrpc/connect": {
+      "optional": true
+    },
     "@types/bun": {
       "optional": true
     }