@dunx/http 3.8.0 → 3.8.2

package/dist/index.d.ts

@@ -32,10 +32,12 @@ export { Gateway, OnClose, OnDrain, OnMessage, OnOpen, OnPing, OnPong, OnUpgrade
 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 { SocketObserver, type SocketOutcome } from './ws/observer.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 { PostgresRelayConnectionOptions, RelayConnectionOptions, WsRelayModule, } from './ws/relay-module.js';
+export { RelayPublisher, type RelayPublisherInit, } from './ws/relay-publisher.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';

package/dist/index.js

@@ -299,19 +299,19 @@ var observe = (next, done) => {
   try {
     result = next();
   } catch (error) {
-    done(error, undefined);
+    done(error, undefined, false);
     throw error;
   }
   if (result instanceof Promise) {
     return result.then((value) => {
-      done(undefined, value);
+      done(undefined, value, true);
       return value;
     }, (error) => {
-      done(error, undefined);
+      done(error, undefined, false);
       throw error;
     });
   }
-  done(undefined, result);
+  done(undefined, result, true);
   return result;
 };
 
@@ -2671,6 +2671,19 @@ var OnMessage = (event) => (value) => {
   markHandler(value, { kind: HandlerKind.MESSAGE, event });
   return value;
 };
+// src/ws/observer.ts
+class SocketObserver {
+  reportsErrors = false;
+  handle(frame, ctx, next) {
+    return observe(next, (error, value, ok) => {
+      try {
+        this.settled(ok ? { ok, value } : { ok, error }, frame, ctx);
+      } catch (failure) {
+        console.error(`[dunx/http] ${this.constructor.name}.settled threw, which cannot ` + "change the outcome it was watching:", failure);
+      }
+    });
+  }
+}
 // src/ws/postgres-relay.ts
 var PROTOCOLS = ["postgres:", "postgresql:"];
 var defaultPostgresRelayUrl = () => process.env["POSTGRES_URL"] ?? process.env["DATABASE_URL"] ?? "postgres://localhost:5432";
@@ -2800,6 +2813,50 @@ Object.defineProperty(RedisRelay, Symbol.for("dunx.deps"), { value: () => [{ unr
 import {
   provide as provide5
 } from "@dunx/core";
+
+// src/ws/relay-publisher.ts
+class RelayPublisher {
+  relay;
+  #origin = `worker:${Bun.randomUUIDv7()}`;
+  #channel;
+  #onError;
+  constructor(relay, init = {}) {
+    this.relay = relay;
+    this.#channel = init.channel ?? DEFAULT_RELAY_CHANNEL;
+    this.#onError = init.onError ?? defaultRelayError;
+  }
+  get origin() {
+    return this.#origin;
+  }
+  get channel() {
+    return this.#channel;
+  }
+  publishEvent(topic, event, data) {
+    this.publish(topic, encode(event, data));
+  }
+  publish(topic, data) {
+    try {
+      const result = this.relay.publish(this.#channel, encodeRelay(this.#origin, topic, data));
+      if (result instanceof Promise) {
+        result.catch((error) => {
+          this.#report(error);
+        });
+      }
+    } catch (error) {
+      this.#report(error);
+    }
+  }
+  #report(error) {
+    try {
+      this.#onError(error, "publish");
+    } catch (failure) {
+      console.error("[dunx/http] a RelayPublisher onError handler threw:", failure);
+    }
+  }
+}
+Object.defineProperty(RelayPublisher, Symbol.for("dunx.deps"), { value: () => [WsRelay, { unresolved: "init: RelayPublisherInit = {}", optional: true }] });
+
+// src/ws/relay-module.ts
 class RelayConnectionOptions {
   url;
   maxRetries;
@@ -2850,7 +2907,12 @@ class RelayLifecycle {
   }
 }
 Object.defineProperty(RelayLifecycle, Symbol.for("dunx.deps"), { value: () => [WsRelay] });
-var redisBindings = (options) => [
+var publisherBinding = (init) => provide5(RelayPublisher, {
+  useFactory: (relay) => new RelayPublisher(relay, init),
+  inject: [WsRelay]
+});
+var redisBindings = (options, publisher) => [
+  publisherBinding(publisher),
   provide5(RelayConnectionOptions, options),
   provide5(RedisRelay, {
     useFactory: (settings) => new RedisRelay(settings.toInit()),
@@ -2865,7 +2927,8 @@ var redisBindings = (options) => [
     inject: [WsRelay]
   })
 ];
-var postgresBindings = (options) => [
+var postgresBindings = (options, publisher) => [
+  publisherBinding(publisher),
   provide5(PostgresRelayConnectionOptions, options),
   provide5(PostgresRelay, {
     useFactory: (settings) => new PostgresRelay(settings.toInit()),
@@ -2882,48 +2945,58 @@ var postgresBindings = (options) => [
 ];
 
 class WsRelayModule {
-  static forRoot(init = {}) {
+  static forRoot(init = {}, publisher = {}) {
     return {
       module: WsRelayModule,
-      exports: [WsRelay, RedisRelay, RelayConnectionOptions],
+      exports: [WsRelay, RedisRelay, RelayConnectionOptions, RelayPublisher],
       providers: redisBindings({
         useFactory: () => new RelayConnectionOptions(init),
         inject: []
-      })
+      }, publisher)
     };
   }
-  static forRootAsync(config) {
+  static forRootAsync(config, publisher = {}) {
     const useFactory = async (...deps) => new RelayConnectionOptions(await config.useFactory(...deps));
     return {
       module: WsRelayModule,
       ...config.imports === undefined ? {} : { imports: config.imports },
-      exports: [WsRelay, RedisRelay, RelayConnectionOptions],
+      exports: [WsRelay, RedisRelay, RelayConnectionOptions, RelayPublisher],
       providers: redisBindings({
         useFactory,
         inject: config.inject ?? []
-      })
+      }, publisher)
     };
   }
-  static forPostgres(init = {}) {
+  static forPostgres(init = {}, publisher = {}) {
     return {
       module: WsRelayModule,
-      exports: [WsRelay, PostgresRelay, PostgresRelayConnectionOptions],
+      exports: [
+        WsRelay,
+        PostgresRelay,
+        PostgresRelayConnectionOptions,
+        RelayPublisher
+      ],
       providers: postgresBindings({
         useFactory: () => new PostgresRelayConnectionOptions(init),
         inject: []
-      })
+      }, publisher)
     };
   }
-  static forPostgresAsync(config) {
+  static forPostgresAsync(config, publisher = {}) {
     const useFactory = async (...deps) => new PostgresRelayConnectionOptions(await config.useFactory(...deps));
     return {
       module: WsRelayModule,
       ...config.imports === undefined ? {} : { imports: config.imports },
-      exports: [WsRelay, PostgresRelay, PostgresRelayConnectionOptions],
+      exports: [
+        WsRelay,
+        PostgresRelay,
+        PostgresRelayConnectionOptions,
+        RelayPublisher
+      ],
       providers: postgresBindings({
         useFactory,
         inject: config.inject ?? []
-      })
+      }, publisher)
     };
   }
 }
@@ -3375,6 +3448,7 @@ export {
   RedisRelay,
   RedisThrottleStore,
   RelayConnectionOptions,
+  RelayPublisher,
   RequestLoggingMiddleware,
   RequestMetrics,
   Roles2 as Roles,
@@ -3382,6 +3456,7 @@ export {
   STREAMS2 as STREAMS,
   SkipThrottle,
   SocketLoggingMiddleware,
+  SocketObserver,
   Sse,
   SseStream,
   StaticFiles2 as StaticFiles,

package/dist/ws/middleware.d.ts

@@ -79,8 +79,11 @@ export declare const composeSocket: (middleware: readonly SocketMiddleware[], ct
  * Calls `next()` and reports how it went, on whichever channel it went out on,
  * leaving the result untouched.
  *
- * `error` is `undefined` on success. A synchronous throw and a rejection both
- * reach `done` and are then rethrown, so a middleware that only observes cannot
- * accidentally swallow a failure.
+ * A synchronous throw and a rejection both reach `done` and are then rethrown, so
+ * a middleware that only observes cannot accidentally swallow a failure.
+ *
+ * `ok` says which happened, and it is not `error === undefined`: a handler may
+ * `throw undefined` or reject with it, and that reads as a success that returned
+ * nothing to anything comparing the value.
  */
-export declare const observe: (next: SocketNext, done: (error: unknown, value: unknown) => void) => unknown;
+export declare const observe: (next: SocketNext, done: (error: unknown, value: unknown, ok: boolean) => void) => unknown;

package/dist/ws/observer.d.ts

@@ -0,0 +1,46 @@
+import { type SocketContext, type SocketFrame, type SocketMiddleware, type SocketNext } from './middleware.js';
+/**
+ * How a handler went. A union rather than an `error` that is `undefined` on
+ * success: a handler may `throw undefined`, and `error !== undefined` reads that
+ * as a success.
+ */
+export type SocketOutcome = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+};
+/**
+ * A {@link SocketMiddleware} that watches a frame and changes nothing about it.
+ *
+ * A gateway handler may return a value or a promise, so a middleware wanting the
+ * outcome has to handle a throw and a rejection and rethrow both; getting it
+ * wrong silently swallows a failure. Extend this and implement {@link settled}
+ * instead - the result reaches the caller untouched, `settled` throwing
+ * included.
+ *
+ * ```ts
+ * export class Reporter extends SocketObserver {
+ *   override readonly reportsErrors = true;
+ *
+ *   protected override settled(outcome: SocketOutcome, _f: SocketFrame, ctx: SocketContext): void {
+ *     if (outcome.ok) return;
+ *     this.logger.error('socket handler failed', { event: ctx.event, err: outcome.error });
+ *   }
+ * }
+ * ```
+ *
+ * One that answers or refuses a frame is not this: implement `SocketMiddleware`.
+ */
+export declare abstract class SocketObserver implements SocketMiddleware {
+    /**
+     * Override to `true` when {@link settled} reports a failure somewhere. See
+     * {@link SocketMiddleware.reportsErrors} - a middleware that ignores a throw
+     * and claims otherwise turns error reporting off for the whole server.
+     */
+    readonly reportsErrors: boolean;
+    handle(frame: SocketFrame, ctx: SocketContext, next: SocketNext): unknown;
+    /** How the handler went, once per frame, on whichever channel it used. */
+    protected abstract settled(outcome: SocketOutcome, frame: SocketFrame, ctx: SocketContext): void;
+}

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

@@ -1,6 +1,7 @@
 import { type AsyncModuleConfig, type Deps, type DynamicModule } from '@dunx/core';
 import { type PostgresRelayOptions } from './postgres-relay.js';
 import { type RedisRelayOptions } from './redis-relay.js';
+import { type RelayPublisherInit } from './relay-publisher.js';
 /**
  * The Redis relay's connection settings, as a class so a factory can bind them.
  *
@@ -48,19 +49,19 @@ export declare class PostgresRelayConnectionOptions {
  */
 export declare class WsRelayModule {
     /** Redis or Valkey, over `Bun.RedisClient`. */
-    static forRoot(init?: RedisRelayOptions): DynamicModule;
+    static forRoot(init?: RedisRelayOptions, publisher?: RelayPublisherInit): DynamicModule;
     /**
      * The same bindings with the settings behind a factory, so the url can come off
      * `ConfigService`. `imports` reaches that factory; importing the module
      * alongside does not, since a dynamic module is its own scope.
      */
-    static forRootAsync<const D extends Deps>(config: AsyncModuleConfig<RedisRelayOptions, D>): DynamicModule;
+    static forRootAsync<const D extends Deps>(config: AsyncModuleConfig<RedisRelayOptions, D>, publisher?: RelayPublisherInit): 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;
+    static forPostgres(init?: PostgresRelayOptions, publisher?: RelayPublisherInit): DynamicModule;
     /** `forPostgres` with the settings behind a factory. */
-    static forPostgresAsync<const D extends Deps>(config: AsyncModuleConfig<PostgresRelayOptions, D>): DynamicModule;
+    static forPostgresAsync<const D extends Deps>(config: AsyncModuleConfig<PostgresRelayOptions, D>, publisher?: RelayPublisherInit): DynamicModule;
 }

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

@@ -0,0 +1,50 @@
+import { WsRelay, type RelayOptions } from './relay.js';
+/** What a publisher needs beyond the relay itself. */
+export interface RelayPublisherInit {
+    /**
+     * The broker channel, which **must** be the one the servers listen on
+     * (`HttpOptionsProvider.relayChannel`). A mismatch is silent - the broker
+     * accepts the publish and delivers it to nobody - so read both from one
+     * constant rather than writing the name twice.
+     */
+    readonly channel?: string;
+    /** Reports a publish the broker refused. Defaults to a `console.warn`. */
+    readonly onError?: RelayOptions['onError'];
+}
+/**
+ * Publishes a socket frame from a process that has no server.
+ *
+ * `PubSub` needs a live `Bun.serve` for the local half of its fan-out, which a
+ * queue worker or a forked job child has none of. This is the other half alone:
+ * every frame goes to the broker and comes back out of the servers listening on
+ * the channel, with no local delivery and no subscribe.
+ *
+ * `WsRelayModule` binds it, so it is a constructor parameter:
+ *
+ * ```ts
+ * export class RoundAnnouncer {
+ *   constructor(private readonly frames: RelayPublisher) {}
+ *
+ *   announce(round: string): void {
+ *     this.frames.publishEvent('lobby', 'round.started', { round });
+ *   }
+ * }
+ * ```
+ */
+export declare class RelayPublisher {
+    #private;
+    private readonly relay;
+    constructor(relay: WsRelay, init?: RelayPublisherInit);
+    /** This process's id on the relay channel. Stable for its lifetime. */
+    get origin(): string;
+    /** The channel frames go out on. */
+    get channel(): string;
+    /** The same envelope `@OnMessage(event)` reads, published to a topic. */
+    publishEvent(topic: string, event: string, data?: unknown): void;
+    /**
+     * **Never throws.** A job handler that failed here would be retried and would
+     * repeat its side effects to deliver a frame nobody awaited. Failures go to
+     * `onError`.
+     */
+    publish(topic: string, data: string | Bun.BufferSource): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/http",
-  "version": "3.8.0",
+  "version": "3.8.2",
   "description": "Bun.serve adapter for the dunx framework: controllers, middleware and WebSocket gateways",
   "keywords": [
     "bun",
@@ -76,7 +76,7 @@
   "peerDependencies": {
     "@bufbuild/protobuf": "^2.15.0",
     "@connectrpc/connect": "^2.2.0",
-    "@dunx/core": "^3.8.0",
+    "@dunx/core": "^3.8.2",
     "@types/bun": ">=1.4.1"
   },
   "peerDependenciesMeta": {