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

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/abstract-socket-forwarding-connection-handler.ts

@@ -175,7 +175,12 @@ export abstract class AbstractSocketForwardingConnectionHandler implements Conne
       if (channel instanceof ForwardingChannel) {
          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;
    }

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;
+}