@hydranium/protocol 1.0.0-next.32 → 1.0.0-next.320

package/src/client/worker-handshake.ts

@@ -0,0 +1,113 @@
+/********************************************************************************
+ * 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 handshake between a page and the worker hosting its heads, shared by
+ * both ends so neither can drift from the other.
+ *
+ * **Every head gets its own `MessagePort`; none is bound to the worker
+ * global.** The heads share one worker so they share one Langium store, and
+ * that makes the global contended: a head bound to it receives every other
+ * head's traffic, since a JSON-RPC reader filters nothing. The global is
+ * unusable even for a single head: GLSP's worker launcher posts its startup
+ * handshake through the global `postMessage` regardless of the connection it
+ * was configured with, a plain string no JSON-RPC reader can parse.
+ *
+ * The global therefore carries the host protocol: the bootstrap in, the ready
+ * message and failure reports out, and whatever else the host adds for
+ * itself. A message that belongs to a head belongs on that head's port.
+ *
+ * The ports are {@link TransferredMessagePort}s, because this package compiles
+ * without the DOM lib and the structural type is also what rejects a `Worker`
+ * or the worker global at an adopter's call site.
+ */
+
+import type { TransferredMessagePort } from './post-message-transport';
+
+/** Discriminator of the bootstrap message a page posts on the worker global. */
+export const WORKER_BOOTSTRAP_MESSAGE_TYPE = 'hydranium/bootstrap';
+
+/** One transferred port per head. */
+export interface HeadPorts {
+   readonly lsp: TransferredMessagePort;
+   readonly data: TransferredMessagePort;
+   readonly glsp: TransferredMessagePort;
+}
+
+/** The one message the worker answers, by starting its heads on the ports. */
+export interface WorkerBootstrapMessage {
+   readonly type: typeof WORKER_BOOTSTRAP_MESSAGE_TYPE;
+   readonly ports: HeadPorts;
+}
+
+export function isWorkerBootstrapMessage(value: unknown): value is WorkerBootstrapMessage {
+   if (typeof value !== 'object' || value === null) {
+      return false;
+   }
+   const candidate = value as Partial<WorkerBootstrapMessage>;
+   return candidate.type === WORKER_BOOTSTRAP_MESSAGE_TYPE && typeof candidate.ports === 'object' && candidate.ports !== null;
+}
+
+/**
+ * Discriminator of the message the worker posts on the global once every head
+ * is up. Until it arrives, the page takes the `Worker`'s `error` event as a
+ * worker that never started and ends the heads; after it, as an uncaught error
+ * the worker runs on from, which it reports and keeps the heads through.
+ */
+export const WORKER_READY_MESSAGE_TYPE = 'hydranium/ready';
+
+export interface WorkerReadyMessage {
+   readonly type: typeof WORKER_READY_MESSAGE_TYPE;
+   /** The files the heads came up on, when the worker's host named a root to read them under. */
+   readonly workspace?: WorkerWorkspace;
+}
+
+/**
+ * What the worker's filesystem holds under {@link rootUri} once its heads are
+ * up, which is what a page opens its editors on: once a store can differ from
+ * the seed, an editor opened on the seed overwrites the restored document.
+ */
+export interface WorkerWorkspace {
+   readonly rootUri: string;
+   /** Every file's content, keyed by its path relative to {@link rootUri}. */
+   readonly files: Readonly<Record<string, string>>;
+   /** The paths of {@link files} that came out of the store rather than the seed. */
+   readonly restored: readonly string[];
+}
+
+export function isWorkerReadyMessage(value: unknown): value is WorkerReadyMessage {
+   return typeof value === 'object' && value !== null && (value as Partial<WorkerReadyMessage>).type === WORKER_READY_MESSAGE_TYPE;
+}
+
+/**
+ * Discriminator of a failure report the worker posts on the global.
+ *
+ * A worker has no console anyone is looking at, and the failures that matter
+ * most reach nobody by default: a workspace walk that throws has no reply to
+ * reject, so it looks exactly like a workspace with no documents in it.
+ */
+export const WORKER_ERROR_MESSAGE_TYPE = 'hydranium/worker-error';
+
+/** The phase a failed bootstrap reports under; no head answers after it. */
+export const WORKER_BOOTSTRAP_PHASE = 'bootstrap';
+
+export interface WorkerErrorMessage {
+   readonly type: typeof WORKER_ERROR_MESSAGE_TYPE;
+   /** What the worker was doing, {@link WORKER_BOOTSTRAP_PHASE} for a failed bootstrap. */
+   readonly phase: string;
+   readonly message: string;
+}
+
+export function isWorkerErrorMessage(value: unknown): value is WorkerErrorMessage {
+   if (typeof value !== 'object' || value === null) {
+      return false;
+   }
+   const candidate = value as Partial<WorkerErrorMessage>;
+   return candidate.type === WORKER_ERROR_MESSAGE_TYPE && typeof candidate.phase === 'string' && typeof candidate.message === 'string';
+}

