@hydranium/data-server 1.0.0-next.10

package/src/default-diagnostics.browser.ts

@@ -0,0 +1,41 @@
+/********************************************************************************
+ * 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 { DataServerDiagnosticsProvider, DataServerProfileCapture } from './diagnostics-provider.js';
+
+/**
+ * Message every method of the browser default rejects with.
+ *
+ * It **throws rather than no-ops** deliberately. A no-op would hand back an
+ * empty snapshot, which reads as "the server is fine" — the same shape as a
+ * real answer, and the failure mode this whole seam exists to avoid. Saying
+ * plainly that the capability is absent is more useful than a plausible lie.
+ */
+function unavailable(method: string): Error {
+   return new Error(
+      `DataServer.${method} is not available in this host: a browser has no process to inspect. ` +
+         'Heap snapshots, profiling, pod memory and server state are Node-only capabilities.'
+   );
+}
+
+/**
+ * Platform default for a browser host, selected by `package.json`'s `browser`
+ * field in place of `default-diagnostics.js`.
+ *
+ * Free of Node imports by construction — that is its entire reason for
+ * existing, and why the head's portable entry can be bundled at all.
+ */
+export function defaultDataServerDiagnostics(): DataServerDiagnosticsProvider {
+   return {
+      dumpServerState: () => Promise.reject(unavailable('dumpServerState')),
+      writeHeapSnapshot: () => Promise.reject(unavailable('writeHeapSnapshot')),
+      dumpPodMemory: () => Promise.reject(unavailable('dumpPodMemory')),
+      startProfiling: (): Promise<DataServerProfileCapture> => Promise.reject(unavailable('startProfiling'))
+   };
+}

package/src/default-diagnostics.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
+ ********************************************************************************/
+
+import type { DataServerDiagnosticsProvider } from './diagnostics-provider.js';
+import { nodeDataServerDiagnostics } from './node/node-diagnostics-provider.js';
+
+/**
+ * Platform default for `DataServerOptions.diagnostics` — the Node one.
+ *
+ * # This file is swapped by the bundler, and that is the whole mechanism
+ *
+ * `package.json`'s `browser` field maps this module to
+ * `default-diagnostics.browser.js`, so a `platform: 'browser'` bundler never
+ * resolves it and never follows its `@hydranium/core/node` import. Node keeps
+ * it, because Node ignores the `browser` field.
+ *
+ * The alternative — reaching for the Node implementation directly from the head
+ * — is what made this package unbundleable for a browser: a static
+ * `@hydranium/core/node` import on the portable entry pulls `node:fs`,
+ * `node:v8` and `node:perf_hooks` into any browser build, over methods a
+ * browser cannot call.
+ *
+ * **`check:neutral` proves the swap works**, since it bundles this package's `.`
+ * entry for the browser and would fail on those imports if the mapping ever
+ * stopped applying. That is the same property the gate relies on for
+ * `@eclipse-glsp/server`, whose own `browser` field selects its node-free
+ * build.
+ *
+ * A host that wants to be explicit — or to supply its own — passes
+ * `diagnostics` and this default is not consulted.
+ */
+export function defaultDataServerDiagnostics(): DataServerDiagnosticsProvider {
+   return nodeDataServerDiagnostics();
+}

