@hydranium/protocol 1.0.0-next.10

package/lib/client/data-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-port.d.ts","sourceRoot":"","sources":["../../src/client/data-port.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,QAAQ;IACtB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEtC;;;;;;;;OAQG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnD;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;CAClC"}

package/lib/client/data-port.js

@@ -0,0 +1,11 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data-port.js.map

package/lib/client/data-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-port.js","sourceRoot":"","sources":["../../src/client/data-port.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF"}

package/lib/client/data-session.d.ts

@@ -0,0 +1,129 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import type { MessageConnection } from 'vscode-jsonrpc';
+import { type DataClientProtocol, type DataServerProtocol } from '../data';
+import { type RpcProxy } from '../rpc';
+import type { TransferDocument } from '../transfer-document';
+import type { TransferElement } from '../transfer-element';
+import type { DataPort } from './data-port';
+/** Options for {@link DataSession}. */
+export interface DataSessionOptions {
+    /**
+     * Wire namespace the server is addressed under. Defaults to the
+     * framework's {@link DATA_SERVER_WIRE_PREFIX}, which is what an unmodified
+     * `DataServer` binds. Override only alongside the server's own
+     * `methodNamespace` option — a mismatch turns every request into
+     * "Unhandled method" rather than failing at wire-up.
+     */
+    readonly methodNamespace?: string;
+}
+/** One connection generation: its connection, its proxy, and its readiness. */
+interface Generation<TTransfer extends TransferElement> {
+    readonly connection: Promise<MessageConnection>;
+    readonly server: RpcProxy<DataServerProtocol<TTransfer>>;
+    /** Set on first use; the shared readiness gate for this generation. */
+    ready?: Promise<void>;
+}
+/**
+ * The host-invariant half of talking to the data head: everything above
+ * {@link DataPort} that would otherwise be re-derived by every host
+ * adapter.
+ *
+ * Three jobs, and deliberately no fourth:
+ *
+ * 1. **Build the typed proxy** over the port's connection, with the framework's
+ *    wire prefix and its drift-proof client-method allowlist.
+ * 2. **Own the readiness gate** — `waitForReady` once per connection, shared
+ *    across concurrent callers. A socket client can connect before the
+ *    workspace walk finishes, and an early request is then answered correctly
+ *    from an empty registry, which reads as a broken project tier rather than
+ *    as a race.
+ * 3. **Own the reconnect policy**, by dropping its connection generation when
+ *    the port disposes and building a fresh one on the next request.
+ *
+ * It does **not** wrap the protocol methods; callers reach them through
+ * {@link connected}. The one exception is {@link openDocument}, which exists
+ * because the open/watch *order* is silently wrong the other way round — see
+ * its own doc.
+ *
+ * Generic over the transfer root so this file names no grammar. An adopter
+ * binds the concrete root (or the union of them, for a multi-grammar head) at
+ * its own edge.
+ */
+export declare class DataSession<TTransfer extends TransferElement> {
+    protected readonly port: DataPort;
+    protected readonly client: DataClientProtocol<TTransfer>;
+    protected readonly methodNamespace: string;
+    /** The current generation, or `undefined` before the first request / after a teardown. */
+    protected generation?: Generation<TTransfer>;
+    protected disposed: boolean;
+    protected readonly portDisposeListener: {
+        dispose(): void;
+    };
+    constructor(port: DataPort, client: DataClientProtocol<TTransfer>, options?: DataSessionOptions);
+    /** The identity every request is made under — the port's, not a second one. */
+    get clientId(): string;
+    /**
+     * The connected, READY server proxy.
+     *
+     * Returns the proxy rather than `void` on purpose. A reconnect replaces the
+     * proxy, so a caller that cached one from an earlier call would go on
+     * addressing a dead connection with no error — handing it back per call
+     * makes the stale reference unrepresentable.
+     *
+     * Concurrent callers share one readiness promise, so `waitForReady` is
+     * awaited once per generation and not once per caller.
+     */
+    connected(): Promise<RpcProxy<DataServerProtocol<TTransfer>>>;
+    /**
+     * Open `uri` for editing and start watching it, in that order, returning
+     * the opened snapshot.
+     *
+     * **The order is the whole reason this method exists.**
+     * `watchModelDocument` baselines its dedup fingerprint from the *current*
+     * document, but only if one exists. Watching first therefore leaves no
+     * baseline, and the first phase event after the open arrives as a spurious
+     * `'changed'` — which a widget that resets its in-memory root to the server
+     * view misreads as a concurrent third-party write, losing whatever the user
+     * had typed. Nothing about the wrong order fails loudly, so it is encoded
+     * here rather than documented and re-derived.
+     *
+     * Note that the returned snapshot's empty `diagnostics` does not mean
+     * valid: `open` settles at the integrity landmark, not at validation.
+     * Validity arrives asynchronously on `onDocumentUpdated`, or synchronously
+     * from `getModelDocument({ includeDiagnostics: true })`.
+     */
+    openDocument(uri: string): Promise<TransferDocument<TTransfer>>;
+    /**
+     * Close `uri`. The server unwatches implicitly, so this is the dual of
+     * {@link openDocument} and needs no separate unwatch.
+     */
+    closeDocument(uri: string): Promise<void>;
+    /**
+     * Whether `event.sourceClientId` identifies this session's own write.
+     *
+     * Every watcher needs this and the check is one comparison, so getting it
+     * wrong is cheap to do and expensive to find: an unfiltered echo looks
+     * exactly like a concurrent third-party edit.
+     */
+    isOwnEcho(sourceClientId: string): boolean;
+    /** Tear down the current connection and stop tracking the port. Idempotent. */
+    dispose(): void;
+    /** The live generation, building one if there is none. */
+    protected currentGeneration(): Generation<TTransfer>;
+    /** Await the connection and the server's startup gate for one generation. */
+    protected awaitReady(generation: Generation<TTransfer>): Promise<void>;
+    /**
+     * Discard the current generation, disposing its connection if it opened.
+     * The next {@link connected} builds a fresh one.
+     */
+    protected dropGeneration(): void;
+}
+export {};
+//# sourceMappingURL=data-session.d.ts.map

