@hydranium/client-theia 1.0.0-next.13 → 1.0.0-next.135

package/lib/node/session-bound-frontend-connection-service.d.ts

@@ -0,0 +1,77 @@
+/********************************************************************************
+ * 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 { WebsocketFrontendConnectionService } from '@theia/core/lib/node/messaging/websocket-frontend-connection-service';
+import { type interfaces } from '@theia/core/shared/inversify';
+import { type ConnectionResilienceOptions } from '../common/connection-resilience-options';
+/**
+ * Socket Theia hands the disconnect handler, read off the base signature rather
+ * than imported, which spares a direct `socket.io` dependency carried purely
+ * for a parameter type.
+ */
+export type FrontendSocket = Parameters<WebsocketFrontendConnectionService['handleSocketDisconnect']>[0];
+/**
+ * Channel Theia hands the disconnect handler, read off the base signature so
+ * this package's emitted declarations name only
+ * `WebsocketFrontendConnectionService`.
+ *
+ * `ReconnectableSocketChannel` is not exported by every Theia release in the
+ * supported range, so importing it would make those declarations unresolvable
+ * for an adopter on one of them — a compile error for a feature they may not
+ * even be using.
+ */
+export type FrontendChannel = Parameters<WebsocketFrontendConnectionService['handleSocketDisconnect']>[1];
+/**
+ * Ignores a disconnect from a socket that no longer belongs to the frontend.
+ *
+ * A frontend that loses its network reconnects on a new socket within seconds;
+ * the server only notices the old one is gone when its next heartbeat write
+ * fails, which is a whole ping interval later. For that stretch both sockets are
+ * registered against the same session, and Theia's disconnect handler tears the
+ * session off its socket without checking which one just died. The late
+ * notification from the abandoned socket therefore cuts the healthy one loose.
+ * The frontend sees a connected socket and never retries, so the session is dead
+ * until the page is reloaded.
+ *
+ * Changed here: only the socket the session is currently using may act on a
+ * disconnect. The handler is rewritten rather than wrapped because the problem
+ * sits inside the listener Theia installs; the rest of the body is Theia's.
+ *
+ * Re-diff against Theia when the supported range moves: `override` catches a changed signature,
+ * not a changed body, so this copy can go stale in silence.
+ */
+export declare class SessionBoundFrontendConnectionService extends WebsocketFrontendConnectionService {
+    /** Socket each frontend's channel is currently bound to, with the time it was bound. */
+    protected readonly bindings: Map<string, {
+        socketId: string;
+        boundAt: number;
+    }>;
+    /** When a frontend's live socket went away, so the reconnect gap can be reported. */
+    protected readonly offlineSince: Map<string, number>;
+    handleSocketDisconnect(socket: FrontendSocket, channel: FrontendChannel, frontEndId: string): void;
+    protected closeConnection(frontEndId: string, reason: string): void;
+    /** Mirrors Theia's private `frontendConnectionTimeout`, including `Number('')` resolving to 0.
+     *  Private there, so the copy is forced; re-diff it with the handler above. */
+    protected connectionTimeout(): number;
+}
+/**
+ * Replaces the server pieces that decide how a session survives a reconnect.
+ *
+ * `FrontendConnectionService` is bound `toService(WebsocketFrontendConnectionService)`,
+ * so rebinding the concrete class is enough. The buffer stays transient (one per
+ * connection), matching Theia's `bind(SocketWriteBuffer).toSelf()`; the frontend
+ * counterpart is bound by `bindConnectionResilience` in a `frontendPreload`
+ * module, which is the only point early enough on that side.
+ *
+ * Does nothing but warn on a Theia too old to expose the buffer binding, so the
+ * package keeps one supported range rather than splitting its floor for this
+ * feature. Returns whether the hardening was installed, for an adopter that
+ * wants to branch on it.
+ */
+export declare function bindConnectionResilience(bind: interfaces.Bind, isBound: interfaces.IsBound, rebind: interfaces.Rebind, options?: ConnectionResilienceOptions): boolean;
+//# sourceMappingURL=session-bound-frontend-connection-service.d.ts.map