package/src/diagnostics-provider.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 { ServerSharedServices } from '@hydranium/core';
+import type { DumpServerStateArgs, StartProfilingArgs, StopProfilingArgs, WriteServerHeapSnapshotArgs } from '@hydranium/protocol';
+
+/**
+ * The runtime-specific half of `DataServerDiagnosticsProtocol`, supplied
+ * by the host rather than reached for directly.
+ *
+ * # Why this is a seam and not four method bodies
+ *
+ * Every operation behind it needs a Node runtime — a V8 heap snapshot, an
+ * inspector session, `process.memoryUsage()`, cgroup files. Calling them
+ * directly puts a static `@hydranium/core/node` import on the data head's
+ * portable `.` entry, which no browser bundler can resolve: the head then fails
+ * to BUILD for a browser even though nothing in a browser would ever call a
+ * diagnostics method. Since the data head exists to serve non-LSP clients —
+ * webviews and browser pages among them — that is a defect rather than a
+ * trade-off.
+ *
+ * Node hosts get the real implementation from `@hydranium/data-server/node`.
+ * Hosts that supply nothing keep the whole rest of the protocol and reject only
+ * these four methods, with a message naming the import that would satisfy them.
+ */
+export interface DataServerDiagnosticsProvider {
+   /**
+    * Snapshot this process's memory, V8 stats, event-loop utilisation and
+    * document counts, formatted for a log.
+    *
+    * Takes the services rather than a document list so the whole shape of the
+    * snapshot — including which of the shared tier's stores it reads — stays a
+    * decision of the implementation, and no Node-only type appears here.
+    */
+   dumpServerState(services: ServerSharedServices, args: DumpServerStateArgs): Promise<string>;
+
+   /** Write a V8 heap snapshot and return its absolute path. */
+   writeHeapSnapshot(args: WriteServerHeapSnapshotArgs): Promise<string>;
+
+   /** Snapshot cgroup/pod memory — the figure an OOM-killer watches. */
+   dumpPodMemory(): Promise<string>;
+
+   /**
+    * Begin a windowed sampled-profile capture.
+    *
+    * Rejecting when a capture is already active is the implementation's
+    * responsibility, because the constraint is the runtime's: one inspector
+    * session per process.
+    */
+   startProfiling(args: StartProfilingArgs): Promise<DataServerProfileCapture>;
+}
+
+/** A profile capture in flight, returned by {@link DataServerDiagnosticsProvider.startProfiling}. */
+export interface DataServerProfileCapture {
+   /**
+    * End the capture, write its artefacts when a directory was given, and
+    * return the formatted report.
+    *
+    * Formatting belongs here rather than in the caller so the report type never
+    * has to cross this boundary — it is a Node-side shape, and naming it in the
+    * portable interface would put the import back.
+    */
+   stop(args: StopProfilingArgs): Promise<string>;
+}

package/src/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
+ ********************************************************************************/
+
+// Public API barrel for `@hydranium/data-server` — the typed-RPC
+// protocol head. Test-only helpers (duplex-connection pair, ...) live
+// under the `./testing` subpath and are NOT re-exported here so
+// production bundles stay free of test scaffolding.
+export * from './data-server.js';
+export * from './diagnostics-provider.js';

package/src/node/index.ts

@@ -0,0 +1,17 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Server-only surface of the data head (`@hydranium/data-server/node`).
+//
+// The rule is the same one `@hydranium/core` follows: `.` is portable and
+// bundles for a browser, everything that needs a Node runtime lives here. Adding
+// a module to this directory is how a Node-only capability reaches the head
+// without costing the portable entry its neutrality.
+
+export * from './node-diagnostics-provider.js';

package/src/node/node-diagnostics-provider.ts

