gemi 0.122.0 → 0.124.0

package/dist/services/broadcast/BroadcastEvent.d.ts

@@ -0,0 +1,67 @@
+import { Event } from "../events/Event";
+import { type BroadcastableEvent } from "./brand";
+import { type ChannelParamsArgs, type ChannelTarget } from "./channels";
+export { BROADCAST_EVENT, isBroadcastEvent, type BroadcastableEvent } from "./brand";
+/**
+ * An event that is also sent to the sockets on a channel, after its listeners
+ * have run.
+ *
+ * ```ts
+ * export class SiteChanged extends BroadcastEvent<{ pages: string[] }, "changed"> {
+ *   static name = "SiteChanged";
+ *   static afterCommit = true;
+ *   constructor(public site: { publicId: string }, public changes: { pages: string[] }) {
+ *     super();
+ *   }
+ *   broadcastOn() {
+ *     return this.channel("site.:siteId", { siteId: this.site.publicId });
+ *   }
+ *   broadcastAs() {
+ *     return "changed" as const;
+ *   }
+ *   broadcastWith() {
+ *     return this.changes;
+ *   }
+ * }
+ *
+ * SiteChanged.dispatch(site, { pages: ["/about"] });
+ * ```
+ *
+ * It is an `Event`: it needs `static name`, listeners bind to it, `static
+ * afterCommit` holds both the listeners and the broadcast until the commit,
+ * and under `Event.fake()` it is recorded and **not** broadcast. Without
+ * `afterCommit`, a dispatch inside a transaction still runs its listeners at
+ * once, and the broadcast itself waits for the commit and is dropped on
+ * rollback, as every `Broadcast` emit does.
+ *
+ * `TPayload` is what `broadcastWith` returns and `TName` what `broadcastAs`
+ * returns. List the class on a channel with `.events(SiteChanged)` and the
+ * generated `BroadcastRPC` types the client's handler for `changed`.
+ */
+export declare abstract class BroadcastEvent<TPayload = undefined, TName extends string = string> extends Event implements BroadcastableEvent {
+    /**
+     * Type-only: what `.events(...)` on a channel reads to type `BroadcastRPC`.
+     * No field is emitted.
+     */
+    readonly __broadcast: {
+        name: TName;
+        payload: TPayload;
+    };
+    constructor();
+    /**
+     * The channel or channels to send this event to: a `this.channel(...)`, a
+     * concrete topic such as `` `user.${id}` ``, or an array of them.
+     */
+    abstract broadcastOn(): ChannelTarget | string | ReadonlyArray<ChannelTarget | string>;
+    /** The event name clients see. Defaults to the class's `static name`. */
+    broadcastAs(): TName;
+    /**
+     * The payload clients receive. Nothing by default: a payload is never
+     * derived from the event's fields, so nothing is broadcast by accident.
+     * Keep it to ids and a change hint, and never put secrets in it.
+     */
+    broadcastWith(): TPayload;
+    /** The channel `pattern` names with `params`, for `broadcastOn`. */
+    protected channel<P extends string>(pattern: P, ...params: ChannelParamsArgs<P>): ChannelTarget;
+}
+//# sourceMappingURL=BroadcastEvent.d.ts.map

package/dist/services/broadcast/BroadcastEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BroadcastEvent.d.ts","sourceRoot":"","sources":["../../../services/broadcast/BroadcastEvent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAc,KAAK,iBAAiB,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEpF,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8BAAsB,cAAc,CAAC,QAAQ,GAAG,SAAS,EAAE,KAAK,SAAS,MAAM,GAAG,MAAM,CACtF,SAAQ,KACR,YAAW,kBAAkB;IAE7B;;;OAGG;IACH,SAAiB,WAAW,EAAE;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,OAAO,EAAE,QAAQ,CAAA;KAAE,CAAC;;IAOjE;;;OAGG;IACH,QAAQ,CAAC,WAAW,IAAI,aAAa,GAAG,MAAM,GAAG,aAAa,CAAC,aAAa,GAAG,MAAM,CAAC;IAEtF,yEAAyE;IACzE,WAAW,IAAI,KAAK;IAIpB;;;;OAIG;IACH,aAAa,IAAI,QAAQ;IAIzB,oEAAoE;IACpE,SAAS,CAAC,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,aAAa;CAGhG"}

package/dist/services/broadcast/BroadcastManager.d.ts

