@hydranium/core 1.0.0-next.34 → 1.0.0-next.341

package/src/browser/host-heads-in-worker.ts

@@ -0,0 +1,218 @@
+/********************************************************************************
+ * 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 {
+   describeErrorWithStack,
+   isWorkerBootstrapMessage,
+   WORKER_BOOTSTRAP_PHASE,
+   WORKER_ERROR_MESSAGE_TYPE,
+   WORKER_READY_MESSAGE_TYPE,
+   type HeadPorts,
+   type WorkerErrorMessage,
+   type WorkerReadyMessage,
+   type WorkerWorkspace
+} from '@hydranium/protocol';
+import { isOperationCancelled, URI } from '@hydranium/langium';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { isFileSystemProviderRegistry } from '../langium/workspace/file-system-provider.js';
+import { hasLspConnection, initializeWorkspaceWithoutLsp } from '../langium/workspace/initialize-workspace.js';
+import { PersistentFileSystemProvider } from '../langium/workspace/persistent-file-system-provider.js';
+import { isConnectionGoneError } from '../util/connection-liveness.js';
+
+/**
+ * Report a failure to the page on the worker global, the channel no head is
+ * allowed to bind, which is what keeps it free for this. A report under
+ * {@link WORKER_BOOTSTRAP_PHASE} ends the page's heads; any other phase is
+ * shown there and the heads stay. The stack goes with it: a worker has no log
+ * anyone reads, so the page is the one place the stack can be seen.
+ */
+export function reportWorkerError(phase: string, error: unknown): void {
+   const report: WorkerErrorMessage = { type: WORKER_ERROR_MESSAGE_TYPE, phase, message: describeErrorWithStack(error) };
+   postMessage(report);
+}
+
+/** What the host's `start` hands back: the shared tier, and the readiness of any head that reports it later. */
+export interface StartedHeads {
+   readonly shared: ServerSharedServicesMinimal;
+   /**
+    * The `started` promise of every head that reports a failed start through
+    * one rather than by throwing, such as the GLSP head's. The ready message
+    * waits for them, and a rejection is a failed bootstrap.
+    */
+   readonly started?: ReadonlyArray<Promise<unknown>>;
+}
+
+/** What {@link hostHeadsInWorker} does beyond starting the heads. */
+export interface HostHeadsInWorkerOptions {
+   /**
+    * The workspace root, as the page names it in `initialize`. Given one, the
+    * ready message carries every file under it with its content, and the paths
+    * restored from a {@link PersistentFileSystemProvider}'s store under it.
+    * Left out, the ready message carries no files and nothing is read. Every
+    * file's content goes in one message, so a workspace too large for that
+    * wants a per-document read instead.
+    *
+    * Required when `start` composes no LSP head: the workspace is then brought
+    * up from it before the ready message, which nothing else would do.
+    */
+   readonly rootUri?: string;
+}
+
+/**
+ * Answer the page's bootstrap by starting the heads on its ports, once per
+ * worker, and tell the page when they are up and when something fails.
+ *
+ * `start` is synchronous by type, and that is the ordering contract: every
+ * head's transport starts its port as it is built but drops what arrives
+ * before the head listens, so an `await` between building a head and
+ * listening loses the page's first request with no error. Everything
+ * asynchronous, the filesystem's restore above all, is `prepared`, which is
+ * awaited before `start` is called. It may be a plain value where nothing has
+ * to be awaited.
+ *
+ * Once `start` has returned, every `started` it handed back has resolved and,
+ * without an LSP head, the workspace has been brought up from
+ * {@link HostHeadsInWorkerOptions.rootUri}, the ready message goes out, so a
+ * page never hears of heads that failed to come up, and an uncaught error from
+ * then on is a report rather than the end
+ * of the heads. It carries the workspace's files when
+ * {@link HostHeadsInWorkerOptions.rootUri} is given. Then every document is
+ * built with validation once the workspace has initialised: Langium's initial
+ * build validates nothing, so a page that only opens its ports would see a
+ * server that indexed the workspace and says nothing. An initial build that
+ * a write during startup cancelled is built the same, since every document
+ * exists by then.
+ *
+ * Call it once: a second call answers the same bootstrap with a second set of
+ * heads on the same ports and reports every rejection twice. The worker's
+ * `unhandledrejection` listener is this function's; it drops Langium's
+ * `OperationCancelled` marker, which a build preempted by a write rejects
+ * with, as the Node host does. An uncaught throw needs no listener, since it
+ * reaches the page as the `Worker`'s own `error` event.
+ */
+export function hostHeadsInWorker<TPrepared>(
+   prepared: TPrepared | PromiseLike<TPrepared>,
+   start: (ports: HeadPorts, prepared: TPrepared) => ServerSharedServicesMinimal | StartedHeads,
+   options: HostHeadsInWorkerOptions = {}
+): void {
+   const preparation = Promise.resolve(prepared);
+   // Handled here, so a restore that fails before the bootstrap arrives reaches
+   // the page once, under the bootstrap phase, and not first as an unhandled
+   // rejection.
+   preparation.catch(() => undefined);
+
+   // Rejections only, and not the ones the framework's own handlers already
+   // settle: a rejected LSP handler is caught by the connection, and a failed
+   // workspace walk rejects `workspaceInitialized`, which is reported below.
+   addEventListener('unhandledrejection', event => {
+      if (isOperationCancelled(event.reason)) {
+         // Dropped from the console too, as a Node listener's presence drops
+         // it there; a reported rejection keeps its console entry, the one
+         // place its stack stays navigable.
+         event.preventDefault();
+      } else {
+         reportWorkerError('unhandled rejection', event.reason);
+      }
+   });
+
+   // One bootstrap per worker: the heads are composed against a single shared
+   // Langium tree, so a second would build a second tree over the same seed and
+   // hand out sessions that silently disagree about the workspace.
+   let bootstrapped = false;
+   // The bare global rather than `self.addEventListener`: only the former is
+   // typed against the dedicated worker's event map, where `message` carries a
+   // `MessageEvent`.
+   addEventListener('message', event => {
+      if (bootstrapped || !isWorkerBootstrapMessage(event.data)) {
+         return;
+      }
+      bootstrapped = true;
+      // `.catch` rather than try/catch: a rejected restore, a `start` that
+      // throws and a head whose `started` rejects arrive by the same route, and
+      // all have to reach the page.
+      onBootstrap(event.data.ports).catch((error: unknown) => reportWorkerError(WORKER_BOOTSTRAP_PHASE, error));
+   });
+
+   async function onBootstrap(ports: HeadPorts): Promise<void> {
+      const value = await preparation;
+      const result = start(ports, value);
+      const { shared, started } = 'shared' in result ? result : { shared: result, started: undefined };
+      // Without an LSP head the workspace is brought up here, queued in the step
+      // `start` returns in: a page message is handled in a later task, so no
+      // request settles against a workspace not yet brought up. Its throw is a
+      // rejection, so the awaiting below still handles every head's `started`.
+      const bringUp = hasLspConnection(shared)
+         ? undefined
+         : new Promise<void>(resolve =>
+              resolve(initializeWorkspaceWithoutLsp(shared, options.rootUri === undefined ? undefined : URI.parse(options.rootUri)))
+           );
+      // Safe to await now: every head listens already, so nothing is lost.
+      await Promise.all([...(started ?? []), bringUp]);
+      const ready: WorkerReadyMessage = {
+         type: WORKER_READY_MESSAGE_TYPE,
+         workspace: options.rootUri === undefined ? undefined : readWorkspace(shared, options.rootUri)
+      };
+      postMessage(ready);
+      validateWorkspace(shared).catch((error: unknown) => reportWorkerError('workspace validation', error));
+   }
+}
+
+/**
+ * Every file under `rootUri`, walked through the bound provider, so a file
+ * that exists only in the store is included, which the seed's keys would miss.
+ */
+function readWorkspace(shared: ServerSharedServicesMinimal, rootUri: string): WorkerWorkspace {
+   const provider = shared.workspace.FileSystemProvider;
+   const root = URI.parse(rootUri);
+   // Keys past the root, a trailing slash on it or not.
+   const prefix = `${root.toString().replace(/\/$/, '')}/`;
+   // No prototype, so a file named `__proto__` is a key like any other.
+   const files: Record<string, string> = Object.create(null);
+   const visit = (uri: URI): void => {
+      for (const node of provider.readDirectorySync(uri)) {
+         if (node.isFile) {
+            files[node.uri.toString().slice(prefix.length)] = provider.readFileSync(node.uri);
+         } else {
+            visit(node.uri);
+         }
+      }
+   };
+   visit(root);
+   // The bound slot is the scheme registry, so the provider that holds the
+   // root is the one its scheme selects. Its store may key under another
+   // root, absolutely or unencoded, so a restored path is resolved as the
+   // provider resolves it, and one outside this root names no file here.
+   const holder = isFileSystemProviderRegistry(provider) ? provider.providerFor(root) : provider;
+   // A set, since a store may hold one file under two spellings.
+   const restored = new Set<string>();
+   if (holder instanceof PersistentFileSystemProvider) {
+      for (const path of holder.restoredPaths) {
+         const uri = holder.storeUri(path).toString();
+         if (uri.startsWith(prefix) && Object.hasOwn(files, uri.slice(prefix.length))) {
+            restored.add(uri.slice(prefix.length));
+         }
+      }
+   }
+   return { rootUri, files, restored: [...restored] };
+}
+
+/**
+ * The trailing validating build, after `workspaceInitialized`: building before
+ * it would validate a partial document set. A cancelled or connection-gone
+ * initial build is routine, so it is built through; any other failure is the
+ * caller's to report.
+ */
+async function validateWorkspace(shared: ServerSharedServicesMinimal): Promise<void> {
+   await shared.workspace.WorkspaceManager.workspaceInitialized.catch((error: unknown) => {
+      if (!isOperationCancelled(error) && !isConnectionGoneError(error)) {
+         throw error;
+      }
+   });
+   await shared.workspace.DocumentBuilder.build(shared.workspace.LangiumDocuments.all.toArray(), { validation: true });
+}

