@hydranium/client-theia 1.0.0-next.7 → 1.0.0-next.71

package/src/browser/session-aware-connection-source.ts

@@ -0,0 +1,179 @@
+/********************************************************************************
+ * 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 { WebSocketConnectionSource } from '@theia/core/lib/browser/messaging/ws-connection-source';
+import { Disposable, DisposableCollection } from '@theia/core/lib/common/disposable';
+import { type Event } from '@theia/core/lib/common/event';
+import { type AbstractChannel, ForwardingChannel } from '@theia/core/lib/common/message-rpc/channel';
+import { Uint8ArrayReadBuffer, Uint8ArrayWriteBuffer } from '@theia/core/lib/common/message-rpc/uint8-array-message-buffer';
+import { ConnectionManagementMessages } from '@theia/core/lib/common/messaging/connection-management';
+import { injectable, type interfaces } from '@theia/core/shared/inversify';
+import { SocketWriteBuffer } from '@theia/core/lib/common/messaging/socket-write-buffer';
+import { type ConnectionResilienceOptions } from '../common/connection-resilience-options';
+import {
+   type ConnectionBufferOverflow,
+   createFramedSocketWriteBuffer,
+   FramedSocketWriteBuffer,
+   supportsConnectionResilience,
+   warnConnectionResilienceUnavailable
+} from '../common/framed-socket-write-buffer';
+
+/**
+ * Sends a message only once the server has confirmed the session, and only
+ * behind anything already queued.
+ *
+ * Theia sends straight away when `socket.connected` is true and buffers
+ * otherwise. The gap is that reconnecting sets that flag immediately, while the
+ * session is only confirmed a round trip later. A message produced in that
+ * window either jumps ahead of older messages still waiting in the buffer, or,
+ * if nothing was waiting, goes out on a socket whose channel the server has not
+ * attached yet and is discarded by a peer with no listener for it.
+ *
+ * Losing one or reordering them is equally unrecoverable for anything that
+ * applies messages by position. Theia's plugin host keeps a line-indexed copy of
+ * every open document, so a single late or missing edit leaves that copy wrong
+ * for good, and the next edit past its end fails.
+ *
+ * The server side needs no equivalent: it adopts its socket and flushes in one
+ * synchronous step, so it has no window of this kind.
+ */
+@injectable()
+export class SessionAwareConnectionSource extends WebSocketConnectionSource {
+   /**
+    * Whether the server has confirmed, on the socket in use right now, that it
+    * still holds this frontend's session. A connected socket is not enough:
+    * until the handshake is answered the server has not attached its channel to
+    * this socket, and a message sent meanwhile reaches a peer with no listener
+    * for it and is discarded without a trace.
+    */
+   protected sessionResumed = false;
+   protected sessionListenersAttached = false;
+
+   /**
+    * Every connect starts a socket the server has not confirmed yet, including
+    * the reconnects socket.io performs on its own. Resetting here rather than on
+    * disconnect also covers a connect that follows no clean disconnect event.
+    */
+   protected override handleSocketConnected(): void {
+      this.trackSessionState();
+      this.sessionResumed = false;
+      super.handleSocketConnected();
+   }
+
+   /**
+    * Watches the connection handshake for its outcome.
+    *
+    * Attached once, to the socket socket.io reuses across reconnects, and before
+    * the base class adds its own per-negotiation listeners — so this has already
+    * recorded the outcome by the time the base class reacts to it by flushing.
+    */
+   protected trackSessionState(): void {
+      if (this.sessionListenersAttached) {
+         return;
+      }
+      this.sessionListenersAttached = true;
+      this.socket.on(ConnectionManagementMessages.INITIAL_CONNECT, () => {
+         this.sessionResumed = true;
+      });
+      this.socket.on(ConnectionManagementMessages.RECONNECT, (hasConnection: boolean) => {
+         this.sessionResumed = hasConnection;
+      });
+   }
+
+   /** Whether a message may go out now, as opposed to waiting in the buffer. */
+   protected get canSend(): boolean {
+      return this.socket.connected && this.sessionResumed;
+   }
+
+   /**
+    * Copied from Theia apart from the `onCommit` body, because the base builds that callback inline
+    * and exposes no narrower seam. Re-diff when the supported range moves.
+    */
+   protected override createChannel(): AbstractChannel {
+      const toDispose = new DisposableCollection();
+      const messageHandler = (data: ArrayBuffer | Uint8Array): void => {
+         this.onIncomingMessageActivityEmitter.fire();
+         if (this.currentChannel) {
+            // socket.io hands binary over as ArrayBuffer in the browser.
+            const buffer = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+            this.currentChannel.onMessageEmitter.fire(() => new Uint8ArrayReadBuffer(buffer));
+         }
+      };
+      this.socket.on('message', messageHandler);
+      toDispose.push(Disposable.create(() => this.socket.off('message', messageHandler)));
+
+      return new ForwardingChannel(
+         'any',
+         () => toDispose.dispose(),
+         () => {
+            const result = new Uint8ArrayWriteBuffer();
+            // Says only whether the session can carry a message; the buffer decides whether it may
+            // go ahead of anything already waiting.
+            result.onCommit(buffer => this.framedBuffer.sendOrQueue(this.canSend ? this.socket : undefined, buffer));
+            return result;
+         }
+      );
+   }
+
+   /** Fires when the buffer runs out of room, so an adopter can say so rather than just stopping. */
+   get onBufferOverflow(): Event<ConnectionBufferOverflow> {
+      return this.framedBuffer.onOverflow;
+   }
+
+   /**
+    * The write buffer Theia injected into the base class.
+    *
+    * Reached through a structural view rather than as `this.writeBuffer`,
+    * because that member is `private` in Theia 1.70 and only became `protected`
+    * in 1.71 — and this package compiles against the whole range. The view
+    * asserts nothing the versions disagree about: the field is there in both,
+    * holding whatever `SocketWriteBuffer` is bound, and the check below is what
+    * establishes it is ours.
+    */
+   protected get framedBuffer(): FramedSocketWriteBuffer {
+      const buffer = (this as unknown as { readonly writeBuffer: SocketWriteBuffer }).writeBuffer;
+      if (!(buffer instanceof FramedSocketWriteBuffer)) {
+         throw new Error('SessionAwareConnectionSource requires FramedSocketWriteBuffer to be bound');
+      }
+      return buffer;
+   }
+}
+
+/**
+ * Replaces the frontend pieces that decide how outgoing messages survive a
+ * reconnect. Every one of them rebinds something Theia's
+ * `messagingFrontendModule` already bound, so this belongs in a module loaded
+ * into the same container.
+ *
+ * It must be a `frontendPreload` module rather than a normal frontend module:
+ * Theia's preloader resolves `WebSocketConnectionSource` (and with it the write
+ * buffer) while loading i18n and OS settings, which happens before any frontend
+ * module is loaded. A rebind there would come too late — the instances would
+ * already exist. All `frontendPreload` modules, by contrast, are loaded before
+ * the preloader constructs anything.
+ *
+ * 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 function bindConnectionResilience(
+   isBound: interfaces.IsBound,
+   rebind: interfaces.Rebind,
+   options: ConnectionResilienceOptions = {}
+): boolean {
+   if (!supportsConnectionResilience(isBound)) {
+      warnConnectionResilienceUnavailable('frontend');
+      return false;
+   }
+   // Scopes are kept as Theia declares them: one buffer per connection source, one shared socket owner.
+   rebind(SocketWriteBuffer).toDynamicValue(() => createFramedSocketWriteBuffer(options.bufferBytes));
+   rebind(WebSocketConnectionSource).to(SessionAwareConnectionSource).inSingletonScope();
+   return true;
+}

package/src/common/connection-resilience-options.ts

@@ -0,0 +1,24 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Options for the `bindConnectionResilience` helper each tier exports.
+ *
+ * Lives in `common` rather than beside either helper so the server entry can
+ * name the type without importing the browser module, and the other way round.
+ */
+export interface ConnectionResilienceOptions {
+   /**
+    * Size of the buffer holding messages while the socket is down, in bytes.
+    * Defaults to Theia's own limit. It decides how long an outage can last
+    * before changes start being rejected, so a deployment on a poor network
+    * trades memory for tolerance here.
+    */
+   readonly bufferBytes?: number;
+}