@@ -0,0 +1,82 @@
+/********************************************************************************
+ * 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 { ServerSharedServices } from '@hydranium/core';
+import {
+   formatPodMemory,
+   formatProfileReport,
+   formatServerState,
+   ProfileCapture,
+   recordServerSummaryEntry,
+   writeHeapSnapshotToDir
+} from '@hydranium/core/node';
+import type { DumpServerStateArgs, StartProfilingArgs, StopProfilingArgs, WriteServerHeapSnapshotArgs } from '@hydranium/protocol';
+import type { DataServerDiagnosticsProvider, DataServerProfileCapture } from '../diagnostics-provider.js';
+
+/**
+ * The Node implementation of the data head's diagnostics, and the reason this
+ * subpath exists.
+ *
+ * Everything here needs a process to inspect — a V8 heap snapshot, an inspector
+ * session, `process.memoryUsage()`, cgroup files — so it is server-only by
+ * nature. Keeping it out of the package's portable `.` entry is what lets a
+ * browser bundle the data head at all.
+ *
+ * Snapshots are computed in THIS process on purpose: the data-server child holds
+ * the model store, so they reflect the heap that actually carries the workspace
+ * AST/CST — the process that OOMs.
+ */
+class NodeProfileCapture implements DataServerProfileCapture {
+   constructor(protected readonly capture: ProfileCapture) {}
+
+   async stop(args: StopProfilingArgs): Promise<string> {
+      const report = await this.capture.stop(args.directory, args.label ?? '');
+      // When a directory was given (the profile files land there), also fold this
+      // window's report into `<dir>/server-summary.json` so an interactive/e2e
+      // bundle carries the same per-window summary the headless `ProfilingRun`
+      // writes.
+      if (args.directory) {
+         recordServerSummaryEntry(args.directory, args.label ?? '', report);
+      }
+      return formatProfileReport(report, args.label ? `Profile report (${args.label})` : undefined);
+   }
+}
+
+class NodeDataServerDiagnostics implements DataServerDiagnosticsProvider {
+   async dumpServerState(services: ServerSharedServices, args: DumpServerStateArgs): Promise<string> {
+      const openDocuments = services.workspace.TextDocuments.openDocuments();
+      return formatServerState(services.workspace.LangiumDocuments, args.label, { openDocuments });
+   }
+
+   async writeHeapSnapshot(args: WriteServerHeapSnapshotArgs): Promise<string> {
+      return writeHeapSnapshotToDir(args.directory, args.label ?? '');
+   }
+
+   async dumpPodMemory(): Promise<string> {
+      return formatPodMemory();
+   }
+
+   async startProfiling(args: StartProfilingArgs): Promise<DataServerProfileCapture> {
+      // `ProfileCapture` is singleton-guarded — one inspector session per
+      // process — so a second concurrent start rejects here rather than in the
+      // caller, which is where the constraint actually lives.
+      return new NodeProfileCapture(await ProfileCapture.start(args));
+   }
+}
+
+/**
+ * The diagnostics provider a Node-hosted `DataServer` should be constructed
+ * with: `new DataServer(connection, shared, { diagnostics: nodeDataServerDiagnostics() })`.
+ *
+ * Omitting it is not an error — the head runs without it and rejects only the
+ * four diagnostics methods — so a host that never calls them can leave it out.
+ */
+export function nodeDataServerDiagnostics(): DataServerDiagnosticsProvider {
+   return new NodeDataServerDiagnostics();
+}

package/src/testing/data-server-harness.ts

