@hydranium/client-theia 1.0.0-next.37 → 1.0.0-next.371

package/src/common/inbound-message-sequence.ts

@@ -0,0 +1,102 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { CONNECTION_LOG_PREFIX } from './framed-socket-write-buffer';
+
+/** The socket.io event that carries the highest message number a side has accepted. */
+export const ACKNOWLEDGEMENT_EVENT = 'hydranium:ack';
+
+/**
+ * What one side has received on a session: drops a message it already accepted
+ * and acknowledges the rest.
+ *
+ * The peer resends everything unacknowledged when a session resumes, because it
+ * cannot tell which of its messages died with the old socket, so every resumed
+ * session can repeat messages already delivered. Delivering one twice corrupts
+ * anything applied by position, just as losing one does.
+ *
+ * Acknowledges once enough has arrived, and otherwise after a short delay. A
+ * timer alone is not enough: a background tab throttles timers, and the peer
+ * holds every unacknowledged message until the acknowledgement arrives. The
+ * first message of a session is acknowledged at once, because the peer resends
+ * nothing until an acknowledgement shows it may.
+ *
+ * Belongs to one session. A new session numbers from the start again, so it
+ * needs a new instance.
+ */
+export class InboundMessageSequence {
+   static readonly ACKNOWLEDGE_AFTER_MESSAGES = 64;
+   static readonly ACKNOWLEDGE_AFTER_BYTES = 32 * 1024;
+   static readonly ACKNOWLEDGE_DELAY_MS = 100;
+
+   protected lastAccepted = 0;
+   protected messagesSinceAcknowledgement = 0;
+   protected bytesSinceAcknowledgement = 0;
+   protected acknowledgementTimer: ReturnType<typeof setTimeout> | undefined;
+
+   constructor(protected readonly sendAcknowledgement: (sequence: number) => void) {}
+
+   /**
+    * Whether to deliver a message that arrived with `sequence`.
+    *
+    * A message without a number comes from a peer that does not number them,
+    * and is delivered as it is. A duplicate is still acknowledged: the peer
+    * resent it because an earlier acknowledgement was lost, and keeps it until
+    * one arrives.
+    *
+    * A skipped number is delivered past, with a warning: the skipped messages
+    * are lost, and this is the one place that can tell.
+    */
+   accept(sequence: unknown, bytes: number): boolean {
+      if (typeof sequence !== 'number') {
+         return true;
+      }
+      const isFirst = this.lastAccepted === 0;
+      const isNew = sequence > this.lastAccepted;
+      if (isNew) {
+         if (sequence > this.lastAccepted + 1) {
+            const missing = sequence - this.lastAccepted - 1;
+            console.warn(
+               `${CONNECTION_LOG_PREFIX} lost ${missing} message(s), numbered ${this.lastAccepted + 1} to ${sequence - 1}; ` +
+                  'they never arrived and nothing will resend them'
+            );
+         }
+         this.lastAccepted = sequence;
+      }
+      this.messagesSinceAcknowledgement++;
+      this.bytesSinceAcknowledgement += bytes;
+      if (
+         isFirst ||
+         this.messagesSinceAcknowledgement >= InboundMessageSequence.ACKNOWLEDGE_AFTER_MESSAGES ||
+         this.bytesSinceAcknowledgement >= InboundMessageSequence.ACKNOWLEDGE_AFTER_BYTES
+      ) {
+         this.acknowledge();
+      } else {
+         this.acknowledgementTimer ??= setTimeout(() => this.acknowledge(), InboundMessageSequence.ACKNOWLEDGE_DELAY_MS);
+      }
+      return isNew;
+   }
+
+   /** Sends the acknowledgement now rather than waiting for more traffic. */
+   acknowledge(): void {
+      this.cancelTimer();
+      this.messagesSinceAcknowledgement = 0;
+      this.bytesSinceAcknowledgement = 0;
+      this.sendAcknowledgement(this.lastAccepted);
+   }
+
+   dispose(): void {
+      this.cancelTimer();
+   }
+
+   protected cancelTimer(): void {
+      clearTimeout(this.acknowledgementTimer);
+      this.acknowledgementTimer = undefined;
+   }
+}

package/src/common/index.ts