package/lib/node/session-bound-frontend-connection-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-bound-frontend-connection-service.d.ts","sourceRoot":"","sources":["../../src/node/session-bound-frontend-connection-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,kCAAkC,EAAE,MAAM,sEAAsE,CAAC;AAC1H,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,yCAAyC,CAAC;AAQ3F;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,kCAAkC,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzG;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,kCAAkC,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE1G;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,qCAAsC,SAAQ,kCAAkC;IAC1F,wFAAwF;IACxF,SAAS,CAAC,QAAQ,CAAC,QAAQ;kBAA+B,MAAM;iBAAW,MAAM;OAAM;IACvF,qFAAqF;IACrF,SAAS,CAAC,QAAQ,CAAC,YAAY,sBAA6B;IAEnD,sBAAsB,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;cA0CxF,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAO5E;mFAC+E;IAC/E,SAAS,CAAC,iBAAiB,IAAI,MAAM;CAOvC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACrC,IAAI,EAAE,UAAU,CAAC,IAAI,EACrB,OAAO,EAAE,UAAU,CAAC,OAAO,EAC3B,MAAM,EAAE,UAAU,CAAC,MAAM,EACzB,OAAO,GAAE,2BAAgC,GACzC,OAAO,CAST"}

package/lib/node/session-bound-frontend-connection-service.js