package/lib/client/data-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-session.d.ts","sourceRoot":"","sources":["../../src/client/data-session.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAyD,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClI,OAAO,EAAE,KAAK,QAAQ,EAAkB,MAAM,QAAQ,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,+EAA+E;AAC/E,UAAU,UAAU,CAAC,SAAS,SAAS,eAAe;IACnD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC;IACzD,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,WAAW,CAAC,SAAS,SAAS,eAAe;IAQpD,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ;IACjC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC,SAAS,CAAC;IAR3D,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAC3C,0FAA0F;IAC1F,SAAS,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAC7C,SAAS,CAAC,QAAQ,UAAS;IAC3B,SAAS,CAAC,QAAQ,CAAC,mBAAmB,EAAE;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,CAAC;gBAGtC,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,kBAAkB,CAAC,SAAS,CAAC,EACxD,OAAO,GAAE,kBAAuB;IAMnC,+EAA+E;IAC/E,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;;;;;;;OAUG;IACG,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC;IAYnE;;;;;;;;;;;;;;;;;OAiBG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAOrE;;;OAGG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/C;;;;;;OAMG;IACH,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAI1C,+EAA+E;IAC/E,OAAO,IAAI,IAAI;IASf,0DAA0D;IAC1D,SAAS,CAAC,iBAAiB,IAAI,UAAU,CAAC,SAAS,CAAC;IAkBpD,6EAA6E;cAC7D,UAAU,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAe5E;;;OAGG;IACH,SAAS,CAAC,cAAc,IAAI,IAAI;CAQlC"}

package/lib/client/data-session.js

