@dunx/http 3.5.1 → 3.7.0

package/dist/client.js

@@ -1,12 +1,12 @@
 // @bun
+import {
+  HttpStatusCode2
+} from "./chunk-bg0dr54z.js";
 import {
   TRACEPARENT_HEADER2,
   TRACESTATE_HEADER2,
   TraceContext2
 } from "./chunk-gmtwad7f.js";
-import {
-  HttpStatusCode2
-} from "./chunk-bg0dr54z.js";
 
 // src/client/errors.ts
 import { AppError } from "@dunx/core";
@@ -71,6 +71,45 @@ class HttpClientOptions {
   }
 }
 Object.defineProperty(HttpClientOptions, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "init: HttpClientOptionsInit = {}", optional: true }] });
+// src/client/retry.ts
+import {
+  RetryClassifier
+} from "@dunx/core";
+var retryAfterMs = (headers, now = Date.now()) => {
+  const header = headers.get("retry-after");
+  if (header === null)
+    return;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds))
+    return Math.max(0, seconds * 1000);
+  const at = Date.parse(header);
+  return Number.isNaN(at) ? undefined : Math.max(0, at - now);
+};
+var isRetryableStatus = (status) => status >= HttpStatusCode2.INTERNAL_SERVER_ERROR || status === HttpStatusCode2.REQUEST_TIMEOUT || status === HttpStatusCode2.TOO_MANY_REQUESTS;
+
+class HttpRetryClassifier extends RetryClassifier {
+  options;
+  constructor(options = {}) {
+    super();
+    this.options = options;
+  }
+  classify(error) {
+    if (error instanceof FetchTransportError)
+      return { retry: !error.aborted };
+    if (error instanceof FetchError) {
+      const {
+        shouldRetryOnStatus = isRetryableStatus,
+        respectRetryAfter = true
+      } = this.options;
+      if (!shouldRetryOnStatus(error.status))
+        return { retry: false };
+      const asked = respectRetryAfter ? retryAfterMs(error.response.headers) : undefined;
+      return asked === undefined ? { retry: true } : { retry: true, delayMs: asked };
+    }
+    return { retry: true };
+  }
+}
+Object.defineProperty(HttpRetryClassifier, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "private readonly options: HttpRetryOptions = {}", optional: true }] });
 // src/client/module.ts
 import {
   Logger as Logger2,
@@ -80,10 +119,16 @@ import {
 } from "@dunx/core";
 
 // src/client/service.ts
-import { Logger, RequestContext } from "@dunx/core";
+import {
+  Logger,
+  RequestContext,
+  ResilienceOptions,
+  ResiliencePolicy
+} from "@dunx/core";
 import { UrlHelper } from "@arkv/shared";
 
 // src/client/json.ts
+import { isPlainObject } from "@dunx/core";
 var safeStringify = (value) => {
   const seen = new WeakSet;
   return JSON.stringify(value, (_key, entry) => {
@@ -102,69 +147,90 @@ var isJsonBody = (payload) => {
     return typeof payload !== "string";
   return !(payload instanceof FormData || payload instanceof URLSearchParams || payload instanceof Blob || payload instanceof ArrayBuffer || payload instanceof ReadableStream || ArrayBuffer.isView(payload));
 };
-
-// src/client/retry.ts
-var uniform = () => {
-  const buffer = new Uint32Array(1);
-  crypto.getRandomValues(buffer);
-  return (buffer[0] ?? 0) / 2 ** 32;
-};
-var backoffDelay = (attempt, { baseMs, power = 2, jitterMs = 1000, maxMs = 30000 }) => Math.min(baseMs * power ** attempt + uniform() * jitterMs, maxMs);
-var retryAfterMs = (headers, now = Date.now()) => {
-  const header = headers.get("retry-after");
-  if (header === null)
+var readBody = async (response) => {
+  const text = await response.text();
+  if (text === "")
     return;
-  const seconds = Number(header);
-  if (Number.isFinite(seconds))
-    return Math.max(0, seconds * 1000);
-  const at = Date.parse(header);
-  return Number.isNaN(at) ? undefined : Math.max(0, at - now);
-};
-var isRetryableStatus = (status) => status >= HttpStatusCode2.INTERNAL_SERVER_ERROR || status === HttpStatusCode2.REQUEST_TIMEOUT || status === HttpStatusCode2.TOO_MANY_REQUESTS;
-var decide = (error, attempt, options) => {
-  const {
-    retryDelayMs = 1000,
-    backoff,
-    shouldRetryOnStatus = isRetryableStatus,
-    respectRetryAfter = true
-  } = options;
-  const computed = backoffDelay(attempt, { baseMs: retryDelayMs, ...backoff });
-  if (error instanceof FetchTransportError) {
-    return { retry: !error.aborted, delayMs: computed };
-  }
-  if (error instanceof FetchError) {
-    if (!shouldRetryOnStatus(error.status))
-      return { retry: false, delayMs: 0 };
-    const asked = respectRetryAfter ? retryAfterMs(error.response.headers) : undefined;
-    const maxMs = backoff?.maxMs ?? 30000;
-    return {
-      retry: true,
-      delayMs: asked === undefined ? computed : Math.min(asked, maxMs)
-    };
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
   }
-  return { retry: true, delayMs: computed };
 };
-var executeWithRetry = async (operation, options = {}) => {
-  const { maxRetries = 3, onAttempt, onError, onSuccess } = options;
-  let lastError;
-  for (let attempt = 0;attempt <= maxRetries; attempt += 1) {
-    onAttempt?.(attempt + 1, attempt > 0);
-    try {
-      const result = await operation();
-      onSuccess?.(result, attempt + 1);
-      return result;
-    } catch (error) {
-      lastError = error;
-      const { retry, delayMs } = decide(error, attempt, options);
-      const willRetry = retry && attempt < maxRetries;
-      onError?.(error, attempt + 1, willRetry);
-      if (!willRetry)
-        throw error;
-      await Bun.sleep(delayMs);
+
+// src/client/sse.ts
+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 = "";
+  let data = [];
+  let event;
+  let id;
+  let retry;
+  for await (const chunk of body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let end = LINE.exec(buffer);
+    while (end !== null) {
+      const line = buffer.slice(0, end.index);
+      buffer = buffer.slice(end.index + end[0].length);
+      end = LINE.exec(buffer);
+      if (line === "") {
+        const payload = data.join(`
+`);
+        data = [];
+        if (payload === "") {
+          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);
     }
   }
-  throw lastError;
-};
+}
+class ConnectDeadline {
+  #controller = new AbortController;
+  #timer;
+  constructor(ms, target) {
+    this.#timer = ms > 0 ? setTimeout(() => {
+      this.#controller.abort(new DOMException(`Connecting to ${target} timed out after ${ms}ms`, "TimeoutError"));
+    }, ms) : undefined;
+  }
+  get signal() {
+    return this.#controller.signal;
+  }
+  clear() {
+    if (this.#timer !== undefined)
+      clearTimeout(this.#timer);
+  }
+}
+Object.defineProperty(ConnectDeadline, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "ms: number" }, { unresolved: "target: string" }] });
 
 // src/client/service.ts
 class HttpService extends UrlHelper {
@@ -184,12 +250,14 @@ class HttpService extends UrlHelper {
     let status;
     const { body, serialised } = this.bodyFor(config.payload);
     const replayable = !(config.payload instanceof ReadableStream);
-    const attempt = async () => {
+    const attempt = async (signal) => {
       attempts += 1;
-      const response = await this.send(config, url, body, serialised);
+      const response = await this.send(config, url, body, serialised, signal);
       status = response.status;
       if (!response.ok) {
-        throw new FetchError(response.status, response.statusText, await readBody(response), {
+        throw new FetchError(response.status, response.statusText, await readBody(response).catch(() => {
+          return;
+        }), {
           method: config.method,
           url: url.href,
           headers: response.headers
@@ -198,15 +266,16 @@ class HttpService extends UrlHelper {
       return await readBody(response);
     };
     const describe = () => `${config.method} ${url.href}`;
+    const policy = this.policyFor(config, {
+      ...this.options.retry,
+      ...config.retry,
+      ...replayable ? {} : { maxRetries: 0 }
+    });
     try {
       const result = await this.requestContext.runWithContext({
         ...config.flow === undefined ? {} : { flow: config.flow },
         event: config.path ?? url.pathname
-      }, () => executeWithRetry(attempt, {
-        ...this.options.retry,
-        ...config.retry,
-        ...replayable ? {} : { maxRetries: 0 }
-      }));
+      }, () => policy.run(attempt));
       this.logger.debug(`${describe()} succeeded`, {
         status,
         attempts,
@@ -261,34 +330,29 @@ 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();
     const { body, serialised } = this.bodyFor(config.payload);
-    const response = await this.send({ ...config, method }, url, body, serialised, "text/event-stream");
+    const deadline = new ConnectDeadline(config.timeoutMs ?? this.options.timeoutMs, url.href);
+    let response;
+    try {
+      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();
+    }
     if (!response.ok || response.body === null) {
-      throw new FetchError(response.status, response.statusText, await readBody(response), { method, url: url.href, headers: response.headers });
+      throw new FetchError(response.status, response.statusText, await readBody(response).catch(() => {
+        return;
+      }), { method, url: url.href, headers: response.headers });
     }
-    const decoder = new TextDecoder;
-    let buffer = "";
     try {
-      for await (const chunk of response.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(`
-`);
-          if (!line.startsWith("data:"))
-            continue;
-          const data = line.slice(5).trim();
-          if (data === "[DONE]")
-            return;
-          yield data;
-        }
-      }
+      yield* sseMessages(response.body);
     } finally {
       this.logger.debug(`SSE ${method} ${url.href} closed`, {
         elapsedMs: Date.now() - startedAt
@@ -313,6 +377,14 @@ class HttpService extends UrlHelper {
       ...config.queryParams === undefined ? {} : { queryParams: config.queryParams }
     });
   }
+  policyFor(config, retry) {
+    return new ResiliencePolicy(new ResilienceOptions({
+      timeoutMs: config.timeoutMs ?? this.options.timeoutMs,
+      ...config.signal === undefined ? {} : { signal: config.signal },
+      retry,
+      classifier: new HttpRetryClassifier(retry)
+    }));
+  }
   bodyFor(payload) {
     if (payload === undefined || payload === null) {
       return { body: undefined, serialised: "", json: false };
@@ -323,7 +395,7 @@ class HttpService extends UrlHelper {
     const serialised = JSON.stringify(payload);
     return { body: serialised, serialised, json: true };
   }
-  async send(config, url, body, serialised, accept = "application/json") {
+  async send(config, url, body, serialised, signal, accept = "application/json") {
     const trace = this.options.propagateTrace ? this.requestContext.getContext() : undefined;
     const headers = {
       accept,
@@ -345,17 +417,12 @@ class HttpService extends UrlHelper {
       }),
       ...config.headers
     };
-    const timeoutMs = config.timeoutMs ?? this.options.timeoutMs;
-    const signals = [
-      ...timeoutMs > 0 ? [AbortSignal.timeout(timeoutMs)] : [],
-      ...config.signal === undefined ? [] : [config.signal]
-    ];
     try {
       return await fetch(url.href, {
         method: config.method,
         headers,
         ...body === undefined ? {} : { body },
-        ...signals.length === 0 ? {} : { signal: AbortSignal.any(signals) },
+        signal,
         ...this.options.fetchOptions
       });
     } catch (error) {
@@ -366,16 +433,6 @@ class HttpService extends UrlHelper {
 }
 Object.defineProperty(HttpService, Symbol.for("dunx.deps"), { value: () => [HttpClientOptions, Logger, RequestContext] });
 var urlOf = (url) => url === undefined ? {} : { url };
-var readBody = async (response) => {
-  const text = await response.text().catch(() => "");
-  if (text === "")
-    return;
-  try {
-    return JSON.parse(text);
-  } catch {
-    return text;
-  }
-};
 var describeError = (error) => {
   if (error instanceof FetchError) {
     return {
@@ -458,6 +515,7 @@ export {
   FetchTransportError,
   HttpClientOptions,
   HttpModule,
+  HttpRetryClassifier,
   HttpService,
   httpClient
 };

package/dist/connect/middleware.d.ts

@@ -0,0 +1,25 @@
+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` is the one that does **not** cover an RPC: it returns early on
+ * every unmatched path so a burst of 404s cannot spend a caller's budget, and an
+ * RPC is unmatched. 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[];
+    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,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';