@hydranium/glsp-server 1.0.0-next.15 → 1.0.0-next.155

package/src/command/hydranium-glsp-recording-command.ts

@@ -10,6 +10,7 @@
 import { type AnyObject, type JsonModelState, JsonRecordingCommand, type MaybePromise } from '@eclipse-glsp/server';
 import { type AstNode } from '@hydranium/langium';
 import { type AbstractHydraniumGlspState } from '../state/abstract-hydranium-glsp-state.js';
+import { type BasedOn } from '@hydranium/protocol';
 
 /**
  * Source-model state shape consumed by {@link HydraniumGlspRecordingCommand}.
@@ -46,25 +47,25 @@ export type HydraniumGlspRecordingState<TSourceModel extends AnyObject> = Abstra
  *
  * **postChange semantics.** GLSP's `JsonRecordingCommand.postChange` calls
  * `modelState.updateSourceModel(newModel)` with the model only. The
- * framework lift overrides `postChange` so it also threads the based-on
- * version captured at command start — letting the downstream
- * `ModelService.update` opt into the `ConflictError` gate. Undo / redo
- * postChange calls run with version `undefined` (no gating): the user
- * authored against the recorded patch, not against a specific server
- * version, so re-applying it should succeed regardless of intervening
- * edits. The recorded patch itself encodes the semantic intent.
+ * framework lift overrides `postChange` so it also threads the snapshot
+ * version taken at command start — letting the downstream
+ * session `update` opt into the `ConflictError` gate. Undo / redo
+ * postChange calls pass `'anything'`: the user authored against the recorded
+ * patch, not against a specific server version, so re-applying it should
+ * succeed regardless of intervening edits. The recorded patch itself encodes
+ * the semantic intent.
  */
 export class HydraniumGlspRecordingCommand<TSourceModel extends AnyObject> extends JsonRecordingCommand<TSourceModel> {
    declare protected modelState: HydraniumGlspRecordingState<TSourceModel>;
 
    /**
-    * Based-on version captured at {@link execute} start; threaded into
-    * {@link postChange} so {@link AbstractHydraniumGlspState.updateSourceModel}
-    * sees the version the user authored against. Cleared after `execute`
-    * returns so undo / redo paths fall through to `updateSourceModel`
-    * without a version (no gating).
+    * What the command was authored against, taken at {@link execute} start and
+    * threaded into {@link postChange} so
+    * {@link AbstractHydraniumGlspState.updateSourceModel} gates on it. Reset to
+    * `'anything'` after `execute` returns so undo / redo paths fall through
+    * ungated.
     */
-   protected activeVersion?: number;
+   protected activeBasedOn: BasedOn = 'anything';
 
    /**
     * Source-model snapshots captured at {@link execute} — the state the
@@ -98,20 +99,19 @@ export class HydraniumGlspRecordingCommand<TSourceModel extends AnyObject> exten
     * via {@link AbstractHydraniumGlspState.updateSourceModel}). The label combines
     * the operation name with the source-uri-stamped logger.
     *
-    * Captures {@link AbstractHydraniumGlspState.version} at start so {@link postChange}
-    * can thread the based-on version into `updateSourceModel`. The capture
-    * is `try`/`finally`-scoped so undo / redo paths invoked later do not
-    * see a stale captured version.
+    * Takes {@link AbstractHydraniumGlspState.basedOn} at start so {@link postChange}
+    * can thread it into `updateSourceModel`. Scoped with `try`/`finally` so undo
+    * / redo paths invoked later do not see a stale value.
     */
    override async execute(): Promise<void> {
       const logger = this.modelState.logger.for('HydraniumGlspRecordingCommand');
-      this.activeVersion = this.modelState.version;
-      logger.debug(`Executing '${this.label}' (based-on doc.version=v${this.activeVersion})`);
+      this.activeBasedOn = this.modelState.basedOn;
+      logger.debug(`Executing '${this.label}' (based-on doc.version=v${this.modelState.version})`);
       this.beforeSnapshot = this.deepClone(await this.getJsonObject());
       try {
          await this.modelState.tracer.for('HydraniumGlspRecordingCommand').time(`Execute command '${this.label}'`, () => super.execute());
       } finally {
-         this.activeVersion = undefined;
+         this.activeBasedOn = 'anything';
       }
       this.afterSnapshot = this.deepClone(await this.getJsonObject());
    }
@@ -119,15 +119,15 @@ export class HydraniumGlspRecordingCommand<TSourceModel extends AnyObject> exten
    /**
     * Override of GLSP's {@link JsonRecordingCommand.postChange} so the
     * call to {@link AbstractHydraniumGlspState.updateSourceModel} threads the
-    * captured based-on version alongside the new model.
+    * based-on version alongside the new model.
     *
-    * During {@link execute} the version is the snapshot captured at
-    * command start; during {@link undo} / {@link redo} it is `undefined`
-    * — replaying a recorded patch does not author against a specific
-    * server version, so no gate applies.
+    * During {@link execute} it is the snapshot version taken at command start;
+    * during {@link undo} / {@link redo} it is `'anything'` — replaying a
+    * recorded patch does not author against a specific server version, so no
+    * gate applies.
     */
    protected override postChange(newModel: TSourceModel): MaybePromise<void> {
-      return this.modelState.updateSourceModel(newModel, this.activeVersion);
+      return this.modelState.updateSourceModel(newModel, this.activeBasedOn);
    }
 
    /**

package/src/command/index.ts

@@ -8,3 +8,4 @@
  ********************************************************************************/
 
 export * from './hydranium-glsp-recording-command.js';
+export * from './hydranium-glsp-command-stack.js';

package/src/launcher/abstract-hydranium-glsp-diagram-module.ts

@@ -7,11 +7,19 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { DiagramModule } from '@eclipse-glsp/server';
+import {
+   type ActionHandlerConstructor,
+   type BindingTarget,
+   type CommandStack,
+   DiagramModule,
+   type InstanceMultiBinding
+} from '@eclipse-glsp/server';
 import { injectable, type interfaces } from 'inversify';
 import type { LanguageMetaData } from '@hydranium/langium';
 import { type ServerLanguageServices, type ServerSharedServices, typedMetadata } from '@hydranium/core';
 import { HydraniumTypes } from '../state/hydranium-shared-core-services.js';
+import { HydraniumGlspRequestSaveModelActionHandler } from '../storage/hydranium-glsp-request-save-model-action-handler.js';
+import { HydraniumGlspCommandStack } from '../command/hydranium-glsp-command-stack.js';
 
 /**
  * Bind {@link HydraniumTypes}.DiagramLanguage on a GLSP **session** container
@@ -20,8 +28,10 @@ import { HydraniumTypes } from '../state/hydranium-shared-core-services.js';
  * Exported separately from {@link AbstractHydraniumGlspDiagramModule} for adopters
  * whose diagram module already extends an intermediate base of their own and
  * cannot take the framework base class; call it from `configure` after
- * `super.configure(...)`. The base class is the preferred entry point because
- * it makes the declaration non-optional.
+ * `super.configure(...)`, add {@link HydraniumGlspRequestSaveModelActionHandler}
+ * in `configureActionHandlers`, and return {@link HydraniumGlspCommandStack} from
+ * `bindCommandStack`, all of which the base also does. The base class is the
+ * preferred entry point because it makes the declaration non-optional.
  *
  * **Why the session tier.** GLSP builds its app container once per process,
  * before any document exists, so a per-language service bound there can only
@@ -114,4 +124,18 @@ export abstract class AbstractHydraniumGlspDiagramModule extends DiagramModule {
       super.configure(bind, unbind, isBound, rebind);
       bindDiagramLanguage(bind, this.declareLanguage());
    }
+
+   /** {@link HydraniumGlspCommandStack}, so the diagram is dirty exactly while a document it has open is. */
+   protected override bindCommandStack(): BindingTarget<CommandStack> {
+      return HydraniumGlspCommandStack;
+   }
+
+   /**
+    * Adds {@link HydraniumGlspRequestSaveModelActionHandler}, the save the
+    * Theia client sends, beside GLSP's own save handler.
+    */
+   protected override configureActionHandlers(binding: InstanceMultiBinding<ActionHandlerConstructor>): void {
+      super.configureActionHandlers(binding);
+      binding.add(HydraniumGlspRequestSaveModelActionHandler);
+   }
 }