@@ -0,0 +1,148 @@
+import type { Application } from "../../foundation/Application";
+import type { ChannelRouter, ChannelRouterClass } from "../../http/ChannelRouter";
+import type { BroadcastDeliver, BroadcastDriver, BroadcastDriverHooks, BroadcastRevocation } from "./BroadcastDriver";
+import type { BroadcastableEvent } from "./brand";
+import { type ChannelParamsArgs, type ChannelTarget } from "./channels";
+import { type BroadcastConfig } from "./config";
+import type { BroadcastDataArgs, BroadcastEventsFor, SentBroadcast } from "./types";
+/** An emit whose frame is bigger than `maxEventBytes`. Nothing was sent. */
+export declare class BroadcastPayloadTooLargeError extends Error {
+    readonly bytes: number;
+    readonly limit: number;
+    constructor(bytes: number, limit: number, event: string);
+}
+/** Something that carries the sender's socket id: a request, or the id. */
+export type SocketSource = string | null | undefined | Request | {
+    rawRequest: Request;
+} | {
+    headers: Headers;
+};
+/**
+ * Real-time, volatile fan-out to the WebSocket clients subscribed to a
+ * channel. Events are hints that something changed, not data: delivery is at
+ * most once, nothing is stored or replayed, and a client that may have missed
+ * something refetches over HTTP.
+ *
+ * ```ts
+ * Broadcast.to("site.:siteId", { siteId: site.publicId }).emit("changed", { pages: ["/about"] });
+ * ```
+ *
+ * The manager builds and checks the frame at the call site, so a bad channel
+ * or a payload over the limit throws there, and then hands it to the driver,
+ * which decides which processes see it. Inside an ORM transaction the
+ * hand-off waits for the commit and is dropped on rollback.
+ *
+ * Delivery to sockets belongs to the transport, which calls `start` with the
+ * function that reaches this process's sockets. Until it does, an emit
+ * reaches no socket in this process.
+ */
+export declare class BroadcastManager {
+    private readonly options;
+    static token: string;
+    readonly config: Required<BroadcastConfig>;
+    readonly driver: BroadcastDriver;
+    private readonly warnedAboutSize;
+    private started;
+    private hooks;
+    private channelRouter;
+    constructor(config?: BroadcastConfig, options?: {
+        application?: Application;
+        /** The app's `ChannelRouter` (`route.channels`). */
+        channels?: ChannelRouterClass;
+    });
+    /**
+     * The app's `ChannelRouter`, built once, or `null` when `route.channels` is
+     * not set (and every subscription is refused). The transport authorizes
+     * each `sub` with its `authorize`.
+     */
+    get channels(): ChannelRouter | null;
+    /**
+     * The channel `pattern` names with `params`, or a concrete topic, or a
+     * `ChannelTarget` (what `BroadcastEvent.channel()` returns).
+     */
+    to<P extends string>(pattern: P | ChannelTarget, ...params: ChannelParamsArgs<P>): PendingBroadcast<BroadcastEventsFor<P>>;
+    /** A user's own channel, `user.<id>`: the one the router's `"user"` channel joins. */
+    toUser(user: {
+        id: unknown;
+    } | string | number): PendingBroadcast<BroadcastEventsFor<"user">>;
+    /**
+     * Skips the socket that made `source`, a request carrying the
+     * `X-Gemi-Socket` header (or the id itself), so the client that saved
+     * something does not refetch what it already has. Without a valid socket id
+     * nobody is skipped.
+     */
+    toOthers(source: SocketSource): BroadcastScope;
+    /** Sends a `BroadcastEvent` to the channels its `broadcastOn` names. */
+    broadcastEvent(event: BroadcastableEvent): void;
+    /**
+     * Checks and encodes an emit, then hands it to the driver: now, or after
+     * the open transaction commits. Throws at the call site for a bad event
+     * name, a payload that is not JSON, or one over `maxEventBytes`.
+     */
+    send(target: ChannelTarget, event: string, data: unknown, except: string | null): void;
+    private prepare;
+    private hand;
+    /**
+     * The hand-off to the driver, after the commit. Never throws: an emit is
+     * fire-and-forget, and a driver failure is logged with the topic and event,
+     * never the payload.
+     */
+    protected publish(sent: SentBroadcast, frame: string): void;
+    /** Whether the transport has started delivering to this process's sockets. */
+    get isStarted(): boolean;
+    /**
+     * For the transport: this process starts receiving, and every frame for a
+     * topic it has sockets on reaches `deliver` (`server.publish`).
+     */
+    start(deliver: BroadcastDeliver, hooks?: BroadcastDriverHooks): Promise<void>;
+    /** For the transport: the first local socket joined `topic`. */
+    topicAdded(topic: string): void | Promise<void>;
+    /** For the transport: the last local socket left `topic`. */
+    topicRemoved(topic: string): void | Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Closes subscriptions that may no longer be allowed: every socket of a
+     * user (`{ user }`: its sockets are closed, and its client reconnects and
+     * authorizes every channel again), or every subscription to a channel
+     * (`{ channel }`, a pattern with `params` or a topic: each is told
+     * `denied` with `revoked`). Sign-out calls it for the user.
+     *
+     * Inside an ORM transaction it waits for the commit, so the
+     * resubscriptions it causes are authorized against the committed state.
+     * Never throws for a transport problem; a bad channel throws at the call
+     * site.
+     */
+    revoke(target: {
+        user: {
+            id: unknown;
+        } | string | number;
+    } | {
+        channel: string | ChannelTarget;
+        params?: Record<string, unknown>;
+    }): void;
+    protected sendRevocation(revocation: BroadcastRevocation): void;
+    private checkSize;
+}
+/** An emit with its channel chosen: `.emit(event, data)` sends it. */
+export declare class PendingBroadcast<Events extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly manager;
+    readonly target: ChannelTarget;
+    private readonly except;
+    constructor(manager: BroadcastManager, target: ChannelTarget, except: string | null);
+    /**
+     * Sends `event` with `data` (JSON) to every socket on the channel. Returns
+     * nothing: delivery is at most once and never acknowledged.
+     */
+    emit<E extends keyof Events & string>(event: E, ...data: BroadcastDataArgs<Events[E]>): void;
+}
+/** `Broadcast.toOthers(...)`: the same `to`, with the sender's socket skipped. */
+export declare class BroadcastScope {
+    private readonly manager;
+    readonly except: string | null;
+    constructor(manager: BroadcastManager, except: string | null);
+    to<P extends string>(pattern: P | ChannelTarget, ...params: ChannelParamsArgs<P>): PendingBroadcast<BroadcastEventsFor<P>>;
+    toUser(user: {
+        id: unknown;
+    } | string | number): PendingBroadcast<BroadcastEventsFor<"user">>;
+}
+//# sourceMappingURL=BroadcastManager.d.ts.map

