@hydranium/protocol 1.0.0-next.10

package/src/client/data-session.ts

@@ -0,0 +1,209 @@
+/********************************************************************************
+ * 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 { MessageConnection } from 'vscode-jsonrpc';
+import { DATA_CLIENT_PROTOCOL_METHODS, DATA_SERVER_WIRE_PREFIX, type DataClientProtocol, type DataServerProtocol } from '../data';
+import { type RpcProxy, createRpcProxy } from '../rpc';
+import type { TransferDocument } from '../transfer-document';
+import type { TransferElement } from '../transfer-element';
+import type { DataPort } from './data-port';
+
+/** Options for {@link DataSession}. */
+export interface DataSessionOptions {
+   /**
+    * Wire namespace the server is addressed under. Defaults to the
+    * framework's {@link DATA_SERVER_WIRE_PREFIX}, which is what an unmodified
+    * `DataServer` binds. Override only alongside the server's own
+    * `methodNamespace` option — a mismatch turns every request into
+    * "Unhandled method" rather than failing at wire-up.
+    */
+   readonly methodNamespace?: string;
+}
+
+/** One connection generation: its connection, its proxy, and its readiness. */
+interface Generation<TTransfer extends TransferElement> {
+   readonly connection: Promise<MessageConnection>;
+   readonly server: RpcProxy<DataServerProtocol<TTransfer>>;
+   /** Set on first use; the shared readiness gate for this generation. */
+   ready?: Promise<void>;
+}
+
+/**
+ * The host-invariant half of talking to the data head: everything above
+ * {@link DataPort} that would otherwise be re-derived by every host
+ * adapter.
+ *
+ * Three jobs, and deliberately no fourth:
+ *
+ * 1. **Build the typed proxy** over the port's connection, with the framework's
+ *    wire prefix and its drift-proof client-method allowlist.
+ * 2. **Own the readiness gate** — `waitForReady` once per connection, shared
+ *    across concurrent callers. A socket client can connect before the
+ *    workspace walk finishes, and an early request is then answered correctly
+ *    from an empty registry, which reads as a broken project tier rather than
+ *    as a race.
+ * 3. **Own the reconnect policy**, by dropping its connection generation when
+ *    the port disposes and building a fresh one on the next request.
+ *
+ * It does **not** wrap the protocol methods; callers reach them through
+ * {@link connected}. The one exception is {@link openDocument}, which exists
+ * because the open/watch *order* is silently wrong the other way round — see
+ * its own doc.
+ *
+ * Generic over the transfer root so this file names no grammar. An adopter
+ * binds the concrete root (or the union of them, for a multi-grammar head) at
+ * its own edge.
+ */
+export class DataSession<TTransfer extends TransferElement> {
+   protected readonly methodNamespace: string;
+   /** The current generation, or `undefined` before the first request / after a teardown. */
+   protected generation?: Generation<TTransfer>;
+   protected disposed = false;
+   protected readonly portDisposeListener: { dispose(): void };
+
+   constructor(
+      protected readonly port: DataPort,
+      protected readonly client: DataClientProtocol<TTransfer>,
+      options: DataSessionOptions = {}
+   ) {
+      this.methodNamespace = options.methodNamespace ?? DATA_SERVER_WIRE_PREFIX;
+      this.portDisposeListener = this.port.onDispose(() => this.dropGeneration());
+   }
+
+   /** The identity every request is made under — the port's, not a second one. */
+   get clientId(): string {
+      return this.port.clientId;
+   }
+
+   /**
+    * The connected, READY server proxy.
+    *
+    * Returns the proxy rather than `void` on purpose. A reconnect replaces the
+    * proxy, so a caller that cached one from an earlier call would go on
+    * addressing a dead connection with no error — handing it back per call
+    * makes the stale reference unrepresentable.
+    *
+    * Concurrent callers share one readiness promise, so `waitForReady` is
+    * awaited once per generation and not once per caller.
+    */
+   async connected(): Promise<RpcProxy<DataServerProtocol<TTransfer>>> {
+      if (this.disposed) {
+         throw new Error('DataSession is disposed');
+      }
+      const generation = this.currentGeneration();
+      if (!generation.ready) {
+         generation.ready = this.awaitReady(generation);
+      }
+      await generation.ready;
+      return generation.server;
+   }
+
+   /**
+    * Open `uri` for editing and start watching it, in that order, returning
+    * the opened snapshot.
+    *
+    * **The order is the whole reason this method exists.**
+    * `watchModelDocument` baselines its dedup fingerprint from the *current*
+    * document, but only if one exists. Watching first therefore leaves no
+    * baseline, and the first phase event after the open arrives as a spurious
+    * `'changed'` — which a widget that resets its in-memory root to the server
+    * view misreads as a concurrent third-party write, losing whatever the user
+    * had typed. Nothing about the wrong order fails loudly, so it is encoded
+    * here rather than documented and re-derived.
+    *
+    * Note that the returned snapshot's empty `diagnostics` does not mean
+    * valid: `open` settles at the integrity landmark, not at validation.
+    * Validity arrives asynchronously on `onDocumentUpdated`, or synchronously
+    * from `getModelDocument({ includeDiagnostics: true })`.
+    */
+   async openDocument(uri: string): Promise<TransferDocument<TTransfer>> {
+      const server = await this.connected();
+      const document = await server.openModelDocument({ uri, clientId: this.clientId });
+      await server.watchModelDocument({ uri, clientId: this.clientId });
+      return document;
+   }
+
+   /**
+    * Close `uri`. The server unwatches implicitly, so this is the dual of
+    * {@link openDocument} and needs no separate unwatch.
+    */
+   async closeDocument(uri: string): Promise<void> {
+      const server = await this.connected();
+      await server.closeModelDocument({ uri, clientId: this.clientId });
+   }
+
+   /**
+    * Whether `event.sourceClientId` identifies this session's own write.
+    *
+    * Every watcher needs this and the check is one comparison, so getting it
+    * wrong is cheap to do and expensive to find: an unfiltered echo looks
+    * exactly like a concurrent third-party edit.
+    */
+   isOwnEcho(sourceClientId: string): boolean {
+      return sourceClientId === this.clientId;
+   }
+
+   /** Tear down the current connection and stop tracking the port. Idempotent. */
+   dispose(): void {
+      if (this.disposed) {
+         return;
+      }
+      this.disposed = true;
+      this.portDisposeListener.dispose();
+      this.dropGeneration();
+   }
+
+   /** The live generation, building one if there is none. */
+   protected currentGeneration(): Generation<TTransfer> {
+      if (this.generation) {
+         return this.generation;
+      }
+      const connection = this.port.connect();
+      // Rejection is reported here rather than left to float: an unhandled
+      // rejection on a connection promise is the failure mode that reads as
+      // "the model is empty" instead of "the transport never opened".
+      connection.catch((error: unknown) => this.port.reportError(error, 'connecting to the data server'));
+      const server = createRpcProxy<DataServerProtocol<TTransfer>, DataClientProtocol<TTransfer>>(connection, {
+         methodNamespace: this.methodNamespace,
+         localTarget: this.client,
+         localMethods: DATA_CLIENT_PROTOCOL_METHODS
+      });
+      this.generation = { connection, server };
+      return this.generation;
+   }
+
+   /** Await the connection and the server's startup gate for one generation. */
+   protected async awaitReady(generation: Generation<TTransfer>): Promise<void> {
+      try {
+         await generation.connection;
+         await generation.server.waitForReady();
+      } catch (error: unknown) {
+         // Drop the generation so the next request retries rather than
+         // re-awaiting a settled rejection forever.
+         if (this.generation === generation) {
+            this.generation = undefined;
+         }
+         this.port.reportError(error, 'waiting for the data server to become ready');
+         throw error;
+      }
+   }
+
+   /**
+    * Discard the current generation, disposing its connection if it opened.
+    * The next {@link connected} builds a fresh one.
+    */
+   protected dropGeneration(): void {
+      const generation = this.generation;
+      this.generation = undefined;
+      if (!generation) {
+         return;
+      }
+      generation.connection.then(connection => connection.dispose()).catch(() => undefined);
+   }
+}

