@dunx/http 3.6.0 → 3.7.0

package/dist/connect/options.d.ts

@@ -0,0 +1,64 @@
+import type { DescService } from '@bufbuild/protobuf';
+import type { ConnectRouterOptions, ServiceImpl } from '@connectrpc/connect';
+import type { Ctor, 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` returns early on every
+     * unmatched path and an RPC is unmatched, so nothing else here bounds how long
+     * or how many streams one caller holds open.
+     *
+     * @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,208 @@
+// @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 {
+  createConnectRouter
+} from "@connectrpc/connect";
+import { createFetchHandler } from "@connectrpc/connect/protocol";
+
+// src/connect/options.ts
+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 Error(`ConnectModule streamTimeout must be a non-negative number of seconds, got ${String(streamTimeout)}.`);
+    }
+    this.router = router;
+    if (!this.connect && !this.grpcWeb) {
+      throw new Error("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 Error("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 Error(`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;
+  }
+  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';