@@ -0,0 +1,179 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataSession = void 0;
+const data_1 = require("../data");
+const rpc_1 = require("../rpc");
+/**
+ * The host-invariant half of talking to the data head: everything above
+ * {@link DataPort} that would otherwise be re-derived by every host
+ * adapter.
+ *
+ * Three jobs, and deliberately no fourth:
+ *
+ * 1. **Build the typed proxy** over the port's connection, with the framework's
+ *    wire prefix and its drift-proof client-method allowlist.
+ * 2. **Own the readiness gate** — `waitForReady` once per connection, shared
+ *    across concurrent callers. A socket client can connect before the
+ *    workspace walk finishes, and an early request is then answered correctly
+ *    from an empty registry, which reads as a broken project tier rather than
+ *    as a race.
+ * 3. **Own the reconnect policy**, by dropping its connection generation when
+ *    the port disposes and building a fresh one on the next request.
+ *
+ * It does **not** wrap the protocol methods; callers reach them through
+ * {@link connected}. The one exception is {@link openDocument}, which exists
+ * because the open/watch *order* is silently wrong the other way round — see
+ * its own doc.
+ *
+ * Generic over the transfer root so this file names no grammar. An adopter
+ * binds the concrete root (or the union of them, for a multi-grammar head) at
+ * its own edge.
+ */
+class DataSession {
+    port;
+    client;
+    methodNamespace;
+    /** The current generation, or `undefined` before the first request / after a teardown. */
+    generation;
+    disposed = false;
+    portDisposeListener;
+    constructor(port, client, options = {}) {
+        this.port = port;
+        this.client = client;
+        this.methodNamespace = options.methodNamespace ?? data_1.DATA_SERVER_WIRE_PREFIX;
+        this.portDisposeListener = this.port.onDispose(() => this.dropGeneration());
+    }
+    /** The identity every request is made under — the port's, not a second one. */
+    get clientId() {
+        return this.port.clientId;
+    }
+    /**
+     * The connected, READY server proxy.
+     *
+     * Returns the proxy rather than `void` on purpose. A reconnect replaces the
+     * proxy, so a caller that cached one from an earlier call would go on
+     * addressing a dead connection with no error — handing it back per call
+     * makes the stale reference unrepresentable.
+     *
+     * Concurrent callers share one readiness promise, so `waitForReady` is
+     * awaited once per generation and not once per caller.
+     */
+    async connected() {
+        if (this.disposed) {
+            throw new Error('DataSession is disposed');
+        }
+        const generation = this.currentGeneration();
+        if (!generation.ready) {
+            generation.ready = this.awaitReady(generation);
+        }
+        await generation.ready;
+        return generation.server;
+    }
+    /**
+     * Open `uri` for editing and start watching it, in that order, returning
+     * the opened snapshot.
+     *
+     * **The order is the whole reason this method exists.**
+     * `watchModelDocument` baselines its dedup fingerprint from the *current*
+     * document, but only if one exists. Watching first therefore leaves no
+     * baseline, and the first phase event after the open arrives as a spurious
+     * `'changed'` — which a widget that resets its in-memory root to the server
+     * view misreads as a concurrent third-party write, losing whatever the user
+     * had typed. Nothing about the wrong order fails loudly, so it is encoded
+     * here rather than documented and re-derived.
+     *
+     * Note that the returned snapshot's empty `diagnostics` does not mean
+     * valid: `open` settles at the integrity landmark, not at validation.
+     * Validity arrives asynchronously on `onDocumentUpdated`, or synchronously
+     * from `getModelDocument({ includeDiagnostics: true })`.
+     */
+    async openDocument(uri) {
+        const server = await this.connected();
+        const document = await server.openModelDocument({ uri, clientId: this.clientId });
+        await server.watchModelDocument({ uri, clientId: this.clientId });
+        return document;
+    }
+    /**
+     * Close `uri`. The server unwatches implicitly, so this is the dual of
+     * {@link openDocument} and needs no separate unwatch.
+     */
+    async closeDocument(uri) {
+        const server = await this.connected();
+        await server.closeModelDocument({ uri, clientId: this.clientId });
+    }
+    /**
+     * Whether `event.sourceClientId` identifies this session's own write.
+     *
+     * Every watcher needs this and the check is one comparison, so getting it
+     * wrong is cheap to do and expensive to find: an unfiltered echo looks
+     * exactly like a concurrent third-party edit.
+     */
+    isOwnEcho(sourceClientId) {
+        return sourceClientId === this.clientId;
+    }
+    /** Tear down the current connection and stop tracking the port. Idempotent. */
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        this.portDisposeListener.dispose();
+        this.dropGeneration();
+    }
+    /** The live generation, building one if there is none. */
+    currentGeneration() {
+        if (this.generation) {
+            return this.generation;
+        }
+        const connection = this.port.connect();
+        // Rejection is reported here rather than left to float: an unhandled
+        // rejection on a connection promise is the failure mode that reads as
+        // "the model is empty" instead of "the transport never opened".
+        connection.catch((error) => this.port.reportError(error, 'connecting to the data server'));
+        const server = (0, rpc_1.createRpcProxy)(connection, {
+            methodNamespace: this.methodNamespace,
+            localTarget: this.client,
+            localMethods: data_1.DATA_CLIENT_PROTOCOL_METHODS
+        });
+        this.generation = { connection, server };
+        return this.generation;
+    }
+    /** Await the connection and the server's startup gate for one generation. */
+    async awaitReady(generation) {
+        try {
+            await generation.connection;
+            await generation.server.waitForReady();
+        }
+        catch (error) {
+            // Drop the generation so the next request retries rather than
+            // re-awaiting a settled rejection forever.
+            if (this.generation === generation) {
+                this.generation = undefined;
+            }
+            this.port.reportError(error, 'waiting for the data server to become ready');
+            throw error;
+        }
+    }
+    /**
+     * Discard the current generation, disposing its connection if it opened.
+     * The next {@link connected} builds a fresh one.
+     */
+    dropGeneration() {
+        const generation = this.generation;
+        this.generation = undefined;
+        if (!generation) {
+            return;
+        }
+        generation.connection.then(connection => connection.dispose()).catch(() => undefined);
+    }
+}
+exports.DataSession = DataSession;
+//# sourceMappingURL=data-session.js.map