package/src/client-ids.ts

@@ -0,0 +1,49 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Well-known values of the wire's `clientId` / `sourceClientId` field.
+ *
+ * The framework tracks each document as belonging to one or more "clients" —
+ * typically an LSP-text client (Monaco, VS Code, …), a GLSP diagram client,
+ * and/or a structured-form client — and keys its holds and watches per
+ * `(uri, clientId)`. These three values are not real participants, so a client
+ * minting its own id must avoid them.
+ *
+ * **Here rather than in the server package, because the side that has to
+ * RECOGNISE them is the client.** An inbound `onDocumentUpdated` carries
+ * `sourceClientId`, and a consumer deciding what to do with it is asking which
+ * of these it is — so a frontend would otherwise have to depend on the server
+ * tier to name three strings, and in practice retypes the literal instead.
+ */
+
+/** Identifier for an LSP-text client (Monaco, VS Code, …). */
+export const LANGUAGE_CLIENT_ID = 'language-client';
+
+/**
+ * The id an event names when no single client is behind it: the source of a
+ * `'rebuilt'` event, a document no client authored, or a build with more than
+ * one cause.
+ */
+export const UNKNOWN_CLIENT_ID = 'unknown';
+
+/**
+ * Synthetic author id on the `onDocumentUpdated` broadcast a data-server
+ * emits for the build that follows a document's release, once no client holds
+ * it; by default that build reverts the document to its disk content,
+ * discarding unsaved edits. Not a real client: it lets consumers tell the
+ * release broadcast from client-authored updates.
+ */
+export const DOCUMENT_RELEASE_CLIENT_ID = 'document-release';
+
+/**
+ * Every id the framework reserves, for a client checking that the identity it
+ * is about to mint collides with none of them.
+ */
+export const FRAMEWORK_CLIENT_IDS: readonly string[] = [LANGUAGE_CLIENT_ID, UNKNOWN_CLIENT_ID, DOCUMENT_RELEASE_CLIENT_ID];

package/src/clock.ts

@@ -14,9 +14,11 @@ import { Disposable } from './util';
  * there is no `start` — you create it at the moment timing begins.
  *
  * Backed by a monotonic source (`performance.now`), so it is sub-millisecond
- * precise and immune to wall-clock jumps (NTP/DST adjustments can make a
- * `Date.now` delta go backwards; a stopwatch cannot). Use this for durations
- * and {@link Clock.now} for "what time is it" (timestamps, TTLs).
+ * precise and immune to wall-clock steps (a time sync or a manual change can
+ * make a `Date.now` delta go backwards; a stopwatch cannot). In Node on Linux
+ * it also leaves out time the system spends suspended, so a duration spanning
+ * a suspend reads as the awake time only. Use this for every duration, a TTL
+ * included, and {@link Clock.now} for "what time is it".
  *
  * It holds no scheduled resource and is therefore NOT a {@link Disposable} —
  * the disposable thing is a {@link Clock.setTimer}. Reads are lazy, so a fake