@@ -0,0 +1,128 @@
+"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 __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionBoundFrontendConnectionService = void 0;
+exports.bindConnectionResilience = bindConnectionResilience;
+const backend_application_config_provider_1 = require("@theia/core/lib/node/backend-application-config-provider");
+const socket_write_buffer_1 = require("@theia/core/lib/common/messaging/socket-write-buffer");
+const websocket_frontend_connection_service_1 = require("@theia/core/lib/node/messaging/websocket-frontend-connection-service");
+const inversify_1 = require("@theia/core/shared/inversify");
+const framed_socket_write_buffer_1 = require("../common/framed-socket-write-buffer");
+/**
+ * Ignores a disconnect from a socket that no longer belongs to the frontend.
+ *
+ * A frontend that loses its network reconnects on a new socket within seconds;
+ * the server only notices the old one is gone when its next heartbeat write
+ * fails, which is a whole ping interval later. For that stretch both sockets are
+ * registered against the same session, and Theia's disconnect handler tears the
+ * session off its socket without checking which one just died. The late
+ * notification from the abandoned socket therefore cuts the healthy one loose.
+ * The frontend sees a connected socket and never retries, so the session is dead
+ * until the page is reloaded.
+ *
+ * Changed here: only the socket the session is currently using may act on a
+ * disconnect. The handler is rewritten rather than wrapped because the problem
+ * sits inside the listener Theia installs; the rest of the body is Theia's.
+ *
+ * Re-diff against Theia when the supported range moves: `override` catches a changed signature,
+ * not a changed body, so this copy can go stale in silence.
+ */
+let SessionBoundFrontendConnectionService = class SessionBoundFrontendConnectionService extends websocket_frontend_connection_service_1.WebsocketFrontendConnectionService {
+    /** Socket each frontend's channel is currently bound to, with the time it was bound. */
+    bindings = new Map();
+    /** When a frontend's live socket went away, so the reconnect gap can be reported. */
+    offlineSince = new Map();
+    handleSocketDisconnect(socket, channel, frontEndId) {
+        const previous = this.bindings.get(frontEndId);
+        this.bindings.set(frontEndId, { socketId: socket.id, boundAt: Date.now() });
+        const wentOfflineAt = this.offlineSince.get(frontEndId);
+        this.offlineSince.delete(frontEndId);
+        const replacing = previous ? `, replacing socket ${previous.socketId}` : '';
+        const gap = wentOfflineAt === undefined ? '' : `, after ${Date.now() - wentOfflineAt} ms offline`;
+        console.info(`${framed_socket_write_buffer_1.CONNECTION_LOG_PREFIX} frontend ${frontEndId} channel bound to socket ${socket.id}${replacing}${gap}`);
+        socket.on('disconnect', reason => {
+            const bound = this.bindings.get(frontEndId);
+            if (bound?.socketId !== socket.id) {
+                // Either a superseded socket being reaped late, or one outliving `closeConnection`, which
+                // deletes the binding. Neither owns the channel, so neither may disconnect it, arm a close
+                // timeout, or close a connection that is no longer in `connectionsByFrontend`.
+                const owner = bound
+                    ? `socket ${bound.socketId} owns it (bound ${Date.now() - bound.boundAt} ms ago)`
+                    : 'the connection is already closed';
+                console.info(`${framed_socket_write_buffer_1.CONNECTION_LOG_PREFIX} ignoring disconnect of stale socket ${socket.id} (frontend ${frontEndId}, ${reason}); ${owner}`);
+                return;
+            }
+            // From here on: Theia's own handler body, unchanged apart from naming the socket.
+            this.offlineSince.set(frontEndId, Date.now());
+            console.info(`${framed_socket_write_buffer_1.CONNECTION_LOG_PREFIX} socket ${socket.id} (frontend ${frontEndId}) disconnected: ${reason}`);
+            channel.disconnect();
+            const timeout = this.connectionTimeout();
+            const isMarkedForClose = this.channelsMarkedForClose.delete(frontEndId);
+            if (timeout === 0 || isMarkedForClose) {
+                this.closeConnection(frontEndId, reason);
+            }
+            else if (timeout > 0) {
+                console.info(`${framed_socket_write_buffer_1.CONNECTION_LOG_PREFIX} close timeout for frontend ${frontEndId} set to ${timeout} ms`);
+                this.closeTimeouts.set(frontEndId, setTimeout(() => this.closeConnection(frontEndId, reason), timeout));
+            }
+            // timeout < 0: never close the back end.
+        });
+    }
+    closeConnection(frontEndId, reason) {
+        console.info(`${framed_socket_write_buffer_1.CONNECTION_LOG_PREFIX} closing frontend ${frontEndId}: ${reason}`);
+        this.bindings.delete(frontEndId);
+        this.offlineSince.delete(frontEndId);
+        super.closeConnection(frontEndId, reason);
+    }
+    /** Mirrors Theia's private `frontendConnectionTimeout`, including `Number('')` resolving to 0.
+     *  Private there, so the copy is forced; re-diff it with the handler above. */
+    connectionTimeout() {
+        const envValue = Number(process.env['FRONTEND_CONNECTION_TIMEOUT']);
+        if (!isNaN(envValue)) {
+            return envValue;
+        }
+        return backend_application_config_provider_1.BackendApplicationConfigProvider.get().frontendConnectionTimeout;
+    }
+};
+exports.SessionBoundFrontendConnectionService = SessionBoundFrontendConnectionService;
+exports.SessionBoundFrontendConnectionService = SessionBoundFrontendConnectionService = __decorate([
+    (0, inversify_1.injectable)()
+], SessionBoundFrontendConnectionService);
+/**
+ * Replaces the server pieces that decide how a session survives a reconnect.
+ *
+ * `FrontendConnectionService` is bound `toService(WebsocketFrontendConnectionService)`,
+ * so rebinding the concrete class is enough. The buffer stays transient (one per
+ * connection), matching Theia's `bind(SocketWriteBuffer).toSelf()`; the frontend
+ * counterpart is bound by `bindConnectionResilience` in a `frontendPreload`
+ * module, which is the only point early enough on that side.
+ *
+ * Does nothing but warn on a Theia too old to expose the buffer binding, so the
+ * package keeps one supported range rather than splitting its floor for this
+ * feature. Returns whether the hardening was installed, for an adopter that
+ * wants to branch on it.
+ */
+function bindConnectionResilience(bind, isBound, rebind, options = {}) {
+    if (!(0, framed_socket_write_buffer_1.supportsConnectionResilience)(isBound)) {
+        (0, framed_socket_write_buffer_1.warnConnectionResilienceUnavailable)('backend');
+        return false;
+    }
+    bind(SessionBoundFrontendConnectionService).toSelf().inSingletonScope();
+    rebind(websocket_frontend_connection_service_1.WebsocketFrontendConnectionService).toService(SessionBoundFrontendConnectionService);
+    rebind(socket_write_buffer_1.SocketWriteBuffer).toDynamicValue(() => (0, framed_socket_write_buffer_1.createFramedSocketWriteBuffer)(options.bufferBytes));
+    return true;
+}
+//# sourceMappingURL=session-bound-frontend-connection-service.js.map

package/lib/node/session-bound-frontend-connection-service.js.map

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

package/lib/node/socket-channel-forwarder.d.ts