package/src/launcher/glsp-server-overrides.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { GLSPServer } from '@eclipse-glsp/server';
+import { DefaultGLSPServer, GLSPServer, LoggerFactory } from '@eclipse-glsp/server';
 import { ContainerModule } from 'inversify';
 import { HydraniumGlspServer } from './hydranium-glsp-server.js';
 
@@ -18,15 +18,17 @@ import { HydraniumGlspServer } from './hydranium-glsp-server.js';
  *
  * **The tier matters, and the app container cannot stand in for it.** GLSP's
  * launcher creates the server container as a child and loads the adopter's
- * `ServerModule` into it, so a `GLSPServer` binding made further up is shadowed
- * rather than consulted, and inversify refuses to rebind a parent's binding
- * from a child at all. The framework's app-tier overrides therefore cannot
- * reach this symbol.
+ * `ServerModule` into it. The framework's server is a singleton of that
+ * container; bound in the app container, every connected application would
+ * share one server.
  *
- * **Load this AFTER the adopter's `ServerModule`, never beside it.** Both bind
- * `GLSPServer`, so a plain second binding resolves to an ambiguous-match error
- * rather than to either one; `rebind` needs the first binding to already be
- * present.
+ * **An adopter's server is kept when it extends {@link HydraniumGlspServer}.**
+ * Any other `GLSPServer` the adopter's `ServerModule` binds, upstream's default
+ * included, is replaced when the container first creates it, so a server that
+ * extends upstream's directly is discarded, with a warning naming its class.
+ * The replacement happens on activation because `rebind` would replace an
+ * adopter's subclass as well; the discarded server is constructed once and
+ * never used.
  *
  * Keeping this out of the adopter's hands is the point: an adopter passes their
  * own `ServerModule` in, so anything they must add themselves is a fix the
