@hydranium/client-theia 1.0.0-next.9 → 1.0.0-next.90

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":";AAAA;;;;;;;kFAOkF;;;;;;;;;AAqIlF,4DAcC;AAjJD,kHAA4G;AAC5G,8FAAyF;AACzF,gIAA0H;AAC1H,4DAA2E;AAE3E,qFAK8C;AAqB9C;;;;;;;;;;;;;;;;;;GAkBG;AAEI,IAAM,qCAAqC,GAA3C,MAAM,qCAAsC,SAAQ,0EAAkC;IAC1F,wFAAwF;IACrE,QAAQ,GAAG,IAAI,GAAG,EAAiD,CAAC;IACvF,qFAAqF;IAClE,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEnD,sBAAsB,CAAC,MAAsB,EAAE,OAAwB,EAAE,UAAkB;QACjG,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC/C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAE5E,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACxD,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACrC,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,sBAAsB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,MAAM,GAAG,GAAG,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,GAAG,aAAa,aAAa,CAAC;QAClG,OAAO,CAAC,IAAI,CAAC,GAAG,kDAAM,aAAa,UAAU,4BAA4B,MAAM,CAAC,EAAE,GAAG,SAAS,GAAG,GAAG,EAAE,CAAC,CAAC;QAExG,MAAM,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC,EAAE;YAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC5C,IAAI,KAAK,EAAE,QAAQ,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC;gBACjC,0FAA0F;gBAC1F,2FAA2F;gBAC3F,+EAA+E;gBAC/E,MAAM,KAAK,GAAG,KAAK;oBAChB,CAAC,CAAC,UAAU,KAAK,CAAC,QAAQ,mBAAmB,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,OAAO,UAAU;oBACjF,CAAC,CAAC,kCAAkC,CAAC;gBACxC,OAAO,CAAC,IAAI,CAAC,GAAG,kDAAM,wCAAwC,MAAM,CAAC,EAAE,cAAc,UAAU,KAAK,MAAM,MAAM,KAAK,EAAE,CAAC,CAAC;gBACzH,OAAO;YACV,CAAC;YAED,kFAAkF;YAClF,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YAC9C,OAAO,CAAC,IAAI,CAAC,GAAG,kDAAM,WAAW,MAAM,CAAC,EAAE,cAAc,UAAU,mBAAmB,MAAM,EAAE,CAAC,CAAC;YAC/F,OAAO,CAAC,UAAU,EAAE,CAAC;YACrB,MAAM,OAAO,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACzC,MAAM,gBAAgB,GAAG,IAAI,CAAC,sBAAsB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACxE,IAAI,OAAO,KAAK,CAAC,IAAI,gBAAgB,EAAE,CAAC;gBACrC,IAAI,CAAC,eAAe,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;YAC5C,CAAC;iBAAM,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;gBACtB,OAAO,CAAC,IAAI,CAAC,GAAG,kDAAM,+BAA+B,UAAU,WAAW,OAAO,KAAK,CAAC,CAAC;gBACxF,IAAI,CAAC,aAAa,CAAC,GAAG,CACnB,UAAU,EACV,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,UAAU,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CACrE,CAAC;YACL,CAAC;YACD,yCAAyC;QAC5C,CAAC,CAAC,CAAC;IACN,CAAC;IAEkB,eAAe,CAAC,UAAkB,EAAE,MAAc;QAClE,OAAO,CAAC,IAAI,CAAC,GAAG,kDAAM,qBAAqB,UAAU,KAAK,MAAM,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACjC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACrC,KAAK,CAAC,eAAe,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED;mFAC+E;IACrE,iBAAiB;QACxB,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC,CAAC;QACpE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YACpB,OAAO,QAAQ,CAAC;QACnB,CAAC;QACD,OAAO,sEAAgC,CAAC,GAAG,EAAE,CAAC,yBAAyB,CAAC;IAC3E,CAAC;CACH,CAAA;AAhEY,sFAAqC;gDAArC,qCAAqC;IADjD,IAAA,sBAAU,GAAE;GACA,qCAAqC,CAgEjD;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,wBAAwB,CACrC,IAAqB,EACrB,OAA2B,EAC3B,MAAyB,EACzB,UAAuC,EAAE;IAEzC,IAAI,CAAC,IAAA,yDAA4B,EAAC,OAAO,CAAC,EAAE,CAAC;QAC1C,IAAA,gEAAmC,EAAC,SAAS,CAAC,CAAC;QAC/C,OAAO,KAAK,CAAC;IAChB,CAAC;IACD,IAAI,CAAC,qCAAqC,CAAC,CAAC,MAAM,EAAE,CAAC,gBAAgB,EAAE,CAAC;IACxE,MAAM,CAAC,0EAAkC,CAAC,CAAC,SAAS,CAAC,qCAAqC,CAAC,CAAC;IAC5F,MAAM,CAAC,uCAAiB,CAAC,CAAC,cAAc,CAAC,GAAG,EAAE,CAAC,IAAA,0DAA6B,EAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACnG,OAAO,IAAI,CAAC;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/client-theia",
-  "version": "1.0.0-next.9",
+  "version": "1.0.0-next.90",
   "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,9 +78,9 @@
     "watch": "tsc -b -w --preserveWatchOutput"
   },
   "devDependencies": {
-    "@hydranium/protocol": "1.0.0-next.9",
-    "@theia/core": "^1.71.0",
-    "@theia/output": "^1.71.0",
+    "@hydranium/protocol": "1.0.0-next.90",
+    "@theia/core": "^1.70.0",
+    "@theia/output": "^1.70.0",
     "@types/node": "^22.0.0",
     "inversify": "6.2.2",
     "reflect-metadata": "0.2.2",
@@ -80,9 +88,9 @@
     "typescript": "^5.8.0"
   },
   "peerDependencies": {
-    "@hydranium/protocol": "1.0.0-next.9",
-    "@theia/core": "^1.71.0",
-    "@theia/output": "^1.71.0",
+    "@hydranium/protocol": "1.0.0-next.90",
+    "@theia/core": "^1.70.0",
+    "@theia/output": "^1.70.0",
     "inversify": "^6.0.0"
   },
   "engines": {
@@ -91,5 +99,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.",
   "//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/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);
+}

package/src/browser/index.ts

@@ -12,3 +12,5 @@ export * from './channel-logger';
 export * from './log-level-preference';
 export * from './browser-capture';
 export * from './memory-diagnostics-contribution';
+export * from './session-aware-connection-source';
+export * from './connection-diagnostics-contribution';

package/src/browser/log-level-preference.ts

@@ -108,7 +108,18 @@ export class LogLevelPreferenceContribution implements FrontendApplicationContri
    protected applyLevel(): void {
       const level = parseLogLevel(this.preferences.get<string>(this.preferenceName));
       if (level) {
+         const previous = Logger.getLevel();
          Logger.setLevel(level);
+         if (previous !== level) {
+            // Through Theia's `ILogger`, which has a threshold of its own and so
+            // is not silenced by the value just applied — the framework logger
+            // this preference governs would drop the line on a switch to `error`.
+            //
+            // Frontend and server announce separately: this preference reaches
+            // the server only if a client delivers it as configuration, so one
+            // line without the other says it did not.
+            this.logger.info(`Log level ${previous} → ${level} (preference '${this.preferenceName}')`);
+         }
       }
    }
 }