@@ -0,0 +1,54 @@
+/********************************************************************************
+ * 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 Clock } from '@hydranium/protocol';
+import { type Channel, Disposable, DisposableCollection, type MessageProvider } from '@theia/core';
+import type * as net from 'node:net';
+import { type Message, type MessageConnection } from 'vscode-jsonrpc/node';
+/**
+ * Relays JSON-RPC messages between a Theia browser-frontend {@link Channel} and
+ * a server's TCP socket — the backend half of a head's transport. The server
+ * speaks vscode-jsonrpc (Content-Length framed) on the socket; the frontend
+ * speaks the same protocol over the channel. This forwarder decodes each side
+ * and re-emits on the other.
+ *
+ * Behaves as `@eclipse-glsp/theia-integration`'s `SocketConnectionForwarder`
+ * does, and both heads use it, except that when the channel closes, the writes
+ * still queued go out before the socket ends. A page going away sends its last
+ * messages and closes its channel in the same tick, and the writer takes
+ * several turns per message, so destroying the socket on the close loses them.
+ */
+export declare class SocketChannelForwarder implements Disposable {
+    protected readonly channel: Channel;
+    protected readonly socket: net.Socket;
+    /** Times {@link flushTimeoutMs}. */
+    protected readonly clock: Clock;
+    protected readonly toDispose: DisposableCollection;
+    /** The last write to the socket; the writer runs its writes one at a time, so this settles last. */
+    protected lastWrite: Promise<void>;
+    /**
+     * How long {@link endSocket} waits for the queued writes before it destroys
+     * the socket anyway. Without a bound, a server that stops reading holds the
+     * socket open for good, and with it the server's end of the connection.
+     */
+    protected readonly flushTimeoutMs: number;
+    constructor(channel: Channel, socket: net.Socket, 
+    /** Times {@link flushTimeoutMs}. */
+    clock?: Clock);
+    /**
+     * Dispose `connection`, which destroys the socket, once the writes queued
+     * before the channel closed are out, or {@link flushTimeoutMs} has passed. A
+     * write has settled once the socket handed its bytes to the OS, and
+     * destroying the socket then loses nothing.
+     */
+    protected endSocket(connection: MessageConnection): Promise<void>;
+    protected decodeChannelMessage(provider: MessageProvider): Message;
+    protected writeToChannel(message: Message): void;
+    dispose(): void;
+}
+//# sourceMappingURL=socket-channel-forwarder.d.ts.map

package/lib/node/socket-channel-forwarder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-channel-forwarder.d.ts","sourceRoot":"","sources":["../../src/node/socket-channel-forwarder.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAe,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,KAAK,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,KAAK,KAAK,GAAG,MAAM,UAAU,CAAC;AACrC,OAAO,EAEJ,KAAK,OAAO,EACZ,KAAK,iBAAiB,EAGxB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAuB,YAAW,UAAU;IAYnD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO;IACnC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM;IACrC,oCAAoC;IACpC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK;IAdlC,SAAS,CAAC,QAAQ,CAAC,SAAS,uBAA8B;IAC1D,oGAAoG;IACpG,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAAqB;IACvD;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAU;gBAG7B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,GAAG,CAAC,MAAM;IACrC,oCAAoC;IACjB,KAAK,GAAE,KAAyB;IAyBtD;;;;;OAKG;cACa,SAAS,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvE,SAAS,CAAC,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO;IAKlE,SAAS,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAMhD,OAAO,IAAI,IAAI;CAGjB"}

package/lib/node/socket-channel-forwarder.js

