@hydranium/client-theia 1.0.0-next.24 → 1.0.0-next.241

package/lib/browser/session-aware-connection-source.js

@@ -0,0 +1,184 @@
+"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.SessionAwareConnectionSource = void 0;
+exports.bindConnectionResilience = bindConnectionResilience;
+const ws_connection_source_1 = require("@theia/core/lib/browser/messaging/ws-connection-source");
+const disposable_1 = require("@theia/core/lib/common/disposable");
+const channel_1 = require("@theia/core/lib/common/message-rpc/channel");
+const uint8_array_message_buffer_1 = require("@theia/core/lib/common/message-rpc/uint8-array-message-buffer");
+const connection_management_1 = require("@theia/core/lib/common/messaging/connection-management");
+const inversify_1 = require("@theia/core/shared/inversify");
+const socket_write_buffer_1 = require("@theia/core/lib/common/messaging/socket-write-buffer");
+const framed_socket_write_buffer_1 = require("../common/framed-socket-write-buffer");
+const inbound_message_sequence_1 = require("../common/inbound-message-sequence");
+/**
+ * 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.
+ */
+let SessionAwareConnectionSource = class SessionAwareConnectionSource extends ws_connection_source_1.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.
+     */
+    sessionResumed = false;
+    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.
+     */
+    handleSocketConnected() {
+        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.
+     */
+    trackSessionState() {
+        if (this.sessionListenersAttached) {
+            return;
+        }
+        this.sessionListenersAttached = true;
+        this.socket.on(connection_management_1.ConnectionManagementMessages.INITIAL_CONNECT, () => {
+            this.sessionResumed = true;
+        });
+        this.socket.on(connection_management_1.ConnectionManagementMessages.RECONNECT, (hasConnection) => {
+            this.sessionResumed = hasConnection;
+        });
+        this.socket.on(inbound_message_sequence_1.ACKNOWLEDGEMENT_EVENT, (sequence) => {
+            if (typeof sequence === 'number') {
+                this.framedBuffer.acknowledge(sequence);
+            }
+        });
+    }
+    /** Whether a message may go out now, as opposed to waiting in the buffer. */
+    get canSend() {
+        return this.socket.connected && this.sessionResumed;
+    }
+    /**
+     * Copied from Theia apart from the duplicate check on receipt and the `onCommit` body, because
+     * the base builds both callbacks inline and exposes no narrower seam. Re-diff when the supported
+     * range moves.
+     *
+     * Called once per session, so the receive-side state starts afresh with the server's numbering.
+     */
+    createChannel() {
+        const toDispose = new disposable_1.DisposableCollection();
+        const inbound = new inbound_message_sequence_1.InboundMessageSequence(sequence => this.socket.emit(inbound_message_sequence_1.ACKNOWLEDGEMENT_EVENT, sequence));
+        toDispose.push(disposable_1.Disposable.create(() => inbound.dispose()));
+        const messageHandler = (data, sequence) => {
+            this.onIncomingMessageActivityEmitter.fire();
+            if (typeof sequence === 'number') {
+                this.framedBuffer.markPeerDeduplicates();
+            }
+            if (!inbound.accept(sequence, data.byteLength)) {
+                return;
+            }
+            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 uint8_array_message_buffer_1.Uint8ArrayReadBuffer(buffer));
+            }
+        };
+        this.socket.on('message', messageHandler);
+        toDispose.push(disposable_1.Disposable.create(() => this.socket.off('message', messageHandler)));
+        return new channel_1.ForwardingChannel('any', () => toDispose.dispose(), () => {
+            const result = new uint8_array_message_buffer_1.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() {
+        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.
+     */
+    get framedBuffer() {
+        const buffer = this.writeBuffer;
+        if (!(buffer instanceof framed_socket_write_buffer_1.FramedSocketWriteBuffer)) {
+            throw new Error('SessionAwareConnectionSource requires FramedSocketWriteBuffer to be bound');
+        }
+        return buffer;
+    }
+};
+exports.SessionAwareConnectionSource = SessionAwareConnectionSource;
+exports.SessionAwareConnectionSource = SessionAwareConnectionSource = __decorate([
+    (0, inversify_1.injectable)()
+], SessionAwareConnectionSource);
+/**
+ * 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.
+ */
+function bindConnectionResilience(isBound, rebind, options = {}) {
+    if (!(0, framed_socket_write_buffer_1.supportsConnectionResilience)(isBound)) {
+        (0, framed_socket_write_buffer_1.warnConnectionResilienceUnavailable)('frontend');
+        return false;
+    }
+    // Scopes are kept as Theia declares them: one buffer per connection source, one shared socket owner.
+    rebind(socket_write_buffer_1.SocketWriteBuffer).toDynamicValue(() => (0, framed_socket_write_buffer_1.createFramedSocketWriteBuffer)(options));
+    rebind(ws_connection_source_1.WebSocketConnectionSource).to(SessionAwareConnectionSource).inSingletonScope();
+    return true;
+}
+//# sourceMappingURL=session-aware-connection-source.js.map

package/lib/browser/session-aware-connection-source.js.map

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

package/lib/common/clock.d.ts

@@ -0,0 +1,19 @@
+/********************************************************************************
+ * 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 type { Clock as ProtocolClock } from '@hydranium/protocol';
+/**
+ * The protocol's `Clock`, as a Theia container binds it: type and injection
+ * token under one identifier, as Theia declares its own. The framework's
+ * frontend and backend classes that time or bound something inject it as
+ * optional, and use a `SystemClock` when the container binds none, so a
+ * container can supply another clock.
+ */
+export type Clock = ProtocolClock;
+export declare const Clock: unique symbol;
+//# sourceMappingURL=clock.d.ts.map

package/lib/common/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../src/common/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,KAAK,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,MAAM,KAAK,GAAG,aAAa,CAAC;AAClC,eAAO,MAAM,KAAK,eAAkB,CAAC"}

package/lib/common/clock.js

@@ -0,0 +1,13 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Clock = void 0;
+exports.Clock = Symbol('Clock');
+//# sourceMappingURL=clock.js.map

package/lib/common/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/common/clock.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAYrE,QAAA,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC"}

package/lib/common/connection-resilience-options.d.ts

@@ -0,0 +1,30 @@
+/********************************************************************************
+ * 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;
+    /**
+     * How much each side keeps of what it sent and the peer has not acknowledged
+     * yet, in bytes. Past it the copies are discarded and a dropped connection
+     * loses them, so it bounds what a peer that never acknowledges can cost.
+     */
+    readonly unacknowledgedBytes?: number;
+}
+//# sourceMappingURL=connection-resilience-options.d.ts.map

package/lib/common/connection-resilience-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-resilience-options.d.ts","sourceRoot":"","sources":["../../src/common/connection-resilience-options.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACxC"}

package/lib/common/connection-resilience-options.js

@@ -0,0 +1,11 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=connection-resilience-options.js.map

package/lib/common/connection-resilience-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-resilience-options.js","sourceRoot":"","sources":["../../src/common/connection-resilience-options.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF"}

package/lib/common/framed-socket-write-buffer.d.ts

@@ -0,0 +1,173 @@
+/********************************************************************************
+ * 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';
+import { type ConnectionResilienceOptions } from './connection-resilience-options';
+/**
+ * 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 declare 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 {
+    /** `sequence` travels as a second socket.io argument, which a reader that does not expect it ignores. */
+    send(data: Uint8Array, sequence: number): 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.
+ *
+ * Added here: every message sent is numbered and kept until the peer
+ * acknowledges it, and {@link flush} resends what is still unacknowledged ahead
+ * of the backlog. A socket whose far end died unnoticed still accepts writes, so
+ * a message is not delivered just because it was sent.
+ *
+ * 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 declare class FramedSocketWriteBuffer extends SocketWriteBuffer {
+    /** Theia's fixed limit, kept as the default. */
+    static readonly DEFAULT_MAX_BYTES: number;
+    /**
+     * 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: number;
+    /** Kept copies past this are discarded, so a peer that never acknowledges cannot grow them without bound. */
+    static readonly DEFAULT_MAX_UNACKNOWLEDGED_BYTES: number;
+    /**
+     * Separate from {@link maxBytes}, which counts only what is produced while
+     * the peer is away: copies kept on a healthy connection must not use up the
+     * room an outage needs.
+     */
+    maxUnacknowledgedBytes: number;
+    protected pending: Uint8Array[];
+    protected pendingBytes: number;
+    protected overflowReported: boolean;
+    protected readonly onOverflowEmitter: Emitter<ConnectionBufferOverflow>;
+    protected nextSequence: number;
+    /** Oldest first: {@link acknowledge} stops at the first entry the peer has not accepted. */
+    protected unacknowledged: {
+        readonly sequence: number;
+        readonly data: Uint8Array;
+    }[];
+    protected unacknowledgedBytes: number;
+    protected unacknowledgedOverflowReported: boolean;
+    /**
+     * Whether the peer drops a message it already has. One without the hardening
+     * applies a resent message a second time, so nothing is resent until the
+     * peer has shown otherwise.
+     */
+    protected peerDeduplicates: boolean;
+    /** Fires once per outage when the limit is reached. */
+    get onOverflow(): Event<ConnectionBufferOverflow>;
+    /**
+     * 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;
+    buffer(data: Uint8Array): void;
+    /**
+     * Kept only once `send` returns: a message whose send threw stays in the
+     * backlog, and keeping it as well would send it again under a second number,
+     * which the receiver cannot recognise as a duplicate.
+     */
+    protected send(socket: MessageSink, data: Uint8Array): void;
+    protected keep(sequence: number, data: Uint8Array): void;
+    /**
+     * Records that the peer numbers its messages, which only a peer that also
+     * drops duplicates does, so resending to it is safe.
+     */
+    markPeerDeduplicates(): void;
+    /** Releases every kept message numbered up to `sequence`, which the peer has accepted. */
+    acknowledge(sequence: number): void;
+    /**
+     * Resends what the peer has not acknowledged, under the same numbers, then
+     * sends the backlog. Some of the resent messages may have arrived already;
+     * the receiver recognises them by number and drops them.
+     *
+     * Resends only to a peer known to drop duplicates, and otherwise discards the
+     * copies, leaving any message lost with the old socket lost.
+     */
+    flush(socket: MessageSink): void;
+    drain(): void;
+    /** Whether messages are still waiting to go out. */
+    get hasBacklog(): boolean;
+    protected reportOverflow(): void;
+    /** Also discards the kept copies: a drain ends the session, and resending them would replay it into the next one. */
+    protected reset(): void;
+}
+/** Named in the warning a skipped install emits, so the reader is told what to upgrade to. */
+export declare 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 declare function supportsConnectionResilience(isBound: (identifier: typeof SocketWriteBuffer) => boolean): boolean;
+/**
+ * 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 declare function warnConnectionResilienceUnavailable(tier: 'frontend' | 'backend'): void;
+/** Builds a buffer with the configured limits, or the defaults for any not configured. */
+export declare function createFramedSocketWriteBuffer(options?: ConnectionResilienceOptions): FramedSocketWriteBuffer;
+//# sourceMappingURL=framed-socket-write-buffer.d.ts.map

package/lib/common/framed-socket-write-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framed-socket-write-buffer.d.ts","sourceRoot":"","sources":["../../src/common/framed-socket-write-buffer.ts"],"names":[],"mappings":"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"}