@hydranium/data-client-theia 1.0.0-next.10

package/src/browser/host-diagnostics-frontend.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
+ ********************************************************************************/
+
+import { HostMemoryDiagnosticsService } from '@hydranium/client-theia/lib/browser';
+import { HOST_DIAGNOSTICS_PATH, type HostDiagnosticsProtocol } from '@hydranium/protocol';
+import { RemoteConnectionProvider, type ServiceConnectionProvider } from '@theia/core/lib/browser/messaging/service-connection-provider';
+import { type interfaces } from '@theia/core/shared/inversify';
+
+/**
+ * Bind the host-process diagnostics frontend proxy to
+ * {@link HostMemoryDiagnosticsService} so `MemoryDiagnosticsContribution`'s
+ * "Dump Backend State" / "Write Heap Snapshot (Backend)" commands light up. The
+ * proxy targets {@link HOST_DIAGNOSTICS_PATH}, served in the Theia backend by
+ * `createHostDiagnosticsBackendModule` (see `../node`). Call from a Theia
+ * frontend `ContainerModule`, alongside `bindMemoryDiagnostics`.
+ */
+export function bindHostDiagnostics(bind: interfaces.Bind): void {
+   bind(HostMemoryDiagnosticsService)
+      .toDynamicValue(context => {
+         const provider = context.container.get<ServiceConnectionProvider>(RemoteConnectionProvider);
+         return provider.createProxy<HostDiagnosticsProtocol>(HOST_DIAGNOSTICS_PATH);
+      })
+      .inSingletonScope();
+}

package/src/browser/index.ts

@@ -0,0 +1,15 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+export * from './channel-connection';
+export * from './data-service-frontend';
+export * from './diagnostics-data-service-frontend';
+export * from './host-diagnostics-frontend';
+export * from './references-data-service-frontend';
+export * from './workspace-gate';

package/src/browser/references-data-service-frontend.ts

@@ -0,0 +1,70 @@
+/********************************************************************************
+ * 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 {
+   FindNextNameArgs,
+   ReferenceCandidate,
+   ReferenceContext,
+   ReferenceRequest,
+   ReferenceServerProtocol,
+   ReferenceTarget,
+   TransferElement
+} from '@hydranium/protocol';
+import { AbstractDataServiceFrontend } from './data-service-frontend';
+
+/**
+ * {@link AbstractDataServiceFrontend} specialised for a server that also
+ * composes the framework {@link ReferenceServerProtocol} fragment. It
+ * implements each reference method as a readiness-gated pass-through —
+ * `await this.ensureConnected()`, then delegate to `this.server` — so an
+ * adopter frontend gets the candidate / resolve / next-name surface without
+ * hand-writing identical one-liner bodies.
+ *
+ * The sibling of `AbstractDiagnosticsDataServiceFrontend`, and the same
+ * shape for the same reason: `this.server` is already a forwarding proxy, but
+ * it queues only on the channel being live, not on the server's `waitForReady`
+ * gate — so the gate has to be interposed per method.
+ *
+ * Extend this instead of {@link AbstractDataServiceFrontend} whenever the
+ * head's `DataServer` registers the reference fragment (typically via a
+ * subclass's `additionalMethods`, since
+ * `REFERENCE_SERVER_PROTOCOL_METHODS` is deliberately NOT part of
+ * `DATA_SERVER_PROTOCOL_METHODS`). The `TServer` bound carries
+ * `ReferenceServerProtocol`, so the delegates are type-checked without casts.
+ *
+ * A frontend needing both fragments extends the diagnostics base and mixes
+ * these three in, or vice versa — TypeScript allows only one base class, so
+ * the two bases are deliberately independent rather than chained. Chaining
+ * them would force every reference-fragment adopter to also carry the
+ * diagnostics surface, which a head that dropped those methods via
+ * `DataServerOptions.excludedMethods` cannot satisfy.
+ */
+export abstract class AbstractReferencesDataServiceFrontend<
+   TTransfer extends TransferElement,
+   TServer extends { waitForReady(): Promise<void> } & ReferenceServerProtocol<TTransfer>,
+   TClient extends object
+>
+   extends AbstractDataServiceFrontend<TServer, TClient>
+   implements ReferenceServerProtocol<TTransfer>
+{
+   async findReferenceCandidates(ctx: ReferenceContext): Promise<ReferenceCandidate[]> {
+      await this.ensureConnected();
+      return this.server.findReferenceCandidates(ctx);
+   }
+
+   async resolveReference(ref: ReferenceRequest): Promise<ReferenceTarget<TTransfer> | undefined> {
+      await this.ensureConnected();
+      return this.server.resolveReference(ref);
+   }
+
+   async findNextName(args: FindNextNameArgs): Promise<string> {
+      await this.ensureConnected();
+      return this.server.findNextName(args);
+   }
+}