@@ -0,0 +1,93 @@
+"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.SocketChannelForwarder = void 0;
+const protocol_1 = require("@hydranium/protocol");
+const core_1 = require("@theia/core");
+const node_1 = require("vscode-jsonrpc/node");
+/**
+ * Relays JSON-RPC messages between a Theia browser-frontend {@link Channel} and
+ * a server's TCP socket — the backend half of a head's transport. The server
+ * speaks vscode-jsonrpc (Content-Length framed) on the socket; the frontend
+ * speaks the same protocol over the channel. This forwarder decodes each side
+ * and re-emits on the other.
+ *
+ * Behaves as `@eclipse-glsp/theia-integration`'s `SocketConnectionForwarder`
+ * does, and both heads use it, except that when the channel closes, the writes
+ * still queued go out before the socket ends. A page going away sends its last
+ * messages and closes its channel in the same tick, and the writer takes
+ * several turns per message, so destroying the socket on the close loses them.
+ */
+class SocketChannelForwarder {
+    channel;
+    socket;
+    clock;
+    toDispose = new core_1.DisposableCollection();
+    /** The last write to the socket; the writer runs its writes one at a time, so this settles last. */
+    lastWrite = Promise.resolve();
+    /**
+     * How long {@link endSocket} waits for the queued writes before it destroys
+     * the socket anyway. Without a bound, a server that stops reading holds the
+     * socket open for good, and with it the server's end of the connection.
+     */
+    flushTimeoutMs = 10_000;
+    constructor(channel, socket, 
+    /** Times {@link flushTimeoutMs}. */
+    clock = new protocol_1.SystemClock()) {
+        this.channel = channel;
+        this.socket = socket;
+        this.clock = clock;
+        const reader = new node_1.SocketMessageReader(socket);
+        const writer = new node_1.SocketMessageWriter(socket);
+        const connection = (0, node_1.createMessageConnection)(reader, writer);
+        // Nothing here destroys the socket directly. `SocketMessageWriter.dispose()`
+        // destroys it itself, which covers both `dispose` and `endSocket`; and
+        // `connection.onClose` fires only from the reader's or writer's own close,
+        // which for a socket means the socket has already gone — so a destroy
+        // handler there is downstream of the effect it would be trying to cause.
+        this.toDispose.pushAll([
+            reader.listen(message => this.writeToChannel(message)),
+            channel.onMessage(provider => {
+                // A failed write means the socket is gone, which its own close reports.
+                this.lastWrite = writer.write(this.decodeChannelMessage(provider)).catch(() => undefined);
+            }),
+            channel.onClose(() => void this.endSocket(connection)),
+            connection.onClose(() => channel.close()),
+            core_1.Disposable.create(() => {
+                channel.close();
+                connection.dispose();
+            })
+        ]);
+    }
+    /**
+     * Dispose `connection`, which destroys the socket, once the writes queued
+     * before the channel closed are out, or {@link flushTimeoutMs} has passed. A
+     * write has settled once the socket handed its bytes to the OS, and
+     * destroying the socket then loses nothing.
+     */
+    async endSocket(connection) {
+        await this.clock.raceTimer(this.lastWrite, this.flushTimeoutMs);
+        connection.dispose();
+    }
+    decodeChannelMessage(provider) {
+        const buffer = provider().readBytes();
+        return JSON.parse(new TextDecoder().decode(buffer));
+    }
+    writeToChannel(message) {
+        const writeBuffer = this.channel.getWriteBuffer();
+        writeBuffer.writeBytes(new TextEncoder().encode(JSON.stringify(message)));
+        writeBuffer.commit();
+    }
+    dispose() {
+        this.toDispose.dispose();
+    }
+}
+exports.SocketChannelForwarder = SocketChannelForwarder;
+//# sourceMappingURL=socket-channel-forwarder.js.map

package/lib/node/socket-channel-forwarder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-channel-forwarder.js","sourceRoot":"","sources":["../../src/node/socket-channel-forwarder.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,kDAA8D;AAC9D,sCAAmG;AAEnG,8CAM6B;AAE7B;;;;;;;;;;;;GAYG;AACH,MAAa,sBAAsB;IAYV;IACA;IAEA;IAdH,SAAS,GAAG,IAAI,2BAAoB,EAAE,CAAC;IAC1D,oGAAoG;IAC1F,SAAS,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IACvD;;;;OAIG;IACgB,cAAc,GAAW,MAAM,CAAC;IAEnD,YACsB,OAAgB,EAChB,MAAkB;IACrC,oCAAoC;IACjB,QAAe,IAAI,sBAAW,EAAE;QAHhC,YAAO,GAAP,OAAO,CAAS;QAChB,WAAM,GAAN,MAAM,CAAY;QAElB,UAAK,GAAL,KAAK,CAA2B;QAEnD,MAAM,MAAM,GAAG,IAAI,0BAAmB,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,0BAAmB,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,UAAU,GAAG,IAAA,8BAAuB,EAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC3D,6EAA6E;QAC7E,uEAAuE;QACvE,2EAA2E;QAC3E,sEAAsE;QACtE,yEAAyE;QACzE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;YACtD,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE;gBAC1B,wEAAwE;gBACxE,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC7F,CAAC,CAAC;YACF,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;YACtD,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACzC,iBAAU,CAAC,MAAM,CAAC,GAAG,EAAE;gBACpB,OAAO,CAAC,KAAK,EAAE,CAAC;gBAChB,UAAU,CAAC,OAAO,EAAE,CAAC;YACxB,CAAC,CAAC;SACJ,CAAC,CAAC;IACN,CAAC;IAED;;;;;OAKG;IACO,KAAK,CAAC,SAAS,CAAC,UAA6B;QACpD,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QAChE,UAAU,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;IAES,oBAAoB,CAAC,QAAyB;QACrD,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAY,CAAC;IAClE,CAAC;IAES,cAAc,CAAC,OAAgB;QACtC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;QAClD,WAAW,CAAC,UAAU,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC1E,WAAW,CAAC,MAAM,EAAE,CAAC;IACxB,CAAC;IAED,OAAO;QACJ,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;CACH;AAjED,wDAiEC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/client-theia",
-  "version": "1.0.0-next.13",
+  "version": "1.0.0-next.135",
   "description": "Cross-head Theia client primitives shared by the hydranium protocol heads. Provides the socket-forwarding connection-handler base that the data-server and GLSP Theia integrations subclass, plus the preference-driven Output-channel logger; carries no head-specific dependency.",
   "keywords": [
     "hydranium",
@@ -36,6 +36,14 @@
       "types": "./lib/browser/index.d.ts",
       "default": "./lib/browser/index.js"
     },