@@ -40,7 +42,21 @@ import { HydraniumGlspServer } from './hydranium-glsp-server.js';
  * a further adopter subclass moves it again.
  */
 export function createGlspServerOverrides(): ContainerModule {
-   return new ContainerModule((_bind, _unbind, _isBound, rebind) => {
-      rebind(GLSPServer).to(HydraniumGlspServer).inSingletonScope();
+   return new ContainerModule((bind, _unbind, _isBound, _rebind, _unbindAsync, onActivation) => {
+      bind(HydraniumGlspServer).toSelf().inSingletonScope();
+      onActivation<GLSPServer>(GLSPServer, (context, server) => {
+         if (server instanceof HydraniumGlspServer) {
+            return server;
+         }
+         if (server.constructor !== DefaultGLSPServer) {
+            context.container
+               .get<LoggerFactory>(LoggerFactory)('HydraniumGlspServer')
+               .warn(
+                  `Replacing the bound GLSP server ${server.constructor.name} with HydraniumGlspServer; ` +
+                     'extend HydraniumGlspServer to keep its behaviour.'
+               );
+         }
+         return context.container.get(HydraniumGlspServer);
+      });
    });
 }

package/src/launcher/hydranium-glsp-server.ts

@@ -15,6 +15,7 @@ import {
    type RequestAction,
    type ResponseAction
 } from '@eclipse-glsp/server';
+import { RequestSaveModelAction } from '@hydranium/protocol';
 import { injectable } from 'inversify';
 
 /**
@@ -26,9 +27,10 @@ import { injectable } from 'inversify';
  * `error.cause?.toString()` whenever the error is a {@link GLSPServerError},
  * and that one value feeds both the server log and the client's
  * {@link RejectAction}. A {@link GLSPServerError} carrying no `cause` therefore
- * reaches no reader at all — not the toast, not the details pane, not the log —
- * while a plain `Error` survives, because the other branch reads the error
- * itself. The typed error is the trap, and it is the one upstream's own
+ * reaches its readers as `undefined` — the log line and the client's
+ * action-dispatcher warning both print it — while a plain `Error` survives,
+ * because the other branch reads the error itself. The typed error is the trap,
+ * and it is the one upstream's own
  * `getOrThrow` helper raises: that helper's signature cannot pass a `cause`, so
  * an adopter using the sanctioned helper has no fix available on their side.
  * Restating the cause at each throw site is the alternative, and it costs
@@ -37,10 +39,10 @@ import { injectable } from 'inversify';
  * Only the REQUEST path needs this. Non-request actions fail through
  * upstream's `handleProcessError`, which reads `message` directly.
  *
- * Adopters who bind their own GLSP server should extend this class rather than
- * {@link DefaultGLSPServer}; the framework's server-container override replaces
- * whatever the adopter's `ServerModule` bound, so a subclass of upstream's
- * server would be discarded.
+ * An adopter who binds their own GLSP server extends this class rather than
+ * {@link DefaultGLSPServer}: the framework's server-container override keeps a
+ * server that extends this one and replaces any other, so a subclass of
+ * upstream's server is discarded.
  */
 @injectable()
 export class HydraniumGlspServer extends DefaultGLSPServer {
@@ -63,9 +65,12 @@ export class HydraniumGlspServer extends DefaultGLSPServer {
    /**
     * Lifted verbatim from `@eclipse-glsp/server` 2.7.0's
     * {@link DefaultGLSPServer.handleClientRequest}, with the detail computation
-    * delegated to {@link requestFailureDetail}. Nothing else here — the
-    * timeout branch, the response dispatch, the nested send-failure handling —
-    * relates to that fallback.
+    * delegated to {@link requestFailureDetail}, and one addition: a failed
+    * {@link RequestSaveModelAction} also raises the error notification a failed
+    * `SaveModelAction` raises. A rejection reaches only the client's log, and a
+    * Theia host only logs a rejected save, so without it a save that failed
+    * would tell the user nothing. Nothing else here — the timeout branch, the
+    * response dispatch, the nested send-failure handling — relates to either.
     *
     * **This body does not track upstream.** A release that changes request
     * handling would silently not apply, on the path every request takes. There
@@ -96,6 +101,11 @@ export class HydraniumGlspServer extends DefaultGLSPServer {
                detail
             });
             this.sendResponseToClient(clientId, reject);
+            // Inside the guard: `process` does not await this method, so a
+            // closed connection throwing here would be an unhandled rejection.
+            if (action.kind === RequestSaveModelAction.KIND) {
+               this.handleProcessError({ clientId, action }, error);
+            }
          } catch (sendError: unknown) {
             this.logger.error(`Failed to send rejection for request '${action.requestId}':`, sendError);
          }

package/src/messages/index.ts

@@ -0,0 +1,30 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Every user-facing message `@hydranium/glsp-server` raises.
+ *
+ * **Each one is rendered AT ITS RAISE SITE**, through the shared
+ * `MessageRenderer`, because GLSP's action protocol carries no slot for an
+ * identity on any of its actions — so the identity is gone the moment a raise
+ * site formats its text, and there is nothing at the error boundary to render
+ * from. That makes this head the one place where a new message can ship
+ * unrendered without any single chokepoint noticing, which is why the package's
+ * own test suite scans for a declaration reached by `.format()` instead.
+ *
+ * The barrel is also how an adopter rendering their own diagram chrome
+ * discovers the codes exist.
+ */
+
+export {
+   DIAGRAM_READONLY_PARSE_ERROR,
+   DIAGRAM_SESSION_REFUSED,
+   SAVE_TARGET_UNKNOWN,
+   SOURCE_URI_MISSING
+} from '../storage/hydranium-glsp-storage.js';

package/src/node/start-glsp-server.ts

@@ -16,8 +16,7 @@ import {
    defaultSocketLaunchOptions
 } from '@eclipse-glsp/server/node.js';
 import { Container, type ContainerModule } from 'inversify';
-import type { Logger } from '@hydranium/protocol';
-import { Deferred } from '@hydranium/langium';
+import { Deferred, type Logger } from '@hydranium/protocol';
 import type * as net from 'node:net';
 import type { IntegratedServer } from '@hydranium/core';
 import { createGlspFrameworkOverrides } from '../launcher/glsp-framework-overrides.js';
@@ -155,8 +154,7 @@ export function startGlspServer(options: GlspServerOptions): StartedGlspServer {
    const launcher = appContainer.resolve<SocketServerLauncher>(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.
+   // the tier where each connection gets a server of its own.
    launcher.configure(options.serverModule, createGlspServerOverrides());
 
    const started = new Deferred<void>();
@@ -177,7 +175,7 @@ export function startGlspServer(options: GlspServerOptions): StartedGlspServer {
             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}`);
+            lifecycle?.info(`[GlspServer] Ready to accept new client requests on ${address.address} port: ${address.port}`);
             started.resolve();
          } else {
             const message = address === null ? 'address is null' : `bound to non-TCP "${String(address)}"`;