package/src/common/framed-socket-write-buffer.ts

@@ -0,0 +1,227 @@
+/********************************************************************************
+ * 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 { Emitter, type Event } from '@theia/core/lib/common/event';
+import { SocketWriteBuffer } from '@theia/core/lib/common/messaging/socket-write-buffer';
+
+/**
+ * Prefix on every connection log line, deliberately shared by the browser and the
+ * server so one pattern greps a console and a pod log at once.
+ */
+export const CONNECTION_LOG_PREFIX = '[connection]';
+
+/**
+ * The part of a socket this buffer uses. Narrower than the socket type Theia
+ * declares, which keeps the dependency honest and lets the class be tested
+ * without a connection.
+ */
+export interface MessageSink {
+   send(data: Uint8Array): void;
+}
+
+/**
+ * Reported when the buffer runs out of room. The message that did not fit is
+ * rejected, and so is every further one for as long as the buffer stays full.
+ * Reconnecting drains it and sending resumes, but whatever was rejected
+ * meanwhile is gone, so the two sides no longer agree about the session.
+ */
+export interface ConnectionBufferOverflow {
+   /** Messages held when the limit was reached. */
+   readonly messages: number;
+   /** Bytes held when the limit was reached. */
+   readonly bytes: number;
+   /** The limit in force, so a reader can tell what to raise it to. */
+   readonly maxBytes: number;
+}
+
+/**
+ * Holds messages while the peer is away and re-sends them when it returns.
+ *
+ * Theia copies them into one growing byte array and flushes that with a single
+ * `send`. A websocket delivers whole messages rather than a byte stream, so
+ * Theia's encoding adds no length prefix and every reader assumes one delivery
+ * is one message. The concatenated flush breaks that assumption: the reader
+ * decodes the first message and throws away the bytes behind it.
+ *
+ * Changed here: one entry per message, sent one at a time, so each arrives as
+ * its own delivery. The buffer also decides whether a message may go out
+ * directly — see {@link sendOrQueue} — because a caller that decides for itself
+ * is how messages end up overtaking a backlog.
+ *
+ * Unchanged from Theia: exceeding the limit rejects the message rather than
+ * dropping something silently. The limit is settable, since the right value
+ * depends on how long an outage has to survive.
+ *
+ * Logging goes to `console` rather than through a `Logger`. On the browser side
+ * Theia's preloader builds this before any Output channel exists, so there is
+ * nothing else to write to; the {@link CONNECTION_LOG_PREFIX} keeps the lines
+ * findable on both sides.
+ */
+export class FramedSocketWriteBuffer extends SocketWriteBuffer {
+   /** Theia's fixed limit, kept as the default. */
+   static readonly DEFAULT_MAX_BYTES = 100 * 1024;
+
+   /**
+    * Settable so a deployment can trade memory for longer outages.
+    *
+    * Consulted directly rather than through the base class's `maxBufferSize`,
+    * which does not exist before Theia 1.71 — an `override` of it would not
+    * compile against the oldest release this package supports. Nothing is lost:
+    * `buffer`, `flush` and `drain` are all replaced here, so the base's own
+    * limit is never reached.
+    */
+   maxBytes = FramedSocketWriteBuffer.DEFAULT_MAX_BYTES;
+
+   protected pending: Uint8Array[] = [];
+   protected pendingBytes = 0;
+   protected overflowReported = false;
+   protected readonly onOverflowEmitter = new Emitter<ConnectionBufferOverflow>();
+
+   /** Fires once per outage when the limit is reached. */
+   get onOverflow(): Event<ConnectionBufferOverflow> {
+      return this.onOverflowEmitter.event;
+   }
+
+   /**
+    * Sends `data` now only if nothing is waiting, and queues it otherwise.
+    *
+    * Callers say whether the peer is ready for a message; the buffer decides
+    * whether it may go ahead of one already waiting. Splitting it this way is
+    * the point: a caller that answers both questions from one flag is how a
+    * fresh message ends up overtaking a backlog.
+    */
+   sendOrQueue(socket: MessageSink | undefined, data: Uint8Array): void {
+      if (socket && !this.hasBacklog) {
+         socket.send(data);
+      } else {
+         this.buffer(data);
+      }
+   }
+
+   override buffer(data: Uint8Array): void {
+      if (this.pendingBytes + data.byteLength > this.maxBytes) {
+         this.reportOverflow();
+         throw new Error(`Max disconnected buffer size exceeded by adding ${data.byteLength} bytes`);
+      }
+      // Copied for the same reason the base class copies: the caller owns `data`.
+      this.pending.push(data.slice());
+      this.pendingBytes += data.byteLength;
+      if (this.pending.length === 1) {
+         console.info(`${CONNECTION_LOG_PREFIX} buffering messages, the peer is disconnected`);
+      }
+   }
+
+   override flush(socket: MessageSink): void {
+      if (this.pending.length === 0) {
+         return;
+      }
+      const count = this.pending.length;
+      const bytes = this.pendingBytes;
+      // Walked with an index and dropped in one slice, not shifted per message: a shift re-indexes
+      // the whole array, so the drain would cost the square of a backlog `bufferBytes` invites an
+      // adopter to enlarge. Leaving the queue in place is what keeps `hasBacklog` true until the
+      // last message is out, and re-reading the length is what drains one appended by a nested send.
+      let index = 0;
+      try {
+         while (index < this.pending.length) {
+            const message = this.pending[index];
+            socket.send(message);
+            index++;
+            this.pendingBytes -= message.byteLength;
+         }
+      } catch (error: unknown) {
+         // Said here because nothing retries: Theia flushes once, from a reconnect handler that has
+         // deregistered by now, so the stall would otherwise surface much later as an overflow —
+         // which names the wrong cause, the socket being up rather than absent.
+         console.error(
+            `${CONNECTION_LOG_PREFIX} send failed ${index} message(s) into a ${count}-message backlog; ` +
+               `${this.pending.length - index} still queued and nothing will retry them`,
+            error
+         );
+         throw error;
+      } finally {
+         this.pending = this.pending.slice(index);
+      }
+      this.overflowReported = false;
+      console.info(`${CONNECTION_LOG_PREFIX} sent ${count} buffered message(s), ${bytes} bytes`);
+   }
+
+   override drain(): void {
+      if (this.pending.length > 0) {
+         console.warn(`${CONNECTION_LOG_PREFIX} discarded ${this.pending.length} buffered message(s), ${this.pendingBytes} bytes`);
+      }
+      this.reset();
+   }
+
+   /** Whether messages are still waiting to go out. */
+   get hasBacklog(): boolean {
+      return this.pending.length > 0;
+   }
+
+   protected reportOverflow(): void {
+      if (this.overflowReported) {
+         return;
+      }
+      this.overflowReported = true;
+      const overflow: ConnectionBufferOverflow = { messages: this.pending.length, bytes: this.pendingBytes, maxBytes: this.maxBytes };
+      console.error(
+         `${CONNECTION_LOG_PREFIX} buffer full at ${overflow.maxBytes} bytes after ${overflow.messages} message(s); ` +
+            'this message is rejected, and so is every further one until the peer returns'
+      );
+      this.onOverflowEmitter.fire(overflow);
+   }
+
+   protected reset(): void {
+      this.pending = [];
+      this.pendingBytes = 0;
+      this.overflowReported = false;
+   }
+}
+
+/** Named in the warning a skipped install emits, so the reader is told what to upgrade to. */
+export const REQUIRED_THEIA_HINT = '@theia/core 1.71 or newer';
+
+/**
+ * Whether this Theia exposes the seam the reconnect hardening replaces.
+ *
+ * Theia only began binding {@link SocketWriteBuffer} in 1.71; before that each
+ * connection built one privately, so there is no binding to rebind and no way
+ * in. Every other API involved has been there throughout, which makes this one
+ * probe the whole compatibility question — and it is a binding check rather
+ * than a version parse, so it answers about the container actually in front of
+ * us instead of a number that may have been overridden or vendored.
+ *
+ * Callers that get `false` must leave Theia's own wiring alone: rebinding half
+ * of it would be worse than not rebinding at all.
+ */
+export function supportsConnectionResilience(isBound: (identifier: typeof SocketWriteBuffer) => boolean): boolean {
+   return isBound(SocketWriteBuffer);
+}
+
+/**
+ * The warning a skipped install emits. Says what is lost rather than only what
+ * is missing: the failures this guards against are silent, so an adopter who
+ * never sees this line has no other way to learn the guard is absent.
+ */
+export function warnConnectionResilienceUnavailable(tier: 'frontend' | 'backend'): void {
+   console.warn(
+      `${CONNECTION_LOG_PREFIX} ${tier} reconnect hardening NOT installed: this Theia does not expose an injectable ` +
+         `socket write buffer (needs ${REQUIRED_THEIA_HINT}). Theia's own behaviour is left in place, which can lose or ` +
+         'reorder messages when a socket drops and reconnects.'
+   );
+}
+
+/** Builds a buffer with the given limit, or Theia's default when none is configured. */
+export function createFramedSocketWriteBuffer(maxBytes?: number): FramedSocketWriteBuffer {
+   const buffer = new FramedSocketWriteBuffer();
+   if (typeof maxBytes === 'number' && maxBytes > 0) {
+      buffer.maxBytes = maxBytes;
+   }
+   return buffer;
+}

