@dunx/http 3.1.1 → 3.1.2

package/dist/{chunk-3xs8zrpv.js → chunk-53cs6qek.js}

@@ -534,6 +534,7 @@ var discoverGateways = (modules, resolve) => {
 };
 
 // src/ws/relay.ts
+import { AppError as AppError4 } from "@dunx/core";
 var DEFAULT_RELAY_CHANNEL = "dunx:ws";
 var defaultRelayError = (error, phase) => {
   console.warn(`[dunx/http] the websocket relay could not ${phase}. Fan-out is local to ` + "this process until it recovers:", error);
@@ -561,6 +562,14 @@ var decodeRelay = (message) => {
   return { origin: o, topic: t, data: b ? Buffer.from(d, "base64") : d };
 };
 
+class WsRelay {
+  constructor() {
+    if (new.target === WsRelay) {
+      throw new AppError4("WsRelay is a contract, not an implementation. Bind one with " + "WsRelayModule.forRoot() for Redis or WsRelayModule.forPostgres() " + "for Postgres, or extend it with a relay of your own.");
+    }
+  }
+}
+
 // src/server/request-id.ts
 var REQUEST_ID_HEADER = "x-request-id";
 var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -651,7 +660,7 @@ var preflight = (options, methods) => {
 var compose = (middleware, ctx, handler) => middleware.reduceRight((next, current) => (req) => current.handle(req, ctx, () => next(req)), handler);
 
 // src/server/routes.ts
-import { AppError as AppError4 } from "@dunx/core";
+import { AppError as AppError5 } from "@dunx/core";
 
 // src/server/raw-body.ts
 var WANTED = Symbol.for("dunx.http.rawBody.wanted");
@@ -793,7 +802,7 @@ var assertNoCollisions = (discovered) => {
     const owner = `${route.controller}.${route.handlerName}`;
     const existing = owners.get(key);
     if (existing !== undefined) {
-      throw new AppError4(`Route collision: ${key} is declared by ${existing} and by ${owner}. ` + "Bun would keep only one of them.");
+      throw new AppError5(`Route collision: ${key} is declared by ${existing} and by ${owner}. ` + "Bun would keep only one of them.");
     }
     owners.set(key, owner);
   }
@@ -802,7 +811,7 @@ var assertNoGatewayCollisions = (discovered, gatewayPaths) => {
   const gateways = new Set(gatewayPaths);
   for (const route of discovered) {
     if (gateways.has(route.path)) {
-      throw new AppError4(`Gateway path collision: ${route.path} is served by a gateway and by ` + `${route.controller}.${route.handlerName}(). The upgrade is a route too, ` + "so one of them would be dropped.");
+      throw new AppError5(`Gateway path collision: ${route.path} is served by a gateway and by ` + `${route.controller}.${route.handlerName}(). The upgrade is a route too, ` + "so one of them would be dropped.");
     }
   }
 };
@@ -1018,7 +1027,7 @@ class CompressionOptions {
 Object.defineProperty(CompressionOptions, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "init: CompressionOptionsInit = {}", optional: true }] });
 
 // src/ws/redis-relay.ts
