@hydranium/data-client-vscode 0.0.0-stage → 1.0.0-next.315

package/src/browser/webview-data-port.ts

@@ -0,0 +1,115 @@
+/********************************************************************************
+ * 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 {
+   createPostMessageTransport,
+   renderFrameworkMessage,
+   type DataPort,
+   type Logger,
+   type PostMessageChannel,
+   type ResolvedMessage
+} from '@hydranium/protocol';
+import { Emitter, type Event, type MessageConnection } from 'vscode-jsonrpc';
+import { createMessageConnection } from 'vscode-jsonrpc/browser';
+
+/** Options for {@link WebviewDataPort}. */
+export interface WebviewDataPortOptions {
+   /**
+    * Surface a data-head failure. Without one it goes to the webview's console;
+    * a webview whose extension shows notifications forwards it there instead.
+    */
+   readonly reportError?: (error: unknown, reported: ResolvedMessage) => void;
+   /** Where the connection logs its protocol faults, and what it does on its own. */
+   readonly logger?: Logger;
+}
+
+/**
+ * The webview's {@link DataPort}: the sandbox side of the data head, over the
+ * extension host's messenger hop.
+ *
+ * `vscode-jsonrpc/browser`, not the package root, which installs no runtime
+ * abstraction layer and throws on the first message rather than at wire-up.
+ */
+export class WebviewDataPort implements DataPort {
+   protected readonly disposeEmitter = new Emitter<void>();
+   readonly onDispose: Event<void> = this.disposeEmitter.event;
+   readonly logger?: Logger;
+   protected disposed = false;
+   /** The connection every generation gets until it is disposed. */
+   protected connection?: MessageConnection;
+
+   constructor(
+      protected readonly channel: PostMessageChannel,
+      protected readonly options: WebviewDataPortOptions = {}
+   ) {
+      this.logger = options.logger;
+   }
+
+   /**
+    * Hand back a listening connection over the hop: the same one until it is
+    * disposed, and then a fresh transport, so a disposed connection leaves no
+    * second reader on the pipe.
+    *
+    * Every connection reaches the one relay behind the pipe, and each numbers
+    * its requests from zero, so a second live one would take answers meant for
+    * the first. A retry after a failed readiness check therefore gets the
+    * connection the check used.
+    */
+   async connect(): Promise<MessageConnection> {
+      if (this.disposed) {
+         throw new Error('WebviewDataPort: the port is disposed');
+      }
+      if (!this.connection) {
+         const transport = createPostMessageTransport(this.channel);
+         const connection = createMessageConnection(transport.reader, transport.writer, this.logger);
+         connection.onDispose(() => {
+            transport.dispose();
+            if (this.connection === connection) {
+               this.connection = undefined;
+            }
+         });
+         connection.listen();
+         this.connection = connection;
+      }
+      return this.connection;
+   }
+
+   reportError(error: unknown, reported: ResolvedMessage): void {
+      if (this.options.reportError) {
+         this.options.reportError(error, reported);
+      } else {
+         console.error(`[data head] ${renderFrameworkMessage(reported)}`, error);
+      }
+   }
+
+   /**
+    * The extension host reports the relay's framed side died.
+    *
+    * A `PostMessageChannel` has no `close()`, so the pipe still looks open from
+    * here: firing `onDispose` makes `DataConnection` drop its generation, and
+    * disposing the connection rejects everything in flight, also when no
+    * generation holds it. The connection is forgotten before the event, so a
+    * listener that connects gets a fresh one rather than the one about to be
+    * disposed.
+    */
+   connectionLost(): void {
+      const lost = this.connection;
+      this.connection = undefined;
+      this.disposeEmitter.fire();
+      lost?.dispose();
+   }
+
+   /** Refuses to connect afterwards: the consumer's reconnect would otherwise open a reader nothing releases. */
+   dispose(): void {
+      this.disposed = true;
+      this.disposeEmitter.fire();
+      this.disposeEmitter.dispose();
+      this.connection?.dispose();
+   }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Neutral: the messenger channel both ends of the hop build on, free of
+// `vscode`, Node and the DOM. The extension host's end is `./node`, the
+// webview's `./browser`.
+export * from './messenger-channel';

package/src/messenger-channel.ts

@@ -0,0 +1,224 @@
+/********************************************************************************
+ * 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 { PostMessageChannel } from '@hydranium/protocol';
+import type { Disposable, Message } from 'vscode-jsonrpc';
+
+/**
+ * A notification type as `vscode-messenger` defines it: a method name, with the
+ * payload type carried only in the generic parameter.
+ *
+ * Restated rather than imported: `vscode-messenger-common`'s
+ * `NotificationType<P>` is `{ method: string }` with `P` phantom, and the import
+ * would pin the adopter's messenger copy, which GLSP's VS Code integration
+ * chooses.
+ */
+export interface NotificationTypeLike {
+   readonly method: string;
+}
+
+/**
+ * The one method both ends of the hop share: hand a message to a participant.
+ *
+ * `TParticipant` stays generic because the two ends address different things,
+ * the extension side a registered webview and the webview side
+ * `HOST_EXTENSION`.
+ */
+export interface MessengerSendLike<TParticipant> {
+   sendNotification(type: NotificationTypeLike, receiver: TParticipant, params?: Message): void;
+}
+
+/**
+ * The two methods the channel needs from the **extension-side** messenger.
+ *
+ * Two methods rather than the class, so any messenger with them fits, GLSP's
+ * included, without pinning a `vscode-messenger` copy.
+ */
+export interface MessengerLike<TParticipant> extends MessengerSendLike<TParticipant> {
+   onNotification(
+      type: NotificationTypeLike,
+      handler: (params: Message, sender: TParticipant) => void,
+      options?: { sender?: TParticipant }
+   ): Disposable;
+}
+
+/**
+ * The **webview-side** messenger, which differs from the extension side in
+ * every point the channel depends on:
+ *
+ * - **`onNotification` returns the messenger itself**, not a `Disposable`, and
+ *   there is no unregister API, so a registration lasts as long as the webview.
+ *   {@link createMessengerChannel} therefore stops delivering through a flag.
+ * - **There is no `sender` option**: a webview has one peer.
+ * - **`start()` must be called** before anything arrives, since it attaches the
+ *   `window` listener. It is absent here because the channel does not call it;
+ *   the webview's bootstrap does.
+ *
+ * A separate interface rather than a wider {@link MessengerLike}: one shape for
+ * both ends would promise a webview an unregisterable handler and a sender
+ * filter it cannot honour.
+ */
+export interface WebviewMessengerLike<TParticipant> extends MessengerSendLike<TParticipant> {
+   onNotification(type: NotificationTypeLike, handler: (params: Message, sender: TParticipant) => void): unknown;
+}
+
+/**
+ * The data head's two notification types, one per direction.
+ *
+ * `vscode-messenger` addresses a notification to its receiver, so one method
+ * for both directions would also deliver correctly. Two keep the direction
+ * readable on the wire and in a messenger trace, and keep a delivery that
+ * routes by method alone, such as `BROADCAST`, from reaching the sender's own
+ * handler.
+ */
+export const DATA_TO_WEBVIEW: NotificationTypeLike = { method: 'hydranium/data/toWebview' };
+export const DATA_TO_EXTENSION: NotificationTypeLike = { method: 'hydranium/data/toExtension' };
+
+/**
+ * Options for {@link createMessengerChannel}.
+ *
+ * Generic over the registration type as well as the participant, because the two
+ * sides disagree on what `onNotification` hands back: a `Disposable` on the
+ * extension side, the messenger itself on the webview side. The type parameter
+ * keeps {@link releaseRegistration} typed; probing an `unknown` for a `dispose`
+ * method would dispose the whole webview messenger if it ever gained one.
+ */
+export interface MessengerChannelOptions<TParticipant, TRegistration> {
+   readonly messenger: {
+      sendNotification(type: NotificationTypeLike, receiver: TParticipant, params?: Message): void;
+      onNotification(
+         type: NotificationTypeLike,
+         handler: (params: Message, sender: TParticipant) => void,
+         options?: { sender?: TParticipant }
+      ): TRegistration;
+   };
+   /** Where this side's outbound messages are addressed. */
+   readonly receiver: TParticipant;
+   /** The notification type this side SENDS on. */
+   readonly outbound: NotificationTypeLike;
+   /** The notification type this side LISTENS on. */
+   readonly inbound: NotificationTypeLike;
+   /**
+    * Accept inbound notifications only from this participant. Supply it
+    * whenever the messenger is shared, as GLSP's is with every diagram
+    * webview, so a second webview cannot inject traffic into this connection.
+    *
+    * Extension side only: the webview-side messenger ignores it.
+    */
+   readonly sender?: TParticipant;
+   /**
+    * Observe the hop going away, the webview being disposed. Passed through to
+    * {@link PostMessageChannel.onClose}, whose reader and writer use it to fire
+    * their own close.
+    */
+   readonly onClose?: (listener: () => void) => Disposable;
+   /**
+    * Release what `onNotification` returned, where the messenger hands back
+    * something releasable: on the extension side, whose registrations would
+    * otherwise accumulate on a hop that outlives every webview on it.
+    */
+   readonly releaseRegistration?: (registration: TRegistration) => void;
+}
+
+/**
+ * Present a messenger as a {@link PostMessageChannel}, so the data head's
+ * transport rides a host's existing notification hop.
+ *
+ * `createPostMessageTransport` turns the channel into a reader and writer,
+ * `relayToPostMessageChannel` pumps the extension host's socket onto it from
+ * the other side, and everything above, `createRpcProxy` and `DataSession`
+ * included, is host-invariant. Sharing GLSP's `Messenger` rather than opening a
+ * second hop gives a diagram and a data webview one lifecycle and one dispose.
+ *
+ * **`onMessage`'s `Disposable` means "stop delivering", not necessarily
+ * "unregister".** The webview-side messenger cannot unregister, so a flag keeps
+ * the promise on both sides. Where unregistering is possible,
+ * {@link MessengerChannelOptions.releaseRegistration} does it too, or every
+ * disposed webview would leave a handler on a shared hop.
+ */
+export function createMessengerChannel<TParticipant, TRegistration>(
+   options: MessengerChannelOptions<TParticipant, TRegistration>
+): PostMessageChannel {
+   const { messenger, receiver, outbound, inbound, sender, onClose, releaseRegistration } = options;
+   return {
+      post(message: Message): void {
+         messenger.sendNotification(outbound, receiver, message);
+      },
+      onMessage(listener: (message: Message) => void): Disposable {
+         let delivering = true;
+         const registration = messenger.onNotification(
+            inbound,
+            message => {
+               if (delivering) {
+                  listener(message);
+               }
+            },
+            sender ? { sender } : undefined
+         );
+         return {
+            dispose: () => {
+               delivering = false;
+               releaseRegistration?.(registration);
+            }
+         };
+      },
+      ...(onClose ? { onClose } : {})
+   };
+}
+
+/**
+ * The extension host's end: posts toward the webview, listens for what the
+ * webview sends.
+ */
+export function createExtensionSideChannel<TParticipant>(
+   messenger: MessengerLike<TParticipant>,
+   webview: TParticipant,
+   onClose?: (listener: () => void) => Disposable
+): PostMessageChannel {
+   return createMessengerChannel<TParticipant, Disposable>({
+      messenger,
+      receiver: webview,
+      outbound: DATA_TO_WEBVIEW,
+      inbound: DATA_TO_EXTENSION,
+      // Only this webview's traffic, since the hop is shared.
+      sender: webview,
+      onClose,
+      // This side can unregister, and must: the hop outlives every webview on it.
+      releaseRegistration: registration => registration.dispose()
+   });
+}
+
+/**
+ * The webview's end: the mirror image, addressed at the extension host.
+ *
+ * Two preconditions the webview's bootstrap owns, both of which present as "no
+ * data ever arrives" when missed:
+ *
+ * - **Read the channel through `WebviewDataPort`**, or build its connection
+ *   with `createMessageConnection` from `vscode-jsonrpc/browser`: the package
+ *   root installs no runtime abstraction layer and throws on the first
+ *   message.
+ * - **Call the messenger's own `start()`**, which attaches the `window`
+ *   listener.
+ *
+ * No `sender` filter: a webview has one peer.
+ */
+export function createWebviewSideChannel<TParticipant>(
+   messenger: WebviewMessengerLike<TParticipant>,
+   hostExtension: TParticipant,
+   onClose?: (listener: () => void) => Disposable
+): PostMessageChannel {
+   return createMessengerChannel<TParticipant, unknown>({
+      messenger,
+      receiver: hostExtension,
+      outbound: DATA_TO_EXTENSION,
+      inbound: DATA_TO_WEBVIEW,
+      onClose
+   });
+}

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

@@ -0,0 +1,85 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * The extension host's end of the data head.
+ *
+ * A webview has no `net`, so the extension host holds the socket to the
+ * data-server and moves whole JSON-RPC messages between it and the webview over
+ * a `vscode-messenger` hop, typically GLSP's own, so a diagram and a data
+ * webview share one lifecycle and one dispose.
+ */
+
+import { relayToPostMessageChannel, type MessageRelay, type RelayTransport, type ResolvedMessage } from '@hydranium/protocol';
+import * as net from 'node:net';
+import type { Disposable } from 'vscode-jsonrpc';
+// `/node` because the extension host is Node and holds the socket. The webview
+// imports `/browser`; the package root installs no runtime abstraction layer.
+import { SocketMessageReader, SocketMessageWriter } from 'vscode-jsonrpc/node';
+import { createExtensionSideChannel, type MessengerLike } from '../messenger-channel';
+
+/** Connect to a head's socket and present it as a relay's framed side. */
+export function openSocketTransport(port: number, host = '127.0.0.1'): Promise<RelayTransport> {
+   return new Promise<RelayTransport>((resolve, reject) => {
+      const socket = net.createConnection({ port, host });
+      socket.once('error', reject);
+      socket.once('connect', () => {
+         // Drop the construction-time handler so a later socket error goes to
+         // the relay's reader rather than rejecting an already-settled promise.
+         socket.removeAllListeners('error');
+         resolve({
+            reader: new SocketMessageReader(socket),
+            writer: new SocketMessageWriter(socket),
+            dispose: () => socket.destroy()
+         });
+      });
+   });
+}
+
+/** What {@link connectDataServer} needs from the host. */
+export interface DataServerConnectionOptions<TParticipant> {
+   /**
+    * The extension-side messenger, typically `GlspVscodeConnector.messenger`.
+    * It must be constructed with `ignoreHiddenViews: false`, or a hidden
+    * webview misses every message the data-server sends it.
+    */
+   readonly messenger: MessengerLike<TParticipant>;
+   /** The registered webview this connection serves. */
+   readonly webview: TParticipant;
+   /**
+    * Resolve the data-server's listening port. Called once per connection
+    * generation, so a restarted server is re-discovered rather than cached —
+    * the language server binds a fresh ephemeral port each start.
+    */
+   readonly findPort: () => Promise<number>;
+   /** Observe the webview going away, so the relay releases with it. */
+   readonly onWebviewDisposed?: (listener: () => void) => Disposable;
+   /**
+    * Surface a relay failure. `reported` is a complete sentence plus the
+    * identity needed to render it in another language — the extension host holds
+    * the locale, so it renders and the relay does not.
+    */
+   readonly reportError?: (error: unknown, reported: ResolvedMessage) => void;
+}
+
+/**
+ * Wire one webview to the data head.
+ *
+ * The returned relay's `onClose` is the host's ONLY notice that the framed side
+ * died — a `PostMessageChannel` has no `close()`, so a dead data-server is
+ * invisible to the webview, whose pending requests would otherwise hang with no
+ * rejection. Tell the webview, whose `WebviewDataPort.connectionLost` rejects
+ * them, or dispose the webview; doing nothing is the one wrong choice.
+ */
+export function connectDataServer<TParticipant>(options: DataServerConnectionOptions<TParticipant>): MessageRelay {
+   const channel = createExtensionSideChannel(options.messenger, options.webview, options.onWebviewDisposed);
+   return relayToPostMessageChannel(channel, async () => openSocketTransport(await options.findPort()), {
+      reportError: options.reportError
+   });
+}

package/src/node/index.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+export * from './data-server-connection';

package/src/testing/index.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+export * from './messenger-harness';

package/src/testing/messenger-harness.ts

@@ -0,0 +1,121 @@
+/********************************************************************************
+ * 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 { Messenger } from 'vscode-messenger';
+import type { WebviewIdMessageParticipant } from 'vscode-messenger-common';
+import { Messenger as WebviewMessenger, type VsCodeApi } from 'vscode-messenger-webview';
+
+/** One webview on a {@link MessengerHarness}. */
+export interface MessengerHarnessWebview {
+   /** How the extension-side messenger addresses this webview. */
+   readonly participant: WebviewIdMessageParticipant;
+   /** The webview's own messenger, already started. */
+   readonly messenger: WebviewMessenger;
+   /** Close the webview, as VS Code disposing its panel does: the extension-side messenger forgets it. */
+   dispose(): void;
+}
+
+/** The real `vscode-messenger` classes, joined without VS Code. */
+export interface MessengerHarness {
+   /** The extension host's messenger, constructed as `GlspVscodeConnector` constructs its own. */
+   readonly extension: Messenger;
+   /** Open a webview: a panel registered with {@link extension}, and the webview's messenger behind it. */
+   openWebview(): MessengerHarnessWebview;
+   /**
+    * Restore the global `window` this harness replaced. A webview messenger
+    * reads `window.crypto` for every request it sends, so its requests throw
+    * once the harness is disposed; notifications still go.
+    */
+   dispose(): void;
+}
+
+/** What the webview messenger reads from the global `window`. */
+interface HarnessWindow {
+   addEventListener(type: string, listener: (event: { data: unknown }) => void): void;
+   readonly crypto: typeof globalThis.crypto;
+}
+
+/**
+ * Join the real extension-side and webview-side messengers in a Node test,
+ * through a fake webview panel on one end and a fake `window` on the other.
+ *
+ * Both classes run unchanged, so their routing is the real one: delivery is
+ * asynchronous, the webview side keeps one handler per method, and the
+ * extension side filters by sender. The webview messenger listens on the
+ * global `window`, so the harness installs one for its lifetime and routes each
+ * listener to the webview that registered it.
+ *
+ * One harness at a time: a second replaces the `window` the first routes its
+ * webviews through, and disposing them out of order restores the wrong one.
+ */
+export function makeMessengerHarness(): MessengerHarness {
+   const host = globalThis as { window?: unknown };
+   const previousWindow = host.window;
+   let starting: Array<(event: { data: unknown }) => void> | undefined;
+   const harnessWindow: HarnessWindow = {
+      addEventListener: (type, listener) => {
+         if (type === 'message') {
+            starting?.push(listener);
+         }
+      },
+      crypto: globalThis.crypto
+   };
+   host.window = harnessWindow;
+   const extension = new Messenger({ ignoreHiddenViews: false });
+
+   return {
+      extension,
+      openWebview: () => {
+         const toWebview: Array<(event: { data: unknown }) => void> = [];
+         const toExtension: Array<(message: unknown) => void> = [];
+         const disposeListeners: Array<() => void> = [];
+         const panel = {
+            viewType: 'hydranium.messengerHarness',
+            visible: true,
+            webview: {
+               postMessage: async (message: unknown) => {
+                  [...toWebview].forEach(listener => listener({ data: message }));
+                  return true;
+               },
+               onDidReceiveMessage: (listener: (message: unknown) => void) => {
+                  toExtension.push(listener);
+                  return {
+                     dispose: () => {
+                        const index = toExtension.indexOf(listener);
+                        if (index >= 0) {
+                           toExtension.splice(index, 1);
+                        }
+                     }
+                  };
+               }
+            },
+            onDidDispose: (listener: () => void) => {
+               disposeListeners.push(listener);
+               return { dispose: () => undefined };
+            },
+            onDidChangeViewState: () => ({ dispose: () => undefined })
+         };
+         // The members the extension-side messenger reads; the rest of a panel is VS Code's.
+         const participant = extension.registerWebviewPanel(panel as unknown as Parameters<Messenger['registerWebviewPanel']>[0]);
+         const vscodeApi: VsCodeApi = {
+            postMessage: message => [...toExtension].forEach(listener => listener(message)),
+            getState: () => undefined,
+            setState: () => undefined
+         };
+         const messenger = new WebviewMessenger(vscodeApi);
+         starting = toWebview;
+         messenger.start();
+         starting = undefined;
+         return { participant, messenger, dispose: () => disposeListeners.forEach(listener => listener()) };
+      },
+      dispose: () => {
+         host.window = previousWindow;
+      }
+   };
+}