package/src/browser/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
+ ********************************************************************************/
+
+// Worker-only entry (`@hydranium/core/browser`). Compiled as its own project
+// against `lib.webworker`, so a worker global such as `indexedDB` or
+// `postMessage` resolves here and nowhere else in the package: the portable
+// `.` barrel must stay free of DOM and worker globals, since it also loads in a
+// plain Node consumer.
+export * from './host-heads-in-worker.js';
+export * from './indexeddb-file-system-store.js';
+export * from './start-language-server-in-worker.js';

package/src/browser/indexeddb-file-system-store.ts

@@ -0,0 +1,192 @@
+/********************************************************************************
+ * 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 { FileSystemSeed } from '../langium/workspace/in-memory-file-system-provider.js';
+import type { FileSystemStore } from '../langium/workspace/persistent-file-system-provider.js';
+
+/** Out-of-line keys, so a key is the store path and the value is the content. */
+const OBJECT_STORE_NAME = 'files';
+
+/**
+ * The schema version. A bump needs a migration in `onupgradeneeded`, or every
+ * returning visitor's rows are left in a store the new code never reads.
+ */
+const DATABASE_VERSION = 1;
+
+/**
+ * A {@link FileSystemStore} in `IndexedDB`, so an edit survives a reload.
+ *
+ * # Why IndexedDB and not OPFS
+ *
+ * OPFS is the tempting answer, because `createSyncAccessHandle` gives
+ * SYNCHRONOUS file reads in a worker, which is what Langium's
+ * `FileSystemProvider` needs. It buys nothing here: directory enumeration
+ * (`FileSystemDirectoryHandle.entries()`) is async-only, so a directory index
+ * still has to live in memory, and once it does the file reads are being served
+ * from memory too. IndexedDB is the smaller dependency for the same shape.
+ *
+ * # It holds the DELTA, not the workspace
+ *
+ * Only what has been written lands here, and `PersistentFileSystemProvider` lays
+ * it over the host's seed. So a fixture edited in the host's bundle still
+ * reaches a returning visitor, and this database stays a few kilobytes rather
+ * than a copy of the workspace.
+ *
+ * # A failure is loud, deliberately
+ *
+ * Nothing here degrades to non-persistent operation. A refused open, a blocked
+ * upgrade or an aborted transaction, which is what a quota overrun looks like,
+ * rejects the call, which fails the worker's bootstrap or the save that asked.
+ * The alternative, carrying on without a store, would report a saved workspace
+ * and lose it on the next load. An origin EVICTED between visits is not a
+ * failure this class can see: its database opens empty, which is a first visit,
+ * and the provider is correct in that state. Evicted mid-session, the next
+ * transaction rejects like any other failure.
+ *
+ * # The database is origin-scoped
+ *
+ * Every page on the origin shares a database of the same name, and the user
+ * agent may evict it. The name is the one per-app value and is REQUIRED for
+ * that reason: a default would let two apps on one origin overwrite each
+ * other's edits with nothing reporting it.
+ */
+export class IndexedDbFileSystemStore implements FileSystemStore {
+   /**
+    * Opened once and shared, and NOT kept when it fails: a refused or blocked
+    * open rejects the call that needed it and the next call opens again, so a
+    * cause that has cleared, such as the other tab closing, does not fail every
+    * later save with the first error.
+    */
+   protected connection?: Promise<IDBDatabase>;
+
+   constructor(protected readonly databaseName: string) {}
+
+   async load(): Promise<FileSystemSeed> {
+      const database = await this.open();
+      return new Promise<FileSystemSeed>((resolve, reject) => {
+         const transaction = database.transaction(OBJECT_STORE_NAME, 'readonly');
+         const files = transaction.objectStore(OBJECT_STORE_NAME);
+         const keyRequest = files.getAllKeys();
+         const valueRequest = files.getAll();
+         // Resolved on the TRANSACTION rather than on either request, which is
+         // what guarantees both have landed, and `getAllKeys` and `getAll`
+         // enumerate in the same key order, so they zip.
+         transaction.oncomplete = () => {
+            const keys: IDBValidKey[] = keyRequest.result;
+            const values: unknown[] = valueRequest.result;
+            const seed: Record<string, string> = {};
+            keys.forEach((key, index) => {
+               const value = values[index];
+               // Guarded rather than cast: this database outlives the code that
+               // wrote it, so a row from an older shape must be skipped instead
+               // of reaching the filesystem as non-string content.
+               if (typeof key === 'string' && typeof value === 'string') {
+                  seed[key] = value;
+               }
+            });
+            resolve(seed);
+         };
+         transaction.onabort = () => reject(this.failure(transaction, 'read the stored workspace'));
+      });
+   }
+
+   async write(path: string, content: string): Promise<void> {
+      await this.mutate('store', files => files.put(content, path));
+   }
+
+   async remove(path: string): Promise<void> {
+      await this.mutate('drop', files => files.delete(path));
+   }
+
+   /**
+    * Drop everything, returning the next load to the seed.
+    *
+    * The escape hatch a persistent host needs and a seeded one does not: a saved
+    * document that no longer parses is otherwise restored on every load, and
+    * clearing site data is the only other way out. Not on {@link FileSystemStore},
+    * which the provider never clears.
+    */
+   async clear(): Promise<void> {
+      await this.mutate('clear', files => files.clear());
+   }
+
+   /**
+    * Run one write transaction and settle on its COMPLETION.
+    *
+    * Not on the request's `success`: a request can succeed inside a transaction
+    * that then aborts, which is exactly what a quota overrun looks like, so
+    * resolving early would report a save the database never kept.
+    */
+   protected async mutate(operation: string, act: (files: IDBObjectStore) => void): Promise<void> {
+      const database = await this.open();
+      return new Promise<void>((resolve, reject) => {
+         const transaction = database.transaction(OBJECT_STORE_NAME, 'readwrite');
+         transaction.oncomplete = () => resolve();
+         transaction.onabort = () => reject(this.failure(transaction, operation));
+         act(transaction.objectStore(OBJECT_STORE_NAME));
+      });
+   }
+
+   protected open(): Promise<IDBDatabase> {
+      this.connection ??= this.openDatabase().catch((error: unknown) => {
+         this.connection = undefined;
+         throw error;
+      });
+      return this.connection;
+   }
+
+   protected openDatabase(): Promise<IDBDatabase> {
+      return new Promise<IDBDatabase>((resolve, reject) => {
+         const request = indexedDB.open(this.databaseName, DATABASE_VERSION);
+         let blocked = false;
+         request.onupgradeneeded = () => {
+            // Runs on a first visit and on a version bump. `createObjectStore`
+            // throws if it already exists, so the guard is not defensive: a page
+            // opened twice with the store created once gets here only when the
+            // version moved.
+            if (!request.result.objectStoreNames.contains(OBJECT_STORE_NAME)) {
+               request.result.createObjectStore(OBJECT_STORE_NAME);
+            }
+         };
+         request.onsuccess = () => {
+            const database = request.result;
+            if (blocked) {
+               // Went through once the other tab closed, after this call had
+               // rejected. Nobody holds it, so it is closed rather than left
+               // open to block the NEXT upgrade.
+               database.close();
+               return;
+            }
+            // A newer version opening in another tab asks this one to let go,
+            // and holding on would block that upgrade for as long as this tab
+            // lives. Dropped, so every later call here rejects, which is loud.
+            database.onversionchange = () => {
+               database.close();
+               this.connection = undefined;
+            };
+            resolve(database);
+         };
+         request.onerror = () => reject(request.error ?? new Error(`Cannot open ${this.databaseName}`));
+         // A tab at an older version that lacks the close above holds the
+         // upgrade indefinitely. Reported rather than waited on: the host can say
+         // so, where a hung open looks like a worker that never started.
+         request.onblocked = () => {
+            blocked = true;
+            reject(new Error(`${this.databaseName} is open in another tab at an older version`));
+         };
+      });
+   }
+
+   protected failure(transaction: IDBTransaction, operation: string): Error {
+      // `transaction.error` names the real cause (`QuotaExceededError` above
+      // all); an abort with no error is a caller-side abort, which nothing here
+      // does.
+      return transaction.error ?? new Error(`Failed to ${operation} in ${this.databaseName}`);
+   }
+}