package/src/common/index.ts

@@ -0,0 +1,14 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Environment-neutral connection primitives, shared by the browser connection
+// source and the server connection service. Kept out of both tier barrels
+// because each side binds the same buffer for its own half of the socket.
+export * from './framed-socket-write-buffer';
+export * from './connection-resilience-options';

package/src/node/index.ts

@@ -8,3 +8,4 @@
  ********************************************************************************/
 
 export * from './abstract-socket-forwarding-connection-handler';
+export * from './session-bound-frontend-connection-service';

package/src/node/session-bound-frontend-connection-service.ts

@@ -0,0 +1,155 @@
+/********************************************************************************
+ * 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 { BackendApplicationConfigProvider } from '@theia/core/lib/node/backend-application-config-provider';
+import { SocketWriteBuffer } from '@theia/core/lib/common/messaging/socket-write-buffer';
+import { WebsocketFrontendConnectionService } from '@theia/core/lib/node/messaging/websocket-frontend-connection-service';
+import { injectable, type interfaces } from '@theia/core/shared/inversify';
+import { type ConnectionResilienceOptions } from '../common/connection-resilience-options';
+import {
+   CONNECTION_LOG_PREFIX as PREFIX,
+   createFramedSocketWriteBuffer,
+   supportsConnectionResilience,
+   warnConnectionResilienceUnavailable
+} from '../common/framed-socket-write-buffer';
+
+/**
+ * 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.
+ */
+@injectable()
+export class SessionBoundFrontendConnectionService extends WebsocketFrontendConnectionService {
+   /** Socket each frontend's channel is currently bound to, with the time it was bound. */
+   protected readonly bindings = new Map<string, { socketId: string; boundAt: number }>();
+   /** When a frontend's live socket went away, so the reconnect gap can be reported. */
+   protected readonly offlineSince = new Map<string, number>();
+
+   override handleSocketDisconnect(socket: FrontendSocket, channel: FrontendChannel, frontEndId: string): void {
+      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(`${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(`${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(`${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(`${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.
+      });
+   }
+
+   protected override closeConnection(frontEndId: string, reason: string): void {
+      console.info(`${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. */
+   protected connectionTimeout(): number {
+      const envValue = Number(process.env['FRONTEND_CONNECTION_TIMEOUT']);
+      if (!isNaN(envValue)) {
+         return envValue;
+      }
+      return BackendApplicationConfigProvider.get().frontendConnectionTimeout;
+   }
+}
+
+/**
+ * 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 function bindConnectionResilience(
+   bind: interfaces.Bind,
+   isBound: interfaces.IsBound,
+   rebind: interfaces.Rebind,
+   options: ConnectionResilienceOptions = {}
+): boolean {
+   if (!supportsConnectionResilience(isBound)) {
+      warnConnectionResilienceUnavailable('backend');
+      return false;
+   }
+   bind(SessionBoundFrontendConnectionService).toSelf().inSingletonScope();
+   rebind(WebsocketFrontendConnectionService).toService(SessionBoundFrontendConnectionService);
+   rebind(SocketWriteBuffer).toDynamicValue(() => createFramedSocketWriteBuffer(options.bufferBytes));
+   return true;
+}