@hydranium/glsp-server 1.0.0-next.10

package/lib/node/start-glsp-server.js

@@ -0,0 +1,103 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 { SocketServerLauncher, createAppModule, defaultSocketLaunchOptions } from '@eclipse-glsp/server/node.js';
+import { Container } from 'inversify';
+import { Deferred } from '@hydranium/langium';
+import { createGlspFrameworkOverrides } from '../launcher/glsp-framework-overrides.js';
+import { createGlspServerOverrides } from '../launcher/glsp-server-overrides.js';
+/**
+ * Start a GLSP socket head. Builds the GLSP app container with framework-
+ * default `Logger` / `LoggerFactory` bindings, layers adopter modules,
+ * resolves {@link SocketServerLauncher}, configures the adopter
+ * {@link ServerModule}, and starts listening.
+ *
+ * **GLSP launcher coupling.** GLSP's {@link SocketServerLauncher} owns the
+ * `net.Server` and per-connection `MessageConnection` construction;
+ * the framework wrapper composes ABOVE that launcher rather than replacing
+ * it. The framework's own `startSocketServer`
+ * helper is NOT used here — it's designed for stdio/raw-JSON-RPC heads
+ * (data-server's pattern), not GLSP's Inversify-driven per-connection
+ * server-instance model. Bridging the two would lose GLSP's action-handler
+ * registry plumbing.
+ */
+export function startGlspServer(options) {
+    const launchOptions = {
+        ...defaultSocketLaunchOptions,
+        host: options.host ?? '127.0.0.1',
+        port: options.port ?? 0
+    };
+    const lifecycle = options.logger;
+    // Start from GLSP's own app module rather than re-deriving its bindings by
+    // hand. createAppModule binds InjectionContainer + Logger/LoggerFactory and
+    // — crucially — whatever else the resolved GLSP version's app container needs,
+    // so the framework tracks GLSP across versions instead of drifting. consoleLog /
+    // fileLog are forced off so GLSP binds a throwaway NullLogger with no winston
+    // instance; the override module below replaces Logger/LoggerFactory with the
+    // adopter's logger, so GLSP server logs flow through options.createLogger.
+    const glspAppModule = createAppModule({ ...launchOptions, consoleLog: false, fileLog: false });
+    const appContainer = new Container();
+    appContainer.load(glspAppModule, createGlspFrameworkOverrides(options.createLogger), ...(options.appModules ?? []));
+    const launcher = appContainer.resolve(SocketServerLauncher);
+    // Passed as an additional module rather than folded into the app container:
+    // the launcher loads these into the per-connection SERVER container, which is
+    // the only tier where the adopter's `ServerModule` binding of `GLSPServer`
+    // can be rebound.
+    launcher.configure(options.serverModule, createGlspServerOverrides());
+    const started = new Deferred();
+    const portHandle = { port: undefined };
+    try {
+        const stoppedPromise = Promise.resolve(launcher.start(launchOptions));
+        // GLSP's `SocketServerLauncher.netServer` field is `protected`; we
+        // access it via property indexing. The alternative is to fork the
+        // launcher or add a 'listening' callback to GLSP upstream.
+        const netServer = launcher.netServer;
+        netServer.on('listening', () => {
+            const address = netServer.address();
+            if (address && typeof address !== 'string') {
+                portHandle.port = address.port;
+                if (options.lspConnection && options.portCommand) {
+                    options.lspConnection.onRequest(options.portCommand, () => portHandle.port);
+                }
+                lifecycle?.info(`[GlspServer] Ready to accept new client requests on port: ${address.port}`);
+                started.resolve();
+            }
+            else {
+                const message = address === null ? 'address is null' : `bound to non-TCP "${String(address)}"`;
+                lifecycle?.error(`[GlspServer] Could not resolve address info — ${message}. Shutting down.`);
+                started.reject(new Error(`startGlspServer could not resolve address info — ${message}`));
+                netServer.close();
+            }
+        });
+        netServer.on('error', (err) => {
+            lifecycle?.error(`[GlspServer] Error: ${err.message}`);
+            started.reject(err);
+        });
+        if (options.onClientConnection) {
+            netServer.on('connection', options.onClientConnection);
+        }
+        return {
+            get port() {
+                return portHandle.port;
+            },
+            started: started.promise,
+            stopped: stoppedPromise
+        };
+    }
+    catch (error) {
+        lifecycle?.error('Error in GLSP server launcher:', error);
+        return {
+            get port() {
+                return portHandle.port;
+            },
+            started: Promise.reject(error),
+            stopped: Promise.resolve()
+        };
+    }
+}
+//# sourceMappingURL=start-glsp-server.js.map