package/src/browser/workspace-gate.ts

@@ -0,0 +1,35 @@
+/********************************************************************************
+ * 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 WorkspaceService } from '@theia/workspace/lib/browser';
+
+/**
+ * Resolve once a workspace is open (one or more roots present). Resolves
+ * immediately if a workspace is already open, otherwise on the first
+ * `onWorkspaceChanged` that reports roots — the listener disposes itself.
+ *
+ * The common Theia gate for a data-server head: the model-server only starts
+ * once the LSP launches for a workspace, so connecting earlier would hang on
+ * port discovery. Pass the returned promise as
+ * `OpenChannelConnectionOptions.whenReady`.
+ */
+export function whenWorkspaceOpen(workspaceService: WorkspaceService): Promise<void> {
+   const roots = workspaceService.tryGetRoots();
+   if (roots && roots.length > 0) {
+      return Promise.resolve();
+   }
+   return new Promise<void>(resolve => {
+      const disposable = workspaceService.onWorkspaceChanged(changedRoots => {
+         if (changedRoots && changedRoots.length > 0) {
+            disposable.dispose();
+            resolve();
+         }
+      });
+   });
+}

package/src/common/emitter-data-client.ts

@@ -0,0 +1,64 @@
+/********************************************************************************
+ * 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 {
+   DataClientProtocol,
+   Project,
+   ProjectsChangedEvent,
+   TransferDiagnostic,
+   TransferDocumentSavedEvent,
+   TransferDocumentUpdatedEvent,
+   TransferElement
+} from '@hydranium/protocol';
+import { Emitter, type Event } from '@theia/core';
+
+/**
+ * Default {@link DataClientProtocol} implementation for a Theia frontend:
+ * each inbound `on*` notification is fanned out to a Theia {@link Event} so
+ * multiple local listeners can subscribe (the framework deliberately leaves
+ * fan-out to the consumer — see `DataClientProtocol`).
+ *
+ * Bind an instance as the `localTarget` of the frontend's `createRpcProxy`
+ * (with `DATA_CLIENT_PROTOCOL_METHODS` as `localMethods`); incoming
+ * `<namespace>onDocumentUpdated` etc. dispatch to the matching method here,
+ * which fires the paired `Event`.
+ *
+ * Adopters subclass to add signals that are not wire notifications, or to
+ * expose domain-renamed aliases of these channels — the event getters stay
+ * accessible to the subclass.
+ */
+export class EmitterDataClient<
+   TTransfer extends TransferElement,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TProject extends Project = Project
+> implements DataClientProtocol<TTransfer, TDiagnostic, TProject> {
+   protected readonly onDocumentUpdatedEmitter = new Emitter<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>();
+   /** Fires for each inbound {@link onDocumentUpdated} notification. */
+   readonly onDidUpdateDocument: Event<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>> = this.onDocumentUpdatedEmitter.event;
+
+   protected readonly onDocumentSavedEmitter = new Emitter<TransferDocumentSavedEvent<TTransfer, TDiagnostic>>();
+   /** Fires for each inbound {@link onDocumentSaved} notification. */
+   readonly onDidSaveDocument: Event<TransferDocumentSavedEvent<TTransfer, TDiagnostic>> = this.onDocumentSavedEmitter.event;
+
+   protected readonly onProjectsChangedEmitter = new Emitter<ProjectsChangedEvent<TProject>>();
+   /** Fires for each inbound {@link onProjectsChanged} notification. */
+   readonly onDidChangeProjects: Event<ProjectsChangedEvent<TProject>> = this.onProjectsChangedEmitter.event;
+
+   onDocumentUpdated(event: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>): void {
+      this.onDocumentUpdatedEmitter.fire(event);
+   }
+
+   onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): void {
+      this.onDocumentSavedEmitter.fire(event);
+   }
+
+   onProjectsChanged(event: ProjectsChangedEvent<TProject>): void {
+      this.onProjectsChangedEmitter.fire(event);
+   }
+}

