@dunx/http 3.6.0 → 3.8.0

package/dist/client.js

@@ -6,7 +6,7 @@ import {
   TRACEPARENT_HEADER2,
   TRACESTATE_HEADER2,
   TraceContext2
-} from "./chunk-gmtwad7f.js";
+} from "./chunk-cx4btdwe.js";
 
 // src/client/errors.ts
 import { AppError } from "@dunx/core";
@@ -159,28 +159,78 @@ var readBody = async (response) => {
 };
 
 // src/client/sse.ts
-async function* sseData(body) {
+var LINE = /\r\n|\r|\n/;
+var split = (line) => {
+  const colon = line.indexOf(":");
+  if (colon === -1)
+    return [line, ""];
+  const value = line.slice(colon + 1);
+  return [line.slice(0, colon), value.startsWith(" ") ? value.slice(1) : value];
+};
+async function* sseMessages(body) {
   const decoder = new TextDecoder;
   let buffer = "";
-  for await (const chunk of body) {
-    buffer += decoder.decode(chunk, { stream: true });
-    let newline = buffer.indexOf(`
-`);
-    while (newline !== -1) {
-      const line = buffer.slice(0, newline).trim();
-      buffer = buffer.slice(newline + 1);
-      newline = buffer.indexOf(`
+  let data = [];
+  let event;
+  let id;
+  let retry;
+  const reader = body.getReader();
+  let done = false;
+  try {
+    for (;; ) {
+      let end = LINE.exec(buffer);
+      while (end !== null) {
+        if (!done && end[0] === "\r" && end.index + 1 === buffer.length)
+          break;
+        const line = buffer.slice(0, end.index);
+        buffer = buffer.slice(end.index + end[0].length);
+        end = LINE.exec(buffer);
+        if (line === "") {
+          const seen = data.length > 0;
+          const payload = data.join(`
 `);
-      if (!line.startsWith("data:"))
-        continue;
-      const data = line.slice(5).trim();
-      if (data === "[DONE]")
+          data = [];
+          if (!seen) {
+            event = undefined;
+            continue;
+          }
+          if (payload === "[DONE]")
+            return;
+          yield {
+            data: payload,
+            ...event === undefined ? {} : { event },
+            ...id === undefined ? {} : { id },
+            ...retry === undefined ? {} : { retry }
+          };
+          event = undefined;
+          continue;
+        }
+        if (line.startsWith(":"))
+          continue;
+        const [field, value] = split(line);
+        if (field === "data")
+          data.push(value);
+        else if (field === "event")
+          event = value;
+        else if (field === "id" && !value.includes("\x00"))
+          id = value;
+        else if (field === "retry" && /^\d+$/.test(value))
+          retry = Number(value);
+      }
+      if (done)
         return;
-      yield data;
+      const next = await reader.read();
+      if (next.done) {
+        buffer += decoder.decode();
+        done = true;
+        continue;
+      }
+      buffer += decoder.decode(next.value, { stream: true });
     }
+  } finally {
+    reader.releaseLock();
   }
 }
-
 class ConnectDeadline {
   #controller = new AbortController;
   #timer;
@@ -297,6 +347,10 @@ class HttpService extends UrlHelper {
     });
   }
   async* streamSse(config) {
+    for await (const message of this.streamSseEvents(config))
+      yield message.data;
+  }
+  async* streamSseEvents(config) {
     const url = this.urlFor(config);
     const method = config.method ?? "POST";
     const startedAt = Date.now();
@@ -304,9 +358,7 @@ class HttpService extends UrlHelper {
     const deadline = new ConnectDeadline(config.timeoutMs ?? this.options.timeoutMs, url.href);
     let response;
     try {
-      const policy = this.policyFor({ ...config, timeoutMs: 0 }, {
-        maxRetries: 0
-      });
+      const policy = this.policyFor({ ...config, timeoutMs: 0 }, { maxRetries: 0 });
       response = await policy.run((signal) => this.send({ ...config, method }, url, body, serialised, AbortSignal.any([signal, deadline.signal]), "text/event-stream"));
     } finally {
       deadline.clear();
@@ -317,7 +369,7 @@ class HttpService extends UrlHelper {
       }), { method, url: url.href, headers: response.headers });
     }
     try {
-      yield* sseData(response.body);
+      yield* sseMessages(response.body);
     } finally {
       this.logger.debug(`SSE ${method} ${url.href} closed`, {
         elapsedMs: Date.now() - startedAt

package/dist/connect/middleware.d.ts

@@ -0,0 +1,26 @@
+import type { BunRequest } from 'bun';
+import type { RouteContext } from '../server/context.js';
+import type { ClaimsPaths, Middleware, Next } from '../server/middleware.js';
+import { ConnectRegistry } from './registry.js';
+/**
+ * Serves every registered RPC as ordinary middleware, so request logging, CORS,
+ * a guard and the dashboard apply to a call as they apply to a route. Register
+ * it with `app.use`, since position in the chain decides what covers it.
+ *
+ * RPC paths are in no route table, so they reach the `fetch` fallback, where
+ * `ctx.get(UNMATCHED)` is true and `ctx.path` is already parsed. Reading it
+ * first is what leaves a matched route paying nothing. Anything outside the
+ * registered paths falls through untouched.
+ *
+ * `ThrottleGuard` covers an RPC: its early return is for an unmatched path
+ * nobody claims, and a claimed path is served. See docs/guide/27-rpc.md.
+ */
+export declare class ConnectMiddleware implements Middleware, ClaimsPaths {
+    #private;
+    constructor(registry: ConnectRegistry);
+    /** Every mounted RPC path, so a controller cannot shadow one unnoticed. */
+    claimedPaths(): readonly string[];
+    /** Connect and gRPC-Web both POST. Connect's GET form is not served here. */
+    claimedMethods(): readonly string[];
+    handle(req: BunRequest, ctx: RouteContext, next: Next): Promise<Response>;
+}

package/dist/connect/module.d.ts

@@ -0,0 +1,29 @@
+import { type AsyncModuleConfig, type Deps, type DynamicModule } from '@dunx/core';
+import { type ConnectOptionsInit, type ConnectServiceRegistration } from './options.js';
+/** Everything `forRoot` takes except the services, which `forRootAsync` needs
+ * synchronously, and `imports`, which `AsyncModuleConfig` already carries. */
+export type ConnectSettings = Omit<ConnectOptionsInit, 'services' | 'imports'>;
+/**
+ * Serves protobuf services over Connect and gRPC-Web on the port `Bun.serve`
+ * already has. See `docs/guide/27-rpc.md`.
+ *
+ * ```ts
+ * ConnectModule.forRoot({
+ *   services: [connectService(GreetService, GreetRpc)],
+ *   // What GreetRpc injects: this module is its own scope.
+ *   imports: [GreetingsModule],
+ * });
+ * ```
+ *
+ * It binds `ConnectMiddleware` and does not register it - position in the chain
+ * decides which guards cover an RPC, so the app calls `app.use`.
+ */
+export declare class ConnectModule {
+    static forRoot(init: ConnectOptionsInit): DynamicModule;
+    /**
+     * `forRoot` with everything but the services behind a factory, so the prefix
+     * or the read limits can come off `ConfigService`. The services are positional
+     * because their classes have to be providers before any factory runs.
+     */
+    static forRootAsync<const D extends Deps>(services: readonly ConnectServiceRegistration[], config: AsyncModuleConfig<ConnectSettings, D>): DynamicModule;
+}

package/dist/connect/options.d.ts

@@ -0,0 +1,63 @@
+import type { DescService } from '@bufbuild/protobuf';
+import type { ConnectRouterOptions, ServiceImpl } from '@connectrpc/connect';
+import { type Ctor, type ModuleRef } from '@dunx/core';
+/**
+ * Everything `createConnectRouter` takes except the protocol switches and
+ * `shutdownSignal`, which the container owns. `interceptors`, `contextValues`,
+ * `requestGate`, `jsonOptions` and the rest pass through untouched.
+ */
+export type ConnectRouterSettings = Omit<ConnectRouterOptions, 'connect' | 'grpc' | 'grpcWeb' | 'shutdownSignal'>;
+/** One protobuf service and the class implementing it. */
+export interface ConnectServiceRegistration {
+    readonly service: DescService;
+    readonly useClass: Ctor<object>;
+}
+/**
+ * Pairs a generated `DescService` with the class serving it, checking at compile
+ * time that the class has a method per RPC. A generic function rather than an
+ * object literal, which would lose the link between the two arguments.
+ */
+export declare const connectService: <T extends DescService>(service: T, useClass: Ctor<ServiceImpl<T>>) => ConnectServiceRegistration;
+export interface ConnectOptionsInit extends ConnectRouterSettings {
+    /** The services to serve, each paired with its implementation class. */
+    readonly services: readonly ConnectServiceRegistration[];
+    /**
+     * Modules whose exports the implementation classes may inject. This module is
+     * its own scope and the classes are constructed in it, so a provider they need
+     * has to be exported by a module named here - importing it alongside does not
+     * reach them.
+     */
+    readonly imports?: readonly ModuleRef[];
+    /**
+     * Mounted in front of every RPC path, empty by default, which leaves them at
+     * `/{package}.{Service}/{Method}`. `setGlobalPrefix` does not move them: that
+     * prefixes discovered routes, and these are matched by a middleware.
+     */
+    readonly prefix?: string;
+    /** Connect, which a `curl` POST of JSON also speaks. @default true */
+    readonly connect?: boolean;
+    /** gRPC-Web, which browsers and `connect-go` speak. @default true */
+    readonly grpcWeb?: boolean;
+    /**
+     * Seconds a **streaming** RPC may idle before `Bun.serve` severs it. `0` lifts
+     * the deadline for the whole call, which is the default because a gap between
+     * messages is the protocol rather than a symptom.
+     *
+     * Worth setting on a public mount: `ThrottleGuard` limits the calls, and this
+     * limits how long one that is already streaming may idle.
+     *
+     * @default 0
+     */
+    readonly streamTimeout?: number;
+}
+/** A class rather than an interface, so it is a runtime value the transform can
+ * record as a constructor parameter type. */
+export declare class ConnectOptions {
+    readonly services: readonly ConnectServiceRegistration[];
+    readonly prefix: string;
+    readonly connect: boolean;
+    readonly grpcWeb: boolean;
+    readonly streamTimeout: number;
+    readonly router: ConnectRouterSettings;
+    constructor(init: ConnectOptionsInit);
+}

package/dist/connect/registry.d.ts

@@ -0,0 +1,47 @@
+import { ConnectOptions } from './options.js';
+/** What `createFetchHandler` returns: the `Bun.serve` signature exactly. */
+export type ConnectHandler = (req: Request) => Promise<Response>;
+/** One mounted RPC. */
+export interface ConnectMethodInfo {
+    /** The path it answers, including {@link ConnectOptions.prefix}. */
+    readonly path: string;
+    /** e.g. `greet.v1.GreetService`. */
+    readonly service: string;
+    /** e.g. `Say`. */
+    readonly method: string;
+    /** `unary`, `server_streaming`, `client_streaming` or `bidi_streaming`. */
+    readonly kind: string;
+    /** e.g. `['grpc-web', 'connect']`. */
+    readonly protocols: readonly string[];
+}
+/** What the middleware needs per path, in one lookup. */
+export interface ConnectRoute {
+    readonly handle: ConnectHandler;
+    /** Anything but `unary`, so the gap between messages is the protocol. */
+    readonly streaming: boolean;
+}
+/**
+ * One fetch handler per RPC, built at boot into a path map, so a request costs a
+ * `Map.get`. Connect's own router picks the protocol off the content type.
+ *
+ * `grpc` is off and cannot be turned on: it carries `grpc-status` in an HTTP
+ * trailer and `Bun.serve` sends none, so advertising it would answer with a
+ * status no client reads. Probed on Bun 1.4.2.
+ */
+export declare class ConnectRegistry {
+    #private;
+    /** Every mounted path, in registration order. */
+    get paths(): readonly string[];
+    /** Seconds a streaming call may idle; `0` lifts the deadline. */
+    readonly streamTimeout: number;
+    constructor(options: ConnectOptions, implementations: readonly object[]);
+    /** In registration order. */
+    get methods(): readonly ConnectMethodInfo[];
+    routeFor(path: string): ConnectRoute | undefined;
+    /**
+     * Aborts the signal every in-flight handler holds, so a long-running
+     * implementation gets its cue. It does not close an open response stream -
+     * the socket closing does. Measured on `@connectrpc/connect` 2.2.0.
+     */
+    onShutdown(): void;
+}

package/dist/connect.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@dunx/http/connect` - protobuf services over Connect and gRPC-Web, mounted as
+ * middleware. `@connectrpc/connect` and `@bufbuild/protobuf` are optional peers,
+ * and importing `@dunx/http` does not load any of this.
+ *
+ * Native gRPC is not here: `grpc-status` travels in an HTTP trailer and
+ * `Bun.serve` sends none. See `internal/notes/research/rpc.md`.
+ */
+export { ConnectMiddleware } from './connect/middleware.js';
+export { ConnectModule, type ConnectSettings } from './connect/module.js';
+export { connectService, ConnectOptions, type ConnectOptionsInit, type ConnectRouterSettings, type ConnectServiceRegistration, } from './connect/options.js';
+export { ConnectRegistry, type ConnectHandler, type ConnectMethodInfo, type ConnectRoute, } from './connect/registry.js';

package/dist/connect.js

@@ -0,0 +1,213 @@
+// @bun
+import {
+  UNMATCHED2,
+  REQUEST_SERVER,
+  normalizePrefix
+} from "./chunk-1jt27yka.js";
+import {
+  HttpStatusCode2
+} from "./chunk-bg0dr54z.js";
+import {
+  __decoratorStart,
+  __decoratorMetadata,
+  __runInitializers,
+  __decorateElement,
+  PathClaims
+} from "./chunk-08k9vq31.js";
+
+// src/connect/registry.ts
+import { AppError as AppError2 } from "@dunx/core";
+import {
+  createConnectRouter
+} from "@connectrpc/connect";
+import { createFetchHandler } from "@connectrpc/connect/protocol";
+
+// src/connect/options.ts
+import { AppError } from "@dunx/core";
+var connectService = (service, useClass) => ({ service, useClass });
+
+class ConnectOptions {
+  services;
+  prefix;
+  connect;
+  grpcWeb;
+  streamTimeout;
+  router;
+  constructor(init) {
+    const {
+      services,
+      prefix,
+      connect,
+      grpcWeb,
+      streamTimeout,
+      imports: _imports,
+      ...router
+    } = init;
+    this.services = services;
+    const mounted = normalizePrefix(prefix ?? "");
+    this.prefix = mounted === "/" ? "" : mounted;
+    this.connect = connect ?? true;
+    this.grpcWeb = grpcWeb ?? true;
+    this.streamTimeout = streamTimeout ?? 0;
+    if (!Number.isFinite(this.streamTimeout) || this.streamTimeout < 0) {
+      throw new AppError(`ConnectModule streamTimeout must be a non-negative number of seconds, got ${String(streamTimeout)}.`);
+    }
+    this.router = router;
+    if (!this.connect && !this.grpcWeb) {
+      throw new AppError("ConnectModule needs at least one protocol, and both connect and " + "grpcWeb are false. Native gRPC is not a third option here: it " + "carries grpc-status in an HTTP trailer and Bun.serve sends none.");
+    }
+    if (services.length === 0) {
+      throw new AppError("ConnectModule.forRoot was given no services. Pass at least one " + "connectService(Desc, Impl), or drop the module.");
+    }
+  }
+}
+Object.defineProperty(ConnectOptions, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "init: ConnectOptionsInit" }] });
+
+// src/connect/registry.ts
+class ConnectRegistry {
+  #routes = new Map;
+  get paths() {
+    return [...this.#routes.keys()];
+  }
+  streamTimeout;
+  #methods = [];
+  #stopping = new AbortController;
+  constructor(options, implementations) {
+    this.streamTimeout = options.streamTimeout;
+    const router = createConnectRouter({
+      ...options.router,
+      connect: options.connect,
+      grpcWeb: options.grpcWeb,
+      grpc: false,
+      shutdownSignal: this.#stopping.signal
+    });
+    options.services.forEach((registration, index) => {
+      const implementation = implementations[index];
+      if (implementation === undefined) {
+        throw new AppError2(`No instance was resolved for ${registration.useClass.name}, which ` + `serves ${registration.service.typeName}.`);
+      }
+      router.service(registration.service, implementation);
+    });
+    const claims = new PathClaims("RPC", "Register each service once, or give one its own prefix.");
+    for (const handler of router.handlers) {
+      const path = `${options.prefix}${handler.requestPath}`;
+      const rpc = `${handler.service.typeName}.${handler.method.name}`;
+      claims.claim(path, rpc);
+      this.#routes.set(path, {
+        handle: createFetchHandler(handler),
+        streaming: handler.method.methodKind !== "unary"
+      });
+      this.#methods.push({
+        path,
+        service: handler.service.typeName,
+        method: handler.method.name,
+        kind: handler.method.methodKind,
+        protocols: handler.protocolNames
+      });
+    }
+  }
+  get methods() {
+    return this.#methods;
+  }
+  routeFor(path) {
+    return this.#routes.get(path);
+  }
+  onShutdown() {
+    this.#stopping.abort();
+  }
+}
+Object.defineProperty(ConnectRegistry, Symbol.for("dunx.deps"), { value: () => [ConnectOptions, { unresolved: "implementations: readonly object[]" }] });
+
+// src/connect/middleware.ts
+var NATIVE_GRPC = /^\s*application\/grpc\s*(?:[;+]|$)/i;
+var grpcUnsupported = () => Response.json({
+  code: "unimplemented",
+  message: "This endpoint serves Connect and gRPC-Web, not gRPC. gRPC carries " + "grpc-status in an HTTP trailer and Bun.serve sends no trailers, so a " + "gRPC client would read every call as a protocol error. Use a Connect " + "or gRPC-Web transport, or put a proxy in front that translates."
+}, { status: HttpStatusCode2.UNSUPPORTED_MEDIA_TYPE });
+
+class ConnectMiddleware {
+  #registry;
+  constructor(registry) {
+    this.#registry = registry;
+  }
+  claimedPaths() {
+    return this.#registry.paths;
+  }
+  claimedMethods() {
+    return ["POST"];
+  }
+  handle(req, ctx, next) {
+    if (ctx.get(UNMATCHED2) !== true)
+      return next();
+    const route = this.#registry.routeFor(ctx.path);
+    if (route === undefined)
+      return next();
+    const contentType = req.headers.get("content-type");
+    if (contentType !== null && NATIVE_GRPC.test(contentType)) {
+      return Promise.resolve(grpcUnsupported());
+    }
+    if (route.streaming) {
+      ctx.get(REQUEST_SERVER)?.timeout(req, this.#registry.streamTimeout);
+    }
+    return route.handle(req);
+  }
+}
+Object.defineProperty(ConnectMiddleware, Symbol.for("dunx.deps"), { value: () => [ConnectRegistry] });
+// src/connect/module.ts
+import {
+  Module,
+  provide
+} from "@dunx/core";
+var build = (services, options, imports) => {
+  const implementations = services.map((registration) => registration.useClass);
+  return {
+    module: ConnectModule,
+    imports,
+    exports: [ConnectOptions, ConnectRegistry, ConnectMiddleware],
+    providers: [
+      ...implementations,
+      options,
+      provide(ConnectRegistry, {
+        useFactory: (...deps) => {
+          const [resolved, ...instances] = deps;
+          return new ConnectRegistry(resolved, instances);
+        },
+        inject: [ConnectOptions, ...implementations]
+      }),
+      provide(ConnectMiddleware, {
+        useFactory: (registry) => new ConnectMiddleware(registry),
+        inject: [ConnectRegistry]
+      })
+    ]
+  };
+};
+var _dec = [
+  Module({})
+];
+var _init = __decoratorStart(undefined);
+
+class ConnectModule {
+  static forRoot(init) {
+    return build(init.services, provide(ConnectOptions, { useValue: new ConnectOptions(init) }), init.imports ?? []);
+  }
+  static forRootAsync(services, config) {
+    return build(services, provide(ConnectOptions, {
+      useFactory: async (...deps) => new ConnectOptions({
+        ...await config.useFactory(...deps),
+        services
+      }),
+      inject: config.inject ?? []
+    }), config.imports ?? []);
+  }
+}
+ConnectModule = __decorateElement(_init, 0, "ConnectModule", _dec, ConnectModule);
+__runInitializers(_init, 1, ConnectModule);
+__decoratorMetadata(_init, ConnectModule);
+let _ConnectModule = ConnectModule;
+export {
+  ConnectMiddleware,
+  ConnectModule,
+  ConnectOptions,
+  ConnectRegistry,
+  connectService
+};

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Controller, Delete, Get, Patch, Post, Put, } from './route/decorators.js';
 export type { HttpMethod, RoutePath } from './route/marker.js';