@@ -0,0 +1,16 @@
+/********************************************************************************
+ * 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 primitives that the browser and the server tiers each
+// bind for their own side, such as the buffer for each half of the socket.
+// Kept out of both tier barrels for that reason.
+export * from './framed-socket-write-buffer';
+export * from './inbound-message-sequence';
+export * from './connection-resilience-options';
+export * from './clock';

package/src/node/abstract-socket-forwarding-connection-handler.ts

@@ -7,6 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+import { SystemClock, describeError, describeErrorWithStack } from '@hydranium/protocol';
 import {
    type Channel,
    CommandService,
@@ -16,10 +17,12 @@ import {
    type MessageProvider,
    MessageService
 } from '@theia/core';
-import { ForwardingChannel } from '@theia/core/lib/common/message-rpc/channel';
+import { AbstractChannel } from '@theia/core/lib/common/message-rpc/channel';
 import { Deferred } from '@theia/core/lib/common/promise-util';
-import { inject, injectable } from '@theia/core/shared/inversify';
+import { inject, injectable, optional } from '@theia/core/shared/inversify';
 import * as net from 'node:net';
+import { Clock } from '../common/clock';
+import { SocketChannelForwarder } from './socket-channel-forwarder';
 
 /** Resolved configuration for a {@link AbstractSocketForwardingConnectionHandler}.
  *  A head-specific subclass derives these from its own (adopter-facing) options
@@ -61,12 +64,10 @@ export interface SocketForwardingConnectionHandlerOptions {
  * the same wire protocol the server speaks, so the backend performs no semantic
  * re-proxy — it relays bytes only and stays oblivious to the server's method set.
  *
- * The single per-head variation — *which* byte forwarder bridges the channel and
- * the socket — is the abstract {@link forwardToSocketConnection} hook: the GLSP
- * head plugs in `@eclipse-glsp/theia-integration`'s `SocketConnectionForwarder`,
- * the data-server head its own `SocketChannelForwarder`. Keeping the forwarder
- * behind the hook is what lets the data head stay GLSP-free while sharing the
- * port-discovery + buffer-and-replay race fix + connect orchestration here.
+ * The byte forwarder that bridges the channel and the socket is
+ * {@link forwardToSocketConnection}; both heads use {@link SocketChannelForwarder},
+ * and the port discovery, buffer-and-replay race fix and connect orchestration
+ * here are shared.
  */
 @injectable()
 export abstract class AbstractSocketForwardingConnectionHandler implements ConnectionHandler {
@@ -76,6 +77,8 @@ export abstract class AbstractSocketForwardingConnectionHandler implements Conne
    // not the spawned language-server process, so the framework `LspLogger`
    // (which needs the Langium connection/services) is out of reach here.
    @inject(ILogger) protected readonly logger!: ILogger;
+   /** The clock each {@link SocketChannelForwarder} bounds its flush on: the container's {@link Clock}, or a `SystemClock`. */
+   @inject(Clock) @optional() protected readonly clock: Clock = new SystemClock();
 
    readonly path: string;
 
@@ -114,31 +117,66 @@ export abstract class AbstractSocketForwardingConnectionHandler implements Conne
       // window.
       const buffered: MessageProvider[] = [];
       const bufferSub = channel.onMessage(provider => buffered.push(provider));
+      const closed = new AbortController();
+      const closeSub = channel.onClose(() => closed.abort());
       try {
-         const port = await this.findPort();
+         const port = await this.findPort(closed.signal);
+         closed.signal.throwIfAborted();
          this.logger.info(`[${this.logComponent}] Connecting to ${this.serverName} on port ${port}...`);
          await this.connectToServer(channel, port, { bufferSub, buffered });
          this.logger.info(`[${this.logComponent}] Connected to ${this.serverName} on port ${port}.`);
       } catch (error) {
          bufferSub.dispose();
-         const message = error && typeof error === 'object' && 'message' in error ? String(error.message) : String(error);
-         this.logger.error(`[${this.logComponent}] Could not connect to ${this.serverName}: ${message}`);
-         this.messageService.error(`Could not connect to ${this.serverName}: ` + message);
+         if (closed.signal.aborted) {
+            this.logger.debug(`[${this.logComponent}] Stopped connecting to ${this.serverName}: the frontend closed the channel.`);
+            return;
+         }
+         this.logger.error(`[${this.logComponent}] Could not connect to ${this.serverName}: ${describeErrorWithStack(error)}`);
+         this.reportConnectFailure(describeError(error));
+         // Closed so the frontend learns of it: left open, the channel has no
+         // server behind it, and every request on it waits for good.
+         channel.close();
+      } finally {
+         closeSub.dispose();
       }
    }
 
