@foir/sdk 0.7.0 → 0.9.0

package/dist/data/ws-transport.d.ts

@@ -0,0 +1,197 @@
+/**
+ * The graphql-ws transport — `@foir/sdk/data`'s second wire, beside the HTTP
+ * one.
+ *
+ * ---------------------------------------------------------------------------
+ * Why the protocol is implemented here rather than imported
+ * ---------------------------------------------------------------------------
+ *
+ * `graphql-ws` (the npm package) would do this, and `packages/shell` uses it.
+ * It is not used here for three reasons that are specific to this subpath:
+ *
+ *  1. `@foir/sdk/data` has exactly one runtime dependency and a build-time
+ *     assertion that nothing in its import graph reaches `graphql` or a Node
+ *     built-in. A second runtime dependency on this subpath is a real cost to
+ *     every storefront that installs it.
+ *  2. The protocol surface actually used is small and closed: `connection_init`
+ *     / `connection_ack`, `subscribe`, `next` / `error` / `complete`, `ping` /
+ *     `pong`. The server (`api-public/internal/ws`) implements exactly that
+ *     set and nothing else, so there is no negotiation to get wrong.
+ *  3. Reconnect-with-resubscribe has to be OURS regardless. A generic client
+ *     reconnects the socket; what a caller needs is their subscriptions still
+ *     running afterwards, which means replaying the subscribe frames — and
+ *     that bookkeeping is the part worth testing, not the framing.
+ *
+ * The wire is the standard `graphql-transport-ws` subprotocol either way, so a
+ * consumer who prefers the package can still talk to the same endpoint.
+ *
+ * ---------------------------------------------------------------------------
+ * Credentials
+ * ---------------------------------------------------------------------------
+ *
+ * A WebSocket handshake carries no request headers a browser will let you set,
+ * so graphql-ws puts credentials in the `connection_init` payload. This client
+ * builds that payload from `buildFoirHeaders` — the same function the HTTP
+ * transport builds its headers from — and drops only `Content-Type`, which
+ * means nothing on a socket. The server reads `x-api-key` and `Authorization`
+ * from those params under exactly those names, so the two surfaces authenticate
+ * with one builder rather than two spellings that can drift.
+ *
+ * A credential the header builder does not know about goes in
+ * `config.connectionParams`, which is a FUNCTION and is called on every
+ * connect — so a short-lived credential is re-resolved on reconnect instead of
+ * being replayed after it expired.
+ */
+import { FoirRequestError } from '../transport/foir-http';
+import { type FoirClientConfig } from './transport';
+/**
+ * The slice of `WebSocket` this transport uses.
+ *
+ * Deliberately the event-handler PROPERTIES rather than `addEventListener`,
+ * because that is the intersection of the browser's `WebSocket`, Node's global
+ * one, and the `ws` package — so a consumer can pass any of the three without
+ * an adapter.
+ */
+export interface FoirWebSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+}
+/** Constructs a socket. Matches `new WebSocket(url, protocols)`. */
+export type FoirWebSocketFactory = (url: string, protocols: string | string[]) => FoirWebSocketLike;
+/** How the transport behaves when the socket drops. */
+export interface FoirReconnectPolicy {
+    /**
+     * Attempts before giving up and reporting the failure to every live
+     * subscription. `Infinity` retries forever, which is the right default for a
+     * long-lived stream in a browser tab.
+     */
+    maxAttempts?: number;
+    /** Delay before the first retry. Doubles, capped at `maxDelayMs`. */
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    /**
+     * Random fraction of the delay added on each attempt, so a server restart
+     * does not bring every client back simultaneously. 0 disables it, which is
+     * what tests want and production does not.
+     */
+    jitter?: number;
+}
+/** A live subscription. Idempotent teardown. */
+export interface FoirSubscription {
+    unsubscribe(): void;
+}
+export interface FoirSubscriptionHandlers<T> {
+    /** One event. Called for every `next` frame the server pushes. */
+    onData: (value: T) => void;
+    /**
+     * A terminal error for THIS subscription: the server refused it, or the
+     * transport gave up reconnecting. Not called for a drop the transport
+     * recovers from — that is what `onReconnect` reports.
+     */
+    onError?: (error: FoirRequestError) => void;
+    /** The server ended the stream (an execution reached a terminal state). */
+    onComplete?: () => void;
+    /**
+     * The socket dropped and this subscription was re-established.
+     *
+     * Worth surfacing rather than hiding, because a subscription is not a
+     * durable log: events published while the socket was down were not buffered
+     * anywhere and are gone. A consumer that needs them refetches here. (The
+     * `events` subscription is the exception — it is cursor-resumable — and it is
+     * not one of the fields this client addresses.)
+     */
+    onReconnect?: () => void;
+}
+/** What to send in one `subscribe` frame. */
+export interface FoirSubscribeRequest {
+    query: string;
+    variables?: Record<string, unknown>;
+}
+/**
+ * Derive the WebSocket endpoint from the HTTP one.
+ *
+ * `apiUrl` is conventionally `https://api.foir.dev` or
+ * `https://api.foir.dev/graphql` — people paste whichever their env holds, and
+ * the HTTP transport already strips a trailing `/graphql` for the same reason.
+ * The socket lives at `/graphql/ws`, so this normalises to the origin and
+ * appends it.
+ */
+export declare function foirSocketEndpoint(apiUrl: string): string;
+/**
+ * The socket, its subscriptions, and the reconnect loop.
+ *
+ * One instance per client. It is lazy — nothing connects until the first
+ * `subscribe` — and it closes itself when the last subscription is dropped, so
+ * a client that is constructed and only used for queries never opens a socket.
+ */
+export declare class FoirSocketTransport {
+    private readonly config;
+    private readonly policy;
+    private readonly registrations;
+    private socket;
+    private acknowledged;
+    private connecting;
+    private attempt;
+    private nextId;
+    private disposed;
+    private keepAlive;
+    private retryTimer;
+    constructor(config: FoirClientConfig);
+    /**
+     * Start a subscription.
+     *
+     * Returns synchronously so a caller can hold the handle immediately, while
+     * the connect and the handshake proceed in the background. A subscription
+     * registered before the socket is acknowledged is sent the moment it is —
+     * which is the same path a reconnect takes, so the ordinary case and the
+     * recovery case exercise one piece of code.
+     */
+    subscribe<T>(request: FoirSubscribeRequest, handlers: FoirSubscriptionHandlers<T>): FoirSubscription;
+    /** Close the socket and drop every subscription. */
+    dispose(): void;
+    /** Live subscription count. Exposed for tests and diagnostics. */
+    get size(): number;
+    private ensureConnected;
+    private sendConnectionInit;
+    private handleClose;
+    private scheduleReconnect;
+    private teardownSocket;
+    private receive;
+    /**
+     * Send every registration the current socket has not yet been told about.
+     *
+     * This IS the resubscribe path. A reconnect clears `sent` on every
+     * registration and lands here, so a subscription re-established after a drop
+     * takes the same code as one opened for the first time — there is no second
+     * implementation that can be correct in one case and wrong in the other.
+     */
+    private flush;
+    private cancel;
+    /**
+     * Close the socket once nothing is using it.
+     *
+     * A socket held open with no subscriptions is a connection the server has to
+     * keep, a keepalive timer that keeps a serverless invocation alive, and
+     * nothing in return.
+     */
+    private closeIfIdle;
+    private failAll;
+    /**
+     * Client-side keepalive.
+     *
+     * The server pings on its own timer and this client answers, which is enough
+     * for the server to know the client is alive. This is the other direction:
+     * an idle subscription can sit for hours with no events, and a proxy that
+     * times out idle sockets will drop it. A periodic `ping` keeps it warm, and
+     * the pong that comes back proves the path is still there.
+     */
+    private startKeepAlive;
+    private send;
+}