@hydranium/data-client-theia 1.0.0-next.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# `@hydranium/data-client-theia`
+
+Theia client primitives for the hydranium **data head** — the companion of
+`@hydranium/data-server` in the
+[Hydranium](https://github.com/eclipse-emfcloud/hydranium) framework.
+
+The data head's frontend speaks the data server's own `vscode-jsonrpc` protocol
+over a channel that the Theia backend relays byte-for-byte onto the server's
+socket. This package is both halves of that arrangement: the browser-side
+connection and typed-frontend bases, and the backend-side connection handler and
+forwarder. Install it if a Theia application needs form editors, trees, or
+code-gen driven from the live AST rather than from LSP text edits.
+
+## What it gives you
+
+- **`openChannelConnection`** with `createChannelConnection` and
+  `ChannelConnectionHandle` — wraps a Theia `Channel` as a `vscode-jsonrpc`
+  `MessageConnection`, gated on a `whenReady` promise, and by default
+  re-establishes it by **re-opening the channel** when the connection is lost.
+  Re-opening rather than rebuilding is what recovers a restarted language server:
+  a server restart closes only the multiplexed sub-channel, so no replacement
+  channel ever arrives on its own. Retries follow `DEFAULT_RECONNECT_DELAYS`,
+  escalating per consecutive loss and resetting after
+  `RECONNECT_ESCALATION_RESET_MS`.
+- **`AbstractDataServiceFrontend`** — base for a frontend that owns the
+  data-server connection: the workspace-gated connect, the typed server proxy,
+  the inbound client binding, and a lazy idempotent init gate (`ensureConnected`).
+  You supply the connection seams (`connectionProvider`, `servicePath`,
+  `methodNamespace`, `client`, `clientMethods`); progress UI and domain caching
+  layer on top.
+- **`AbstractDiagnosticsDataServiceFrontend`** and
+  **`AbstractReferencesDataServiceFrontend`** — the same base specialised for the
+  two protocol fragments an adopter most often keeps: each diagnostics
+  (`dumpServerState`, `writeHeapSnapshot`, `dumpPodMemory`, the profiling and
+  latency calls) and each reference method is implemented as a readiness-gated
+  pass-through, so you do not hand-write identical one-line bodies. They are
+  deliberately independent bases rather than chained.
+- **`EmitterDataClient`** (on `./common`, not `./browser`) — the default
+  client-side implementation of the data protocol's inbound notifications,
+  fanning each one out to a Theia `Event`: `onDidUpdateDocument`,
+  `onDidSaveDocument`, `onDidChangeProjects`. Bind an instance as the
+  `localTarget` of the frontend's RPC proxy. It sits on the common tier because
+  its only runtime dependency is `@theia/core`'s root entry, which is Theia's own
+  common tier, so a backend or a plain-Node consumer can bind it too.
+- **`whenWorkspaceOpen`** — resolves once Theia reports a workspace root. The data
+  server only starts once the LSP launches for a workspace, so connecting earlier
+  would hang in port discovery; pass this as `whenReady`.
+- **Backend (`./node`)** — `DataServerConnectionHandler` (the socket bridge, with
+  its own GLSP-free `SocketChannelForwarder`),
+  `createDataServerConnectionContainerModule(...handlers)` for the
+  frontend-scoped module boilerplate, and `HostDiagnosticsServer` with
+  `createHostDiagnosticsBackendModule()` — which, paired with the browser-side
+  `bindHostDiagnostics`, lights up the "Backend" diagnostics commands in
+  `@hydranium/client-theia`'s contribution.
+
+## Install
+
+```bash
+npm install @hydranium/data-client-theia
+```
+
+You must already have a Theia application with `@theia/workspace` available, and a
+running hydranium data server to connect to. The declared peer dependencies are:
+
+| Peer                      | Range                |
+| ------------------------- | -------------------- |
+| `@hydranium/client-theia` | `^1.0.0-next`        |
+| `@hydranium/core`         | `^1.0.0-next`        |
+| `@hydranium/protocol`     | `^1.0.0-next`        |
+| `@theia/core`             | `^1.71.0`            |
+| `@theia/workspace`        | `^1.71.0`            |
+| `inversify`               | `^6.0.0`             |
+| `vscode-jsonrpc`          | `^8.0.0 \|\| ^9.0.0` |
+
+`@hydranium/core` is reached only from the `./node` tier (the host-diagnostics
+service), so a frontend-only consumer never loads it.
+
+## Wiring
+
+This package declares no `theiaExtensions` — it is a library your own Theia
+extension builds on. That extension's `package.json` declares the entries, and
+each entry names one frontend/backend module pair:
+
+- the **frontend** module binds your `AbstractDataServiceFrontend` subclass (and,
+  for the diagnostics commands, calls `bindHostDiagnostics`);
+- the **backend** module is typically a one-liner:
+  `export default createDataServerConnectionContainerModule(MyHandler)`, where
+  `MyHandler` extends `DataServerConnectionHandler`.
+
+More than one handler is the normal case, not an exotic one. Theia keys a
+frontend channel by its service path and refuses a second channel on a path
+already open, so every frontend abstraction reaching the data head needs its own
+`servicePath` — while the shared `portCommand` still names the one server process
+behind them all.
+
+The refusal is silent, which is what makes it expensive: the loser's promise is
+left unsettled rather than rejected, so a frontend that shared a path hangs on
+its loading state indefinitely with nothing in the server log to say why.
+
+## Entry points
+
+| Subpath     | Holds                                                                                                                                                                                                | Environment                      |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| `.`         | Nothing — the surface is split by environment, so the root barrel stays empty.                                                                                                                        | browser-neutral (gated)          |
+| `./common`  | `EmitterDataClient` — a module lands here only when values, types and relative imports are all neutral or Theia COMMON tier. No error-reconstruction bridge, and that is a property of the transport: the direct `vscode-jsonrpc` connection carries a typed error across the relay natively. | browser-neutral (gated)          |
+| `./browser` | `openChannelConnection`, `createChannelConnection`, the three `Abstract*DataServiceFrontend` bases, `bindHostDiagnostics`, `whenWorkspaceOpen`                                                         | browser / Theia frontend (gated) |
+| `./node`    | `DataServerConnectionHandler`, `createDataServerConnectionContainerModule`, `SocketChannelForwarder`, `HostDiagnosticsServer`, `createHostDiagnosticsBackendModule`                                    | Node / Theia backend             |
+
+Every subpath also has a `./lib/<name>` twin for consumers on
+`moduleResolution: "Node"`. "Gated" means the repository's neutral-bundle check
+enforces that the entry bundles for the browser with no `node:*` import,
+transitive ones included; `./node` is deliberately outside that gate. Also
+worth reading: [what "gated neutral" does and does not promise](../../docs/concepts/browser-hosting.md#a-note-on-what-gated-neutral-does-and-does-not-promise).
+
+## Status
+
+Alpha — pre-v0, not yet published. The API is not stable and may change without a
+deprecation cycle. See [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md) for
+the data head's place among the heads, and the
+[repository README](../../README.md) for current status and known limitations.
+
+## License
+
+`MIT` — see this package's [`LICENSE`](./LICENSE). Third-party notices for the
+runtime dependency closure are collected in the repository
+[`NOTICE.md`](../../NOTICE.md).

package/lib/browser/channel-connection.d.ts

@@ -0,0 +1,174 @@
+/********************************************************************************
+ * 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 Channel, type Event } from '@theia/core';
+import { type ServiceConnectionProvider } from '@theia/core/lib/browser';
+import { type Logger, type MessageConnection } from 'vscode-jsonrpc/browser';
+/**
+ * Build a `vscode-jsonrpc` {@link MessageConnection} on top of a Theia
+ * {@link Channel}. This is the browser-side transport for the data-server
+ * head: the frontend obtains a channel to the backend forwarder (via
+ * `connectionProvider.listen`), wraps it here, and drives the typed
+ * `createRpcProxy` over the returned connection — so the frontend
+ * speaks the same vscode-jsonrpc protocol the model-server speaks, with the
+ * backend relaying bytes between the two.
+ *
+ * Mirrors `@eclipse-glsp/theia-integration`'s `createChannelConnection`, but
+ * lives here so the data-server head carries no GLSP dependency.
+ */
+export declare function createChannelConnection(channel: Channel, logger?: Logger): MessageConnection;
+/** Options for {@link openChannelConnection}. */
+export interface OpenChannelConnectionOptions {
+    /**
+     * Resolves when it is safe to open the channel. The handler holds back the
+     * `connectionProvider.listen` call until this settles — e.g. pass
+     * `whenWorkspaceOpen` so the backend forwarder isn't asked for the
+     * model-server port before a workspace (and therefore the LSP launch that
+     * publishes the port) exists.
+     */
+    whenReady?: Promise<void>;
+    /** Optional `vscode-jsonrpc` logger threaded into the connection. */
+    logger?: Logger;
+    /**
+     * Re-establish the connection whenever the live one is lost, by RE-OPENING
+     * the channel on `path` — not merely by rebuilding over a channel Theia hands
+     * back.
+     *
+     * **Default `true`, and the default is the point.** Re-opening is the only
+     * thing that recovers a restarted language server. Theia replays a `listen`
+     * handler solely from `ServiceConnectionProvider.handleChannelCreated`, i.e.
+     * when the MAIN frontend-backend channel is (re)created — a page reload, a
+     * dropped socket, a backend restart. A language-server restart closes just the
+     * multiplexed sub-channel for this service path while the main channel stays
+     * open, so no replacement channel ever arrives on its own and a handle that
+     * only waits for one holds a connection to the dead process forever: its
+     * requests neither answer nor reject.
+     *
+     * **Why on by default, where the older rebuild-on-a-fresh-channel behaviour
+     * was opt-in.** That one had a working alternative to weigh against — the
+     * existing connection was fine, and opting in only decided whether to swap to
+     * a fresher one, so leaving a consumer's readiness gate (and the progress UI it
+     * drives) undisturbed was worth more. A CLOSED channel offers no such choice:
+     * the alternative to re-opening is a permanently dead handle. Re-running a
+     * readiness gate against a live replacement is what a restarted server should
+     * cost.
+     *
+     * Turn it off for a consumer that treats transport loss as terminal and tears
+     * itself down instead. Off means build-once: every channel after the first is
+     * ignored and {@link ChannelConnectionHandle.onDidLoseConnection} never fires.
+     */
+    reconnect?: boolean;
+    /**
+     * Delay before the re-open following each CONSECUTIVE connection loss, in ms;
+     * the last entry repeats once the schedule is exhausted. Defaults to
+     * {@link DEFAULT_RECONNECT_DELAYS}.
+     *
+     * A delay rather than an immediate re-open, for two independent reasons.
+     * Theia's `ChannelMultiplexer.handleClose` fires the close emitter BEFORE it
+     * deletes the id from `openChannels`, so a re-open issued from inside the
+     * close listener can still see the id as open — and `open()` throws
+     * "Another channel with the id '<id>' is already open" then, which
+     * `ServiceConnectionProvider.listen` neither catches nor reports: the handler
+     * is simply never invoked, and the consumer hangs rather than failing. And a
+     * server that is flapping would otherwise be re-opened against at whatever
+     * rate it can close a channel, which is what the escalation is for.
+     *
+     * The escalation resets once a connection has survived
+     * {@link RECONNECT_ESCALATION_RESET_MS}, so an hour-long session with
+     * occasional restarts does not converge on the longest delay.
+     */
+    reconnectDelays?: readonly number[];
+}
+/**
+ * Default {@link OpenChannelConnectionOptions.reconnectDelays}.
+ *
+ * The first entry only has to outlast the synchronous close dispatch, so it is
+ * short: the backend forwarder, not this delay, is what absorbs a server that is
+ * still down. `AbstractSocketForwardingConnectionHandler` re-runs its port command per
+ * connection and retries it indefinitely, so a channel re-opened while the
+ * server is restarting parks in `findPort` and connects when the replacement
+ * publishes its new port. The later entries exist for the case that machinery
+ * cannot absorb — a server that accepts a socket and then dies again.
+ */
+export declare const DEFAULT_RECONNECT_DELAYS: readonly number[];
+/** How long a connection must survive before the reconnect escalation resets. */
+export declare const RECONNECT_ESCALATION_RESET_MS = 30000;
+/**
+ * A live channel connection plus the two things a bare
+ * `Promise<MessageConnection>` cannot express: that the connection can be
+ * REPLACED, and that it can be released.
+ */
+export interface ChannelConnectionHandle {
+    /**
+     * The current connection. Read it per use rather than caching it: after a
+     * reconnect this returns a NEW promise, and a cached one resolves to the
+     * dead connection forever. The same reasoning makes
+     * `AbstractDataServiceFrontend` rebuild its proxy rather than hold one.
+     */
+    readonly current: Promise<MessageConnection>;
+    /**
+     * Fires when the live connection is gone and a replacement is on the way.
+     * {@link current} has ALREADY been repointed at the replacement (still
+     * unresolved) by the time listeners run, so a listener re-derives from
+     * `current` and whatever it queues waits for the new channel instead of being
+     * addressed at the dead one.
+     *
+     * **This is the event a consumer wants, not {@link onDidReconnect}.** Anything
+     * derived from a connection — an `createRpcProxy`, a readiness gate, a
+     * `DataSession` generation — is dead from this moment, and a consumer that
+     * waits for the replacement to be live instead keeps sending into the dead one
+     * for the whole gap. A `DataPort` implementation translates this into the
+     * port's own `onDispose`, which is what makes `DataSession` drop its
+     * generation.
+     *
+     * Never fires when {@link OpenChannelConnectionOptions.reconnect} is off.
+     */
+    readonly onDidLoseConnection: Event<void>;
+    /**
+     * Fires with each connection built AFTER the first, once it is live. For a
+     * consumer that needs the connection object itself; for rebuilding what was
+     * derived from the previous one, use {@link onDidLoseConnection} instead —
+     * it fires at the start of the gap rather than at its end.
+     *
+     * Never fires when {@link OpenChannelConnectionOptions.reconnect} is off.
+     */
+    readonly onDidReconnect: Event<MessageConnection>;
+    /**
+     * Dispose the live connection and stop tracking the channel. Idempotent.
+     *
+     * Without it, a frontend being torn down leaves its connection and its
+     * inbound handler bindings attached — a leak that accumulates per cycle in
+     * tests and in a reloading workbench.
+     */
+    dispose(): void;
+}
+/**
+ * Open a Theia channel to a backend forwarder and wrap it as the
+ * `vscode-jsonrpc` {@link MessageConnection} the data-server proxy speaks over.
+ *
+ * Awaits `options.whenReady` (if given), then registers the channel handler via
+ * `connectionProvider.listen` and keeps a live connection to `path` for as long
+ * as the handle is undisposed — re-opening the channel whenever the current one
+ * closes, which {@link OpenChannelConnectionOptions.reconnect} governs. Callers
+ * build their `createRpcProxy` / `bindRpcMethods` over
+ * {@link ChannelConnectionHandle.current}, which queues outbound calls and
+ * inbound bindings until the channel is live.
+ *
+ * **The `reconnect` argument to Theia's `listen` is deliberately `false`**, in
+ * both modes. Passing `true` there registers the handler for replay from
+ * `handleChannelCreated`, and this handle then has two independent re-openers for
+ * one path: Theia's replay when the main frontend-backend channel is recreated,
+ * and the close-driven re-open below — which also fires then, because
+ * `ChannelMultiplexer.onUnderlyingChannelClose` closes every sub-channel. Two
+ * `open()` calls for one id means the loser throws "Another channel with the id
+ * '<id>' is already open" inside a promise `listen` neither awaits nor reports,
+ * so the consumer's request is left unsettled: a hang with a clean log, not an
+ * error. Owning the re-open here means owning it exclusively.
+ */
+export declare function openChannelConnection(connectionProvider: ServiceConnectionProvider, path: string, options?: OpenChannelConnectionOptions): ChannelConnectionHandle;
+//# sourceMappingURL=channel-connection.d.ts.map

package/lib/browser/channel-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-connection.d.ts","sourceRoot":"","sources":["../../src/browser/channel-connection.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,OAAO,EAAiC,KAAK,KAAK,EAAwB,MAAM,aAAa,CAAC;AAC5G,OAAO,EAAE,KAAK,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAEzE,OAAO,EAMJ,KAAK,MAAM,EAEX,KAAK,iBAAiB,EAQxB,MAAM,wBAAwB,CAAC;AAkEhC;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAI5F;AAED,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC1C;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;;;;;;;;;;;;OAkBG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAA2C,CAAC;AAElG,iFAAiF;AACjF,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE7C;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,mBAAmB,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAE1C;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAElD;;;;;;OAMG;IACH,OAAO,IAAI,IAAI,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAClC,kBAAkB,EAAE,yBAAyB,EAC7C,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,4BAAiC,GAC1C,uBAAuB,CA4IzB"}

package/lib/browser/channel-connection.js

@@ -0,0 +1,264 @@
+"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.RECONNECT_ESCALATION_RESET_MS = exports.DEFAULT_RECONNECT_DELAYS = void 0;
+exports.createChannelConnection = createChannelConnection;
+exports.openChannelConnection = openChannelConnection;
+const core_1 = require("@theia/core");
+const promise_util_1 = require("@theia/core/lib/common/promise-util");
+const browser_1 = require("vscode-jsonrpc/browser");
+/**
+ * A `vscode-jsonrpc` {@link MessageReader} that reads JSON-RPC messages off a
+ * Theia {@link Channel}. Each Theia channel message carries exactly one
+ * JSON-RPC message (the channel does its own length framing); the reader
+ * decodes the bytes and fires the parsed message.
+ */
+class ChannelMessageReader extends browser_1.AbstractMessageReader {
+    channel;
+    onMessageEmitter = new core_1.Emitter();
+    toDispose = new core_1.DisposableCollection();
+    constructor(channel) {
+        super();
+        this.channel = channel;
+        this.toDispose.push(this.onMessageEmitter);
+        this.toDispose.push(channel.onMessage(provider => this.handleMessage(provider)));
+        this.toDispose.push(channel.onClose(() => this.fireClose()));
+    }
+    handleMessage(provider) {
+        const buffer = provider().readBytes();
+        const message = JSON.parse(new TextDecoder().decode(buffer));
+        this.onMessageEmitter.fire(message);
+    }
+    listen(callback) {
+        return this.onMessageEmitter.event(callback);
+    }
+    dispose() {
+        super.dispose();
+        this.toDispose.dispose();
+    }
+}
+/**
+ * A `vscode-jsonrpc` {@link MessageWriter} that writes JSON-RPC messages onto a
+ * Theia {@link Channel} — one channel message per JSON-RPC message, the dual of
+ * {@link ChannelMessageReader}. Uses `TextEncoder` (not node `Buffer`) so the
+ * writer is browser-native, since the frontend constructs the connection.
+ */
+class ChannelMessageWriter extends browser_1.AbstractMessageWriter {
+    channel;
+    toDispose;
+    constructor(channel) {
+        super();
+        this.channel = channel;
+        this.toDispose = channel.onClose(() => this.fireClose());
+    }
+    write(message) {
+        const writeBuffer = this.channel.getWriteBuffer();
+        writeBuffer.writeBytes(new TextEncoder().encode(JSON.stringify(message)));
+        writeBuffer.commit();
+        return Promise.resolve();
+    }
+    end() {
+        this.dispose();
+    }
+    dispose() {
+        super.dispose();
+        this.toDispose.dispose();
+    }
+}
+/**
+ * Build a `vscode-jsonrpc` {@link MessageConnection} on top of a Theia
+ * {@link Channel}. This is the browser-side transport for the data-server
+ * head: the frontend obtains a channel to the backend forwarder (via
+ * `connectionProvider.listen`), wraps it here, and drives the typed
+ * `createRpcProxy` over the returned connection — so the frontend
+ * speaks the same vscode-jsonrpc protocol the model-server speaks, with the
+ * backend relaying bytes between the two.
+ *
+ * Mirrors `@eclipse-glsp/theia-integration`'s `createChannelConnection`, but
+ * lives here so the data-server head carries no GLSP dependency.
+ */
+function createChannelConnection(channel, logger) {
+    const reader = new ChannelMessageReader(channel);
+    const writer = new ChannelMessageWriter(channel);
+    return (0, browser_1.createMessageConnection)(reader, writer, logger);
+}
+/**
+ * Default {@link OpenChannelConnectionOptions.reconnectDelays}.
+ *
+ * The first entry only has to outlast the synchronous close dispatch, so it is
+ * short: the backend forwarder, not this delay, is what absorbs a server that is
+ * still down. `AbstractSocketForwardingConnectionHandler` re-runs its port command per
+ * connection and retries it indefinitely, so a channel re-opened while the
+ * server is restarting parks in `findPort` and connects when the replacement
+ * publishes its new port. The later entries exist for the case that machinery
+ * cannot absorb — a server that accepts a socket and then dies again.
+ */
+exports.DEFAULT_RECONNECT_DELAYS = [250, 500, 1_000, 2_000, 4_000, 8_000];
+/** How long a connection must survive before the reconnect escalation resets. */
+exports.RECONNECT_ESCALATION_RESET_MS = 30_000;
+/**
+ * Open a Theia channel to a backend forwarder and wrap it as the
+ * `vscode-jsonrpc` {@link MessageConnection} the data-server proxy speaks over.
+ *
+ * Awaits `options.whenReady` (if given), then registers the channel handler via
+ * `connectionProvider.listen` and keeps a live connection to `path` for as long
+ * as the handle is undisposed — re-opening the channel whenever the current one
+ * closes, which {@link OpenChannelConnectionOptions.reconnect} governs. Callers
+ * build their `createRpcProxy` / `bindRpcMethods` over
+ * {@link ChannelConnectionHandle.current}, which queues outbound calls and
+ * inbound bindings until the channel is live.
+ *
+ * **The `reconnect` argument to Theia's `listen` is deliberately `false`**, in
+ * both modes. Passing `true` there registers the handler for replay from
+ * `handleChannelCreated`, and this handle then has two independent re-openers for
+ * one path: Theia's replay when the main frontend-backend channel is recreated,
+ * and the close-driven re-open below — which also fires then, because
+ * `ChannelMultiplexer.onUnderlyingChannelClose` closes every sub-channel. Two
+ * `open()` calls for one id means the loser throws "Another channel with the id
+ * '<id>' is already open" inside a promise `listen` neither awaits nor reports,
+ * so the consumer's request is left unsettled: a hang with a clean log, not an
+ * error. Owning the re-open here means owning it exclusively.
+ */
+function openChannelConnection(connectionProvider, path, options = {}) {
+    const reconnect = options.reconnect ?? true;
+    const reconnectDelays = options.reconnectDelays ?? exports.DEFAULT_RECONNECT_DELAYS;
+    const reconnectEmitter = new core_1.Emitter();
+    const loseEmitter = new core_1.Emitter();
+    let deferred = new promise_util_1.Deferred();
+    let live;
+    let generation = 0;
+    let disposed = false;
+    /** Set from the close that repointed `deferred`, cleared by the accept that resolves it. */
+    let awaitingReplacement = false;
+    /** Consecutive losses, indexing `reconnectDelays`. */
+    let losses = 0;
+    /** When the live connection was built, for the escalation reset. `0` before the first. */
+    let liveSince = 0;
+    let reopenTimer;
+    // Own synchronous flag, deliberately NOT `deferred.state`. Theia's
+    // `Deferred` sets `state` inside a `.then()` on its own promise, so it is
+    // still `'unresolved'` for a microtask after `resolve()` returns. Guarding on
+    // it means two channels arriving in the SAME synchronous turn both pass the
+    // guard: the second connection gets built and starts listening, the
+    // first-wins `resolve` keeps the promise pointed at the first, and the second
+    // leaks — attached to a channel, reachable by nobody, never disposed. A test
+    // that only checks which connection the promise resolves with cannot see
+    // that; it takes counting the connections built per channel.
+    let built = false;
+    const scheduleReopen = () => {
+        if (liveSince > 0 && Date.now() - liveSince >= exports.RECONNECT_ESCALATION_RESET_MS) {
+            losses = 0;
+        }
+        const delay = reconnectDelays[Math.min(losses, reconnectDelays.length - 1)];
+        losses++;
+        reopenTimer = setTimeout(() => {
+            reopenTimer = undefined;
+            // `awaitingReplacement` is the guard against re-opening a path that
+            // already has a channel: a second `open()` for one id is the "already
+            // open" throw, and its symptom is a hang rather than an error.
+            if (disposed || !awaitingReplacement) {
+                return;
+            }
+            requestChannel();
+        }, delay);
+    };
+    /**
+     * The live connection's channel closed. Retire the generation and arm the
+     * replacement, in that order — a listener on `onDidLoseConnection` must
+     * already see `current` pointing at the replacement.
+     */
+    const handleChannelClosed = () => {
+        if (disposed || awaitingReplacement) {
+            return;
+        }
+        // Dispose rather than merely drop. vscode-jsonrpc rejects pending
+        // responses from `dispose`, never from a reader-side close — so a
+        // connection left undisposed keeps every in-flight request unsettled
+        // forever, which is the failure this whole path exists to end.
+        live?.dispose();
+        live = undefined;
+        deferred = new promise_util_1.Deferred();
+        awaitingReplacement = true;
+        loseEmitter.fire(undefined);
+        scheduleReopen();
+    };
+    const acceptChannel = (channel) => {
+        if (disposed) {
+            return;
+        }
+        if (built && !awaitingReplacement) {
+            // Unsolicited: a channel arrived while one is already live and no close
+            // asked for a replacement. Exactly one channel is outstanding at a time
+            // here, so this is either the build-once case (`reconnect` off) or a
+            // handler re-fire, and adopting it would leave the previous connection
+            // listening on its own channel, reachable by nobody and never disposed.
+            // The close-driven path is the only way a second generation is built.
+            return;
+        }
+        const connection = createChannelConnection(channel, options.logger);
+        connection.listen();
+        live = connection;
+        built = true;
+        awaitingReplacement = false;
+        generation++;
+        liveSince = Date.now();
+        if (reconnect) {
+            // Registered AFTER `createChannelConnection`, so the connection's own
+            // reader and writer see the close first and `connection.onClose` still
+            // fires for whoever is listening to it. Disposing before they run would
+            // put the connection in `Disposed`, from which vscode-jsonrpc
+            // deliberately emits no close event at all.
+            const acceptedGeneration = generation;
+            channel.onClose(() => {
+                if (acceptedGeneration === generation) {
+                    handleChannelClosed();
+                }
+            });
+        }
+        deferred.resolve(connection);
+        if (generation > 1) {
+            reconnectEmitter.fire(connection);
+        }
+    };
+    /** Register the channel handler for one open attempt on `path`. */
+    function requestChannel() {
+        connectionProvider.listen(path, (_path, channel) => acceptChannel(channel), false);
+    }
+    const start = async () => {
+        await options.whenReady;
+        if (disposed) {
+            return;
+        }
+        requestChannel();
+    };
+    start();
+    return {
+        get current() {
+            return deferred.promise;
+        },
+        onDidLoseConnection: loseEmitter.event,
+        onDidReconnect: reconnectEmitter.event,
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            if (reopenTimer !== undefined) {
+                clearTimeout(reopenTimer);
+                reopenTimer = undefined;
+            }
+            live?.dispose();
+            live = undefined;
+            loseEmitter.dispose();
+            reconnectEmitter.dispose();
+        }
+    };
+}
+//# sourceMappingURL=channel-connection.js.map

package/lib/browser/channel-connection.js.map

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