-   protected async findPort(): Promise<number> {
+   /** Tell the user this handler gave up; `message` is the reason it logged. */
+   protected reportConnectFailure(message: string): void {
+      this.messageService.error(`Could not connect to ${this.serverName}: ` + message);
+   }
+
+   /** Poll the port command until it answers, its attempts run out, or `signal` aborts. */
+   protected async findPort(signal?: AbortSignal): Promise<number> {
       const pendingContent = new Deferred<number>();
       let counter = 0;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const stop = (): void => {
+         clearTimeout(timer);
+         pendingContent.reject(signal?.reason);
+      };
+      if (signal?.aborted) {
+         stop();
+      }
+      signal?.addEventListener('abort', stop, { once: true });
       const tryQueryingPort = (): void => {
-         setTimeout(async () => {
+         if (signal?.aborted) {
+            return;
+         }
+         timer = setTimeout(async () => {
             try {
                const port = await this.commandService.executeCommand<number>(this.portCommand);
-               if (port) {
-                  pendingContent.resolve(port);
+               // An empty answer fails the attempt like a throw does: left
+               // unanswered, it neither resolves nor re-queues, and the lookup
+               // stays pending with nothing logged.
+               if (!port) {
+                  throw new Error(`Port command '${this.portCommand}' answered without a port.`);
                }
+               pendingContent.resolve(port);
             } catch (error) {
                counter++;
+               const message = describeError(error);
+               this.logger.debug(`[${this.logComponent}] Port command '${this.portCommand}' attempt ${counter} failed: ${message}`);
                if (this.findPortAttempts >= 0 && counter > this.findPortAttempts) {
                   pendingContent.reject(error);
                } else {
@@ -159,9 +197,20 @@ export abstract class AbstractSocketForwardingConnectionHandler implements Conne
       const connected = new Deferred<void>();
       const socket = new net.Socket();
       this.onSocketCreated?.(socket);
-      socket.on('ready', () => connected.resolve());
+      let ready = false;
+      socket.on('ready', () => {
+         ready = true;
+         connected.resolve();
+      });
       socket.on('close', () => connected.reject(`Socket to ${this.serverName} was closed.`));
-      socket.on('error', error => this.logger.error(`Error occurred with the ${this.serverName} socket: ${error.name}; ${error.message}`));
+      // Before `ready` the error fails the connect, whose caller logs it; the `close` that follows rejects too late to count.
+      socket.on('error', error => {
+         if (ready) {
+            this.logger.error(`Error occurred with the ${this.serverName} socket: ${describeErrorWithStack(error)}`);
+         } else {
+            connected.reject(error);
+         }
+      });
       // Synchronous hand-off: dispose the pre-forward buffer FIRST, then wire the
       // forwarder, then replay buffered messages. The event loop cannot
       // interleave between these synchronous statements, so no message is both
@@ -172,10 +221,15 @@ export abstract class AbstractSocketForwardingConnectionHandler implements Conne
       if (preForwardBuffer && preForwardBuffer.buffered.length > 0) {
          this.replayBufferedMessages(channel, preForwardBuffer.buffered);
       }
-      if (channel instanceof ForwardingChannel) {
+      if (channel instanceof AbstractChannel) {
          socket.on('error', error => channel.onErrorEmitter.fire(error));
       }
-      socket.connect({ port });
+      // `127.0.0.1`, not the `localhost` Node dials when no host is given, and it
+      // has to match the head: the socket launchers bind `127.0.0.1` by default,
+      // so on a dual-stack machine where `localhost` resolves to `::1` first the
+      // dial fails as ECONNREFUSED with nothing in the message naming the address
+      // family as the cause.
+      socket.connect({ port, host: '127.0.0.1' });
       setTimeout(() => connected.reject('Timeout reached.'), this.connectTimeoutMs);
       return connected.promise;
    }
@@ -185,34 +239,29 @@ export abstract class AbstractSocketForwardingConnectionHandler implements Conne
     * relay both ways. Called once, after the socket is created and the
     * pre-forward buffer is about to be replayed.
     */
-   protected abstract forwardToSocketConnection(clientChannel: Channel, socket: net.Socket): Disposable;
+   protected forwardToSocketConnection(clientChannel: Channel, socket: net.Socket): Disposable {
+      return new SocketChannelForwarder(clientChannel, socket, this.clock);
+   }
 
    /**
-    * Re-fire pre-forward buffered `MessageProvider`s on the channel's internal
+    * Re-fire pre-forward buffered `MessageProvider`s on the channel's
     * `onMessageEmitter` so the now-subscribed forwarder picks them up in arrival
     * order. `MessageProvider` is a thunk (`() => ReadBuffer`) — buffering does
     * not consume the read position, so replay produces the same bytes the
     * forwarder would have seen if wired earlier.
     *
-    * `AbstractChannel.onMessageEmitter` is `protected` in `@theia/core` but
-    * reachable at runtime; the cast is the workaround. A future Theia rename
-    * surfaces as a clear warning here.
+    * The emitter is public on `AbstractChannel`; the `Channel` interface
+    * carries just its `Event`, so any other channel has its messages logged as
+    * dropped. A Theia rename of the emitter fails to compile here.
     */
    protected replayBufferedMessages(channel: Channel, buffered: MessageProvider[]): void {
-      if (!(channel instanceof ForwardingChannel)) {
-         this.logger.warn(`[${this.logComponent}] dropping ${buffered.length} pre-forward message(s) — channel is not a ForwardingChannel`);
-         return;
-      }
-      const internals = channel as unknown as { onMessageEmitter?: { fire(provider: MessageProvider): void } };
-      if (!internals.onMessageEmitter) {
-         this.logger.warn(
-            `[${this.logComponent}] dropping ${buffered.length} pre-forward message(s) — ForwardingChannel.onMessageEmitter not accessible`
-         );
+      if (!(channel instanceof AbstractChannel)) {
+         this.logger.error(`[${this.logComponent}] dropping ${buffered.length} pre-forward message(s) — channel is not an AbstractChannel`);
          return;
       }
-      this.logger.info(`[${this.logComponent}] replaying ${buffered.length} pre-forward message(s) onto the wired socket forwarder`);
+      this.logger.debug(`[${this.logComponent}] replaying ${buffered.length} pre-forward message(s) onto the wired socket forwarder`);
       for (const provider of buffered) {
-         internals.onMessageEmitter.fire(provider);
+         channel.onMessageEmitter.fire(provider);
       }
    }
 }

package/src/node/index.ts

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

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

@@ -0,0 +1,264 @@
+/********************************************************************************
+ * 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 Stopwatch, SystemClock } from '@hydranium/protocol';
+import { Disposable, DisposableCollection } from '@theia/core/lib/common/disposable';
+import { AbstractChannel } from '@theia/core/lib/common/message-rpc/channel';
+import { type WriteBuffer } from '@theia/core/lib/common/message-rpc/message-buffer';
+import { Uint8ArrayReadBuffer, Uint8ArrayWriteBuffer } from '@theia/core/lib/common/message-rpc/uint8-array-message-buffer';
+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 { inject, injectable, optional, type interfaces } from '@theia/core/shared/inversify';
+import { Clock } from '../common/clock';
+import { type ConnectionResilienceOptions } from '../common/connection-resilience-options';
+import {
+   CONNECTION_LOG_PREFIX as PREFIX,
+   createFramedSocketWriteBuffer,
+   FramedSocketWriteBuffer,
+   supportsConnectionResilience,
+   warnConnectionResilienceUnavailable
+} from '../common/framed-socket-write-buffer';
+import { ACKNOWLEDGEMENT_EVENT, InboundMessageSequence } from '../common/inbound-message-sequence';
+
+/**
+ * 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];
+
+/**
+ * The server end of one frontend's session, carried across the sockets the
+ * frontend reconnects on.
+ *
+ * Theia's own channel sends straight into any socket that reports itself
+ * connected. A socket whose far end died unnoticed still does, so whatever is
+ * sent until the server notices is lost. This one numbers and keeps every
+ * message through {@link FramedSocketWriteBuffer}, resends what is still
+ * unacknowledged when the frontend reconnects, and drops what it has received
+ * twice. Otherwise it behaves as Theia's.
+ */
+export class AcknowledgedSocketChannel extends AbstractChannel {
+   protected socket: FrontendSocket | undefined;
+   protected socketDisposables = new DisposableCollection();
+   protected readonly inbound = new InboundMessageSequence(sequence => this.socket?.emit(ACKNOWLEDGEMENT_EVENT, sequence));
+
+   constructor(protected readonly socketBuffer: FramedSocketWriteBuffer) {
+      super();
+      this.toDispose.push(this.inbound);
+      this.toDispose.push(Disposable.create(() => this.socketDisposables.dispose()));
+   }
+
+   /** Flushes in the same step that attaches the listeners, so nothing new can overtake the resend. */
+   connect(socket: FrontendSocket): void {
+      this.socketDisposables.dispose();
+      this.socketDisposables = new DisposableCollection();
+      this.socket = socket;
+      const errorHandler = (error: unknown): void => this.onErrorEmitter.fire(error);
+      const dataListener = (data: ArrayBuffer | Uint8Array, sequence?: unknown): void => {
+         if (typeof sequence === 'number') {
+            this.socketBuffer.markPeerDeduplicates();
+         }
+         if (!this.inbound.accept(sequence, data.byteLength)) {
+            return;
+         }
+         const buffer = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+         this.onMessageEmitter.fire(() => new Uint8ArrayReadBuffer(buffer));
+      };
+      const acknowledgementListener = (sequence: unknown): void => {
+         if (typeof sequence === 'number') {
+            this.socketBuffer.acknowledge(sequence);
+         }
+      };
+      socket.on('error', errorHandler);
+      socket.on('message', dataListener);
+      socket.on(ACKNOWLEDGEMENT_EVENT, acknowledgementListener);
+      this.socketDisposables.push(
+         Disposable.create(() => {
+            socket.off('error', errorHandler);
+            socket.off('message', dataListener);
+            socket.off(ACKNOWLEDGEMENT_EVENT, acknowledgementListener);
+         })
+      );
+      this.socketBuffer.flush(socket);
+   }
+
+   disconnect(): void {
+      this.socketDisposables.dispose();
+      this.socket = undefined;
+   }
+
+   drainBuffer(): void {
+      this.socketBuffer.drain();
+   }
+
+   getWriteBuffer(): WriteBuffer {
+      const writeBuffer = new Uint8ArrayWriteBuffer();
+      writeBuffer.onCommit(data => this.socketBuffer.sendOrQueue(this.socket?.connected ? this.socket : undefined, data));
+      return writeBuffer;
+   }
+}
+
+/**
+ * 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 {
+   /** Times the gaps the log reports: the container's {@link Clock}, or a `SystemClock`. */
+   @inject(Clock) @optional() protected readonly clock: Clock = new SystemClock();
+   /** Socket each frontend's channel is currently bound to, with how long it has been. */
+   protected readonly bindings = new Map<string, { socketId: string; sinceBound: Stopwatch }>();
+   /** Running since a frontend's live socket went away, so the reconnect gap can be reported. */
+   protected readonly sinceOffline = new Map<string, Stopwatch>();
+
+   override handleSocketDisconnect(socket: FrontendSocket, channel: FrontendChannel, frontEndId: string): void {
+      const previous = this.bindings.get(frontEndId);
+      this.bindings.set(frontEndId, { socketId: socket.id, sinceBound: this.clock.stopwatch() });
+
+      const sinceOffline = this.sinceOffline.get(frontEndId);
+      this.sinceOffline.delete(frontEndId);
+      const replacing = previous ? `, replacing socket ${previous.socketId}` : '';
+      const gap = sinceOffline === undefined ? '' : `, after ${Math.round(sinceOffline.elapsedMs)} 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 ${Math.round(bound.sinceBound.elapsedMs)} 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.sinceOffline.set(frontEndId, this.clock.stopwatch());
+         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.
+      });
+   }
+
+   /**
+    * Theia's body, building an {@link AcknowledgedSocketChannel} in place of its own channel.
+    *
+    * Handed over through a cast, because Theia types the slot as its own channel class. The cast
+    * also hides from the compiler what Theia calls on the channel, so a release that calls a member
+    * this one lacks fails at runtime: re-diff with the disconnect handler.
+    */
+   protected override createConnection(socket: FrontendSocket, frontEndId: string): FrontendChannel {
+      const channel = new AcknowledgedSocketChannel(this.createWriteBuffer()) as unknown as FrontendChannel;
+      channel.connect(socket);
+      this.connectionsByFrontend.set(frontEndId, channel);
+      return channel;
+   }
+
+   /**
+    * One buffer per session, from the container Theia resolves its own channel's buffer from.
+    * Reached through a structural view because Theia 1.70 does not declare `container`.
+    */
+   protected createWriteBuffer(): FramedSocketWriteBuffer {
+      const container = (this as unknown as { readonly container: interfaces.Container }).container;
+      const buffer = container.get<SocketWriteBuffer>(SocketWriteBuffer);
+      if (!(buffer instanceof FramedSocketWriteBuffer)) {
+         throw new Error('SessionBoundFrontendConnectionService requires FramedSocketWriteBuffer to be bound');
+      }
+      return buffer;
+   }
+
+   protected override closeConnection(frontEndId: string, reason: string): void {
+      console.info(`${PREFIX} closing frontend ${frontEndId}: ${reason}`);
+      this.bindings.delete(frontEndId);
+      this.sinceOffline.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));
+   return true;
+}