@@ -0,0 +1,147 @@
+/********************************************************************************
+ * 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 { createRpcProxy, type Project, type TransferDiagnostic, type TransferElement } from '@hydranium/protocol';
+import {
+   DATA_CLIENT_PROTOCOL_METHODS,
+   DATA_SERVER_WIRE_PREFIX,
+   type DataClientProtocol,
+   type DataServerProtocol,
+   type ProjectsChangedEvent,
+   type TransferDocumentSavedEvent,
+   type TransferDocumentUpdatedEvent
+} from '@hydranium/protocol/data';
+import { type Harness, makeCapturingDataClient } from '@hydranium/protocol/testing';
+import { makeDuplexConnectionPair, type DuplexConnectionPair } from '@hydranium/protocol/testing/node';
+import type { MessageConnection } from 'vscode-jsonrpc/node';
+
+/**
+ * Configuration for {@link makeDataServerHarness}.
+ *
+ * `server` is the only required field — a factory that constructs the
+ * DataServer subclass under test against the supplied {@link MessageConnection}
+ * (the "server side" of the duplex pair). The factory is invoked once,
+ * synchronously, after the pair is wired.
+ *
+ * `client` lets tests override individual handlers on the captured
+ * {@link DataClientProtocol}. Unspecified handlers default to pushing
+ * incoming events into the {@link DataServerHarness} bundle's `events` /
+ * `saves` / `projectsChanges` arrays — the typical assertion target.
+ */
+export interface MakeDataServerHarnessOptions<
+   TServer,
+   TTransfer extends TransferElement,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TProject extends Project = Project
+> {
+   /**
+    * Construct the `DataServer` (or subclass) under test against
+    * `channel`. The harness invokes this once after `pair.left` is
+    * established.
+    */
+   server: (channel: MessageConnection) => TServer;
+   /**
+    * Override per-method handlers on the captured {@link DataClientProtocol}.
+    * Each overridden handler REPLACES the default (which pushes into the
+    * bundle's capture arrays); test code wanting to BOTH capture AND
+    * react should push to the array manually inside the override.
+    */
+   client?: Partial<DataClientProtocol<TTransfer, TDiagnostic, TProject>>;
+   /**
+    * Wire namespace the proxy addresses the server under. Defaults to
+    * {@link DATA_SERVER_WIRE_PREFIX}. Override when the `DataServer`
+    * subclass registers under a custom namespace (its constructor's
+    * `methodNamespace` option). Must match the server's namespace, or every
+    * request is "Unhandled method".
+    */
+   methodNamespace?: string;
+}
+
+/**
+ * Wiring bundle returned by {@link makeDataServerHarness}. Satisfies the
+ * uniform {@link Harness} contract — `server` is the **subject** (the
+ * DataServer under test), `proxy`/`pair` are the **seam** (the typed RPC
+ * proxy tests drive the subject through, plus the underlying duplex pair),
+ * `events`/`saves`/`projectsChanges` are the **capture arrays** for inbound
+ * client-side events, and `dispose()` is the uniform teardown hook.
+ *
+ * `dispose()` releases the duplex pair (and therefore both
+ * {@link MessageConnection}s); call at test teardown.
+ */
+export interface DataServerHarness<
+   TServer,
+   TTransfer extends TransferElement,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TProject extends Project = Project
+> extends Harness {
+   readonly server: TServer;
+   readonly proxy: DataServerProtocol<TTransfer, TDiagnostic, TProject>;
+   readonly pair: DuplexConnectionPair;
+   /** Captured `onDocumentUpdated` events — append order; never cleared by the harness. */
+   readonly events: ReadonlyArray<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>;
+   /** Captured `onDocumentSaved` events. */
+   readonly saves: ReadonlyArray<TransferDocumentSavedEvent<TTransfer, TDiagnostic>>;
+   /** Captured `onProjectsChanged` events. */
+   readonly projectsChanges: ReadonlyArray<ProjectsChangedEvent<TProject>>;
+   /** Dispose the underlying duplex pair. Idempotent. */
+   dispose(): void;
+}
+
+/**
+ * Wire a DataServer + local {@link DataClientProtocol} + typed RPC proxy
+ * over an in-process duplex {@link MessageConnection} pair. Tests then
+ * exercise the server via `harness.proxy.*()` and assert on
+ * `harness.events` / `harness.saves` / `harness.projectsChanges`.
+ *
+ * Moves the duplex pair, the local client and the proxy construction behind
+ * a single factory call, so a test file carries only its own setup: seeded
+ * documents, server options, assertions.
+ */
+export function makeDataServerHarness<
+   TServer,
+   TTransfer extends TransferElement,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TProject extends Project = Project
+>(
+   options: MakeDataServerHarnessOptions<TServer, TTransfer, TDiagnostic, TProject>
+): DataServerHarness<TServer, TTransfer, TDiagnostic, TProject> {
+   const pair = makeDuplexConnectionPair();
+   const server = options.server(pair.left);
+
+   // The capture half is the shared client double, not a local copy: the same
+   // recording semantics (all three channels, an override replacing rather than
+   // supplementing) then hold for a client-side suite that stands the double up
+   // without a server, so an assertion learnt against one reads the same in the
+   // other.
+   const {
+      client: localClient,
+      updates: events,
+      saves,
+      projectsChanges
+   } = makeCapturingDataClient<TTransfer, TDiagnostic, TProject>(options.client);
+
+   const proxy = createRpcProxy<DataServerProtocol<TTransfer, TDiagnostic, TProject>, DataClientProtocol<TTransfer, TDiagnostic, TProject>>(
+      pair.right,
+      {
+         methodNamespace: options.methodNamespace ?? DATA_SERVER_WIRE_PREFIX,
+         localTarget: localClient,
+         localMethods: DATA_CLIENT_PROTOCOL_METHODS
+      }
+   );
+
+   return {
+      server,
+      proxy,
+      pair,
+      events,
+      saves,
+      projectsChanges,
+      dispose: () => pair.dispose()
+   };
+}

package/src/testing/index.ts

@@ -0,0 +1,19 @@
+/********************************************************************************
+ * 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/data-server/testing` — the
+// `makeDataServerHarness` harness for in-process round-trip testing without a
+// real wire. The duplex `MessageConnection` pair lives in
+// `@hydranium/protocol/testing`, which owns the transport; only its TYPE is
+// re-exported here, because `DataServerHarness.pair` names it in a public
+// signature. A test that wires its own server rather than using the harness
+// calls `makeDuplexConnectionPair` from `@hydranium/protocol/testing` directly.
+
+export type { DuplexConnectionPair } from '@hydranium/protocol/testing/node';
+export * from './data-server-harness.js';