package/dist/services/broadcast/BroadcastManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BroadcastManager.d.ts","sourceRoot":"","sources":["../../../services/broadcast/BroadcastManager.ts"],"names":[],"mappings":"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"}

package/dist/services/broadcast/BroadcastServiceProvider.d.ts

@@ -0,0 +1,26 @@
+import { ServiceProvider } from "../../support/ServiceProvider";
+import type { BroadcastDriver } from "./BroadcastDriver";
+import type { BroadcastConfig } from "./config";
+export declare class BroadcastServiceProvider extends ServiceProvider {
+    register(): void;
+    /**
+     * Fails the boot on a malformed channel pattern, rather than refusing every
+     * subscription to it at runtime.
+     */
+    boot(): void;
+    /**
+     * Says `bye` to the sockets (the server's drain did already, in
+     * production; a dev reload retiring this application did not), then stops
+     * receiving and closes the driver's connections.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * The redis driver carries one frame to every instance, and a `toOthers`
+ * frame names the socket to skip by a tag keyed from `SECRET` (`socketTag`).
+ * Without `SECRET` each process keys it at random, so the sender's own socket
+ * on another instance would not recognise its tag and would get its own
+ * emit back. Fails the boot in production; warns elsewhere.
+ */
+export declare function assertSharedSecret(config: BroadcastConfig, env?: Record<string, string | undefined>, driver?: BroadcastDriver): void;
+//# sourceMappingURL=BroadcastServiceProvider.d.ts.map

package/dist/services/broadcast/BroadcastServiceProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BroadcastServiceProvider.d.ts","sourceRoot":"","sources":["../../../services/broadcast/BroadcastServiceProvider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAGhD,qBAAa,wBAAyB,SAAQ,eAAe;IAC3D,QAAQ;IAcR;;;OAGG;IACH,IAAI;IAaJ;;;;OAIG;IACG,QAAQ;CAKf;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,eAAe,EACvB,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EACrD,MAAM,CAAC,EAAE,eAAe,GACvB,IAAI,CASN"}

package/dist/services/broadcast/FakeBroadcastManager.d.ts

@@ -0,0 +1,45 @@
+import type { Application } from "../../foundation/Application";
+import { BroadcastManager } from "./BroadcastManager";
+import type { BroadcastRevocation } from "./BroadcastDriver";
+import type { SentBroadcast } from "./types";
+/**
+ * What `Broadcast.fake()` installs: a `BroadcastManager` that records every
+ * emit instead of handing it to a driver.
+ *
+ * Everything before the hand-off is the real manager's: channels and params
+ * are checked, payloads encoded and size-checked, and inside an ORM
+ * transaction an emit is recorded only once the transaction commits (and
+ * never if it rolls back). So a test sees what clients would have been sent.
+ *
+ * `restore()` is not optional, for the reason it is not on `Event.fake()`.
+ */
+export declare class FakeBroadcastManager extends BroadcastManager {
+    private readonly application;
+    private readonly previous;
+    readonly sent: SentBroadcast[];
+    /** Every `Broadcast.revoke`, as it would travel: `{ user }` or `{ topic }`. */
+    readonly revoked: BroadcastRevocation[];
+    static install(application: Application): FakeBroadcastManager;
+    private constructor();
+    private readonly channelsFrom;
+    get channels(): import("gemi/http").ChannelRouter;
+    protected publish(sent: SentBroadcast): void;
+    protected sendRevocation(revocation: BroadcastRevocation): void;
+    /** Puts the real manager back. */
+    restore(): void;
+    /**
+     * Asserts something was sent to `channel`: a pattern (`"site.:siteId"`,
+     * matching every topic it builds), a concrete topic (`"site.abc123"`), or
+     * `"user"` (every `user.<id>`). `event` and `predicate` narrow it.
+     */
+    assertSent(channel: string, event?: string, predicate?: (data: any, sent: SentBroadcast) => boolean): void;
+    /** Asserts nothing matching was sent. Same arguments as `assertSent`. */
+    assertNotSent(channel: string, event?: string, predicate?: (data: any, sent: SentBroadcast) => boolean): void;
+    /** Asserts exactly `times` matching emits. */
+    assertSentTimes(channel: string, times: number, event?: string, predicate?: (data: any, sent: SentBroadcast) => boolean): void;
+    /** Asserts nothing at all was broadcast. */
+    assertNothingSent(): void;
+    private matching;
+    private summary;
+}
+//# sourceMappingURL=FakeBroadcastManager.d.ts.map

package/dist/services/broadcast/FakeBroadcastManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeBroadcastManager.d.ts","sourceRoot":"","sources":["../../../services/broadcast/FakeBroadcastManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,qBAAa,oBAAqB,SAAQ,gBAAgB;IAmBtD,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAnB3B,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,CAAM;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,mBAAmB,EAAE,CAAM;IAE7C,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,WAAW,GAAG,oBAAoB;IAa9D,OAAO;IAiBP,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA+B;IAE5D,IAAa,QAAQ,sCAEpB;cAEkB,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;cAIlC,cAAc,CAAC,UAAU,EAAE,mBAAmB,GAAG,IAAI;IAIxE,kCAAkC;IAClC,OAAO,IAAI,IAAI;IAQf;;;;OAIG;IACH,UAAU,CACR,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,GACtD,IAAI;IAQP,yEAAyE;IACzE,aAAa,CACX,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,GACtD,IAAI;IASP,8CAA8C;IAC9C,eAAe,CACb,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,GACtD,IAAI;IAUP,4CAA4C;IAC5C,iBAAiB,IAAI,IAAI;IAQzB,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,OAAO;CAIhB"}

package/dist/services/broadcast/MemoryBroadcastDriver.d.ts

@@ -0,0 +1,23 @@
+import type { BroadcastDeliver, BroadcastDriver, BroadcastDriverHooks, BroadcastRevocation } from "./BroadcastDriver";
+/**
+ * The default driver: an emit reaches the sockets of **this process only**.
+ *
+ * Right for one instance whose web processes also run the jobs and cron that
+ * emit. Wrong as soon as there are two replicas, or a `gemi queue:work`
+ * worker that emits: those frames reach nobody, with nothing to say so. Use
+ * the Redis driver there.
+ *
+ * Before the HTTP server starts the transport, there is nobody to deliver to,
+ * and `publish` drops the frame.
+ */
+export declare class MemoryBroadcastDriver implements BroadcastDriver {
+    private deliver;
+    private hooks;
+    /** Whether the transport has started this driver. */
+    get started(): boolean;
+    publish(topic: string, frame: string): void;
+    start(deliver: BroadcastDeliver, hooks?: BroadcastDriverHooks): void;
+    revoke(revocation: BroadcastRevocation): void;
+    close(): void;
+}
+//# sourceMappingURL=MemoryBroadcastDriver.d.ts.map

package/dist/services/broadcast/MemoryBroadcastDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryBroadcastDriver.d.ts","sourceRoot":"","sources":["../../../services/broadcast/MemoryBroadcastDriver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,KAAK,CAAmC;IAEhD,qDAAqD;IACrD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAI3C,KAAK,CAAC,OAAO,EAAE,gBAAgB,EAAE,KAAK,CAAC,EAAE,oBAAoB,GAAG,IAAI;IAKpE,MAAM,CAAC,UAAU,EAAE,mBAAmB,GAAG,IAAI;IAI7C,KAAK,IAAI,IAAI;CAId"}

package/dist/services/broadcast/RedisBroadcastDriver.d.ts

@@ -0,0 +1,155 @@
+import type { RedisOptions } from "bun";
+import type { BroadcastDeliver, BroadcastDriver, BroadcastDriverHooks, BroadcastRevocation } from "./BroadcastDriver";
+/**
+ * The part of a Redis client the driver uses: Bun's `RedisClient` has it.
+ * Described structurally so tests can hand in a fake (`createClient`).
+ */
+export interface RedisPubSubClient {
+    connect(): Promise<void>;
+    publish(channel: string, message: string): Promise<number>;
+    subscribe(channel: string, listener: (message: string, channel: string) => void): Promise<number>;
+    /** Without a listener: drops the channel and every listener on it. */
+    unsubscribe(channel: string): Promise<void>;
+    ping(): Promise<unknown>;
+    close(): void;
+    onclose: ((error: Error) => void) | null;
+}
+export interface RedisBroadcastDriverOptions {
+    /** Defaults to `app/config/redis.ts`'s `url`, then `REDIS_URL`. */
+    url?: string;
+    /** Bun `RedisClient` options. Defaults to `app/config/redis.ts`'s `options`. */
+    options?: RedisOptions;
+    /**
+     * Prepended to every topic to name its Redis channel. Default:
+     * `gemi:bc:<8 hex characters derived from SECRET>:`, so instances of one
+     * app share channels and other apps or environments on the same Redis
+     * (which have another `SECRET`) do not. `"gemi:bc:"` without `SECRET`.
+     */
+    prefix?: string;
+    /**
+     * How long a first socket's subscription may wait for Redis before it is
+     * denied with `error` (the client retries it). Default `5000`.
+     */
+    subscribeTimeoutMs?: number;
+    /**
+     * How often the subscriber connection is pinged, in ms. A ping that fails
+     * or goes unanswered for `subscribeTimeoutMs` drops the connection, which
+     * is reconnected (and sockets told `gap`): a connection a proxy cut
+     * silently would otherwise stay subscribed to nothing. `0` turns it off.
+     * Default `30000`.
+     */
+    healthCheckMs?: number;
+    /** Builds a client. Default: `new Bun.RedisClient(url, options)`. */
+    createClient?: (role: "publisher" | "subscriber") => RedisPubSubClient;
+}
+/**
+ * The default channel prefix: `gemi:bc:<8 hex>:`, the hex derived from
+ * `secret` with HKDF, never the secret itself. `"gemi:bc:"` without one.
+ */
+export declare function defaultBroadcastPrefix(secret?: string | undefined): string;
+/**
+ * Broadcast over Redis pub/sub: an emit reaches the sockets of every process
+ * of the app, `gemi queue:work` workers' emits included.
+ *
+ * - **Publishing.** Every emit is `PUBLISH`ed on `<prefix><topic>`, from a
+ *   publisher connection opened on the first emit. A process without the
+ *   HTTP server (a worker) only ever has this one.
+ * - **Receiving.** A process that serves sockets has one subscriber
+ *   connection. It `SUBSCRIBE`s to a topic when the first local socket joins
+ *   it and `UNSUBSCRIBE`s when the last leaves, so a process receives only the
+ *   topics its sockets are on. It delivers what it receives, its own emits
+ *   included: one delivery path, nothing delivered twice.
+ * - **Revocations** travel on `<prefix>__control`, and every process applies
+ *   them. The process that revokes applies it at once too, so its own sockets
+ *   are covered while Redis is unreachable.
+ * - **Reconnects.** When the subscriber connection drops, the driver opens a
+ *   new one with backoff, subscribes every topic again, and then tells the
+ *   transport (`onGap`), which sends its sockets `{op:"gap"}` so clients
+ *   refetch what they may have missed.
+ *
+ * Needs `SECRET`: a `toOthers` frame names the skipped socket by a tag keyed
+ * from it, which every process must compute alike.
+ */
+export declare class RedisBroadcastDriver implements BroadcastDriver {
+    private readonly config;
+    readonly prefix: string;
+    private readonly controlChannel;
+    private readonly instanceId;
+    private readonly subscribeTimeoutMs;
+    private readonly healthCheckMs;
+    private publisher;
+    private subscriber;
+    /** Resolves with the subscriber once it is connected and subscribed. */
+    private ready;
+    private deliver;
+    private hooks;
+    /** Topics with local sockets: the ones the subscriber should be on. */
+    private readonly wanted;
+    /** Topics the current subscriber connection is subscribed to. */
+    private readonly active;
+    /** Per topic, the tail of its SUBSCRIBE/UNSUBSCRIBE chain. */
+    private readonly chains;
+    private connectedOnce;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private healthTimer;
+    private closed;
+    constructor(config?: RedisBroadcastDriverOptions);
+    /** Whether the subscriber connection is up and subscribed. */
+    get connected(): boolean;
+    publish(topic: string, frame: string): Promise<void>;
+    /**
+     * Applies the revocation here at once, then sends it to every other
+     * process. A process whose subscriber is reconnecting while it is sent
+     * misses it, and re-authorizes every subscription after its gap instead
+     * (the transport does, on `onGap`).
+     */
+    revoke(revocation: BroadcastRevocation): Promise<void>;
+    /**
+     * Opens the subscriber connection. Resolves once it is connected, or at
+     * `subscribeTimeoutMs` when Redis is unreachable, in which case it keeps
+     * trying in the background: the HTTP server does not wait on Redis to
+     * boot.
+     */
+    start(deliver: BroadcastDeliver, hooks?: BroadcastDriverHooks): Promise<void>;
+    topicAdded(topic: string): Promise<void>;
+    topicRemoved(topic: string): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Publishes, retrying once on a new publisher: Bun's client that gave up
+     * (Redis was away for longer than its retries) fails the first command
+     * after Redis is back, before its `onclose` lets it be replaced.
+     */
+    private send;
+    private dropPublisher;
+    /**
+     * The publisher, built on first use. Bun's client reconnects it on its
+     * own; one that has given up (`onclose`) is replaced on the next publish.
+     */
+    private publisherClient;
+    private createClient;
+    /**
+     * Opens a subscriber connection and subscribes the control channel and
+     * every wanted topic on it. On failure, or when it drops later, the next
+     * one is tried with backoff. Every connection after the first reports a
+     * gap, once it is subscribed: what was published in between is lost.
+     */
+    private connectSubscriber;
+    /** The subscriber connection closed under it. */
+    private lost;
+    private drop;
+    private scheduleReconnect;
+    private startHealthCheck;
+    /** The connected subscriber, waiting up to `subscribeTimeoutMs` for one. */
+    private whenReady;
+    /**
+     * Brings the subscription to `topic` in line with `wanted`, after whatever
+     * was already queued for it: a socket leaving and another joining in the
+     * next tick become UNSUBSCRIBE then SUBSCRIBE, in that order.
+     */
+    private sync;
+    private reconcile;
+    private readonly onMessage;
+    private onControl;
+}
+//# sourceMappingURL=RedisBroadcastDriver.d.ts.map

package/dist/services/broadcast/RedisBroadcastDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisBroadcastDriver.d.ts","sourceRoot":"","sources":["../../../services/broadcast/RedisBroadcastDriver.ts"],"names":[],"mappings":"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"}