-import { AppError as AppError5 } from "@dunx/core";
+import { AppError as AppError6 } from "@dunx/core";
 var PROTOCOLS = [
   "redis:",
   "rediss:",
@@ -1034,21 +1043,22 @@ var assertUrl = (url) => {
   try {
     parsed = new URL(url);
   } catch {
-    throw new AppError5(`${JSON.stringify(url)} is not a valid URL for the websocket relay. ` + "Expected something like redis://localhost:6379.");
+    throw new AppError6(`${JSON.stringify(url)} is not a valid URL for the websocket relay. ` + "Expected something like redis://localhost:6379.");
   }
   if (!PROTOCOLS.includes(parsed.protocol)) {
-    throw new AppError5(`Unsupported protocol ${JSON.stringify(parsed.protocol)} in ` + `${JSON.stringify(url)}. Expected one of ${PROTOCOLS.join(", ")}.`);
+    throw new AppError6(`Unsupported protocol ${JSON.stringify(parsed.protocol)} in ` + `${JSON.stringify(url)}. Expected one of ${PROTOCOLS.join(", ")}.`);
   }
   return url;
 };
 
-class RedisRelay {
+class RedisRelay extends WsRelay {
   #url;
   #options;
   #pub;
   #sub;
   #channel;
   constructor(options = {}) {
+    super();
     this.#url = assertUrl(options.url ?? defaultRelayUrl());
     this.#options = {
       maxRetries: options.maxRetries ?? 0,
@@ -1303,4 +1313,4 @@ __runInitializers(_init, 1, HiddenHealthController);
 __decoratorMetadata(_init, HiddenHealthController);
 let _HiddenHealthController = HiddenHealthController;
 
-export { defaultStatusFor, Controller, Get, Post, Put, Patch, Delete, metaKey, meta, ROLES, PUBLIC, HIDDEN, UNMATCHED, Roles, Public, ApiHidden, UseGuards, guardsOf, metaOf, mergeMeta, HttpError, ValidationError, ErrorFilter, isErrorFilter, toErrorMapper, errorMapper, defaultErrorMapper, joinPath, discoverRoutes, encode, decode, HandlerKind, markHandler, markGateway, isGateway, composeSocket, observe, buildRuntime, buildGateways, buildWebSocket, normalizePath, discoverGateway, discoverGateways, DEFAULT_RELAY_CHANNEL, defaultRelayError, encodeRelay, decodeRelay, RawBody, REQUEST_ID_HEADER, RequestIds, buildContext, withCors, preflight, compose, assertNoCollisions, assertNoGatewayCollisions, withUpgradeRoutes, buildFallback, buildRoutes, StaticOptions, normalizePrefix, negotiate, CompressionEncoding, isCompressibleType, CompressionOptions, defaultRelayUrl, RedisRelay, HEALTH_REPORT_SCHEMA, HealthOptions, HealthRegistry, HealthController, HiddenHealthController };
+export { defaultStatusFor, Controller, Get, Post, Put, Patch, Delete, metaKey, meta, ROLES, PUBLIC, HIDDEN, UNMATCHED, Roles, Public, ApiHidden, UseGuards, guardsOf, metaOf, mergeMeta, HttpError, ValidationError, ErrorFilter, isErrorFilter, toErrorMapper, errorMapper, defaultErrorMapper, joinPath, discoverRoutes, encode, decode, HandlerKind, markHandler, markGateway, isGateway, composeSocket, observe, buildRuntime, buildGateways, buildWebSocket, normalizePath, discoverGateway, discoverGateways, DEFAULT_RELAY_CHANNEL, defaultRelayError, encodeRelay, decodeRelay, WsRelay, RawBody, REQUEST_ID_HEADER, RequestIds, buildContext, withCors, preflight, compose, assertNoCollisions, assertNoGatewayCollisions, withUpgradeRoutes, buildFallback, buildRoutes, StaticOptions, normalizePrefix, negotiate, CompressionEncoding, isCompressibleType, CompressionOptions, defaultRelayUrl, RedisRelay, HEALTH_REPORT_SCHEMA, HealthOptions, HealthRegistry, HealthController, HiddenHealthController };

package/dist/index.d.ts

@@ -30,9 +30,10 @@ export type { Envelope } from './ws/envelope.js';
 export type { SocketContext, SocketDispatch, SocketFrame, SocketMiddleware, SocketNext, } from './ws/middleware.js';
 export { SocketLoggingMiddleware, type SocketLoggingOptions, } from './ws/logging.js';
 export { PubSub } from './ws/pubsub.js';
+export { PostgresRelay, type PostgresRelayOptions, } from './ws/postgres-relay.js';
 export { RedisRelay, type RedisRelayOptions } from './ws/redis-relay.js';
-export { RelayConnectionOptions, WsRelayModule } from './ws/relay-module.js';
-export { DEFAULT_RELAY_CHANNEL, type PubSubRelay, type RelayOptions, } from './ws/relay.js';
+export { PostgresRelayConnectionOptions, RelayConnectionOptions, WsRelayModule, } from './ws/relay-module.js';
+export { DEFAULT_RELAY_CHANNEL, WsRelay, type PubSubRelay, type RelayOptions, } from './ws/relay.js';
 export type { Socket, SocketData, SocketErrorHandler, SocketOptions, } from './ws/socket.js';
 export { HealthIndicator, PingProbe, QueryProbe, type ProbeResult, type ProbeState, } from './health/contracts.js';
 export { HealthController } from './health/controller.js';

package/dist/index.js

@@ -36,6 +36,7 @@ import {
   UNMATCHED,
   UseGuards,
   ValidationError,
+  WsRelay,
   assertNoCollisions,
   assertNoGatewayCollisions,
   buildFallback,
@@ -60,7 +61,7 @@ import {
   observe,
   toErrorMapper,
   withUpgradeRoutes
-} from "./chunk-3xs8zrpv.js";
+} from "./chunk-53cs6qek.js";
 import {
   HttpStatusCode,
   __decorateElement,
@@ -1396,6 +1397,71 @@ var OnMessage = (event) => (value) => {
   markHandler(value, { kind: HandlerKind.MESSAGE, event });
   return value;
 };
+// src/ws/postgres-relay.ts
+import { AppError as AppError7 } from "@dunx/core";
+var PROTOCOLS = ["postgres:", "postgresql:"];
+var defaultPostgresRelayUrl = () => process.env["POSTGRES_URL"] ?? process.env["DATABASE_URL"] ?? "postgres://localhost:5432";
+var assertUrl = (url) => {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new AppError7(`${JSON.stringify(url)} is not a valid URL for the websocket relay. ` + "Expected something like postgres://localhost:5432/app.");
+  }
+  if (!PROTOCOLS.includes(parsed.protocol)) {
+    throw new AppError7(`Unsupported protocol ${JSON.stringify(parsed.protocol)} in ` + `${JSON.stringify(url)}. Expected one of ${PROTOCOLS.join(", ")}.`);
+  }
+  return url;
+};
+
+class PostgresRelay extends WsRelay {
+  #url;
+  #max;
+  #sql;
+  #subscription;
+  constructor(options = {}) {
+    super();
+    this.#url = assertUrl(options.url ?? defaultPostgresRelayUrl());
+    this.#max = options.max ?? 1;
+  }
+  get url() {
+    const parsed = new URL(this.#url);
+    if (parsed.password)
+      parsed.password = "***";
+    return parsed.toString();
+  }
+  #client() {
+    return this.#sql ??= new Bun.SQL({ url: this.#url, max: this.#max });
+  }
+  async publish(channel, message) {
+    await this.#client().notify(channel, message);
+  }
+  async subscribe(channel, listener) {
+    const sql = this.#client();
+    try {
+      this.#subscription = await sql.listen(channel, listener);
+    } catch (error) {
+      if (this.#sql === sql) {
+        this.#sql = undefined;
+        await sql.close();
+      }
+      throw error;
+    }
+  }
+  async close() {
+    const sql = this.#sql;
+    const subscription = this.#subscription;
+    this.#sql = undefined;
+    this.#subscription = undefined;
+    if (subscription) {
+      try {
+        await subscription.unlisten();
+      } catch {}
+    }
+    await sql?.close();
+  }
+}
+Object.defineProperty(PostgresRelay, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "options: PostgresRelayOptions = {}", optional: true }] });
 // src/ws/relay-module.ts
 import {
   provide as provide5
@@ -1424,6 +1490,22 @@ class RelayConnectionOptions {
 }
 Object.defineProperty(RelayConnectionOptions, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "init: RedisRelayOptions = {}", optional: true, typeOnly: "RedisRelayOptions" }] });
 
