@hydranium/data-client-theia 1.0.0-next.6 → 1.0.0-next.61

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

@@ -7,11 +7,17 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { createRpcProxy } from '@hydranium/protocol';
+import {
+   type DataPort,
+   type ReadyServer,
+   type ResolvedMessage,
+   RpcConnection,
+   type RpcProxy,
+   renderFrameworkMessage
+} from '@hydranium/protocol';
+import { Emitter, nls, type MessageService } from '@theia/core';
 import type { ServiceConnectionProvider } from '@theia/core/lib/browser';
-import { Deferred } from '@theia/core/lib/common/promise-util';
 import type { WorkspaceService } from '@theia/workspace/lib/browser';
-import type { MessageConnection } from 'vscode-jsonrpc';
 import { type ChannelConnectionHandle, openChannelConnection } from './channel-connection';
 import { whenWorkspaceOpen } from './workspace-gate';
 
@@ -28,138 +34,116 @@ import { whenWorkspaceOpen } from './workspace-gate';
  * the local notification target `TClient`. A subclass supplies the abstract
  * members below, calls {@link start} from its `@postConstruct`, and awaits
  * {@link ensureConnected} before its first `this.server.*` call.
+ *
+ * The lifecycle is `RpcConnection`'s — the same proxy, readiness gate and
+ * reconnect generation the host-neutral tier uses. What stays here is the Theia
+ * half: the channel, the workspace gate and the notification sink.
  */
