gemi 0.122.0 → 0.123.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,16 @@
+import { ServiceProvider } from "../../support/ServiceProvider";
+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>;
+}
+//# 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;AAKhE,qBAAa,wBAAyB,SAAQ,eAAe;IAC3D,QAAQ;IAcR;;;OAGG;IACH,IAAI;IAKJ;;;;OAIG;IACG,QAAQ;CAKf"}

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/SocketHub.d.ts

@@ -0,0 +1,192 @@
+import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
+import type { Application } from "../../foundation/Application";
+import { type CarriedContext } from "../../http/requestContext";
+import type { BroadcastRevocation } from "./BroadcastDriver";
+import type { BroadcastManager } from "./BroadcastManager";
+/** What the hub keeps on each of its sockets (`ws.data`). */
+export interface GemiSocketData {
+    /** Marks a broadcast socket, as opposed to the dev server's HMR relay. */
+    readonly gemiSocket: true;
+    /** The hub that accepted it. After a dev reload that may not be the current one. */
+    readonly hub: SocketHub;
+    readonly socketId: string;
+    readonly tag: string;
+    /** The upgrade request, kept to rebuild a request context for every `sub`. */
+    readonly request: {
+        url: string;
+        headers: [string, string][];
+    };
+    /** What the global middleware resolved for the upgrade: its user. */
+    readonly carried: CarriedContext | null;
+    /** The signed-in user's id at the upgrade, for limits and `revoke({ user })`. */
+    readonly userId: string | null;
+    readonly ip: string | null;
+    /** Subscription id → its topic, `null` while it is being authorized. */
+    readonly subs: Map<string, Subscription>;
+    /** Topic → how many of this socket's subscriptions are on it. */
+    readonly topics: Map<string, number>;
+    rate: {
+        windowStart: number;
+        subs: number;
+        pings: number;
+    };
+    /**
+     * The process, IP and user connection counts this socket holds. Taken
+     * before the upgrade's first `await`, so concurrent upgrades cannot
+     * overshoot the caps, and given back exactly once.
+     */
+    reservation: Reservation | null;
+    /** The hub has closed it (backpressure, revoke, bye); its close is on the way. */
+    closing: boolean;
+    closed: boolean;
+}
+interface Subscription {
+    pattern: string;
+    params: Record<string, string | number>;
+    topic: string | null;
+}
+interface Reservation {
+    ip: string | null;
+    userId: string | null;
+}
+type GemiSocket = ServerWebSocket<GemiSocketData>;
+/**
+ * The WebSocket side of broadcasting, one per HTTP server process: accepts
+ * upgrades on the configured path, speaks the `gemi.v1` protocol (see
+ * `protocol.ts`), authorizes every subscription through the app's
+ * `ChannelRouter`, and delivers what the driver hands it with
+ * `server.publish`.
+ *
+ * Nothing here keeps a queue or a log. A socket that falls behind is closed
+ * (`1013`), one whose user signs out is closed (`4001`), and a server that
+ * stops says `bye` (`1012`); in every case the client reconnects and
+ * refetches what it shows.
+ */
+export declare class SocketHub {
+    private readonly manager;
+    private readonly application;
+    static token: string;
+    private server;
+    private readonly sockets;
+    private readonly byTopic;
+    private readonly topicReady;
+    private readonly perIp;
+    private readonly perUser;
+    /** Sockets held or being upgraded: the process cap's count. */
+    private connections;
+    /** Bumped by every topic revocation; see `revokedAt`. */
+    private revocationSeq;
+    /** Topic → the `revocationSeq` of its last revocation. */
+    private readonly revokedAt;
+    private closing;
+    /** Resolves once every socket `shutdown` closed is gone, or was cut. */
+    private closed;
+    private onAllClosed;
+    private startPromise;
+    constructor(manager: BroadcastManager, application: Application);
+    private get config();
+    /** Whether `req` is for the socket endpoint (an upgrade or not). */
+    matches(req: Request): boolean;
+    /** Sockets open on this process. */
+    get size(): number;
+    /**
+     * Starts delivering: the driver's frames for this process go out with
+     * `server.publish`. Call once the server is listening.
+     */
+    start(server: Server<any>): Promise<void>;
+    /**
+     * Answers a request for the socket endpoint: upgrades it, or refuses it
+     * with a status saying why. `undefined` once Bun has taken it over.
+     */
+    upgrade(req: Request, server: Server<any>): Promise<Response | undefined>;
+    private tryUpgrade;
+    private authenticate;
+    /**
+     * `true`, or why the upgrade is refused. A browser always sends `Origin` on
+     * a WebSocket upgrade, and cookies ride along with it whatever the page
+     * that opened it, so an upgrade carrying cookies must come from an allowed
+     * origin and one without `Origin` is refused. A native client sends its
+     * token in a header and no cookies, and may leave `Origin` out.
+     */
+    private checkOrigin;
+    /** Whether `origin` may open a socket. */
+    originAllowed(origin: string, req: Request): boolean;
+    private reserve;
+    private release;
+    /** `Bun.serve`'s `websocket` option. */
+    get websocket(): WebSocketHandler<GemiSocketData>;
+    /** The server-wide socket settings, also for a handler shared with HMR in dev. */
+    socketOptions(): {
+        readonly maxPayloadLength: number;
+        readonly idleTimeout: number;
+        readonly backpressureLimit: number;
+        readonly closeOnBackpressureLimit: true;
+        readonly sendPings: true;
+        readonly perMessageDeflate: false;
+    };
+    onOpen(ws: GemiSocket): void;
+    onMessage(ws: GemiSocket, message: string | Buffer): void;
+    onClose(ws: GemiSocket): void;
+    private rateWindow;
+    /**
+     * Counts a `sub`. Only `sub` frames count: an `unsub` costs the server
+     * nothing to speak of, and counting it would charge a component's every
+     * mount and unmount twice.
+     */
+    private countSub;
+    /** `false` when the socket was closed for pinging too often. */
+    private countPing;
+    private subscribe;
+    /** Runs the channel's authorization for `sub`, as the socket's upgrade request. */
+    private authorize;
+    private unsubscribeFrame;
+    /** Puts `ws` on `topic`, and resolves once the driver delivers the topic here. */
+    private join;
+    private leave;
+    /**
+     * The driver's delivery for this process. A socket already over the
+     * backpressure limit is closed first (1013): it would only fall further
+     * behind, and its client recovers by reconnecting and refetching.
+     */
+    deliver(topic: string, frame: string): void;
+    /** Applies a revocation that reached this process. */
+    applyRevocation(revocation: BroadcastRevocation): void;
+    /**
+     * After `revoke({ channel })`: every subscription `ws` has on `topic` is
+     * authorized again, as the socket's upgrade request. The ones refused are
+     * denied with `revoked`; the others stay, and get a fresh `subscribed` so
+     * the client resyncs whatever was published while the topic was paused.
+     * The socket receives nothing on the topic until the answers are in.
+     */
+    private reauthorize;
+    private sendAll;
+    /**
+     * Stops accepting sockets and says `bye` to every open one, with a
+     * jittered `retryAfter` (1–5 s) so a restart's reconnects do not arrive at
+     * once, then closes them (1012). Sockets that have not closed after
+     * `terminateAfterMs` are cut. Idempotent.
+     *
+     * Resolves once every socket has closed, or at `terminateAfterMs` when the
+     * rest were cut: by the hub's own count, which the drain waits on instead
+     * of Bun's (on a loaded CI runner, Bun's graceful `stop()` was seen to wait
+     * on terminated sockets for good).
+     */
+    shutdown(options?: {
+        terminateAfterMs?: number;
+    }): Promise<void>;
+    /** Whether `shutdown` ran. */
+    get isClosing(): boolean;
+    private sayBye;
+    /** In the application's scope, as a request is: facades resolve from it. */
+    private run;
+}
+/**
+ * Whether an `allowedOrigins` entry (or `APP_URL` / `HOST_NAME`) admits
+ * `url`. An entry is an origin (`https://app.example.com`), a bare host
+ * (`app.example.com`), or a wildcard for the subdomains of a host
+ * (`*.example.com`, `https://*.example.com`), which does not admit the host
+ * itself.
+ */
+export declare function originMatches(allowed: string, url: URL): boolean;
+export {};
+//# sourceMappingURL=SocketHub.d.ts.map

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

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

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