package/lib/client/data-session.js.map

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

package/lib/client/index.d.ts

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+/**
+ * Subpath barrel for `@hydranium/protocol/client` — the **host-neutral client
+ * tier** of the data head.
+ *
+ * Where `./data` is the wire *contract* and `./rpc` is the machinery that lowers
+ * it onto a connection, this is what a client wraps around both: the seam a host
+ * fills in (`DataPort`), the lifecycle above it (`DataSession` —
+ * readiness gate, open/watch ordering, echo recognition, reconnect), the inbound
+ * fan-out (`DataEvents`), and the two halves of the hop for hosts whose
+ * client cannot hold a socket — `createPostMessageTransport` on the client
+ * side and `relayToPostMessageChannel` on the side that does hold it.
+ *
+ * **Neutral, and gate-enforced so.** Nothing here imports a host package or a
+ * Node builtin, which is what lets one client tier serve a Theia frontend, a VS
+ * Code extension host, a VS Code webview and a plain browser app. `npm run
+ * check:neutral` bundles these modules for the browser; `scripts/check-neutral-bundles.mjs`
+ * carries the entries.
+ *
+ * The Theia-specific mounting of the same contract lives in
+ * `@hydranium/data-client-theia`: its `AbstractDataServiceFrontend` solves the
+ * same problem against Theia's channel transport, and its `EmitterDataClient`
+ * is the Theia-bound counterpart of `DataEvents`. Prefer this tier for
+ * anything new, and reach for the Theia package only for what genuinely needs
+ * Theia DI.
+ */
+export * from './data-events';
+export * from './data-port';
+export * from './data-session';
+export * from './message-relay';
+export * from './post-message-transport';
+//# sourceMappingURL=index.d.ts.map

package/lib/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}

package/lib/client/index.js

