@grackle-ai/ahp-transport 0.132.0

package/dist/ahp-client-socket.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Client-side AHP transport. Connects to an {@link AhpServerSocket} over a
+ * WebSocket, performs the AHP `initialize` handshake, persists the client
+ * identifier via a {@link ClientIdStore}, and reconnects with exponential
+ * backoff on transport failures.
+ *
+ * Channel-scoped concerns (per-`(host, channel)` `serverSeq` tracking,
+ * subscription replay, generation counter) live in `MultiHostClient`
+ * (HR8b). This class only owns the per-host connection lifecycle.
+ */
+import type { CommandMap, InitializeResult } from "@grackle-ai/ahp";
+import { WebSocket } from "ws";
+import { type BackoffPolicy } from "./backoff.js";
+import type { ClientIdStore } from "./client-id-store.js";
+import { type NotificationHandler, type RequestHandler } from "./json-rpc-session.js";
+/** Connection-lifecycle state for an {@link AhpClientSocket}. */
+export type AhpConnectionState = "connecting" | "open" | "reconnecting" | "closed";
+/** Construction options for {@link AhpClientSocket}. */
+export interface AhpClientSocketOptions {
+    /** Full WebSocket URL, e.g. `ws://host:7433/ahp`. */
+    readonly url: string;
+    /** Bearer token sent on the HTTP upgrade. Empty string disables auth. */
+    readonly powerlineToken: string;
+    /** Persistent store for the AHP clientId across reconnects/restarts. */
+    readonly clientIdStore: ClientIdStore;
+    /** Namespacing key for the clientId in the store (e.g., the host identifier). */
+    readonly clientIdKey: string;
+    /** Called when the host sends a JSON-RPC notification. */
+    readonly onNotification?: NotificationHandler;
+    /** Called when the host sends a JSON-RPC request (e.g., resourceRequest). */
+    readonly onRequest?: RequestHandler;
+    /** Called on every connection-state transition. */
+    readonly onStateChange?: (state: AhpConnectionState) => void;
+    /** Override the reconnect backoff policy (testing). */
+    readonly backoff?: BackoffPolicy;
+    /** Override the WebSocket constructor (testing). */
+    readonly webSocketCtor?: typeof WebSocket;
+    /** Locale forwarded to the host in InitializeParams.locale. */
+    readonly locale?: string;
+}
+/**
+ * Bidirectional AHP transport over a single WebSocket with automatic
+ * reconnect, persistent client identity, and queued operations during
+ * reconnect.
+ *
+ * @example Connect, issue a typed request, react to server notifications:
+ * ```ts
+ * const client = new AhpClientSocket({
+ *   url: "ws://127.0.0.1:7433/ahp",
+ *   powerlineToken: process.env.GRACKLE_POWERLINE_TOKEN ?? "",
+ *   clientIdStore: new FileClientIdStore(join(homedir(), ".grackle", "ahp")),
+ *   clientIdKey: "powerline-1",
+ *   onNotification: (n) => {
+ *     if (n.method === "action") applyAction(n.params);
+ *   },
+ *   onStateChange: (state) => console.log("transport state:", state),
+ * });
+ * const result = await client.open();
+ * await client.request("createSession", { ... });
+ * ```
+ *
+ * @example Clean shutdown:
+ * ```ts
+ * await client.close();
+ * // client.state === "closed"; further request() calls reject immediately.
+ * ```
+ */
+export declare class AhpClientSocket {
+    private readonly url;
+    private readonly powerlineToken;
+    private readonly clientIdStore;
+    private readonly clientIdKey;
+    private readonly onNotification;
+    private readonly onRequest;
+    private readonly onStateChange;
+    private readonly backoff;
+    private readonly WebSocketCtor;
+    private readonly locale;
+    private currentState;
+    private currentClientId;
+    private session;
+    private socket;
+    private userClosed;
+    private openInProgress;
+    private reconnectTimer;
+    private readonly pendingOps;
+    constructor(opts: AhpClientSocketOptions);
+    /** Current lifecycle state. */
+    get state(): AhpConnectionState;
+    /** Current AHP clientId, available once `open()` has resolved at least once. */
+    get clientId(): string | undefined;
+    /** Opens the connection and resolves after the initialize handshake. */
+    open(): Promise<InitializeResult>;
+    /** Sends a request; queues during reconnect, rejects after `.close()`. */
+    request<M extends keyof CommandMap>(method: M, params: CommandMap[M]["params"]): Promise<CommandMap[M]["result"]>;
+    /** Fires a notification; silently drops if not currently open. */
+    notify(method: string, params: unknown): void;
+    /** Closes the connection permanently. Idempotent. */
+    close(): Promise<void>;
+    private loadOrMintClientId;
+    private connectOnce;
+    private headersForUpgrade;
+    private handleSessionClose;
+    private scheduleReconnect;
+    private flushPendingOps;
+    private failPendingOps;
+    private setState;
+}
+//# sourceMappingURL=ahp-client-socket.d.ts.map