package/src/client/index.ts

@@ -0,0 +1,40 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Subpath barrel for `@hydranium/protocol/client` — the **host-neutral client
+ * tier** of the data head.
+ *
+ * Where `./data` is the wire *contract* and `./rpc` is the machinery that lowers
+ * it onto a connection, this is what a client wraps around both: the seam a host
+ * fills in (`DataPort`), the lifecycle above it (`DataSession` —
+ * readiness gate, open/watch ordering, echo recognition, reconnect), the inbound
+ * fan-out (`DataEvents`), and the two halves of the hop for hosts whose
+ * client cannot hold a socket — `createPostMessageTransport` on the client
+ * side and `relayToPostMessageChannel` on the side that does hold it.
+ *
+ * **Neutral, and gate-enforced so.** Nothing here imports a host package or a
+ * Node builtin, which is what lets one client tier serve a Theia frontend, a VS
+ * Code extension host, a VS Code webview and a plain browser app. `npm run
+ * check:neutral` bundles these modules for the browser; `scripts/check-neutral-bundles.mjs`
+ * carries the entries.
+ *
+ * The Theia-specific mounting of the same contract lives in
+ * `@hydranium/data-client-theia`: its `AbstractDataServiceFrontend` solves the
+ * same problem against Theia's channel transport, and its `EmitterDataClient`
+ * is the Theia-bound counterpart of `DataEvents`. Prefer this tier for
+ * anything new, and reach for the Theia package only for what genuinely needs
+ * Theia DI.
+ */
+
+export * from './data-events';
+export * from './data-port';
+export * from './data-session';
+export * from './message-relay';
+export * from './post-message-transport';