+    "./common": {
+      "types": "./lib/common/index.d.ts",
+      "default": "./lib/common/index.js"
+    },
+    "./lib/common": {
+      "types": "./lib/common/index.d.ts",
+      "default": "./lib/common/index.js"
+    },
     "./node": {
       "types": "./lib/node/index.d.ts",
       "default": "./lib/node/index.js"
@@ -70,20 +78,26 @@
     "watch": "tsc -b -w --preserveWatchOutput"
   },
   "devDependencies": {
-    "@hydranium/protocol": "1.0.0-next.13",
-    "@theia/core": "^1.71.0",
-    "@theia/output": "^1.71.0",
+    "@hydranium/protocol": "1.0.0-next.135",
+    "@theia/core": "^1.70.0",
+    "@theia/editor": "^1.70.0",
+    "@theia/filesystem": "^1.70.0",
+    "@theia/output": "^1.70.0",
     "@types/node": "^22.0.0",
     "inversify": "6.2.2",
     "reflect-metadata": "0.2.2",
     "rimraf": "^5.0.0",
-    "typescript": "^5.8.0"
+    "typescript": "^5.8.0",
+    "vscode-jsonrpc": "9.0.1"
   },
   "peerDependencies": {
-    "@hydranium/protocol": "1.0.0-next.13",
-    "@theia/core": "^1.71.0",
-    "@theia/output": "^1.71.0",
-    "inversify": "^6.0.0"
+    "@hydranium/protocol": "1.0.0-next.135",
+    "@theia/core": "^1.70.0",
+    "@theia/editor": "^1.70.0",
+    "@theia/filesystem": "^1.70.0",
+    "@theia/output": "^1.70.0",
+    "inversify": "^6.0.0",
+    "vscode-jsonrpc": "9.0.1"
   },
   "engines": {
     "node": ">=22.13"
@@ -91,5 +105,6 @@
   "publishConfig": {
     "access": "public"
   },
+  "//peerDependencies": "@theia/core stays at 1.70 here, matching the sibling Theia packages, even though the connection-resilience bindings need 1.71: Theia only began binding `SocketWriteBuffer` then, and before that each connection built one privately, so there is no binding to rebind. Rather than split the package's floor for one feature, `bindConnectionResilience` probes for that binding and warns instead of installing when it is absent — a capability check rather than a version parse, so it answers about the container in front of it. Everything else the feature touches exists at 1.70, and the emitted declarations deliberately name no type that 1.70 lacks, so the package still compiles there. Verified by unpacking 1.70, 1.71 and 1.72, not inferred from a changelog. `vscode-jsonrpc` is EXACT because it is one link of an atomic chain: `vscode-languageserver-protocol` depends on it at exactly 9.0.1, so any other value is a second physical copy, and this wire stack breaks on copy identity.",
   "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error."
 }

package/src/browser/channel-logger.ts