@@ -0,0 +1,16 @@
+import type { ChannelTarget } from "./channels";
+/**
+ * Marks a `BroadcastEvent` instance. A symbol in the global registry rather
+ * than `instanceof`, for the reason `Event` gives: a production build can hold
+ * two copies of an event class, and `instanceof` would tell them apart.
+ */
+export declare const BROADCAST_EVENT: unique symbol;
+/** What `EventManager` needs of an event to broadcast it. */
+export interface BroadcastableEvent {
+    broadcastOn(): ChannelTarget | string | ReadonlyArray<ChannelTarget | string>;
+    broadcastAs(): string;
+    broadcastWith(): unknown;
+}
+/** Whether `event` is a `BroadcastEvent`, from any copy of gemi. */
+export declare function isBroadcastEvent(event: unknown): event is BroadcastableEvent;
+//# sourceMappingURL=brand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"brand.d.ts","sourceRoot":"","sources":["../../../services/broadcast/brand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAMhD;;;;GAIG;AACH,eAAO,MAAM,eAAe,eAAoC,CAAC;AAEjE,6DAA6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC,WAAW,IAAI,aAAa,GAAG,MAAM,GAAG,aAAa,CAAC,aAAa,GAAG,MAAM,CAAC,CAAC;IAC9E,WAAW,IAAI,MAAM,CAAC;IACtB,aAAa,IAAI,OAAO,CAAC;CAC1B;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAM5E"}

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