package/src/client/message-relay.ts

@@ -0,0 +1,216 @@
+/********************************************************************************
+ * 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 Disposable, type Event, type Message, type MessageReader, type MessageWriter } from 'vscode-jsonrpc';
+import type { PostMessageChannel } from './post-message-transport';
+
+/**
+ * The framed side of a relay: the reader/writer pair over whatever transport the
+ * host actually holds — a TCP socket to the data-server, a child process' stdio,
+ * a websocket.
+ *
+ * Structurally the same pair `PostMessageTransport` exposes, and
+ * deliberately so: either can stand on either side of a relay. What differs is
+ * only who owns the framing, which is why this tier never needs to know.
+ */
+export interface RelayTransport {
+   readonly reader: MessageReader;
+   readonly writer: MessageWriter;
+   /** Release the transport. Called when the relay is disposed. */
+   dispose?(): void;
+}
+
+/** Options for {@link relayToPostMessageChannel}. */
+export interface MessageRelayOptions {
+   /**
+    * Surface a failure the way the host does. Same contract as
+    * `DataPort.reportError`: `context` names what was being attempted.
+    *
+    * A relay has no other way to report — it sits between two transports and
+    * owns neither, so a swallowed error here presents as a form that never
+    * populates.
+    */
+   readonly reportError?: (error: unknown, context: string) => void;
+}
+
+/** A live relay. Dispose to tear both directions down. */
+export interface MessageRelay extends Disposable {
+   /**
+    * Resolves `true` once messages are flowing in both directions, `false` if
+    * opening the framed transport failed or the relay was disposed first.
+    *
+    * It resolves rather than rejects on failure so that a caller which never
+    * awaits it cannot produce an unhandled rejection; the error itself goes to
+    * {@link MessageRelayOptions.reportError}. Tests await it to get a
+    * deterministic "wiring is done" edge instead of polling.
+    */
+   readonly wired: Promise<boolean>;
+
+   /**
+    * Fires when the framed side goes away — the data-server exiting, the socket
+    * erroring, a language-server restart taking its ports with it.
+    *
+    * **The relay cannot propagate this to the clone hop itself**, and the host
+    * has to. {@link PostMessageChannel} is deliberately an input-only contract:
+    * it offers `onClose` for observing the pipe but no `close()` for ending it,
+    * because a webview's pipe belongs to the webview's lifecycle, not to
+    * whoever relays over it. So a framed-side death is invisible to the far
+    * end, whose pending requests would otherwise hang forever with no rejection
+    * — the far side's `MessageConnection` sees an open pipe and no answer. On
+    * this event a host disposes the webview, reloads it, or sends its own
+    * "connection lost" notification; doing nothing is the one wrong choice.
+    */
+   readonly onClose: Event<void>;
+}
+
+/**
+ * Pump JSON-RPC messages between a framed transport and a structured-clone
+ * {@link PostMessageChannel}, decoding neither.
+ *
+ * This is the extension-host half of the hop whose webview half is
+ * `createPostMessageTransport`. A webview has no `net`, so the data-server
+ * socket can only be held by the extension host; the host therefore has to move
+ * whole messages between a Content-Length-framed socket and a pipe that carries
+ * objects. Both sides speak the same JSON-RPC, so this moves messages and adds
+ * no semantics — there is no re-proxy in between, and `createRpcProxy` on the far
+ * side is unaware the relay exists.
+ *
+ * **No `MessageConnection` is built here, and that is what keeps the module
+ * browser-neutral.** A relay is not a JSON-RPC endpoint: it has no requests of
+ * its own, so it needs no message queue, hence no vscode-jsonrpc runtime
+ * abstraction layer. `reader.listen` / `writer.write` are enough. The caller
+ * imports the entrypoint that frames its own transport (`vscode-jsonrpc/node`
+ * for a socket) and the RAL that comes with it; this tier stays neutral and is
+ * gated so by `npm run check:neutral`. Contrast
+ * `@hydranium/data-client-theia`'s `SocketChannelForwarder`, which does build a
+ * connection only to borrow its `onClose`, and pays a Theia dependency for the
+ * byte coding this shape does not need.
+ *
+ * **The race this exists to close.** `openTransport` is asynchronous — a real
+ * host discovers a port first, then connects — while the clone pipe is usable
+ * immediately. `PostMessageChannel.onMessage` is a plain emitter with no replay,
+ * so a message sent during the connect window is dropped outright.
+ *
+ * It is not enough that a disciplined client awaits its own connection before
+ * sending: a host builds the far-side connection and hands it back *without*
+ * waiting for the relay, so `DataSession`'s very first call — the readiness
+ * handshake — is already in flight while the socket is still opening. Dropping
+ * that first request presents as a client hanging forever on connect against a
+ * perfectly healthy server.
+ *
+ * So the subscription is taken **synchronously, before the first await**, and
+ * buffers; the hand-off then swaps listeners and replays within one turn of the
+ * event loop, which is what makes it impossible for a message to be both
+ * buffered and forwarded, or to arrive between the two. Replay is FIFO because
+ * order is load-bearing — a `getModelDocument` that overtook its own
+ * `openModelDocument` would answer against an unopened document.
+ * `@hydranium/client-theia`'s `AbstractSocketForwardingConnectionHandler` carries the
+ * same fix for the Theia channel transport.
+ */
+export function relayToPostMessageChannel(
+   channel: PostMessageChannel,
+   openTransport: () => Promise<RelayTransport>,
+   options: MessageRelayOptions = {}
+): MessageRelay {
+   const closeEmitter = new Emitter<void>();
+   const subscriptions: Disposable[] = [];
+   let transport: RelayTransport | undefined;
+   let disposed = false;
+
+   // Taken before the first await, so nothing the far side sends during the
+   // connect window is lost. See the race note above.
+   const buffered: Message[] = [];
+   let bufferSubscription: Disposable | undefined = channel.onMessage(message => buffered.push(message));
+
+   const closeFramedSide = (): void => {
+      if (disposed) {
+         return;
+      }
+      closeEmitter.fire();
+   };
+
+   const wired = (async (): Promise<boolean> => {
+      let opened: RelayTransport;
+      try {
+         opened = await openTransport();
+      } catch (error: unknown) {
+         bufferSubscription?.dispose();
+         bufferSubscription = undefined;
+         buffered.length = 0;
+         options.reportError?.(error, 'opening the transport to relay');
+         closeFramedSide();
+         return false;
+      }
+
+      if (disposed) {
+         // Disposed while connecting: the transport is ours now, so it is ours
+         // to release, or the socket outlives the relay that owns it.
+         opened.dispose?.();
+         return false;
+      }
+      transport = opened;
+
+      // Synchronous hand-off: drop the buffering listener, wire both
+      // directions, then replay. No await in between, so the event loop cannot
+      // interleave a message into the gap.
+      bufferSubscription?.dispose();
+      bufferSubscription = undefined;
+
+      subscriptions.push(
+         opened.reader.listen(message => channel.post(message)),
+         opened.reader.onClose(() => closeFramedSide()),
+         opened.reader.onError(error => {
+            options.reportError?.(error, 'reading from the relayed transport');
+            closeFramedSide();
+         }),
+         channel.onMessage(message => {
+            void opened.writer.write(message).catch((error: unknown) => {
+               options.reportError?.(error, 'writing to the relayed transport');
+            });
+         })
+      );
+
+      const onChannelClose = channel.onClose?.(() => dispose());
+      if (onChannelClose) {
+         subscriptions.push(onChannelClose);
+      }
+
+      for (const message of buffered) {
+         void opened.writer.write(message).catch((error: unknown) => {
+            options.reportError?.(error, 'replaying a buffered message to the relayed transport');
+         });
+      }
+      buffered.length = 0;
+
+      return true;
+   })();
+
+   function dispose(): void {
+      if (disposed) {
+         return;
+      }
+      disposed = true;
+      bufferSubscription?.dispose();
+      bufferSubscription = undefined;
+      buffered.length = 0;
+      for (const subscription of subscriptions) {
+         subscription.dispose();
+      }
+      subscriptions.length = 0;
+      transport?.dispose?.();
+      transport = undefined;
+      closeEmitter.dispose();
+   }
+
+   return {
+      wired,
+      onClose: closeEmitter.event,
+      dispose
+   };
+}