@@ -0,0 +1,55 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Subpath barrel for `@hydranium/protocol/client` — the **host-neutral client
+ * tier** of the data head.
+ *
+ * Where `./data` is the wire *contract* and `./rpc` is the machinery that lowers
+ * it onto a connection, this is what a client wraps around both: the seam a host
+ * fills in (`DataPort`), the lifecycle above it (`DataSession` —
+ * readiness gate, open/watch ordering, echo recognition, reconnect), the inbound
+ * fan-out (`DataEvents`), and the two halves of the hop for hosts whose
+ * client cannot hold a socket — `createPostMessageTransport` on the client
+ * side and `relayToPostMessageChannel` on the side that does hold it.
+ *
+ * **Neutral, and gate-enforced so.** Nothing here imports a host package or a
+ * Node builtin, which is what lets one client tier serve a Theia frontend, a VS
+ * Code extension host, a VS Code webview and a plain browser app. `npm run
+ * check:neutral` bundles these modules for the browser; `scripts/check-neutral-bundles.mjs`
+ * carries the entries.
+ *
+ * The Theia-specific mounting of the same contract lives in
+ * `@hydranium/data-client-theia`: its `AbstractDataServiceFrontend` solves the
+ * same problem against Theia's channel transport, and its `EmitterDataClient`
+ * is the Theia-bound counterpart of `DataEvents`. Prefer this tier for
+ * anything new, and reach for the Theia package only for what genuinely needs
+ * Theia DI.
+ */
+__exportStar(require("./data-events"), exports);
+__exportStar(require("./data-port"), exports);
+__exportStar(require("./data-session"), exports);
+__exportStar(require("./message-relay"), exports);
+__exportStar(require("./post-message-transport"), exports);
+//# sourceMappingURL=index.js.map

package/lib/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,gDAA8B;AAC9B,8CAA4B;AAC5B,iDAA+B;AAC/B,kDAAgC;AAChC,2DAAyC"}

package/lib/client/message-relay.d.ts