-export { ApiHidden, HIDDEN, meta, metaKey, metaOf, mergeMeta, Public, PUBLIC, Roles, ROLES, UNMATCHED, UseGuards, type MetaKey, type MetaRecord, } from './route/metadata.js';
+export { ApiHidden, HIDDEN, meta, metaKey, metaOf, mergeMeta, Public, PUBLIC, Roles, ROLES, STREAMS, UNMATCHED, UseGuards, type MetaKey, type MetaRecord, } from './route/metadata.js';
 export type { InferOutput, Input, JsonSchema, ResponseMap, Returns, RouteInput, RouteSchemas, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1, } from './route/schema.js';
 export { ClientAddress } from './server/client-address.js';
 export type { RouteContext } from './server/context.js';
@@ -19,6 +19,9 @@ export { StaticOptions, type StaticOptionsInit } from './static/options.js';
 export { Compression } from './compression/compression.js';
 export { CompressionModule } from './compression/module.js';
 export { CompressionEncoding, CompressionOptions, type CompressionOptionsInit, } from './compression/options.js';
+export { Sse, type SseInput, type SseResult, type SseSchemas, } from './sse/decorators.js';
+export type { SseEvent } from './sse/event.js';
+export { SseStream, type SseStreamOptions } from './sse/stream.js';
 export { SKIP_THROTTLE, SkipThrottle, THROTTLE, Throttle, type ThrottleLimit, } from './throttle/decorators.js';
 export { ThrottleGuard } from './throttle/guard.js';
 export { ThrottleModule } from './throttle/module.js';