package/src/browser/start-language-server-in-worker.ts

@@ -0,0 +1,56 @@
+/********************************************************************************
+ * 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 { createMessagePortTransport, type LatencyCollector, type TransferredMessagePort } from '@hydranium/protocol';
+import { createConnection, ProposedFeatures, type Connection } from 'vscode-languageserver/browser';
+import type { ServerSharedServices } from '../langium/module.js';
+import { withHydraniumLspFeatures } from '../lsp/connection-features.js';
+import { lspLatencyOptions } from '../lsp/lsp-latency.js';
+import { listenToSaveTextDocument, withSaveTextDocumentCapability } from '../lsp/save-text-document.js';
+import { startLanguageServer } from '../lsp/start-language-server.js';
+
+export interface WorkerLanguageServerOptions {
+   /** Records every request the head answers. One collector serves every head, so a report covers them all. */
+   readonly latency?: LatencyCollector;
+}
+
+/**
+ * Start the LSP head on the port the page transferred for it, and return the
+ * shared tier `compose` built around its connection.
+ *
+ * `compose` is the adopter's services factory, called with the connection
+ * exactly as a Node entry calls it with a stdio one; the filesystem it spreads
+ * in must already be restored, since every read the head makes is synchronous
+ * and the transport drops a message that arrives before `startLanguageServer`
+ * listens. The page's end of the port closing ends only this head's
+ * connection, not the worker the other heads share, so the language client's
+ * documents are closed here, each reverting as its last close does.
+ *
+ * The worker holds the files, so the page cannot write them and `didSave`
+ * reports nothing: the head answers and advertises `SaveTextDocumentRequest`.
+ */
+export function startLanguageServerInWorker<TShared extends ServerSharedServices>(
+   port: TransferredMessagePort,
+   compose: (connection: Connection) => TShared,
+   options: WorkerLanguageServerOptions = {}
+): TShared {
+   // Both ends use `createMessagePortTransport`; see it for why.
+   const transport = createMessagePortTransport(port);
+   const connection = createConnection(
+      withSaveTextDocumentCapability(withHydraniumLspFeatures(ProposedFeatures.all)),
+      transport.reader,
+      transport.writer,
+      lspLatencyOptions(options.latency)
+   );
+   const shared = compose(connection);
+   listenToSaveTextDocument(connection, shared);
+   startLanguageServer(shared);
+   transport.reader.onClose(() => void shared.workspace.TextDocuments.closeLanguageClientDocuments());
+   return shared;
+}