package/dist/ahp-client-socket.d.ts.map

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

package/dist/ahp-client-socket.js

@@ -0,0 +1,364 @@
+/**
+ * Client-side AHP transport. Connects to an {@link AhpServerSocket} over a
+ * WebSocket, performs the AHP `initialize` handshake, persists the client
+ * identifier via a {@link ClientIdStore}, and reconnects with exponential
+ * backoff on transport failures.
+ *
+ * Channel-scoped concerns (per-`(host, channel)` `serverSeq` tracking,
+ * subscription replay, generation counter) live in `MultiHostClient`
+ * (HR8b). This class only owns the per-host connection lifecycle.
+ */
+import { randomUUID } from "node:crypto";
+import { WebSocket } from "ws";
+import { exponentialBackoff } from "./backoff.js";
+import { TransportError, WsCloseCode } from "./error-codes.js";
+import { JsonRpcSession, } from "./json-rpc-session.js";
+/** Protocol versions the client offers in `InitializeParams.protocolVersions`. */
+const SUPPORTED_PROTOCOL_VERSIONS = ["0.1.0"];
+/**
+ * Bidirectional AHP transport over a single WebSocket with automatic
+ * reconnect, persistent client identity, and queued operations during
+ * reconnect.
+ *
+ * @example Connect, issue a typed request, react to server notifications:
+ * ```ts
+ * const client = new AhpClientSocket({
+ *   url: "ws://127.0.0.1:7433/ahp",
+ *   powerlineToken: process.env.GRACKLE_POWERLINE_TOKEN ?? "",
+ *   clientIdStore: new FileClientIdStore(join(homedir(), ".grackle", "ahp")),
+ *   clientIdKey: "powerline-1",
+ *   onNotification: (n) => {
+ *     if (n.method === "action") applyAction(n.params);
+ *   },
+ *   onStateChange: (state) => console.log("transport state:", state),
+ * });
+ * const result = await client.open();
+ * await client.request("createSession", { ... });
+ * ```
+ *
+ * @example Clean shutdown:
+ * ```ts
+ * await client.close();
+ * // client.state === "closed"; further request() calls reject immediately.
+ * ```
+ */
+export class AhpClientSocket {
+    url;
+    powerlineToken;
+    clientIdStore;
+    clientIdKey;
+    onNotification;
+    onRequest;
+    onStateChange;
+    backoff;
+    WebSocketCtor;
+    locale;
+    currentState = "closed";
+    currentClientId;
+    session;
+    socket;
+    userClosed = false;
+    openInProgress = false;
+    reconnectTimer;
+    pendingOps = [];
+    constructor(opts) {
+        this.url = opts.url;
+        this.powerlineToken = opts.powerlineToken;
+        this.clientIdStore = opts.clientIdStore;
+        this.clientIdKey = opts.clientIdKey;
+        this.onNotification = opts.onNotification;
+        this.onRequest = opts.onRequest;
+        this.onStateChange = opts.onStateChange;
+        this.backoff = opts.backoff ?? exponentialBackoff();
+        this.WebSocketCtor = opts.webSocketCtor ?? WebSocket;
+        this.locale = opts.locale;
+    }
+    /** Current lifecycle state. */
+    get state() {
+        return this.currentState;
+    }
+    /** Current AHP clientId, available once `open()` has resolved at least once. */
+    get clientId() {
+        return this.currentClientId;
+    }
+    /** Opens the connection and resolves after the initialize handshake. */
+    async open() {
+        if (this.userClosed) {
+            throw new TransportError("user-closed", "open() called after close()");
+        }
+        if (this.openInProgress || this.currentState !== "closed") {
+            // "connecting", "open", "reconnecting", or a concurrent open() in
+            // flight before the first await reached `connectOnce()`.
+            throw new TransportError("connection-lost", `open() called in state '${this.currentState}'`);
+        }
+        // Synchronously claim the lifecycle so a concurrent open() call (which
+        // also runs to its first await without yielding) sees the flag and bails.
+        this.openInProgress = true;
+        try {
+            this.currentClientId = this.currentClientId ?? (await this.loadOrMintClientId());
+            // close() may have been called while we were awaiting storage I/O. If
+            // so, don't establish a WebSocket — surface a user-closed error.
+            if (this.userClosed) {
+                throw new TransportError("user-closed", "close() called during open()");
+            }
+            return await this.connectOnce(/* isReconnect */ false);
+        }
+        finally {
+            this.openInProgress = false;
+        }
+    }
+    /** Sends a request; queues during reconnect, rejects after `.close()`. */
+    request(method, params) {
+        if (this.currentState === "closed" || this.userClosed) {
+            return Promise.reject(new TransportError("user-closed", `request ${String(method)} after close`));
+        }
+        if (this.currentState === "open" && this.session !== undefined) {
+            return this.session.request(method, params);
+        }
+        return new Promise((resolve, reject) => {
+            this.pendingOps.push({
+                run: (s) => {
+                    s.request(method, params).then(resolve, reject);
+                },
+                reject,
+            });
+        });
+    }
+    /** Fires a notification; silently drops if not currently open. */
+    notify(method, params) {
+        if (this.currentState === "open" && this.session !== undefined) {
+            this.session.notify(method, params);
+        }
+    }
+    /** Closes the connection permanently. Idempotent. */
+    async close() {
+        if (this.userClosed) {
+            return;
+        }
+        this.userClosed = true;
+        if (this.reconnectTimer !== undefined) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+        const wasInTerminal = this.currentState === "closed";
+        if (this.session !== undefined) {
+            this.session.close(WsCloseCode.Normal, "client closed");
+        }
+        else if (this.socket !== undefined) {
+            try {
+                this.socket.close(WsCloseCode.Normal, "client closed");
+            }
+            catch {
+                // ignore
+            }
+        }
+        this.failPendingOps(new TransportError("user-closed", "close() called"));
+        if (!wasInTerminal) {
+            this.setState("closed");
+        }
+    }
+    // ─── Internals ─────────────────────────────────────────────────────
+    async loadOrMintClientId() {
+        const stored = await this.clientIdStore.load(this.clientIdKey);
+        if (stored !== undefined) {
+            return stored;
+        }
+        const minted = randomUUID();
+        await this.clientIdStore.save(this.clientIdKey, minted);
+        return minted;
+    }
+    connectOnce(isReconnect) {
+        this.setState(isReconnect ? "reconnecting" : "connecting");
+        return new Promise((resolveOuter, rejectOuter) => {
+            // Distinguishes "expected" closes (handshake failed, terminal teardown
+            // during connectOnce) from real transport drops that should trigger
+            // reconnect. Set BEFORE calling session.close() in the failure paths.
+            let suppressReconnect = false;
+            const failTransport = (err) => {
+                // Transport-layer failure (TCP error, WS upgrade rejected, etc.).
+                // On reconnect attempts, chain the next retry; on initial open,
+                // terminate.
+                rejectOuter(err);
+                if (isReconnect && !this.userClosed) {
+                    this.scheduleReconnect();
+                }
+                else {
+                    this.socket = undefined;
+                    this.session = undefined;
+                    this.failPendingOps(err);
+                    this.setState("closed");
+                }
+            };
+            const failHandshake = (err) => {
+                // Handshake-layer failure (initialize rejected). Always terminal —
+                // a stale clientId or unsupported protocol won't fix itself on retry.
+                rejectOuter(err);
+                this.socket = undefined;
+                this.session = undefined;
+                this.failPendingOps(err);
+                this.setState("closed");
+            };
+            let ws;
+            try {
+                ws = new this.WebSocketCtor(this.url, {
+                    headers: this.headersForUpgrade(),
+                });
+            }
+            catch (err) {
+                failTransport(err);
+                return;
+            }
+            this.socket = ws;
+            // `ws` emits `unexpected-response` for every non-101 HTTP response to
+            // the upgrade. ws delegates response handling to us once this event
+            // fires, so we MUST drain (or destroy) the response — otherwise the
+            // socket leaks. 401 is terminal (auth-failed, no point retrying with
+            // the same creds); other statuses (404, 426, 500, ...) are treated as
+            // transport failures so reconnect attempts chain via the backoff.
+            let upgradeRejected = false;
+            ws.once("unexpected-response", (_req, res) => {
+                upgradeRejected = true;
+                const status = res.statusCode ?? 0;
+                // Drain the response body so the socket can close cleanly.
+                res.resume();
+                // IncomingMessage can emit BOTH 'end' and 'close' during an upgrade
+                // rejection. Guard so fail-* fires exactly once — otherwise a
+                // reconnect-time non-401 would schedule duplicate retries.
+                let finished = false;
+                const done = () => {
+                    if (finished) {
+                        return;
+                    }
+                    finished = true;
+                    if (status === 401) {
+                        failHandshake(new TransportError("auth-failed", "host rejected upgrade with HTTP 401"));
+                    }
+                    else {
+                        failTransport(new TransportError("connection-lost", `host rejected upgrade with HTTP ${status}`));
+                    }
+                };
+                // Use both 'end' and 'close' so we don't hang if the server destroys
+                // the response without an explicit end. The `finished` guard above
+                // ensures we still complete exactly once.
+                res.once("end", done);
+                res.once("close", done);
+            });
+            const onError = (err) => {
+                // ws emits "error" before "close" on transport failures. If the
+                // session is already constructed (we're past initialize), let
+                // handleSessionClose drive recovery; otherwise this is a transport
+                // failure during the upgrade. `unexpected-response` handles non-101
+                // statuses; suppress here so we don't double-fail.
+                if (this.session !== undefined) {
+                    return;
+                }
+                if (upgradeRejected) {
+                    return;
+                }
+                failTransport(err);
+            };
+            ws.once("open", () => {
+                ws.off("error", onError);
+                const session = new JsonRpcSession({
+                    socket: ws,
+                    onRequest: this.onRequest,
+                    onNotification: this.onNotification,
+                    onClose: (code, reason) => {
+                        if (suppressReconnect) {
+                            // Expected close after a handshake failure — failHandshake
+                            // already cleaned up the session/socket and set state.
+                            void code;
+                            void reason;
+                            return;
+                        }
+                        this.handleSessionClose(code, reason);
+                    },
+                });
+                this.session = session;
+                // Send initialize.
+                const params = {
+                    channel: "ahp-root://",
+                    protocolVersions: SUPPORTED_PROTOCOL_VERSIONS,
+                    clientId: this.currentClientId,
+                    ...(this.locale !== undefined ? { locale: this.locale } : {}),
+                };
+                session.request("initialize", params).then((result) => {
+                    this.setState("open");
+                    this.backoff.reset();
+                    this.flushPendingOps();
+                    resolveOuter(result);
+                }, (err) => {
+                    // Handshake failure is terminal on both initial and reconnect
+                    // attempts. Suppress the session-close handler so it doesn't
+                    // schedule a reconnect, then run the handshake-failure cleanup.
+                    suppressReconnect = true;
+                    session.close(WsCloseCode.Normal, "initialize failed");
+                    failHandshake(err);
+                });
+            });
+            ws.once("error", onError);
+        });
+    }
+    headersForUpgrade() {
+        if (this.powerlineToken === "") {
+            return {};
+        }
+        return { Authorization: `Bearer ${this.powerlineToken}` };
+    }
+    handleSessionClose(code, _reason) {
+        this.session = undefined;
+        this.socket = undefined;
+        if (this.userClosed) {
+            this.setState("closed");
+            return;
+        }
+        if (code === WsCloseCode.AuthRejected) {
+            this.failPendingOps(new TransportError("auth-failed", `host closed with code ${code}`));
+            this.setState("closed");
+            return;
+        }
+        this.scheduleReconnect();
+    }
+    scheduleReconnect() {
+        if (this.userClosed) {
+            return;
+        }
+        this.setState("reconnecting");
+        const delay = this.backoff.next();
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            if (this.userClosed) {
+                return;
+            }
+            // Fire-and-forget; on success/failure we update state internally.
+            this.connectOnce(/* isReconnect */ true).catch(() => {
+                // connectOnce schedules its own reconnect on failure.
+            });
+        }, delay);
+    }
+    flushPendingOps() {
+        if (this.session === undefined) {
+            return;
+        }
+        const ops = this.pendingOps.splice(0, this.pendingOps.length);
+        for (const op of ops) {
+            op.run(this.session);
+        }
+    }
+    failPendingOps(err) {
+        const ops = this.pendingOps.splice(0, this.pendingOps.length);
+        for (const op of ops) {
+            op.reject(err);
+        }
+    }
+    setState(next) {
+        if (next === this.currentState) {
+            return;
+        }
+        this.currentState = next;
+        this.onStateChange?.(next);
+    }
+}
+// AhpRequest / AhpResponse are not re-exported from this package — consumers
+// import them directly from `@grackle-ai/ahp`.
+//# sourceMappingURL=ahp-client-socket.js.map