+class PostgresRelayConnectionOptions {
+  url;
+  max;
+  constructor(init = {}) {
+    this.url = init.url;
+    this.max = init.max;
+  }
+  toInit() {
+    return {
+      ...this.url !== undefined && { url: this.url },
+      ...this.max !== undefined && { max: this.max }
+    };
+  }
+}
+Object.defineProperty(PostgresRelayConnectionOptions, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "init: PostgresRelayOptions = {}", optional: true, typeOnly: "PostgresRelayOptions" }] });
+
 class RelayLifecycle {
   relay;
   constructor(relay) {
@@ -1433,16 +1515,35 @@ class RelayLifecycle {
     await this.relay.close();
   }
 }
-Object.defineProperty(RelayLifecycle, Symbol.for("dunx.deps"), { value: () => [RedisRelay] });
-var bindings = (options) => [
+Object.defineProperty(RelayLifecycle, Symbol.for("dunx.deps"), { value: () => [WsRelay] });
+var redisBindings = (options) => [
   provide5(RelayConnectionOptions, options),
   provide5(RedisRelay, {
     useFactory: (settings) => new RedisRelay(settings.toInit()),
     inject: [RelayConnectionOptions]
   }),
+  provide5(WsRelay, {
+    useFactory: (relay) => relay,
+    inject: [RedisRelay]
+  }),
   provide5(RelayLifecycle, {
     useFactory: (relay) => new RelayLifecycle(relay),
-    inject: [RedisRelay]
+    inject: [WsRelay]
+  })
+];
+var postgresBindings = (options) => [
+  provide5(PostgresRelayConnectionOptions, options),
+  provide5(PostgresRelay, {
+    useFactory: (settings) => new PostgresRelay(settings.toInit()),
+    inject: [PostgresRelayConnectionOptions]
+  }),
+  provide5(WsRelay, {
+    useFactory: (relay) => relay,
+    inject: [PostgresRelay]
+  }),
+  provide5(RelayLifecycle, {
+    useFactory: (relay) => new RelayLifecycle(relay),
+    inject: [WsRelay]
   })
 ];
 
@@ -1450,8 +1551,8 @@ class WsRelayModule {
   static forRoot(init = {}) {
     return {
       module: WsRelayModule,
-      exports: [RedisRelay, RelayConnectionOptions],
-      providers: bindings({
+      exports: [WsRelay, RedisRelay, RelayConnectionOptions],
+      providers: redisBindings({
         useFactory: () => new RelayConnectionOptions(init),
         inject: []
       })
@@ -1462,8 +1563,30 @@ class WsRelayModule {
     return {
       module: WsRelayModule,
       ...config.imports === undefined ? {} : { imports: config.imports },
-      exports: [RedisRelay, RelayConnectionOptions],
-      providers: bindings({
+      exports: [WsRelay, RedisRelay, RelayConnectionOptions],
+      providers: redisBindings({
+        useFactory,
+        inject: config.inject ?? []
+      })
+    };
+  }
+  static forPostgres(init = {}) {
+    return {
+      module: WsRelayModule,
+      exports: [WsRelay, PostgresRelay, PostgresRelayConnectionOptions],
+      providers: postgresBindings({
+        useFactory: () => new PostgresRelayConnectionOptions(init),
+        inject: []
+      })
+    };
+  }
+  static forPostgresAsync(config) {
+    const useFactory = async (...deps) => new PostgresRelayConnectionOptions(await config.useFactory(...deps));
+    return {
+      module: WsRelayModule,
+      ...config.imports === undefined ? {} : { imports: config.imports },
+      exports: [WsRelay, PostgresRelay, PostgresRelayConnectionOptions],
+      providers: postgresBindings({
         useFactory,
         inject: config.inject ?? []
       })
@@ -1707,6 +1830,8 @@ export {
   Patch,
   PingProbe,
   Post,
+  PostgresRelay,
+  PostgresRelayConnectionOptions,
   PubSub,
   Public,
   Put,
@@ -1739,6 +1864,7 @@ export {
   UNMATCHED,
   UseGuards,
   ValidationError,
+  WsRelay,
   WsRelayModule,
   defaultErrorMapper,
   errorMapper,

package/dist/internal.js

@@ -36,7 +36,7 @@ import {
   toErrorMapper,
   withCors,
   withUpgradeRoutes
-} from "./chunk-3xs8zrpv.js";
+} from "./chunk-53cs6qek.js";
 import {
   backoffDelay,
   executeWithRetry,

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

@@ -0,0 +1,38 @@
+import { WsRelay } from './relay.js';
+/** The same fallback chain `Bun.SQL` uses when given no URL. */
+export declare const defaultPostgresRelayUrl: () => string;
+export interface PostgresRelayOptions {
+    /** @default `$POSTGRES_URL`, `$DATABASE_URL`, then `postgres://localhost:5432` */
+    readonly url?: string;
+    /**
+     * Size of the query pool `notify` publishes through. **`subscribe` opens a
+     * dedicated connection on top of it**, so a relay that is listening holds up to
+     * `max + 1`. Measured: `max: 1` shows two rows in `pg_stat_activity`.
+     *
+     * @default 1
+     */
+    readonly max?: number;
+}
+/**
+ * A {@link WsRelay} on `Bun.SQL`'s `LISTEN`/`NOTIFY`, a Bun global, so it costs
+ * `@dunx/http` no dependency and an app already on Postgres needs no broker.
+ *
+ * One client, two connections while it listens: Bun dedicates one to the `LISTEN`
+ * and leaves the pool to answer `notify`. Budget `max + 1` per replica.
+ *
+ * **A frame over about 7.9 KB is refused**, because Postgres caps a `NOTIFY`
+ * payload at 7999 bytes and the relay envelope adds to the frame. `PubSub` reports
+ * one `logger.warn` and fan-out stays local for that message. Redis has no
+ * comparable ceiling; measured in docs/architecture/http.md.
+ *
+ * Reconnection is Bun's, so there is no retry budget here.
+ */
+export declare class PostgresRelay extends WsRelay {
+    #private;
+    constructor(options?: PostgresRelayOptions);
+    /** The URL with any password removed, for logs and error messages. */
+    get url(): string;
+    publish(channel: string, message: string): Promise<void>;
+    subscribe(channel: string, listener: (message: string) => void): Promise<void>;
+    close(): Promise<void>;
+}

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

@@ -1,4 +1,4 @@
-import type { PubSubRelay } from './relay.js';
+import { WsRelay } from './relay.js';
 /** The same fallback chain `Bun.RedisClient` uses when given no URL. */
 export declare const defaultRelayUrl: () => string;
 export interface RedisRelayOptions {
@@ -18,14 +18,14 @@ export interface RedisRelayOptions {
     readonly tls?: boolean | Bun.TLSOptions;
 }
 /**
- * A {@link PubSubRelay} on `Bun.RedisClient`, a Bun global, so it costs
+ * A {@link WsRelay} on `Bun.RedisClient`, a Bun global, so it costs
  * `@dunx/http` no dependency.
  *
  * Two connections: a client in subscriber mode rejects every data command, so the
  * subscription cannot share the publishing socket. Both open lazily, and a failed
  * one is discarded rather than reused.
  */
-export declare class RedisRelay implements PubSubRelay {
+export declare class RedisRelay extends WsRelay {
     #private;
     constructor(options?: RedisRelayOptions);
     /** The URL with any password removed, for logs and error messages. */

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

@@ -1,7 +1,8 @@
 import { type AsyncModuleConfig, type Deps, type DynamicModule } from '@dunx/core';
+import { type PostgresRelayOptions } from './postgres-relay.js';
 import { type RedisRelayOptions } from './redis-relay.js';
 /**
- * The relay's connection settings, as a class so a factory can bind them.
+ * The Redis relay's connection settings, as a class so a factory can bind them.
  *
  * `RedisRelayOptions` stays the interface a caller writes; this is what the
  * container holds, which is the same split `HttpClientOptions` and
@@ -16,15 +17,22 @@ export declare class RelayConnectionOptions {
     /** Only the keys actually set, so each `RedisRelay` default still applies. */
     toInit(): RedisRelayOptions;
 }
+/** The same, for the Postgres relay. */
+export declare class PostgresRelayConnectionOptions {
+    readonly url: string | undefined;
+    readonly max: number | undefined;
+    constructor(init?: PostgresRelayOptions);
+    toInit(): PostgresRelayOptions;
+}
 /**
  * Binds the websocket relay, so `relay` is a provider rather than an instance
  * `main.ts` constructs and threads into `HttpFactory.create`.
  *
- * `RedisRelay` is a class, so an options provider takes it as a parameter:
+ * Name {@link WsRelay} at the injection site and the backend is a wiring choice:
  *
  * ```ts
  * export class AppHttpOptions extends HttpOptionsProvider {
- *   constructor(private readonly bus: RedisRelay) {
+ *   constructor(private readonly bus: WsRelay) {
  *     super();
  *   }
  *
@@ -34,11 +42,12 @@ export declare class RelayConnectionOptions {
  * }
  * ```
  *
- * A relay of your own needs no module: bind the class and return it from that
- * same getter. This one exists because `RedisRelay` is the one dunx ships and its
- * url comes from config like everything else.
+ * The backend is chosen by which method you call, not by a field in the options.
+ * A relay of your own needs no module: extend `WsRelay`, bind it, and return it
+ * from that same getter.
  */
 export declare class WsRelayModule {
+    /** Redis or Valkey, over `Bun.RedisClient`. */
     static forRoot(init?: RedisRelayOptions): DynamicModule;
     /**
      * The same bindings with the settings behind a factory, so the url can come off
@@ -46,4 +55,12 @@ export declare class WsRelayModule {
      * alongside does not, since a dynamic module is its own scope.
      */
     static forRootAsync<const D extends Deps>(config: AsyncModuleConfig<RedisRelayOptions, D>): DynamicModule;
+    /**
+     * Postgres, over `Bun.SQL`'s `LISTEN`/`NOTIFY`, for an app that already has a
+     * database and would rather not run a broker. A frame over about 7.9 KB is
+     * refused; see {@link PostgresRelay}.
+     */
+    static forPostgres(init?: PostgresRelayOptions): DynamicModule;
+    /** `forPostgres` with the settings behind a factory. */
+    static forPostgresAsync<const D extends Deps>(config: AsyncModuleConfig<PostgresRelayOptions, D>): DynamicModule;
 }

package/dist/ws/relay.d.ts

@@ -81,3 +81,18 @@ export interface RelayFrame {
 export declare const encodeRelay: (origin: string, topic: string, data: string | Bun.BufferSource) => string;
 /** `undefined` for anything that is not one of our frames, which is then ignored. */
 export declare const decodeRelay: (message: string) => RelayFrame | undefined;
+/**
+ * The injectable form of {@link PubSubRelay}. An interface has no runtime value
+ * for the container to record, so a module binds this and a consumer that wants
+ * the relay names this rather than `RedisRelay` or `PostgresRelay` - which is
+ * what lets the backend change without the code that publishes changing with it.
+ *
+ * `close` is abstract here though it is optional on the interface: a relay the
+ * container built is the container's to close.
+ */
+export declare abstract class WsRelay implements PubSubRelay {
+    constructor();
+    abstract publish(channel: string, message: string): unknown;
+    abstract subscribe(channel: string, listener: (message: string) => void): unknown;
+    abstract close(): unknown;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/http",
-  "version": "3.1.1",
+  "version": "3.1.2",
   "description": "Bun.serve adapter for the dunx framework: controllers, middleware and WebSocket gateways",
   "keywords": [
     "bun",
@@ -62,7 +62,7 @@
     "@dunx/core": "workspace:*"
   },
   "peerDependencies": {
-    "@dunx/core": "^3.1.1",
+    "@dunx/core": "^3.1.2",
     "@types/bun": ">=1.3.0"
   },
   "peerDependenciesMeta": {