package/src/common/index.ts

@@ -0,0 +1,21 @@
+/********************************************************************************
+ * 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-agnostic shared surface for the data-server-head Theia
+// integration. A module lands here only when its whole dependency closure —
+// values, types and relative imports alike — is either neutral or Theia's
+// COMMON tier; `@theia/core`'s root entry is that tier, while anything reaching
+// `@theia/*/lib/browser` or `/lib/node` belongs in the tier it names, even when
+// the import is type-only and erases at runtime.
+//
+// This tier deliberately holds no error-reconstruction bridge, and that is a
+// property of the transport rather than an omission: the direct vscode-jsonrpc
+// connection carries a typed error such as `ConflictError` across the channel
+// relay natively, with no Theia msgpack hop to drop its data.
+export * from './emitter-data-client';

package/src/index.ts

@@ -0,0 +1,18 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Root barrel, deliberately empty: this package integrates a host whose own
+// packages declare no root entry, so a consumer names a tier. The
+// environment-agnostic surface is `@hydranium/data-client-theia/common`,
+// browser-side primitives (channel transport / proxy wiring) are
+// `.../browser`, and node-side ones (connection bootstrap) are `.../node`, so
+// env-specific imports cannot leak into the wrong bundle. Re-exporting `common/`
+// from here would make the root a partial surface that hides which tier a
+// symbol lives on, which is the ambiguity the split exists to remove.
+export {};

package/src/node/connection-container-module.ts

@@ -0,0 +1,51 @@
+/********************************************************************************
+ * 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 { ConnectionHandler } from '@theia/core';
+import { ConnectionContainerModule } from '@theia/core/lib/node/messaging/connection-container-module';
+import { ContainerModule, type interfaces } from '@theia/core/shared/inversify';
+
+/**
+ * Creates the frontend-scoped Theia backend module that registers a
+ * data-server {@link ConnectionHandler} (a `DataServerConnectionHandler`
+ * subclass) per browser-frontend connection. Returns a ready-to-export
+ * `ContainerModule` so adopters can
+ * `export default createDataServerConnectionContainerModule(MyHandler)` from
+ * their backend-module entry point.
+ *
+ * Sibling of `@hydranium/glsp-client-theia`'s
+ * `createGlspConnectionContainerModule` — the `ContainerModule +
+ * ConnectionContainerModule.create` boilerplate every frontend-scoped Theia
+ * connection adopter writes by hand, lifted so adopters declare only the
+ * handler class.
+ *
+ * **More than one handler is the normal case, not an exotic one.** Theia keys a
+ * frontend channel by its service path and refuses a second channel on a path
+ * already open, so every frontend abstraction reaching the data head needs its
+ * own path and therefore its own handler — a host-neutral `DataPort` beside a
+ * Theia `AbstractDataServiceFrontend` is exactly that shape. They still forward
+ * to the SAME data server: the path distinguishes the channel, the shared
+ * `portCommand` names the one process behind it.
+ */
+export function createDataServerConnectionContainerModule(...handlerClasses: interfaces.Newable<ConnectionHandler>[]): ContainerModule {
+   const frontendScopedConnectionModule = ConnectionContainerModule.create(({ bind }) => {
+      for (const handlerClass of handlerClasses) {
+         bind(handlerClass).toSelf().inSingletonScope();
+         // `toDynamicValue` over `to(handlerClass)`: `ConnectionHandler` is
+         // multi-bound here, and resolving through the container keeps each
+         // entry the SAME singleton the adopter can inject by its own class.
+         bind(ConnectionHandler)
+            .toDynamicValue(context => context.container.get(handlerClass))
+            .inSingletonScope();
+      }
+   });
+   return new ContainerModule(bind => {
+      bind(ConnectionContainerModule).toConstantValue(frontendScopedConnectionModule);
+   });
+}

package/src/node/data-server-connection-handler.ts

@@ -0,0 +1,76 @@
+/********************************************************************************
+ * 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 { AbstractSocketForwardingConnectionHandler } from '@hydranium/client-theia/lib/node';
+import { DATA_SERVER_PATH, DATA_SERVER_PORT_COMMAND } from '@hydranium/protocol';
+import { type Channel, type Disposable } from '@theia/core';
+import { injectable, unmanaged } from '@theia/core/shared/inversify';
+import type * as net from 'node:net';
+import { SocketChannelForwarder } from './socket-channel-forwarder';
+
+/** Options for {@link DataServerConnectionHandler}. `servicePath` is the Theia
+ *  service path the browser frontend opens a channel to; `portCommand` is the
+ *  command id whose return value is the data-server's listening port (the
+ *  data-server publishes it on the LSP connection at startup, the same handshake
+ *  GLSP uses). */
+export interface DataServerConnectionHandlerOptions {
+   /** Theia service path the browser frontend opens a channel to. Defaults to
+    *  the framework `DATA_SERVER_PATH`; override for an adopter-specific path,
+    *  and NECESSARILY when a second frontend reaches the same head — Theia
+    *  refuses a second channel on a path already open, so paths are per
+    *  FRONTEND while `portCommand` stays per server. */
+   readonly servicePath?: string;
+   /** Command id whose return value is the data-server's listening port.
+    *  Defaults to the framework `DATA_SERVER_PORT_COMMAND`; override to match
+    *  an adopter's established id. */
+   readonly portCommand?: string;
+   readonly findPortTimeout?: number;
+   readonly findPortAttempts?: number;
+   readonly connectTimeoutMs?: number;
+   /**
+    * Optional diagnostic hook called immediately after the outbound
+    * `net.Socket` to the data-server is created, BEFORE `socket.connect()` is
+    * invoked. Adopters attach `'data'` / `'close'` listeners here for
+    * byte-level observability when debugging wire-level issues; attaching
+    * before `connect()` guarantees the very first bytes are observed.
+    */
+   readonly onSocketCreated?: (socket: net.Socket) => void;
+}
+
+/**
+ * Bridges a Theia browser-frontend channel to a data-server's TCP socket — the
+ * backend half of the data-server head's transport.
+ *
+ * The port-discovery + buffer-and-replay race fix + connect orchestration live
+ * on the cross-head {@link AbstractSocketForwardingConnectionHandler} base; this
+ * subclass supplies only the data-server defaults (service path / port command /
+ * log labels) and plugs in {@link SocketChannelForwarder} as the byte relay —
+ * its own forwarder, so the data head carries no GLSP dependency. Sibling of
+ * `@hydranium/glsp-client-theia`'s `GlspServerConnectionHandler`, which
+ * subclasses the same base with `@eclipse-glsp`'s `SocketConnectionForwarder`.
+ */
+@injectable()
+export class DataServerConnectionHandler extends AbstractSocketForwardingConnectionHandler {
+   constructor(@unmanaged() options: DataServerConnectionHandlerOptions = {}) {
+      super({
+         path: options.servicePath ?? DATA_SERVER_PATH,
+         portCommand: options.portCommand ?? DATA_SERVER_PORT_COMMAND,
+         logComponent: 'DataServer',
+         serverName: 'Model Server',
+         findPortTimeout: options.findPortTimeout,
+         findPortAttempts: options.findPortAttempts,
+         connectTimeoutMs: options.connectTimeoutMs,
+         onSocketCreated: options.onSocketCreated
+      });
+   }
+
+   protected forwardToSocketConnection(clientChannel: Channel, socket: net.Socket): Disposable {
+      return new SocketChannelForwarder(clientChannel, socket);
+   }
+}

package/src/node/host-diagnostics-server.ts

@@ -0,0 +1,57 @@
+/********************************************************************************
+ * 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 { formatProcessMemory, writeHeapSnapshotToDir } from '@hydranium/core/lib/node';
+import {
+   HOST_DIAGNOSTICS_PATH,
+   type DumpHostStateArgs,
+   type HostDiagnosticsProtocol,
+   type WriteHostHeapSnapshotArgs
+} from '@hydranium/protocol';
+import { ConnectionHandler, RpcConnectionHandler } from '@theia/core';
+import { ContainerModule, injectable } from '@theia/core/shared/inversify';
+
+/**
+ * Host-process diagnostics, computed IN the Theia backend process this service
+ * runs in (the parent / host, distinct from the data-server child that holds the
+ * model store). Universal — `process.memoryUsage()` always works — so the
+ * framework wires it by default. Each result is also written to the backend's
+ * stdout so it reaches the pod log (`kubectl logs`), not only the RPC caller.
+ */
+@injectable()
+export class HostDiagnosticsServer implements HostDiagnosticsProtocol {
+   async dumpHostState(args: DumpHostStateArgs): Promise<string> {
+      const snapshot = formatProcessMemory(args.label ? `Host backend state (${args.label})` : 'Host backend state');
+      console.info(snapshot);
+      return snapshot;
+   }
+
+   async writeHostHeapSnapshot(args: WriteHostHeapSnapshotArgs): Promise<string> {
+      const filePath = writeHeapSnapshotToDir(args.directory, args.label ?? 'backend', 'heap-backend');
+      console.info(`Host heap snapshot written to ${filePath}`);
+      return filePath;
+   }
+}
+
+/**
+ * Theia backend module that exposes {@link HostDiagnosticsServer} as an ordinary
+ * in-process RPC service at {@link HOST_DIAGNOSTICS_PATH} (not the socket-
+ * forwarded data-server transport). The frontend reaches it with
+ * `bindHostDiagnostics` (see `../browser`). Adopters
+ * `export default createHostDiagnosticsBackendModule()` from a backend-module
+ * entry point.
+ */
+export function createHostDiagnosticsBackendModule(): ContainerModule {
+   return new ContainerModule(bind => {
+      bind(HostDiagnosticsServer).toSelf().inSingletonScope();
+      bind(ConnectionHandler)
+         .toDynamicValue(context => new RpcConnectionHandler(HOST_DIAGNOSTICS_PATH, () => context.container.get(HostDiagnosticsServer)))
+         .inSingletonScope();
+   });
+}

package/src/node/index.ts

@@ -0,0 +1,13 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+export * from './connection-container-module';
+export * from './data-server-connection-handler';
+export * from './host-diagnostics-server';
+export * from './socket-channel-forwarder';

package/src/node/socket-channel-forwarder.ts

@@ -0,0 +1,64 @@
+/********************************************************************************
+ * 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 Channel, Disposable, DisposableCollection, type MessageProvider } from '@theia/core';
+import type * as net from 'node:net';
+import { createMessageConnection, type Message, SocketMessageReader, SocketMessageWriter } from 'vscode-jsonrpc/node';
+
+/**
+ * Relays JSON-RPC messages between a Theia browser-frontend {@link Channel} and
+ * a data-server's TCP socket — the backend half of the data-server head's
+ * transport. The model-server speaks vscode-jsonrpc (Content-Length framed) on
+ * the socket; the frontend speaks the same protocol over the channel (via
+ * `createChannelConnection`). This forwarder decodes each side and re-emits on
+ * the other, so the two ends share one protocol with no semantic re-proxy in
+ * between.
+ *
+ * Framework-owned equivalent of `@eclipse-glsp/theia-integration`'s
+ * `SocketConnectionForwarder` — reproduced here (rather than imported) so the
+ * data-server head carries no GLSP dependency.
+ */
+export class SocketChannelForwarder implements Disposable {
+   protected readonly toDispose = new DisposableCollection();
+
+   constructor(
+      protected readonly channel: Channel,
+      protected readonly socket: net.Socket
+   ) {
+      const reader = new SocketMessageReader(socket);
+      const writer = new SocketMessageWriter(socket);
+      const connection = createMessageConnection(reader, writer);
+      this.toDispose.pushAll([
+         connection.onClose(() => socket.destroy()),
+         reader.listen(message => this.writeToChannel(message)),
+         channel.onMessage(provider => void writer.write(this.decodeChannelMessage(provider))),
+         channel.onClose(() => connection.dispose()),
+         connection.onClose(() => channel.close()),
+         Disposable.create(() => {
+            channel.close();
+            connection.dispose();
+         })
+      ]);
+   }
+
+   protected decodeChannelMessage(provider: MessageProvider): Message {
+      const buffer = provider().readBytes();
+      return JSON.parse(new TextDecoder().decode(buffer)) as Message;
+   }
+
+   protected writeToChannel(message: Message): void {
+      const writeBuffer = this.channel.getWriteBuffer();
+      writeBuffer.writeBytes(new TextEncoder().encode(JSON.stringify(message)));
+      writeBuffer.commit();
+   }
+
+   dispose(): void {
+      this.toDispose.dispose();
+   }
+}