package/src/client/post-message-transport.ts

@@ -0,0 +1,167 @@
+/********************************************************************************
+ * 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 {
+   AbstractMessageReader,
+   AbstractMessageWriter,
+   Emitter,
+   type DataCallback,
+   type Disposable,
+   type Message,
+   type MessageReader,
+   type MessageWriter
+} from 'vscode-jsonrpc';
+
+/**
+ * A `postMessage`-shaped pipe: fire-and-forget, structured-clone-only, no
+ * framing and no bytes.
+ *
+ * This is the shape every extension↔webview hop reduces to, and the reason the
+ * data head needs a port at all. A webview has no `net`, no reach into the
+ * extension host's connection, and nothing but structured clone — so a
+ * transport built on it can carry plain data and nothing else.
+ *
+ * Deliberately minimal, and deliberately not typed against any host's messaging
+ * library — a host adapter satisfies it in a few lines over whatever messenger
+ * it already has, so a diagram and a form can share one hop, one lifecycle and
+ * one dispose rather than opening a second channel for the form.
+ */
+export interface PostMessageChannel {
+   /**
+    * Hand one JSON-RPC message to the other side. Fire-and-forget: delivery
+    * failures surface through {@link onClose}, never as a rejection, because
+    * `postMessage` has no completion to report.
+    */
+   post(message: Message): void;
+
+   /** Register for messages arriving from the other side. */
+   onMessage(listener: (message: Message) => void): Disposable;
+
+   /**
+    * Register for the pipe going away — the webview being disposed, the
+    * extension deactivating. Optional: a channel with no observable end simply
+    * never fires close, and the reader/writer then rely on their owner's
+    * dispose instead.
+    */
+   onClose?(listener: () => void): Disposable;
+}
+
+/**
+ * A reader/writer pair over a {@link PostMessageChannel}, ready to be handed to
+ * `createMessageConnection`.
+ *
+ * The connection is NOT built here, and that omission is the point:
+ * `createMessageConnection`'s message queue needs a vscode-jsonrpc runtime
+ * abstraction layer, and only the `/node` and `/browser` entrypoints install
+ * one. vscode-jsonrpc 9's package ROOT resolves to the RAL-less common API and
+ * throws `No runtime abstraction layer installed` on the first message. Only
+ * the host knows which side it is on, so the host imports the matching entry
+ * (`/browser` in a webview, `/node` in an extension host) and builds the
+ * connection there.
+ *
+ * Keeping the factory out of this module is also what lets the module stay
+ * browser-neutral: it touches only `AbstractMessageReader` /
+ * `AbstractMessageWriter` / `Emitter`, none of which need a RAL.
+ */
+export interface PostMessageTransport {
+   readonly reader: MessageReader;
+   readonly writer: MessageWriter;
+   /** Release the channel subscriptions. */
+   dispose(): void;
+}
+
+/**
+ * A `MessageReader` over a {@link PostMessageChannel}.
+ *
+ * Structured clone moves objects, so there is nothing to frame and nothing to
+ * decode — the message arrives as the message.
+ */
+class PostMessageReader extends AbstractMessageReader implements MessageReader {
+   protected readonly messageEmitter = new Emitter<Message>();
+   protected readonly subscriptions: Disposable[] = [];
+
+   constructor(channel: PostMessageChannel) {
+      super();
+      this.subscriptions.push(channel.onMessage(message => this.messageEmitter.fire(message)));
+      const onClose = channel.onClose?.(() => this.fireClose());
+      if (onClose) {
+         this.subscriptions.push(onClose);
+      }
+   }
+
+   listen(callback: DataCallback): Disposable {
+      return this.messageEmitter.event(callback);
+   }
+
+   override dispose(): void {
+      super.dispose();
+      for (const subscription of this.subscriptions) {
+         subscription.dispose();
+      }
+      this.subscriptions.length = 0;
+      this.messageEmitter.dispose();
+   }
+}
+
+/** The dual of {@link PostMessageReader} — one `post` per JSON-RPC message. */
+class PostMessageWriter extends AbstractMessageWriter implements MessageWriter {
+   protected readonly subscriptions: Disposable[] = [];
+
+   constructor(protected readonly channel: PostMessageChannel) {
+      super();
+      const onClose = channel.onClose?.(() => this.fireClose());
+      if (onClose) {
+         this.subscriptions.push(onClose);
+      }
+   }
+
+   write(message: Message): Promise<void> {
+      this.channel.post(message);
+      // `postMessage` reports no completion, so the resolved promise means
+      // "handed over", not "delivered". vscode-jsonrpc only needs the former.
+      return Promise.resolve();
+   }
+
+   end(): void {
+      this.dispose();
+   }
+
+   override dispose(): void {
+      super.dispose();
+      for (const subscription of this.subscriptions) {
+         subscription.dispose();
+      }
+      this.subscriptions.length = 0;
+   }
+}
+
+/**
+ * Build the reader/writer pair for `channel`.
+ *
+ * What this buys, and why `DataPort` is shaped the way it is:
+ * `createRpcProxy` runs **unchanged** over the result. The typed surface, the
+ * `DATA_*_PROTOCOL_METHODS` allowlists and the whole open → watch → update →
+ * close sequence are identical in a webview and in a Node extension host,
+ * because only the `MessageConnection` the port hands back differs. Terminating
+ * JSON-RPC in the extension host and declaring one request type per data-head
+ * method is the wrong trade: it hand-maintains a per-method mapping and
+ * discards the `as const satisfies keyof` allowlists, which cannot drift.
+ */
+export function createPostMessageTransport(channel: PostMessageChannel): PostMessageTransport {
+   const reader = new PostMessageReader(channel);
+   const writer = new PostMessageWriter(channel);
+   return {
+      reader,
+      writer,
+      dispose(): void {
+         reader.dispose();
+         writer.dispose();
+      }
+   };
+}