@@ -10,6 +10,7 @@
 import { AbstractLogger, DefaultTracer, type LogLevel, type MemoryReader, SystemClock } from '@hydranium/protocol';
 import { injectable, type interfaces, unmanaged, inject } from '@theia/core/shared/inversify';
 import { type OutputChannel, OutputChannelManager } from '@theia/output/lib/browser/output-channel';
+import { Clock } from '../common/clock';
 
 /**
  * Configuration for a {@link ChannelLogger}, supplied once at bind time via
@@ -94,9 +95,10 @@ const ChannelLoggerBase = Symbol('ChannelLoggerBase');
 
 /**
  * Inversify token for the browser `Tracer` — a {@link DefaultTracer} over
- * the {@link ChannelLogger} (emit sink) + a {@link SystemClock} + a browser
- * heap reader. The browser head has no Langium `services.Tracer` slot, so this
- * is how frontend services that time obtain a tracer: `@inject(ChannelTracer)`.
+ * the {@link ChannelLogger} (emit sink) + the container's {@link Clock}, or a
+ * `SystemClock` when it binds none, + a browser heap reader. The browser head
+ * has no Langium `services.Tracer` slot, so this is how frontend services that
+ * time obtain a tracer: `@inject(ChannelTracer)`.
  * Bound by {@link bindChannelLogger}.
  */
 export const ChannelTracer = Symbol('ChannelTracer');
@@ -134,7 +136,10 @@ export function bindChannelLogger(bind: interfaces.Bind, options: ChannelLoggerO
       return parentName ? base.for(parentName) : base;
    });
    bind(ChannelTracer)
-      .toDynamicValue(ctx => new DefaultTracer(ctx.container.get<ChannelLogger>(ChannelLoggerBase), new SystemClock(), readBrowserMemory))
+      .toDynamicValue(ctx => {
+         const clock = ctx.container.isBound(Clock) ? ctx.container.get<Clock>(Clock) : new SystemClock();
+         return new DefaultTracer(ctx.container.get<ChannelLogger>(ChannelLoggerBase), clock, readBrowserMemory);
+      })
       .inSingletonScope();
 }
 

package/src/browser/connection-diagnostics-contribution.ts

