@dunx/http 3.8.1 → 3.8.3

package/README.md

@@ -95,6 +95,10 @@ from, and it may change in any release.
   otherwise silently keep one.
 - Handlers may return a `Response`, any JSON-serialisable value, or `undefined`
   for a 204.
+- `Authorize` and `gate()` are the contract an ops surface gates itself with:
+  raw request in, 404 on refusal, and a returned `Response` sent as written for a
+  browser that needs a sign-in page. `@dunx/dashboard` and `@dunx/openapi` both
+  take one, so an app writes the policy once and hands it to both.
 - Schemas, parsers and the status resolve at boot into the same closure the
   middleware chain folds into. A request reads no metadata and does no lookup.
 - Every request adopts W3C Trace Context, so `traceId`, `spanId`, `parentSpanId`

package/dist/client.js

@@ -41,7 +41,7 @@ class FetchTransportError extends AppError {
     this.aborted = aborted;
   }
 }
-Object.defineProperty(FetchTransportError, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "readonly response: { readonly method: string; readonly url: string }" }, { unresolved: "readonly aborted: boolean" }, ErrorOptions] });
+Object.defineProperty(FetchTransportError, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "readonly response: { readonly method: string; readonly url: string }" }, { unresolved: "readonly aborted: boolean" }, typeof ErrorOptions === "undefined" ? { unresolved: "options?: ErrorOptions" } : ErrorOptions] });
 // src/client/options.ts
 class HttpClientOptions {
   baseUrl;

package/dist/health/contracts.d.ts

@@ -54,3 +54,9 @@ export declare abstract class PingProbe {
 export declare abstract class QueryProbe {
     abstract ping(): Promise<void>;
 }
+/** Enough of an object store to answer "can I reach it", which `Storage` from
+ * `@dunx/infra/files` is on either backend. `exists` and not a read or a write:
+ * one `HEAD` against S3, one `stat` locally, and nothing left behind. */
+export declare abstract class StorageProbe {
+    abstract exists(key: string): Promise<boolean>;
+}

package/dist/health/indicators.d.ts

@@ -1,16 +1,47 @@
-import { HealthIndicator, type PingProbe, type ProbeResult, type QueryProbe } from './contracts.js';
+import { HealthIndicator, type PingProbe, type ProbeResult, type QueryProbe, type StorageProbe } from './contracts.js';
+/** Up on a completed round trip, down with the thrown message, detail the
+ * latency. Subclass it with a `name` for anything else answering a `ping()`. */
+export declare abstract class RoundTripIndicator extends HealthIndicator {
+    private readonly probe;
+    constructor(probe: QueryProbe);
+    check(): Promise<ProbeResult>;
+}
 /** Redis is up if it answers `PING`. */
-export declare class RedisIndicator extends HealthIndicator {
-    private readonly redis;
+export declare class RedisIndicator extends RoundTripIndicator {
     readonly name = "redis";
     constructor(redis: PingProbe);
-    check(): Promise<ProbeResult>;
 }
 /** The database is up if a round trip completes. */
-export declare class DatabaseIndicator extends HealthIndicator {
-    private readonly db;
+export declare class DatabaseIndicator extends RoundTripIndicator {
     readonly name = "database";
-    constructor(db: QueryProbe);
+}
+/**
+ * The AMQP broker, up while the connection is established and unblocked, and
+ * satisfied by `AmqpConnection` from `@dunx/infra/amqp`. The first probe on an
+ * unopened connection waits `readyTimeoutMs`, whose 5 s default outruns
+ * `timeoutMs` at 2 s and so reports `unknown`; the rest never wait.
+ */
+export declare class AmqpIndicator extends RoundTripIndicator {
+    readonly name = "amqp";
+}
+export interface StorageProbeOptionsInit {
+    readonly key?: string;
+}
+export declare class StorageProbeOptions {
+    readonly key: string;
+    constructor(init?: StorageProbeOptionsInit);
+}
+/**
+ * The configured object store, which is what `DiskIndicator` stops measuring the
+ * moment an app moves to `S3Storage`. Whether the key exists is no part of the
+ * signal and the answer is discarded: a store that replies is up, one that throws
+ * is down with the message expired credentials and a missing bucket arrive as.
+ */
+export declare class StorageIndicator extends HealthIndicator {
+    private readonly storage;
+    private readonly options;
+    readonly name = "storage";
+    constructor(storage: StorageProbe, options?: StorageProbeOptions);
     check(): Promise<ProbeResult>;
 }
 export interface MemoryOptionsInit {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { Controller, Delete, Get, Patch, Post, Put, } from './route/decorators.j
 export type { HttpMethod, RoutePath } from './route/marker.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 { gate, type Authorize, type AuthorizeDecision, } from './server/authorize.js';
 export { ClientAddress } from './server/client-address.js';
 export type { RouteContext } from './server/context.js';
 export type { CorsOptions, CorsOrigin } from './server/cors.js';
@@ -32,15 +33,17 @@ 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';
+export { HealthIndicator, PingProbe, QueryProbe, StorageProbe, type ProbeResult, type ProbeState, } from './health/contracts.js';
 export { HealthController } from './health/controller.js';
-export { DatabaseIndicator, DiskIndicator, DiskOptions, MemoryIndicator, MemoryOptions, RedisIndicator, type DiskOptionsInit, type MemoryOptionsInit, } from './health/indicators.js';
+export { AmqpIndicator, DatabaseIndicator, DiskIndicator, DiskOptions, MemoryIndicator, MemoryOptions, RedisIndicator, RoundTripIndicator, StorageIndicator, StorageProbeOptions, type DiskOptionsInit, type MemoryOptionsInit, type StorageProbeOptionsInit, } from './health/indicators.js';
 export { HealthModule } from './health/module.js';
 export { HEALTH_REPORT_SCHEMA } from './health/report-schema.js';
 export { Readiness, ReadinessOptions } from './health/readiness.js';

package/dist/index.js

@@ -62,6 +62,17 @@ var Post = verb("POST");
 var Put = verb("PUT");
 var Patch = verb("PATCH");
 var Delete = verb("DELETE");
+// src/server/authorize.ts
+var gate = async (authorize, req) => {
+  if (authorize === undefined)
+    return;
+  const decision = await authorize(req);
+  if (decision === true)
+    return;
+  if (decision instanceof Response)
+    return decision;
+  return Response.json({ error: "NOT_FOUND", status: 404 }, { status: 404 });
+};
 // src/server/client-address.ts
 import { AppError } from "@dunx/core";
 var trustedHops = (setting) => {
@@ -299,19 +310,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 +2682,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 +2824,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 +2918,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 +2938,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 +2956,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)
     };
   }
 }
@@ -2937,6 +3021,9 @@ class PingProbe {
 
 class QueryProbe {
 }
+
+class StorageProbe {
+}
 // src/health/controller.ts
 import { inject } from "@dunx/core";
 
@@ -3138,35 +3225,64 @@ let _HiddenHealthController = HiddenHealthController;
 import { statfs } from "fs/promises";
 var ms = (started) => Math.round(performance.now() - started);
 
-class RedisIndicator extends HealthIndicator {
-  redis;
-  name = "redis";
-  constructor(redis) {
+class RoundTripIndicator extends HealthIndicator {
+  probe;
+  constructor(probe) {
     super();
-    this.redis = redis;
+    this.probe = probe;
   }
   async check() {
     const started = performance.now();
-    await this.redis.ping();
+    await this.probe.ping();
     return { state: "up", detail: `${ms(started)} ms` };
   }
 }
-Object.defineProperty(RedisIndicator, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "private readonly redis: PingProbe", typeOnly: "PingProbe" }] });
+Object.defineProperty(RoundTripIndicator, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "private readonly probe: QueryProbe", typeOnly: "QueryProbe" }] });
+
+class RedisIndicator extends RoundTripIndicator {
+  name = "redis";
+  constructor(redis) {
+    super({
+      ping: async () => {
+        await redis.ping();
+      }
+    });
+  }
+}
+Object.defineProperty(RedisIndicator, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "redis: PingProbe", typeOnly: "PingProbe" }] });
 