@@ -0,0 +1,111 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type Disposable, type Event, type MessageReader, type MessageWriter } from 'vscode-jsonrpc';
+import type { PostMessageChannel } from './post-message-transport';
+/**
+ * The framed side of a relay: the reader/writer pair over whatever transport the
+ * host actually holds — a TCP socket to the data-server, a child process' stdio,
+ * a websocket.
+ *
+ * Structurally the same pair `PostMessageTransport` exposes, and
+ * deliberately so: either can stand on either side of a relay. What differs is
+ * only who owns the framing, which is why this tier never needs to know.
+ */
+export interface RelayTransport {
+    readonly reader: MessageReader;
+    readonly writer: MessageWriter;
+    /** Release the transport. Called when the relay is disposed. */
+    dispose?(): void;
+}
+/** Options for {@link relayToPostMessageChannel}. */
+export interface MessageRelayOptions {
+    /**
+     * Surface a failure the way the host does. Same contract as
+     * `DataPort.reportError`: `context` names what was being attempted.
+     *
+     * A relay has no other way to report — it sits between two transports and
+     * owns neither, so a swallowed error here presents as a form that never
+     * populates.
+     */
+    readonly reportError?: (error: unknown, context: string) => void;
+}
+/** A live relay. Dispose to tear both directions down. */
+export interface MessageRelay extends Disposable {
+    /**
+     * Resolves `true` once messages are flowing in both directions, `false` if
+     * opening the framed transport failed or the relay was disposed first.
+     *
+     * It resolves rather than rejects on failure so that a caller which never
+     * awaits it cannot produce an unhandled rejection; the error itself goes to
+     * {@link MessageRelayOptions.reportError}. Tests await it to get a
+     * deterministic "wiring is done" edge instead of polling.
+     */
+    readonly wired: Promise<boolean>;
+    /**
+     * Fires when the framed side goes away — the data-server exiting, the socket
+     * erroring, a language-server restart taking its ports with it.
+     *
+     * **The relay cannot propagate this to the clone hop itself**, and the host
+     * has to. {@link PostMessageChannel} is deliberately an input-only contract:
+     * it offers `onClose` for observing the pipe but no `close()` for ending it,
+     * because a webview's pipe belongs to the webview's lifecycle, not to
+     * whoever relays over it. So a framed-side death is invisible to the far
+     * end, whose pending requests would otherwise hang forever with no rejection
+     * — the far side's `MessageConnection` sees an open pipe and no answer. On
+     * this event a host disposes the webview, reloads it, or sends its own
+     * "connection lost" notification; doing nothing is the one wrong choice.
+     */
+    readonly onClose: Event<void>;
+}
+/**
+ * Pump JSON-RPC messages between a framed transport and a structured-clone
+ * {@link PostMessageChannel}, decoding neither.
+ *
+ * This is the extension-host half of the hop whose webview half is
+ * `createPostMessageTransport`. A webview has no `net`, so the data-server
+ * socket can only be held by the extension host; the host therefore has to move
+ * whole messages between a Content-Length-framed socket and a pipe that carries
+ * objects. Both sides speak the same JSON-RPC, so this moves messages and adds
+ * no semantics — there is no re-proxy in between, and `createRpcProxy` on the far
+ * side is unaware the relay exists.
+ *
+ * **No `MessageConnection` is built here, and that is what keeps the module
+ * browser-neutral.** A relay is not a JSON-RPC endpoint: it has no requests of
+ * its own, so it needs no message queue, hence no vscode-jsonrpc runtime
+ * abstraction layer. `reader.listen` / `writer.write` are enough. The caller
+ * imports the entrypoint that frames its own transport (`vscode-jsonrpc/node`
+ * for a socket) and the RAL that comes with it; this tier stays neutral and is
+ * gated so by `npm run check:neutral`. Contrast
+ * `@hydranium/data-client-theia`'s `SocketChannelForwarder`, which does build a
+ * connection only to borrow its `onClose`, and pays a Theia dependency for the
+ * byte coding this shape does not need.
+ *
+ * **The race this exists to close.** `openTransport` is asynchronous — a real
+ * host discovers a port first, then connects — while the clone pipe is usable
+ * immediately. `PostMessageChannel.onMessage` is a plain emitter with no replay,
+ * so a message sent during the connect window is dropped outright.
+ *
+ * It is not enough that a disciplined client awaits its own connection before
+ * sending: a host builds the far-side connection and hands it back *without*
+ * waiting for the relay, so `DataSession`'s very first call — the readiness
+ * handshake — is already in flight while the socket is still opening. Dropping
+ * that first request presents as a client hanging forever on connect against a
+ * perfectly healthy server.
+ *
+ * So the subscription is taken **synchronously, before the first await**, and
+ * buffers; the hand-off then swaps listeners and replays within one turn of the
+ * event loop, which is what makes it impossible for a message to be both
+ * buffered and forwarded, or to arrive between the two. Replay is FIFO because
+ * order is load-bearing — a `getModelDocument` that overtook its own
+ * `openModelDocument` would answer against an unopened document.
+ * `@hydranium/client-theia`'s `AbstractSocketForwardingConnectionHandler` carries the
+ * same fix for the Theia channel transport.
+ */
+export declare function relayToPostMessageChannel(channel: PostMessageChannel, openTransport: () => Promise<RelayTransport>, options?: MessageRelayOptions): MessageRelay;
+//# sourceMappingURL=message-relay.d.ts.map

package/lib/client/message-relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-relay.d.ts","sourceRoot":"","sources":["../../src/client/message-relay.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAW,KAAK,UAAU,EAAE,KAAK,KAAK,EAAgB,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5H,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,gEAAgE;IAChE,OAAO,CAAC,IAAI,IAAI,CAAC;CACnB;AAED,qDAAqD;AACrD,MAAM,WAAW,mBAAmB;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnE;AAED,0DAA0D;AAC1D,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC7C;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,yBAAyB,CACtC,OAAO,EAAE,kBAAkB,EAC3B,aAAa,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,EAC5C,OAAO,GAAE,mBAAwB,GACjC,YAAY,CAgGd"}