@@ -45,16 +47,16 @@ export interface Stopwatch {
  * testable instead of waiting on real wall-clock. The {@link SystemClock}
  * default delegates to the platform; tests bind `makeFakeClock`.
  *
- * Two distinct readings on purpose: {@link now} is wall-clock (for timestamps
- * and TTLs that compare against a file's mtime), while {@link stopwatch}
- * measures durations off a monotonic source. They are different clocks; do not
- * subtract two {@link now} readings to measure a duration.
+ * Two distinct readings on purpose: {@link now} is wall-clock, for a
+ * timestamp, while {@link stopwatch} measures durations off a monotonic
+ * source. They are different clocks; do not subtract two {@link now} readings
+ * to measure a duration. Framework code reads time only through a `Clock`, so
+ * a platform workaround lives in one place.
  *
  * A cross-head contract, so it carries no platform or DI-framework coupling.
  *
- * Note: the runtime health monitors (event-loop, memory) intentionally keep
- * the real wall-clock rather than taking a `Clock` — faking the time they
- * measure would invert their meaning.
+ * Note: code that measures real CPU, heap or event-loop time never takes the
+ * bound `Clock`: faking the time it measures would invert its meaning.
  */
 export interface Clock {
    /** Current wall-clock time in milliseconds (the `Date.now` reading). */
@@ -76,8 +78,30 @@ export interface Clock {
     */
    measure<T>(callback: () => Promise<T>): Promise<Timed<T>>;
    measure<T>(callback: () => T): Timed<T>;
+   /**
+    * Settle with `promise`, or with {@link TIMED_OUT} once `ms` have elapsed
+    * first. A promise that rejects first rejects this one; one that rejects
+    * after the timer is ignored. The timer is disposed the moment `promise`
+    * settles, so a won race leaves nothing scheduled, but `promise` itself
+    * runs on: nothing here can cancel it.
+    *
+    * Unlike VS Code's `raceTimeout`, this settles with a sentinel rather than
+    * `undefined`, so a promise resolving to `undefined` is not taken for a
+    * timeout; the caller branches on the result instead of passing an
+    * `onTimeout`.
+    *
+    * A custom implementation extends {@link SystemClock}, whose race runs over
+    * the subclass's {@link setTimer}.
+    */
+   raceTimer<T>(promise: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT>;
 }
 
+/**
+ * What {@link Clock.raceTimer} settles with when its timer fires first.
+ * Registered under a global key, so two copies of this package agree on it.
+ */
+export const TIMED_OUT = Symbol.for('hydranium/protocol/timed-out');
+
 /**
  * The result of {@link Clock.measure}: a callback's return value paired with
  * its elapsed wall-time in milliseconds. A plain value object — no methods, no
@@ -144,6 +168,10 @@ function unrefTimer(handle: { unref?: () => void }): void {
  * Default {@link Clock}: delegates to the platform's `Date.now`,
  * `performance.now`, and `setTimeout`/`clearTimeout`. Bound everywhere in
  * production; swapped for `makeFakeClock` in tests.
+ *
+ * {@link measure} and {@link raceTimer} run over {@link stopwatch} and
+ * {@link setTimer}, so a clock that extends this one and replaces those
+ * measures and races on its own time, as the test clock does.
  */
 export class SystemClock implements Clock {
    now(): number {
@@ -170,4 +198,34 @@ export class SystemClock implements Clock {
       }
       return { result: result as T, elapsedMs: stopwatch.elapsedMs };
    }
+
+   /**
+    * The timer settles the race one microtask after it fires. A real timer
+    * runs only once pending resolutions are delivered, while a fake one fires
+    * inside its `advance`, so settling at once would let a promise already
+    * resolved when `advance` runs lose to a timer it beats in production. The
+    * deferral covers only that promise: one that settles through further
+    * chained reactions, such as a `.then` chain, an async function or
+    * `Promise.allSettled`, can still lose to an `advance` in the same turn,
+    * while it wins on the platform's timer. The handlers go on `promise`
+    * before {@link setTimer} runs, so a `setTimer` that throws still leaves
+    * `promise` observed.
+    */
+   raceTimer<T>(promise: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT> {
+      return new Promise<T | typeof TIMED_OUT>((resolve, reject) => {
+         // eslint-disable-next-line prefer-const -- with a `const`, a `setTimer` that throws leaves it uninitialised, and the handlers' later read of it is an unhandled ReferenceError
+         let timer: Disposable | undefined;
+         promise.then(
+            value => {
+               timer?.dispose();
+               resolve(value);
+            },
+            (err: unknown) => {
+               timer?.dispose();
+               reject(err);
+            }
+         );
+         timer = this.setTimer(() => void Promise.resolve().then(() => resolve(TIMED_OUT)), ms);
+      });
+   }
 }

package/src/console-logger.ts

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * 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 { AbstractLogger } from './abstract-logger';
+import { type LogLevel, type Logger } from './logger';
+
+/** `console.trace` prints a stack with every line, so `trace` goes out at `debug`. */
+const CONSOLE_METHODS: Record<LogLevel, 'error' | 'warn' | 'info' | 'debug'> = {
+   error: 'error',
+   warn: 'warn',
+   info: 'info',
+   debug: 'debug',
+   trace: 'debug'
+};
+
+/**
+ * {@link Logger} that writes each line to `console`, at the method matching its
+ * level: the framework's `[Label - time] [component]` prefix and the message,
+ * then any trailing arguments as they are, so a browser console can expand
+ * them. For a browser page, webview or extension host, which has no other sink
+ * to hand. On Node, `info` and `debug` reach stdout, so a process whose stdout
+ * carries a protocol stream must not use it.
+ */
+export class ConsoleLogger extends AbstractLogger implements Logger {
+   protected emit(level: LogLevel, label: string, message: string, args: readonly unknown[]): void {
+      console[CONSOLE_METHODS[level]](`${this.formatLinePrefix(label)} ${message}`, ...args);
+   }
+
+   protected derive(component: string): this {
+      const Subclass = this.constructor as new (component?: string) => this;
+      return new Subclass(component);
+   }
+}

package/src/data/data-protocol-methods.ts

@@ -20,11 +20,17 @@ import type {
 
 /** Request-method names on {@link DocumentServerProtocol}. */
 export const DOCUMENT_SERVER_PROTOCOL_METHODS = [
+   'createSession',
+   'closeSession',
+   'createModelDocument',
+   'updateModelDocuments',
    'openModelDocument',
    'closeModelDocument',
    'getModelDocument',
    'updateModelDocument',
    'saveModelDocument',
+   'persistModelDocument',
+   'deleteModelDocument',
    'watchModelDocument',
    'unwatchModelDocument',
    'waitForReady'
@@ -56,12 +62,16 @@ export const REFERENCE_SERVER_PROTOCOL_METHODS = [
    'findReferenceCandidates',
    'resolveReference',
    'findNextName'
-] as const satisfies ReadonlyArray<keyof ReferenceServerProtocol<TransferElement> & string>;
+] as const satisfies ReadonlyArray<keyof ReferenceServerProtocol & string>;
 
 /** Notification-method names on {@link DocumentClientProtocol}. */
-export const DOCUMENT_CLIENT_PROTOCOL_METHODS = ['onDocumentUpdated', 'onDocumentSaved'] as const satisfies ReadonlyArray<
-   keyof DocumentClientProtocol<TransferElement> & string
->;
+export const DOCUMENT_CLIENT_PROTOCOL_METHODS = [
+   'onDocumentUpdated',
+   'onDocumentSaved',
+   'onDocumentDirtyChanged',
+   'onDocumentDeleted',
+   'onDocumentsBuilt'
+] as const satisfies ReadonlyArray<keyof DocumentClientProtocol<TransferElement> & string>;
 
 /** Notification-method names on {@link ProjectClientProtocol}. */
 export const PROJECT_CLIENT_PROTOCOL_METHODS = ['onProjectsChanged'] as const satisfies ReadonlyArray<keyof ProjectClientProtocol & string>;