@@ -0,0 +1,77 @@
+/**
+ * Channel names: patterns, the topics they build, and the checks both go
+ * through. Shared by the `Broadcast` facade (which builds the topic an emit
+ * goes to), `ChannelRouter` (which builds the topic a socket may join) and the
+ * fake (which matches a pattern against recorded topics), so the three can
+ * never disagree on what `site.:siteId` with `{ siteId: "abc" }` is called.
+ *
+ * A pattern is dot-separated segments, each either a literal (`site`) or a
+ * param (`:siteId`). A topic is the same with every param filled in:
+ * `site.abc123`. Param values are restricted to `[A-Za-z0-9_-]`, so a value
+ * can never contain a dot and add a segment, and a topic can always be read
+ * back as exactly one pattern's.
+ */
+/** The longest topic, in characters. */
+export declare const MAX_TOPIC_LENGTH = 255;
+/** The longest event name, in characters. */
+export declare const MAX_EVENT_NAME_LENGTH = 64;
+/** The names of a pattern's params: `"site.:siteId"` → `"siteId"`. */
+export type ChannelParamNames<P extends string> = P extends `${infer Head}.${infer Rest}` ? SegmentParam<Head> | ChannelParamNames<Rest> : SegmentParam<P>;
+type SegmentParam<S extends string> = S extends `:${infer Name}` ? Name : never;
+/** The params a pattern takes: `"site.:siteId"` → `{ siteId: string | number }`. */
+export type ChannelParams<P extends string> = {
+    [K in ChannelParamNames<P>]: string | number;
+};
+/**
+ * `[]` for a pattern without params (or a concrete topic), `[params]` for one
+ * with them, so `Broadcast.to("status")` and `Broadcast.to("site.:siteId",
+ * { siteId })` both type-check and `Broadcast.to("site.:siteId")` does not.
+ */
+export type ChannelParamsArgs<P extends string> = [ChannelParamNames<P>] extends [never] ? [params?: Record<string, never>] : [params: ChannelParams<P>];
+/**
+ * A resolved channel: the topic sockets subscribe to, and the pattern it came
+ * from when it was built from one. What `BroadcastEvent.channel()` returns and
+ * `Broadcast.to()` accepts.
+ */
+export interface ChannelTarget {
+    readonly topic: string;
+    readonly pattern?: string;
+}
+/** A pattern, topic or param was refused. The message says which and why. */
+export declare class InvalidChannelError extends Error {
+    constructor(message: string);
+}
+/** Whether `value` is a `ChannelTarget` rather than a pattern string. */
+export declare function isChannelTarget(value: unknown): value is ChannelTarget;
+/** The segments of a pattern, checked. Throws `InvalidChannelError`. */
+export declare function parsePattern(pattern: string): string[];
+/** The param names of a pattern, in order. */
+export declare function patternParams(pattern: string): string[];
+/**
+ * The topic `pattern` names with `params` filled in. Every param must be
+ * given, and nothing else: a missing one, an extra one, or a value outside
+ * `[A-Za-z0-9_-]` throws `InvalidChannelError`, so a client can never steer a
+ * subscription onto a topic its pattern does not describe.
+ */
+export declare function buildTopic(pattern: string, params?: Record<string, unknown>): string;
+/** Checks a concrete topic (no params). Throws `InvalidChannelError`. */
+export declare function assertTopic(topic: string): string;
+/** Checks an event name. Throws `InvalidChannelError`. */
+export declare function assertEventName(event: string): string;
+/**
+ * Whether `topic` is one `pattern` builds. A pattern without params matches
+ * only itself, except `"user"`, which also matches every `user.<id>`: that is
+ * the topic the router's `user` channel resolves to.
+ */
+export declare function topicMatches(pattern: string, topic: string): boolean;
+/**
+ * The channel `ChannelRouter` resolves from the session rather than from
+ * params: a socket that subscribes to `"user"` joins `user.<its user's id>`.
+ */
+export declare const USER_CHANNEL = "user";
+/** The topic of a user's own channel. */
+export declare function userTopic(user: {
+    id: unknown;
+} | string | number): string;
+export {};
+//# sourceMappingURL=channels.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../../../services/broadcast/channels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wCAAwC;AACxC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,6CAA6C;AAC7C,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAOxC,sEAAsE;AACtE,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,GACrF,YAAY,CAAC,IAAI,CAAC,GAAG,iBAAiB,CAAC,IAAI,CAAC,GAC5C,YAAY,CAAC,CAAC,CAAC,CAAC;AAEpB,KAAK,YAAY,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,IAAI,MAAM,IAAI,EAAE,GAAG,IAAI,GAAG,KAAK,CAAC;AAEhF,oFAAoF;AACpF,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,MAAM,IAAI;KAC3C,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM;CAC7C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACpF,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,GAChC,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAE/B;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,6EAA6E;AAC7E,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAMtE;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAqCtD;AAED,8CAA8C;AAC9C,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAIvD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,MAAM,CAkCxF;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASjD;AAED,0DAA0D;AAC1D,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAarD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAYpE;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,SAAS,CAAC;AAEnC,yCAAyC;AACzC,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAGzE"}