-class DatabaseIndicator extends HealthIndicator {
-  db;
+class DatabaseIndicator extends RoundTripIndicator {
   name = "database";
-  constructor(db) {
+}
+
+class AmqpIndicator extends RoundTripIndicator {
+  name = "amqp";
+}
+
+class StorageProbeOptions {
+  key;
+  constructor(init = {}) {
+    this.key = init.key ?? ".dunx-health";
+  }
+}
+Object.defineProperty(StorageProbeOptions, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "init: StorageProbeOptionsInit = {}", optional: true }] });
+
+class StorageIndicator extends HealthIndicator {
+  storage;
+  options;
+  name = "storage";
+  constructor(storage, options = new StorageProbeOptions) {
     super();
-    this.db = db;
+    this.storage = storage;
+    this.options = options;
   }
   async check() {
     const started = performance.now();
-    await this.db.ping();
+    await this.storage.exists(this.options.key);
     return { state: "up", detail: `${ms(started)} ms` };
   }
 }
-Object.defineProperty(DatabaseIndicator, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "private readonly db: QueryProbe", typeOnly: "QueryProbe" }] });
+Object.defineProperty(StorageIndicator, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "private readonly storage: StorageProbe", typeOnly: "StorageProbe" }, StorageProbeOptions] });
 
 class MemoryOptions {
   maxRssBytes;
@@ -3320,6 +3436,7 @@ __runInitializers(_init, 1, HealthModule);
 __decoratorMetadata(_init, HealthModule);
 let _HealthModule = HealthModule;
 export {
+  AmqpIndicator,
   ApiHidden2 as ApiHidden,
   ClientAddress,
   Compression,
@@ -3375,18 +3492,24 @@ export {
   RedisRelay,
   RedisThrottleStore,
   RelayConnectionOptions,
+  RelayPublisher,
   RequestLoggingMiddleware,
   RequestMetrics,
   Roles2 as Roles,
+  RoundTripIndicator,
   SKIP_THROTTLE,
   STREAMS2 as STREAMS,
   SkipThrottle,
   SocketLoggingMiddleware,
+  SocketObserver,
   Sse,
   SseStream,
   StaticFiles2 as StaticFiles,
   StaticModule,
   StaticOptions2 as StaticOptions,
+  StorageIndicator,
+  StorageProbe,
+  StorageProbeOptions,
   THROTTLE,
   TRACEPARENT_HEADER2 as TRACEPARENT_HEADER,
   TRACERESPONSE_HEADER2 as TRACERESPONSE_HEADER,
@@ -3405,6 +3528,7 @@ export {
   WsRelayModule,
   defaultErrorMapper,
   errorMapper,
+  gate,
   mergeMeta2 as mergeMeta,
   meta2 as meta,
   metaKey2 as metaKey,

package/dist/server/authorize.d.ts

@@ -0,0 +1,18 @@
+import type { BunRequest } from 'bun';
+/**
+ * What an {@link Authorize} answers. `true` passes and `false` refuses with a
+ * 404; a `Response` refuses with itself, which is what a browser needs.
+ */
+export type AuthorizeDecision = boolean | Response;
+/**
+ * Decides whether a request may see an ops surface at all - the dashboard page,
+ * the OpenAPI explorer. Both sit outside the app's session guard, so this gets
+ * the raw `BunRequest` and asks the auth library. Refusal is 404, not 403.
+ */
+export type Authorize = (req: BunRequest) => AuthorizeDecision | Promise<AuthorizeDecision>;
+/**
+ * Runs the gate: `undefined` to carry on, or the response to answer with. Only
+ * `true` admits and only a `Response` replaces the refusal, so an `authorize`
+ * that falls off the end of a branch closes rather than opens.
+ */
+export declare const gate: (authorize: Authorize | undefined, req: BunRequest) => Promise<Response | undefined>;

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.1",
+  "version": "3.8.3",
   "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.1",
+    "@dunx/core": "^3.8.3",
     "@types/bun": ">=1.4.1"
   },
   "peerDependenciesMeta": {