-export abstract class AbstractDataServiceFrontend<TServer extends { waitForReady(): Promise<void> }, TClient extends object> {
-   /**
-    * The workspace-gated connection to the backend forwarder. Set by
-    * {@link start}, and REPLACED whenever the connection is lost and
-    * {@link reconnectOnConnectionLoss} is on — so read it per use and never
-    * cache the resolved connection.
-    */
-   protected connectionPromise!: Promise<MessageConnection>;
-   /**
-    * Typed proxy over {@link connectionPromise}, addressing the server under
-    * {@link methodNamespace}. Set by {@link start}, and replaced alongside
-    * {@link connectionPromise} on reconnect.
-    *
-    * `createRpcProxy` resolves the connection promise once and binds to it for
-    * good, so a reconnect necessarily means a new proxy. Reading
-    * `this.server.foo()` per call — rather than hoisting `this.server` into a
-    * local or a constructor-time field — is what keeps a subclass correct
-    * across one.
-    */
-   protected server!: TServer;
-   /** The channel handle {@link start} opened; owns reconnect and disposal. */
-   protected channel?: ChannelConnectionHandle;
-   /** Shared init Deferred so concurrent {@link ensureConnected} callers await one initialization. */
-   protected initialized?: Deferred<void>;
-
-   /** Theia connection provider the channel is opened through. */
+export abstract class AbstractDataServiceFrontend<TServer extends ReadyServer, TClient extends object> {
    protected abstract readonly connectionProvider: ServiceConnectionProvider;
-   /**
-    * Optional workspace service. When provided, the default
-    * {@link connectionReadyGate} waits for a workspace before opening the
-    * channel; a head that is not workspace-scoped omits it (and may override
-    * {@link connectionReadyGate} for a different gate).
-    */
    protected abstract readonly workspaceService?: WorkspaceService;
-   /** Local inbound-notification target bound on the connection (the `localTarget`). */
    protected abstract readonly client: TClient;
-   /**
-    * Theia service path the backend forwarder is registered under.
-    *
-    * **Unique per frontend, not per server.** Theia keys a frontend channel by
-    * this path and throws `Another channel with the id '<path>' is already open`
-    * on a second opener — so a subclass sharing the framework default with any
-    * other consumer of the same head (a host-neutral `DataPort`, a sibling
-    * service frontend) breaks whichever opens second. The failure is remote from
-    * its cause: the throw escapes an `openChannelConnection` the other consumer
-    * awaited, leaving its request permanently unsettled rather than rejected,
-    * which presents as a view stuck on its loading state with a clean server
-    * log. Give each frontend its own path and register a forwarder per path;
-    * they still reach one server, since the shared `portCommand` is what names
-    * the process.
-    */
+   /** Frontend service path the backend forwarder for this head is registered under. */
    protected abstract readonly servicePath: string;
-   /** Wire namespace the server + client methods are addressed under. */
    protected abstract readonly methodNamespace: string;
    /** Allowlist of {@link client} methods to bind as inbound handlers. */
    protected abstract readonly clientMethods: readonly (keyof TClient & string)[];
 
+   /** Surfaces a transport failure. Optional: a frontend with no UI of its own omits it. */
+   protected readonly messageService?: MessageService;
+
    /**
-    * Rebuild the connection and the proxy when the current connection is lost,
-    * and re-run initialization against the replacement. Defaults to `true` —
-    * see `OpenChannelConnectionOptions.reconnect` for why re-opening the
-    * channel is the only thing that recovers a restarted language server, and
-    * why a dead connection leaves no alternative worth preserving.
-    *
-    * The subclass-facing cost is that {@link doInitialize} runs again per
-    * connection, so any progress UI it drives reappears. Turn this off for a
-    * frontend that would rather show nothing than show its warm-up twice, or
-    * that tears itself down on transport loss.
+    * Rebuild the connection when the current one is lost. Defaults to `true` —
+    * re-opening the channel is the only thing that recovers a restarted
+    * language server, which binds new ephemeral ports. Turn it off for a
+    * frontend that would rather tear itself down than show its warm-up twice.
     */
    protected readonly reconnectOnConnectionLoss: boolean = true;
 
+   protected channel?: ChannelConnectionHandle;
+   protected connection?: RpcConnection<TServer, TClient>;
+   protected readonly lossEmitter = new Emitter<void>();
+
    /**
     * Readiness gate for the connection — the channel opens only once the
     * returned promise settles. Default: waits for a workspace when
-    * {@link workspaceService} is provided, otherwise opens immediately
-    * (`undefined`). Override for a different gate (e.g. a fixed model store
-    * that is always ready, or a custom warm-up).
+    * {@link workspaceService} is provided, otherwise opens immediately.
     */
    protected connectionReadyGate(): Promise<void> | undefined {
       return this.workspaceService ? whenWorkspaceOpen(this.workspaceService) : undefined;
    }
 
+   /** A connection generation is opening, including on each reconnect. */
+   protected onConnecting(): void {
+      // nothing by default
+   }
+
+   /** The server's readiness gate has settled for a generation. */
+   protected onReady(): void {
+      // nothing by default
+   }
+
+   /** A generation failed; the awaiting caller still rejects. */
+   protected onFailed(_error: unknown): void {
+      // nothing by default
+   }
+
    /**
-    * Open the connection (workspace-gated by default via
-    * {@link connectionReadyGate}) and build the combined server proxy +
-    * inbound client binding. Call once (typically from the adopter's
-    * `@postConstruct`). Outbound calls + inbound notifications queue over the
-    * connection promise until the channel is live.
+    * Open the channel and build the connection over it. Call once, typically
+    * from the adopter's `@postConstruct`. Outbound calls and inbound
+    * notifications queue until the channel is live.
     */
    protected start(): void {
       this.channel = openChannelConnection(this.connectionProvider, this.servicePath, {
          whenReady: this.connectionReadyGate(),
          reconnect: this.reconnectOnConnectionLoss
       });
-      this.bindConnection();
-      // The LOSS, not the replacement's arrival: rebinding when the channel
-      // closes points `server` at the queueing replacement promise, so a request
-      // made during the gap waits for the new server instead of being addressed
-      // at the dead one and never settling.
-      this.channel.onDidLoseConnection(() => this.handleConnectionLost());
+      // The LOSS, not the replacement's arrival: the connection drops its
+      // generation here, so a request made during the gap waits for the fresh
+      // one instead of addressing the dead one and never settling.
+      this.channel.onDidLoseConnection(() => this.lossEmitter.fire(undefined));
+      this.connection = new RpcConnection<TServer, TClient>(this.channelPort(), this.client, {
+         methodNamespace: this.methodNamespace,
+         clientMethods: this.clientMethods,
+         lifecycle: {
+            onConnecting: () => this.onConnecting(),
+            onReady: () => this.onReady(),
+            onFailed: error => this.onFailed(error)
+         }
+      });
+   }
+
+   /** The channel as a {@link DataPort} — the whole Theia-specific half. */
+   protected channelPort(): DataPort {
+      return {
+         // Read per call: `current` is repointed on every re-open, so reaching
+         // through the handle is what makes a later generation find the live
+         // server.
+         connect: () => this.requireChannel().current,
+         reportError: (_error, reported) => this.reportError(reported),
+         onDispose: this.lossEmitter.event
+      };
+   }
+
+   /** Surface a transport failure the way this host does. */
+   protected reportError(reported: ResolvedMessage): void {
+      this.messageService?.error(renderFrameworkMessage(reported, nls.localization?.translations));
    }
 
    /**
-    * Point {@link connectionPromise} and {@link server} at the channel's
-    * current connection. Called by {@link start} and again per reconnect.
+    * The server proxy. Calls queue against the connection, so await
+    * {@link ensureConnected} first wherever the server's readiness matters.
     */
-   protected bindConnection(): void {
-      if (!this.channel) {
-         throw new Error('bindConnection called before start');
-      }
-      this.connectionPromise = this.channel.current;
-      this.server = createRpcProxy<TServer, TClient>(this.connectionPromise, {
-         methodNamespace: this.methodNamespace,
-         localTarget: this.client,
-         localMethods: this.clientMethods
-      });
+   protected get server(): RpcProxy<TServer> {
+      return this.requireConnection().server;
    }
 
    /**
-    * Rebind onto the replacement connection and arm initialization to run again.
-    *
-    * Clearing {@link initialized} is the load-bearing half. A restarted server
-    * has an unwarmed workspace, so its `waitForReady` gate has to be awaited
-    * afresh; leaving the old resolved Deferred in place would let the first
-    * request after a restart through against a server still walking the
-    * workspace, and be answered correctly from an empty registry — which reads
-    * as data loss rather than as a race.
+    * Await the connection and the server's readiness gate, shared across
+    * concurrent callers and re-run once per connection generation.
     */
-   protected handleConnectionLost(): void {
-      this.initialized = undefined;
-      this.bindConnection();
+   protected async ensureConnected(): Promise<void> {
+      await this.requireConnection().connected();
    }
 
    /**
@@ -170,39 +154,24 @@ export abstract class AbstractDataServiceFrontend<TServer extends { waitForReady
     * lifecycle of its own.
     */
    dispose(): void {
+      this.connection?.dispose();
+      this.connection = undefined;
       this.channel?.dispose();
       this.channel = undefined;
-      this.initialized = undefined;
+      this.lossEmitter.dispose();
    }
 
-   /**
-    * Lazily drive initialization, shared across concurrent callers via one
-    * {@link Deferred}. Request methods `await this.ensureConnected()` before
-    * their first `this.server.*` call.
-    */
-   protected ensureConnected(): Promise<void> {
-      if (!this.initialized) {
-         this.initialized = new Deferred<void>();
-         void this.doInitialize(this.initialized);
+   protected requireConnection(): RpcConnection<TServer, TClient> {
+      if (!this.connection) {
+         throw new Error('the connection is not open: call start() first');
       }
-      return this.initialized.promise;
+      return this.connection;
    }
 
-   /**
-    * Default initialization: await the connection, await the server's readiness
-    * gate, then resolve the passed Deferred. Initialization completion is
-    * observable by awaiting {@link ensureConnected} (which returns this same
-    * Deferred's promise) — there is no separate post-init hook. Override
-    * wholesale to interleave progress UI / extra warm-up; an override owns
-    * resolving/rejecting `initialized` (there is no `super` step to call).
-    */
-   protected async doInitialize(initialized: Deferred<void>): Promise<void> {
-      try {
-         await this.connectionPromise;
-         await this.server.waitForReady();
-         initialized.resolve();
-      } catch (error) {
-         initialized.reject(error instanceof Error ? error : new Error(String(error)));
+   protected requireChannel(): ChannelConnectionHandle {
+      if (!this.channel) {
+         throw new Error('the channel is not open: call start() first');
       }
+      return this.channel;
    }
 }

package/src/browser/index.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 export * from './channel-connection';
+export * from './channel-data-port';
 export * from './data-service-frontend';
 export * from './diagnostics-data-service-frontend';
 export * from './host-diagnostics-frontend';

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

@@ -12,7 +12,9 @@ import type {
    Project,
    ProjectsChangedEvent,
    TransferDiagnostic,
+   TransferDocumentDeletedEvent,
    TransferDocumentSavedEvent,
+   TransferDocumentsBuiltEvent,
    TransferDocumentUpdatedEvent,
    TransferElement
 } from '@hydranium/protocol';
@@ -46,6 +48,14 @@ export class EmitterDataClient<
    /** Fires for each inbound {@link onDocumentSaved} notification. */
    readonly onDidSaveDocument: Event<TransferDocumentSavedEvent<TTransfer, TDiagnostic>> = this.onDocumentSavedEmitter.event;
 
+   protected readonly onDocumentDeletedEmitter = new Emitter<TransferDocumentDeletedEvent>();
+   /** Fires for each inbound {@link onDocumentDeleted} notification. */
+   readonly onDidDeleteDocument: Event<TransferDocumentDeletedEvent> = this.onDocumentDeletedEmitter.event;
+
+   protected readonly onDocumentsBuiltEmitter = new Emitter<TransferDocumentsBuiltEvent>();
+   /** Fires for each inbound {@link onDocumentsBuilt} notification. */
+   readonly onDidBuildDocuments: Event<TransferDocumentsBuiltEvent> = this.onDocumentsBuiltEmitter.event;
+
    protected readonly onProjectsChangedEmitter = new Emitter<ProjectsChangedEvent<TProject>>();
    /** Fires for each inbound {@link onProjectsChanged} notification. */
    readonly onDidChangeProjects: Event<ProjectsChangedEvent<TProject>> = this.onProjectsChangedEmitter.event;
@@ -58,6 +68,14 @@ export class EmitterDataClient<
       this.onDocumentSavedEmitter.fire(event);
    }
 
+   onDocumentDeleted(event: TransferDocumentDeletedEvent): void {
+      this.onDocumentDeletedEmitter.fire(event);
+   }
+
+   onDocumentsBuilt(event: TransferDocumentsBuiltEvent): void {
+      this.onDocumentsBuiltEmitter.fire(event);
+   }
+
    onProjectsChanged(event: ProjectsChangedEvent<TProject>): void {
       this.onProjectsChangedEmitter.fire(event);
    }

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

@@ -30,6 +30,16 @@ export interface DataServerConnectionHandlerOptions {
     *  Defaults to the framework `DATA_SERVER_PORT_COMMAND`; override to match
     *  an adopter's established id. */
    readonly portCommand?: string;
+   /**
+    * Product name for the connect-failure dialog this handler raises.
+    *
+    * It reaches the adopter's UI verbatim, so the framework default leaks a
+    * framework noun into a product that is not ours. Not a translation concern —
+    * routing it through a catalogue would ask an adopter to "translate" English
+    * into their own product name, and would make their branding
+    * locale-dependent.
+    */
+   readonly serverName?: string;
    readonly findPortTimeout?: number;
    readonly findPortAttempts?: number;
    readonly connectTimeoutMs?: number;
@@ -62,7 +72,7 @@ export class DataServerConnectionHandler extends AbstractSocketForwardingConnect
          path: options.servicePath ?? DATA_SERVER_PATH,
          portCommand: options.portCommand ?? DATA_SERVER_PORT_COMMAND,
          logComponent: 'DataServer',
-         serverName: 'Model Server',
+         serverName: options.serverName ?? 'Model Server',
          findPortTimeout: options.findPortTimeout,
          findPortAttempts: options.findPortAttempts,
          connectTimeoutMs: options.connectTimeoutMs,

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

@@ -34,8 +34,13 @@ export class SocketChannelForwarder implements Disposable {
       const reader = new SocketMessageReader(socket);
       const writer = new SocketMessageWriter(socket);
       const connection = createMessageConnection(reader, writer);
+      // Nothing here destroys the socket, and adding it back would be dead
+      // code in both directions. `SocketMessageWriter.dispose()` destroys it
+      // itself, which covers the dispose path; and `connection.onClose` fires
+      // only from the reader's or writer's own close, which for a socket means
+      // the socket has already gone — so a destroy handler there is downstream
+      // of the effect it would be trying to cause.
       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()),