@@ -0,0 +1,142 @@
+/********************************************************************************
+ * 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 { MessageService, nls } from '@theia/core';
+import { FrontendApplicationContribution } from '@theia/core/lib/browser/frontend-application-contribution';
+import { ConnectionStatus, ConnectionStatusService } from '@theia/core/lib/browser/connection-status-service';
+import { WebSocketConnectionSource } from '@theia/core/lib/browser/messaging/ws-connection-source';
+import { inject, injectable, type interfaces } from '@theia/core/shared/inversify';
+import { type ConnectionBufferOverflow } from '../common/framed-socket-write-buffer';
+import { ChannelLogger } from './channel-logger';
+import { SessionAwareConnectionSource } from './session-aware-connection-source';
+
+/**
+ * Records the browser side of the websocket lifecycle into the adopter's Output
+ * channel, and tells the user the one thing they cannot recover from on their
+ * own.
+ *
+ * Theia reports an outage only as an "Offline" status-bar item, which cannot
+ * distinguish a plain network drop from the server having stopped answering on a
+ * socket that is still up. The latter is what a connection defect looks like
+ * from here, so the two are logged differently — that distinction is what says
+ * whether reopening an editor helps or only a reload does.
+ *
+ * Purely observational apart from the overflow message: nothing here changes how
+ * the connection behaves.
+ */
+@injectable()
+export class ConnectionDiagnosticsContribution implements FrontendApplicationContribution {
+   @inject(WebSocketConnectionSource) protected readonly connectionSource: WebSocketConnectionSource;
+   @inject(ConnectionStatusService) protected readonly connectionStatus: ConnectionStatusService;
+   @inject(ChannelLogger) protected readonly logger: ChannelLogger;
+   @inject(MessageService) protected readonly messageService: MessageService;
+
+   /** Main channels created so far; more than one means the server did not recognise this frontend. */
+   protected channelCount = 0;
+   protected socketClosedAt?: number;
+   protected offlineAt?: number;
+
+   initialize(): void {
+      this.connectionSource.onSocketDidOpen(() => this.handleSocketOpen());
+      this.connectionSource.onSocketDidClose(() => this.handleSocketClose());
+      this.connectionSource.onConnectionDidOpen(() => this.handleChannelOpen());
+      this.connectionStatus.onStatusChange(status => this.handleStatusChange(status));
+      if (this.connectionSource instanceof SessionAwareConnectionSource) {
+         this.connectionSource.onBufferOverflow(overflow => this.handleBufferOverflow(overflow));
+      }
+      // The socket is opened by the preloader, before this contribution exists, so the first
+      // `onSocketDidOpen` has already fired; state the current situation instead.
+      this.logger.info(`diagnostics active; socket ${this.socketId()}, backend ${this.statusName(this.connectionStatus.currentStatus)}`);
+   }
+
+   protected handleSocketOpen(): void {
+      const downFor = this.socketClosedAt === undefined ? '' : ` after ${Date.now() - this.socketClosedAt} ms down`;
+      this.socketClosedAt = undefined;
+      this.logger.info(`websocket connected: socket ${this.socketId()}${downFor}`);
+   }
+
+   protected handleSocketClose(): void {
+      this.socketClosedAt = Date.now();
+      this.logger.info(`websocket disconnected: socket ${this.socketId()}; outgoing messages are buffered until it returns`);
+   }
+
+   /**
+    * A second channel means the reconnect was refused and the session discarded.
+    * Only reachable with `reloadOnReconnect` off — with it on, Theia reloads the
+    * page instead of opening another channel.
+    */
+   protected handleChannelOpen(): void {
+      this.channelCount++;
+      if (this.channelCount === 1) {
+         this.logger.info(`initial channel opened on socket ${this.socketId()}`);
+         return;
+      }
+      this.logger.warn(
+         `new channel #${this.channelCount} on socket ${this.socketId()}: the backend did not recognise this frontend, ` +
+            'so its session was discarded and every pending request rejected'
+      );
+   }
+
+   protected handleStatusChange(status: ConnectionStatus): void {
+      if (status === ConnectionStatus.ONLINE) {
+         const offlineFor = this.offlineAt === undefined ? '' : ` after ${Date.now() - this.offlineAt} ms`;
+         this.offlineAt = undefined;
+         this.logger.info(`backend reachable again${offlineFor}`);
+         return;
+      }
+      this.offlineAt = Date.now();
+      const socket = this.connectionSource.socket;
+      if (socket?.connected) {
+         this.logger.warn(
+            `backend stopped answering while socket ${socket.id} is still connected: nothing this session sends will ` +
+               'arrive, and socket.io will not reconnect on its own. Reload the page to recover.'
+         );
+         return;
+      }
+      this.logger.info(`backend unreachable; websocket is disconnected (socket ${this.socketId()})`);
+   }
+
+   /**
+    * The outage outlasted what the buffer can hold, so changes made from here on
+    * are being thrown away rather than queued. Reconnecting resumes sending but
+    * cannot bring those back, which leaves the editor disagreeing with the
+    * server — and without a message the user would see nothing but an editor
+    * that has quietly stopped saving, so say it plainly.
+    */
+   protected handleBufferOverflow(overflow: ConnectionBufferOverflow): void {
+      this.logger.error(`buffer full at ${overflow.maxBytes} bytes holding ${overflow.messages} message(s)`);
+      this.messageService.error(
+         nls.localize(
+            'hydranium/connection/offlineLimitReached',
+            'Disconnected for too long: recent changes were not sent. Reload the page before continuing.'
+         )
+      );
+   }
+
+   protected socketId(): string {
+      return this.connectionSource.socket?.id ?? WebSocketConnectionSource.NO_CONNECTION;
+   }
+
+   protected statusName(status: ConnectionStatus): string {
+      return status === ConnectionStatus.ONLINE ? 'online' : 'offline';
+   }
+}
+
+/**
+ * Bind {@link ConnectionDiagnosticsContribution} as a `FrontendApplicationContribution`.
+ *
+ * Needs a {@link ChannelLogger} binding, so call it from a module that has also
+ * called `bindChannelLogger`. Unlike `bindConnectionResilience` this belongs in a
+ * normal frontend module: it only observes, so it has no reason to run during
+ * preload, and `MessageService` is not available that early.
+ */
+export function bindConnectionDiagnostics(bind: interfaces.Bind): void {
+   bind(ConnectionDiagnosticsContribution).toSelf().inSingletonScope();
+   bind(FrontendApplicationContribution).toService(ConnectionDiagnosticsContribution);
+}