package/lib/node/start-glsp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-glsp-server.js","sourceRoot":"","sources":["../../src/node/start-glsp-server.ts"],"names":[],"mappings":"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"}

package/lib/state/abstract-hydranium-glsp-state.d.ts

@@ -0,0 +1,333 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 { DefaultModelState, type MaybePromise } from '@eclipse-glsp/server';
+import { Emitter, type Event } from 'vscode-jsonrpc';
+import { type AstNode, DocumentState } from '@hydranium/langium';
+import { type HydraniumScopeProvider, type LanguageTarget, type NameProvider, type ReferenceCandidateProvider, type ServerLanguageServices, type ServerSharedServices } from '@hydranium/core';
+import type { ConflictResolver, Logger, Tracer } from '@hydranium/protocol';
+import { type HydraniumGlspIndex } from './hydranium-glsp-index.js';
+import { ModelReadyTimeoutError } from './model-ready-timeout-error.js';
+/**
+ * GLSP model state base shared by all hydranium adopters. Tracks the source
+ * AST root + URI alongside GLSP's GModel, exposes a build-state wait with
+ * timeout-and-race semantics, and wires a logger labelled with the adopter's
+ * component name + current document URI.
+ *
+ * **Source-root vs GLSP's `sourceUri`.** GLSP's {@link DefaultModelState}
+ * stores `sourceUri` via the loosely-typed properties map
+ * (`state.set(SOURCE_URI_ARG, uri)`). This base class makes the URI a
+ * first-class typed field set through {@link setSourceRoot}, then mirrors
+ * the value into the inherited properties map so legacy code paths that
+ * still call `state.get(SOURCE_URI_ARG)` continue to work. The inherited
+ * `sourceUri` getter is overridden to a narrowed `string` return (no
+ * `undefined` once {@link setSourceRoot} has run).
+ *
+ * **Hooks.**
+ * - {@link onReadyRefreshed} — runs after {@link ready} returns. Default
+ *   calls {@link refreshSourceRoot} so callers see a fresh AST after a
+ *   wait that may have rebuilt the document. Adopters whose AST is
+ *   immutable between build phases can override to a no-op.
+ * - {@link buildReadyTimeoutError} — constructs the timeout error with the
+ *   workspace-relative path + the document builder's build-status snapshot;
+ *   override only to change the error shape (richer per-adopter output comes
+ *   from overriding `wsRelativePath` / `formatBuildStatus`).
+ * - logging — see {@link baseTracer}. Adopters wanting a different label
+ *   override `setSourceRoot` and derive via
+ *   `this.baseTracer.for('Name').withUri(uri)`.
+ *
+ * **Lifecycle ordering.** Reading {@link sourceUri} or {@link sourceRoot}
+ * before the first {@link setSourceRoot} call throws via the
+ * definite-assignment assertions — callers must invoke `setSourceRoot`
+ * (typically from the storage `loadSourceModel` flow) before reading them.
+ * The {@link logger}/{@link tracer} are the exception: the injected
+ * {@link baseTracer} is always available, so the getters fall back to it
+ * before {@link setSourceRoot} derives the URI-tagged {@link _tracer} —
+ * logging is never `undefined`.
+ */
+export declare abstract class AbstractHydraniumGlspState<TRoot extends AstNode, TSourceModel = string> extends DefaultModelState {
+    protected readonly sharedServices: ServerSharedServices;
+    /**
+     * Conflict-resolution policy consulted when a write races a foreign edit
+     * (forward-write, undo, redo, save). Bound by
+     * `HydraniumGlspAppModule` to the adopter's choice — default
+     * `ReconcilingConflictResolver` (field-level merge) unless the adopter
+     * passes a `ForceConflictResolver` (last-writer-wins). Read by
+     * `HydraniumGlspRecordingCommand`'s undo / redo and by adopter
+     * `updateSourceModel` implementations.
+     */
+    readonly conflictResolver: ConflictResolver;
+    /**
+     * Per-class tracer, caller-tagged with this state's runtime subclass name by
+     * the `HydraniumTypes.Tracer` binding. {@link setSourceRoot} derives the
+     * URI-tagged {@link _tracer} from it; the {@link tracer}/{@link logger}
+     * getters fall back to it before then, so logging is never `undefined`.
+     */
+    protected readonly baseTracer: Tracer;
+    /** Narrows {@link DefaultModelState.index} to the framework-extended index type. */
+    readonly index: HydraniumGlspIndex;
+    protected _sourceUri: string;
+    protected _sourceRoot: TRoot;
+    protected _tracer?: Tracer;
+    protected _version: number;
+    /** Based-on versions of the secondary write set, keyed by URI. See {@link trackSecondaryDocument}. */
+    protected readonly _secondaryVersions: Map<string, number>;
+    /** Backing emitter for {@link onSecondaryUrisChanged}; fired only on a membership change. */
+    protected readonly secondaryUrisChangedEmitter: Emitter<void>;
+    /** Default of one minute. */
+    static readonly DEFAULT_READY_TIMEOUT_MS = 60000;
+    /** Maximum wait inside {@link readyWithTimeout} before raising {@link ModelReadyTimeoutError}. */
+    protected readyTimeoutMs: number;
+    /**
+     * Capture a freshly built source root alongside its URI, refresh the
+     * logger to label log lines with the URI, and re-index the AST so
+     * downstream GModel projection can resolve elements back to nodes.
+     *
+     * Also mirrors `uri` into the inherited properties map under
+     * {@link SOURCE_URI_ARG} so legacy GLSP code paths (`state.get(...)`)
+     * stay consistent with the typed field.
+     */
+    setSourceRoot(uri: string, root: TRoot): void;
+    /**
+     * Typed override of {@link DefaultModelState.sourceUri}. Narrows the
+     * inherited `string | undefined` to `string` (defined after
+     * {@link setSourceRoot}; throws on definite-assignment otherwise).
+     */
+    get sourceUri(): string;
+    get sourceRoot(): TRoot;
+    /**
+     * The language services of the grammar this DIAGRAM TYPE edits, as declared
+     * by `AbstractHydraniumGlspDiagramModule.declareLanguage`.
+     *
+     * **Named for what it is, not for "the language".** Reach for it only when
+     * the thing you are asking about lives in the diagram document itself.
+     * Anything reached *through* a reference is decided by its own document: use
+     * {@link languageServicesFor}. Making that choice explicit at the call site
+     * is the point; a neutral-looking `languageServices` invites the diagram's
+     * grammar to be applied to a foreign node, which is the defect this whole
+     * seam exists to prevent.
+     *
+     * Injected rather than derived from {@link sourceUri} so it is available
+     * before the first {@link setSourceRoot} — GLSP constructs operation
+     * handlers at `InitializeClientSession`, well before `RequestModelAction`.
+     * `@optional()` so a harness that binds no diagram module still resolves;
+     * `undefined` then means no diagram module declared a grammar.
+     */
+    readonly diagramLanguage?: ServerLanguageServices;
+    /**
+     * The language services owning `target` — an AST node (routed by its
+     * document), a URI, or a URI string — falling back to
+     * {@link diagramLanguage} when `target` routes nowhere.
+     *
+     * Use this wherever the thing being named, keyed or completed may live in
+     * another document than the diagram. Two registered languages are free to
+     * differ in `nameProperties` / `nameSeparator` and in their element-key
+     * strategy, so applying the diagram's provider to a foreign node yields a
+     * plausible-looking string that matches nothing — silently, with no
+     * diagnostic. The fallback covers the genuinely unroutable case, a synthetic
+     * node not yet attached to a document, where the diagram's own language is
+     * the only defensible answer.
+     */
+    languageServicesFor(target: LanguageTarget | undefined): ServerLanguageServices | undefined;
+    /**
+     * The `NameProvider` of the language owning `target` — the shorthand for
+     * `languageServicesFor(target)?.references.NameProvider`.
+     *
+     * The shorthands exist because the long form names `target` twice and
+     * threads an optional through a four-link chain, which is enough friction
+     * that the tempting alternative is a captured provider — the defect this
+     * seam exists to prevent. Keeping the correct call the SHORT one is the
+     * point. They stay provider-level rather than operation-level so they
+     * compose with every provider method and the state does not grow a naming
+     * API of its own.
+     */
+    nameProviderFor(target: LanguageTarget | undefined): NameProvider | undefined;
+    /** The `ScopeProvider` of the language owning `target`. See {@link nameProviderFor}. */
+    scopeProviderFor(target: LanguageTarget | undefined): HydraniumScopeProvider | undefined;
+    /** The `ReferenceCandidateProvider` of the language owning `target`. See {@link nameProviderFor}. */
+    candidateProviderFor(target: LanguageTarget | undefined): ReferenceCandidateProvider | undefined;
+    /**
+     * Warn when the loaded document does not route to the grammar this diagram
+     * module declared.
+     *
+     * The declared language is the one fact the module states that the grammar
+     * itself does not, so it is the one that can drift — a diagram type pointed
+     * at the wrong `LanguageMetaData`, or a file extension reassigned. Both
+     * would otherwise surface much later as references resolving against the
+     * wrong scope. Only a warning, not a throw: the document is loaded and
+     * usable either way, and a hard failure here would take out a diagram over
+     * a mismatch that may be intentional in an adopter serving one diagram type
+     * over several grammars.
+     */
+    protected checkDeclaredLanguage(uri: string): void;
+    /** The observability handle as a plain {@link Logger} (a {@link Tracer} is-a Logger). */
+    get logger(): Logger;
+    /** URI-tagged once {@link setSourceRoot} has run; the class-tagged injected {@link baseTracer} before that. */
+    get tracer(): Tracer;
+    /**
+     * Text-document version captured at the last {@link setSourceRoot}
+     * call. Mirrors the server-side `TextDocuments.version(uri)` counter
+     * at that point in time — frozen until the next `setSourceRoot`, then
+     * re-read from `LangiumDocuments`.
+     *
+     * Threaded by `HydraniumGlspRecordingCommand` into
+     * {@link updateSourceModel}'s optional `version` parameter so the
+     * downstream `ModelService.update` / `.save` call can opt into the
+     * conflict gate against the captured based-on version. See
+     * `@hydranium/protocol#ConflictError` for the detection contract.
+     *
+     * Falls back to `0` when the document is absent from `LangiumDocuments`
+     * at capture time — the same observable state callers see for a doc
+     * that was never opened. Callers that need to distinguish
+     * "never-versioned" from "v0" must consult the document registry
+     * directly.
+     */
+    get version(): number;
+    /**
+     * Register `uri` as a document this state also writes, capturing its current
+     * text-document version.
+     *
+     * A diagram whose layout lives in its own file, or whose canvas creates
+     * elements in a referenced semantic document, writes more than the document
+     * it was opened on. The primary (`sourceUri`) stays the one that drives
+     * GModel projection and the conflict gate; secondaries are the rest of the
+     * write set.
+     *
+     * Registering is the adopter's call because the set is usually discovered
+     * rather than known: the semantic document a node belongs to is only
+     * identified once the operation names the node. What the framework supplies
+     * is the part an adopter cannot reconstruct after the fact — the version each
+     * document was at BEFORE the command mutated anything (see
+     * {@link capturedVersionOf}). Idempotent; registering the primary is ignored,
+     * since {@link version} already tracks it. Registering a URI not already in
+     * the set fires {@link onSecondaryUrisChanged}.
+     */
+    trackSecondaryDocument(uri: string): void;
+    /**
+     * Drop every registered secondary. Call when the write set is rebuilt from
+     * scratch. Fires {@link onSecondaryUrisChanged} when the set was non-empty.
+     */
+    untrackSecondaryDocuments(): void;
+    /**
+     * Fires whenever the secondary write set gains or loses a URI — never when a
+     * tracked document's captured version is merely refreshed, which happens on
+     * every {@link setSourceRoot} and changes nothing a subscriber cares about.
+     *
+     * **This exists so no caller has to know when the set can change.** The set is
+     * usually discovered rather than known, and the discovery point is an
+     * operation handler naming a node — not a capture. A subscriber that instead
+     * re-derived the set after each capture would miss exactly that case, and miss
+     * it silently: the document would simply never be watched, with nothing logged.
+     * Announcing the change here moves the obligation to the one place that can
+     * always discharge it.
+     *
+     * The set is the one {@link trackSecondaryDocument} /
+     * {@link untrackSecondaryDocuments} maintain. A subclass that writes
+     * {@link _secondaryVersions} directly bypasses the notification and owns the
+     * consequences.
+     */
+    get onSecondaryUrisChanged(): Event<void>;
+    /** Registered secondary document URIs, in registration order. */
+    get secondaryUris(): readonly string[];
+    /**
+     * Based-on version captured for `uri` — {@link version} for the primary, the
+     * value captured at {@link trackSecondaryDocument} (refreshed by
+     * {@link setSourceRoot}) for a secondary, `undefined` for anything untracked.
+     *
+     * `undefined` rather than `0` for an untracked URI deliberately: `0` is a real
+     * version meaning "present but never edited", so collapsing the two would let
+     * a caller gate a write against a document it never captured.
+     */
+    capturedVersionOf(uri: string): number | undefined;
+    /**
+     * Read a document's current text-document version through the model service's
+     * canonicalizing gateway, so a URI spelled through a symlink still resolves to
+     * the document keyed by its real path rather than stranding at `0` (which
+     * would silently weaken the conflict gate). Optional-chained on `textDocument`
+     * so a fixture that omits it does not throw; real Langium documents always
+     * populate it.
+     */
+    protected readDocumentVersion(uri: string): number;
+    /** Re-read every registered secondary's version from the document store. */
+    protected refreshSecondaryVersions(): void;
+    /**
+     * Re-capture the source root from the current Langium document,
+     * replacing any orphaned root. A rebuild between an earlier
+     * {@link setSourceRoot} and the current read can swap the AST out
+     * from under us; downstream consumers (GModel factories, action
+     * handlers) must see the root the freshly built document carries.
+     */
+    protected refreshSourceRoot(): void;
+    /**
+     * Wait until the captured document reaches `state`, then run
+     * {@link onReadyRefreshed} so consumers see a fresh AST. Wraps the
+     * wait in {@link Tracer.time} for observability.
+     */
+    ready(state: DocumentState): Promise<void>;
+    /**
+     * Race `ModelService.waitForDocumentState` against
+     * {@link readyTimeoutMs}. If the timeout fires but the document has
+     * already reached `state` silently (Langium build-phase event race),
+     * log a warning and resolve; otherwise raise
+     * {@link ModelReadyTimeoutError} via {@link buildReadyTimeoutError}.
+     */
+    protected readyWithTimeout(state: DocumentState): Promise<void>;
+    /**
+     * Hook for post-{@link ready} work. Default refreshes the captured
+     * source root via {@link refreshSourceRoot} so submission handlers and
+     * GModel factories see the AST the now-ready document carries.
+     * Adopters whose AST is immutable between build phases override to a
+     * no-op.
+     */
+    protected onReadyRefreshed(): Promise<void>;
+    /**
+     * Build the {@link ModelReadyTimeoutError} thrown by
+     * {@link readyWithTimeout}. Reports the workspace-relative path plus the
+     * document builder's current build-status snapshot, both via framework
+     * methods — so adopters that override `WorkspaceManager.wsRelativePath` /
+     * `DocumentBuilder.formatBuildStatus` for richer output get it here without
+     * touching this method. Override only to change the error shape itself.
+     */
+    protected buildReadyTimeoutError(state: DocumentState, elapsed: number): ModelReadyTimeoutError;
+    /**
+     * Persist a new source-model representation back to the document store
+     * after an interactive edit. Adopters wire this against their
+     * language-services facade. The `HydraniumGlspRecordingCommand` calls
+     * it from its `postChange` hook to commit the edited AST back to the
+     * document store.
+     *
+     * Adopters whose source model is a structured transfer projection
+     * round-tripped through `ModelService` should extend
+     * `ReconcilingTransferHydraniumGlspState` instead of implementing this
+     * directly — it ships a concrete forward-write reconcile template
+     * (persist + conflict resolve) over overridable `persist` / `refetch`
+     * hooks. This base stays abstract for whole-document-text and read-only
+     * adopters.
+     *
+     * Abstract rather than no-op so adopters that mean to be editable cannot
+     * silently lose edits — read-only adopters can throw with a clear message,
+     * but the decision is explicit.
+     *
+     * The read side of the source-model contract (a `sourceModel` getter) is
+     * NOT lifted onto the framework state — adopters that consume the
+     * recording-command pattern declare `implements JsonModelState<TSourceModel>`
+     * themselves so the framework state stays slim. Both halves of the GLSP
+     * `JsonModelState` shape meet the framework state via structural
+     * intersection at the recording-command call site.
+     *
+     * `version` is the based-on text-document version captured at command
+     * start by `HydraniumGlspRecordingCommand.execute`. Adopters that
+     * route through `ModelService.update` / `.save` pass it as the args'
+     * `version` field to opt into the conflict gate; adopters that don't
+     * care (or whose write path doesn't go through `ModelService`) ignore
+     * the parameter. Undefined when the writer is not the recording-command
+     * (e.g. external storage refresh paths).
+     */
+    abstract updateSourceModel(model: TSourceModel, version?: number): MaybePromise<void>;
+}
+//# sourceMappingURL=abstract-hydranium-glsp-state.d.ts.map

package/lib/state/abstract-hydranium-glsp-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-hydranium-glsp-state.d.ts","sourceRoot":"","sources":["../../src/state/abstract-hydranium-glsp-state.ts"],"names":[],"mappings":"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"}