package/dist/ahp-client-socket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ahp-client-socket.js","sourceRoot":"","sources":["../src/ahp-client-socket.ts"],"names":[],"mappings":"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"}

package/dist/ahp-server-socket.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Server-side AHP transport. Mounts on an existing HTTP/HTTP2 server,
+ * authenticates the upgrade request via `Authorization: Bearer <token>`,
+ * runs the AHP `initialize` handshake, then surfaces an
+ * {@link AhpServerConnection} (with a ready-to-use {@link JsonRpcSession})
+ * to the application.
+ *
+ * Heartbeat: WebSocket-level pings every 30s; 2 consecutive missed pongs
+ * close with code 4001.
+ */
+import type { InitializeParams, InitializeResult, AhpNotification, AhpRequest, AhpResponse } from "@grackle-ai/ahp";
+import type { Server as HttpServer } from "node:http";
+import type { Http2SecureServer } from "node:http2";
+import { JsonRpcSession } from "./json-rpc-session.js";
+/** A connected, fully-initialized AHP client. */
+export interface AhpServerConnection {
+    /** Client-supplied stable identifier from `InitializeParams.clientId`. */
+    readonly clientId: string;
+    /** The initialize params the client sent. */
+    readonly initializeParams: InitializeParams;
+    /** Bidirectional JSON-RPC session for this connection. */
+    readonly session: JsonRpcSession;
+    /** Remote socket address, if known. */
+    readonly remoteAddress: string | undefined;
+}
+/** Construction options for {@link AhpServerSocket}. */
+export interface AhpServerSocketOptions {
+    /** Host HTTP/HTTP2 server. The socket attaches an "upgrade" listener. */
+    readonly server: HttpServer | Http2SecureServer;
+    /** Bearer token validated on the HTTP upgrade. Pass "" to disable auth (dev only). */
+    readonly powerlineToken: string;
+    /** Path component of the WS URL. Defaults to "/ahp". */
+    readonly path?: string;
+    /**
+     * Builds the `InitializeResult` (from `@grackle-ai/ahp`) given the client's
+     * `InitializeParams`. May return a Promise. Throw or reject to fail the
+     * handshake — the session will receive a JSON-RPC error response and close.
+     */
+    readonly onInitialize: (params: InitializeParams) => Promise<InitializeResult> | InitializeResult;
+    /** Handles requests other than `initialize`. */
+    readonly onRequest?: (req: AhpRequest, conn: AhpServerConnection) => Promise<AhpResponse>;
+    /**
+     * Handles client→server notifications (e.g., `dispatchAction`, `unsubscribe`).
+     * Fires only after the handshake completes; pre-initialize notifications are dropped.
+     */
+    readonly onNotification?: (notif: AhpNotification, conn: AhpServerConnection) => void;
+    /** Called once the handshake succeeds and the connection is usable. */
+    readonly onConnection?: (conn: AhpServerConnection) => void;
+    /** Called when a connection closes. */
+    readonly onDisconnect?: (clientId: string, code: number, reason: string) => void;
+    /** Override the WS-level ping interval (testing). Default 30_000ms. */
+    readonly heartbeatIntervalMs?: number;
+    /** Override the missed-pong threshold (testing). Default 2. */
+    readonly heartbeatMissedLimit?: number;
+}
+/**
+ * AHP-spec JSON-RPC/WebSocket server. Mounts on an existing
+ * `http.Server`/`http2.SecureServer` and surfaces fully-initialized
+ * `AhpServerConnection`s to the application.
+ *
+ * @example Mount on an HTTP server and accept one client:
+ * ```ts
+ * import { createServer } from "node:http";
+ * const server = createServer();
+ * server.listen(7433, "127.0.0.1");
+ *
+ * const ahp = new AhpServerSocket({
+ *   server,
+ *   powerlineToken: process.env.GRACKLE_POWERLINE_TOKEN ?? "",
+ *   onInitialize: (params) => ({
+ *     protocolVersion: "0.1.0",
+ *     serverSeq: 0,
+ *     snapshots: [],
+ *   }),
+ *   onConnection: (conn) => {
+ *     console.log("client connected:", conn.clientId);
+ *     conn.session.notify("action", { channel: "ahp-session:/x", serverSeq: 1, action: {...} });
+ *   },
+ *   onRequest: async (req, conn) => {
+ *     // typed dispatch on req.method
+ *     return { jsonrpc: "2.0", id: req.id, result: null };
+ *   },
+ * });
+ * ```
+ */
+export declare class AhpServerSocket {
+    private readonly server;
+    private readonly powerlineToken;
+    private readonly path;
+    private readonly onInitialize;
+    private readonly onRequest;
+    private readonly onNotification;
+    private readonly onConnection;
+    private readonly onDisconnect;
+    private readonly heartbeatIntervalMs;
+    private readonly heartbeatMissedLimit;
+    private readonly wss;
+    private readonly connections;
+    private readonly upgradeListener;
+    private closed;
+    constructor(opts: AhpServerSocketOptions);
+    /** Stops accepting new connections and closes all existing sessions. */
+    close(): Promise<void>;
+    private handleUpgrade;
+    private authorizeUpgrade;
+    private attachSocket;
+    private handleRequest;
+    private handleNotification;
+    private handleSocketClose;
+}
+//# sourceMappingURL=ahp-server-socket.d.ts.map

package/dist/ahp-server-socket.d.ts.map

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