@hydranium/glsp-server 1.0.0-next.31 → 1.0.0-next.315

package/src/launcher/glsp-connection-logger.ts

@@ -0,0 +1,27 @@
+/********************************************************************************
+ * 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 type { Logger as GlspLogger } from '@eclipse-glsp/server';
+import type { Logger as ConnectionLogger } from 'vscode-jsonrpc';
+
+/**
+ * A GLSP logger in the shape a `vscode-jsonrpc` connection logs to. A launcher
+ * that overrides `createConnection` passes it over its injected `logger`, or
+ * the connection logs to `console` or nowhere instead of the adopter's logger.
+ * GLSP's logger has no `log`; the connection's `log` lines go to `info`, the
+ * threshold the framework's own `Logger.log` emits at.
+ */
+export function createGlspConnectionLogger(logger: GlspLogger): ConnectionLogger {
+   return {
+      error: message => logger.error(message),
+      warn: message => logger.warn(message),
+      info: message => logger.info(message),
+      log: message => logger.info(message)
+   };
+}

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

@@ -8,42 +8,122 @@
  ********************************************************************************/
 
 import {
+   type ActionMessage,
+   ClientAction,
    type ClientSession,
    DefaultGLSPServer,
    GLSPServerError,
+   type InitializeClientSessionParameters,
+   MessageAction,
    RejectAction,
-   type RequestAction,
-   type ResponseAction
+   RequestAction,
+   type ResponseAction,
+   SourceModelStorage
 } from '@eclipse-glsp/server';
+import { describeErrorWithStack, RequestSaveModelAction } from '@hydranium/protocol';
 import { injectable } from 'inversify';
+import { logActionFailure } from '../command/diagram-edit-dropped-error.js';
+import { HydraniumGlspStorage } from '../storage/hydranium-glsp-storage.js';
 
 /**
  * The GLSP server the framework binds in place of upstream's
  * {@link DefaultGLSPServer}, so a failed REQUEST reaches its reader with the
- * text the thrower wrote.
+ * text the thrower wrote, and a diagram whose connection ends keeps its unsaved
+ * text for the release grace (see {@link shutdown}).
  *
  * **What breaks without it.** Upstream projects a failing request's detail as
  * `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
  * every adopter a rule they must know and cannot apply to `getOrThrow`.
  *
- * Only the REQUEST path needs this. Non-request actions fail through
- * upstream's `handleProcessError`, which reads `message` directly.
+ * Only the REQUEST path needs this. A non-request action fails through
+ * {@link handleProcessError}, which reads `message` directly; it and
+ * {@link process} are lifted for their logging only.
  *
- * 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, and with it both behaviours.
  */
 @injectable()
 export class HydraniumGlspServer extends DefaultGLSPServer {
+   /**
+    * End each diagram's client session as lost rather than closed, before
+    * upstream disposes the sessions, so its unsaved text waits out the release
+    * grace for the client to reconnect. A shutdown is how the client's
+    * connection ending reaches the server; a client that stops on purpose
+    * shuts the server down the same way, and its diagrams are held as well.
+    */
+   override shutdown(): void {
+      for (const session of this.clientSessions.values()) {
+         const storage = session.container.isBound(SourceModelStorage) ? session.container.get(SourceModelStorage) : undefined;
+         if (storage instanceof HydraniumGlspStorage) {
+            storage.dispose('lost');
+         } else if (storage) {
+            this.logger.debug(`Shutdown leaves ending ${session.id} to its storage, which is not a HydraniumGlspStorage`);
+         }
+      }
+      super.shutdown();
+   }
+
+   /**
+    * End a session the id still has before initializing it again. A model
+    * source initializes once, so a second initialize under one id is a new
+    * widget, a reopened tab whose closed predecessor's dispose never arrived;
+    * upstream would hand it that stale session.
+    */
+   override async initializeClientSession(params: InitializeClientSessionParameters): Promise<void> {
+      if (!this.clientSessions.has(params.clientSessionId)) {
+         return super.initializeClientSession(params);
+      }
+      this.logger.debug(`Client session ${params.clientSessionId} initialized again before its dispose arrived; ending the old one`);
+      // Not awaited before the initialize: both drop and set the session before
+      // their first await, and the model request that follows is read without
+      // waiting for this one to settle.
+      const disposed = this.disposeClientSession({ clientSessionId: params.clientSessionId });
+      const initialized = super.initializeClientSession(params);
+      await Promise.all([disposed, initialized]);
+   }
+
+   /**
+    * Lifted from `@eclipse-glsp/server` 2.7.0's {@link DefaultGLSPServer.process}:
+    * each action is logged at `debug` rather than `info`, and an action that
+    * fails once its session has ended, which disposing the session's dispatcher
+    * does to every action it holds, is logged at `debug` and told to no client,
+    * since the one that sent it has gone. The accompanying test pins upstream's
+    * source.
+    */
+   override process(message: ActionMessage): void {
+      this.validateServerInitialized();
+      this.logger.debug(`process [action=${message.action.kind}, clientId=${message.clientId}]`);
+      const clientSessionId = message.clientId;
+      const clientSession = this.clientSessions.get(clientSessionId);
+      if (!clientSession) {
+         throw new Error(`No client session has been initialized for client id: ${clientSessionId}`);
+      }
+      const action = message.action;
+      ClientAction.mark(action);
+      if (RequestAction.is(action)) {
+         void this.handleClientRequest(clientSession, action, message.clientId);
+         return;
+      }
+      clientSession.actionDispatcher.dispatch(action).catch((error: unknown) => {
+         if (this.clientSessions.get(clientSessionId) === clientSession) {
+            void this.handleProcessError(message, error);
+         } else {
+            this.logger.debug(`Action '${action.kind}' ended with its session: ${describeErrorWithStack(error)}`);
+         }
+      });
+   }
+
    /**
     * The detail projected into the client's {@link RejectAction} and the server
     * log when a request fails.
@@ -61,11 +141,40 @@ export class HydraniumGlspServer extends DefaultGLSPServer {
    }
 
    /**
-    * Lifted verbatim from `@eclipse-glsp/server` 2.7.0's
+    * Lifted from `@eclipse-glsp/server` 2.7.0's
+    * {@link DefaultGLSPServer.handleProcessError}, logging the failure once
+    * with {@link logActionFailure} where upstream logs the action and the
+    * reason as two lines.
+    *
+    * The notification is upstream's, text and all, and this body does not
+    * track upstream: the accompanying test pins upstream's source as it does
+    * for {@link handleClientRequest}.
+    */
+   protected override handleProcessError(message: ActionMessage, reason: unknown): void {
+      const kind = message.action.kind;
+      logActionFailure(this.logger, message.action, reason);
+      let errorMsg = `Could not process action: '${kind}`;
+      let details = stringifyAsUpstream(reason);
+      if (reason instanceof GLSPServerError) {
+         details = stringifyAsUpstream(reason.cause);
+         errorMsg = reason.message;
+      }
+      this.sendToClient({ clientId: message.clientId, action: MessageAction.create(errorMsg, { severity: 'ERROR', details }) });
+   }
+
+   /**
+    * Lifted 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}, the failure logged once with
+    * its stack, a request that fails once its session has ended logged at
+    * `debug` and answered to no client, as {@link process} treats an action,
+    * and one addition: a failed {@link RequestSaveModelAction} also
+    * raises the error notification a failed `SaveModelAction` raises, through
+    * {@link handleProcessError}, which then logs it instead. 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
@@ -88,17 +197,38 @@ export class HydraniumGlspServer extends DefaultGLSPServer {
             this.sendResponseToClient(clientId, response);
          }
       } catch (error: unknown) {
+         if (this.clientSessions.get(clientSession.id) !== clientSession) {
+            this.logger.debug(`Request '${action.kind}' (${action.requestId}) ended with its session: ${describeErrorWithStack(error)}`);
+            return;
+         }
          const detail = this.requestFailureDetail(error);
-         this.logger.error(`Failed to handle request '${action.kind}' (${action.requestId}):`, detail);
+         const isSave = action.kind === RequestSaveModelAction.KIND;
+         if (!isSave) {
+            this.logger.error(`Failed to handle request '${action.kind}' (${action.requestId}): ${describeErrorWithStack(error)}`);
+         }
+         // Inside the guard: `process` does not await this method, so a throw
+         // here would be an unhandled rejection.
          try {
-            const reject = RejectAction.create(`Failed to handle request '${action.kind}' (${action.requestId})`, {
-               responseId: action.requestId,
-               detail
-            });
-            this.sendResponseToClient(clientId, reject);
+            try {
+               const reject = RejectAction.create(`Failed to handle request '${action.kind}' (${action.requestId})`, {
+                  responseId: action.requestId,
+                  detail
+               });
+               this.sendResponseToClient(clientId, reject);
+            } finally {
+               // Also when the reject could not be sent, since this logs the save's failure.
+               if (isSave) {
+                  this.handleProcessError({ clientId, action }, error);
+               }
+            }
          } catch (sendError: unknown) {
-            this.logger.error(`Failed to send rejection for request '${action.requestId}':`, sendError);
+            this.logger.error(`Failed to send rejection for request '${action.requestId}': ${describeErrorWithStack(sendError)}`);
          }
       }
    }
 }
+
+/** `value?.toString?.()`, as upstream projects a reason into a notification's details. */
+function stringifyAsUpstream(value: unknown): string | undefined {
+   return (value as { toString?: () => string } | null | undefined)?.toString?.();
+}

package/src/launcher/index.ts

@@ -13,10 +13,11 @@ export * from './abstract-hydranium-glsp-diagram-module.js';
 // rather than upstream's — the server-container override discards a subclass of
 // `DefaultGLSPServer`.
 export * from './hydranium-glsp-server.js';
+export * from './drop-notifications-to-gone-client.js';
+export * from './glsp-connection-logger.js';
 // The socket bringup lives in `@hydranium/glsp-server/node` and the worker
 // bringup in `@hydranium/glsp-server/browser`, not here: each pulls the
 // upstream build for its platform, which the portable `.` entry must stay free
-// of. `glsp-framework-overrides.js` and `glsp-server-overrides.js` are
-// deliberately NOT re-exported — they are the bindings those two bringups share,
-// reached by relative import, and an adopter composing a container by hand wants
-// the launcher rather than its internals.
+// of. The container overrides those two bringups share stay unexported, reached
+// by relative import: an adopter composing a container by hand wants the
+// launcher rather than its internals.

package/src/logging/glsp-client-logger.ts

@@ -9,7 +9,7 @@
 
 import { type Logger as GlspLogger, LogLevel } from '@eclipse-glsp/server';
 import { LspLogger, type LspLoggerOptions, type ServerSharedServices } from '@hydranium/core';
-import { Logger, type LogThreshold } from '@hydranium/protocol';
+import { describeErrorWithStack, LEVEL_ORDER, Logger, type LogThreshold } from '@hydranium/protocol';
 
 /**
  * Options accepted by {@link GlspClientLogger}. Extends
@@ -19,11 +19,11 @@ import { Logger, type LogThreshold } from '@hydranium/protocol';
 export interface GlspClientLoggerOptions extends LspLoggerOptions {
    /**
     * Per-instance NARROWING of the framework threshold. Omit it — the default
-    * tracks `Logger.getLevel()` live, which is what makes one
+    * tracks the framework thresholds live, which is what makes one
     * `HYDRANIUM_LOG_LEVEL` / one LSP setting govern GLSP output too.
     *
     * It can only narrow, never widen, and that is not a policy choice:
-    * `AbstractLogger.send` gates every emission on the process-wide threshold
+    * `AbstractLogger.send` gates every emission on `Logger.isLevelEnabled`
     * before it reaches the output channel, so a value more verbose than the
     * global is silently ineffective. Set it only to make ONE component quieter
     * than the rest.
@@ -66,8 +66,8 @@ export function glspLogLevelOf(threshold: LogThreshold): LogLevel {
  * GLSP-specific concerns layered on top of {@link LspLogger}:
  *
  * - A {@link logLevel} field, because GLSP's `Logger` contract declares one.
- *   **It tracks the framework's process-wide threshold by default**, resolving
- *   `Logger.getLevel()` through {@link glspLogLevelOf} on every read — so
+ *   **It tracks the framework's thresholds by default**, resolving them
+ *   through {@link glspLogLevelOf} on every read — so
  *   `HYDRANIUM_LOG_LEVEL`, the LSP log-level setting and the Theia preference
  *   all reach GLSP output without a second knob. Assigning the field (or
  *   passing `logLevel`) pins an explicit per-instance NARROWING; see
@@ -104,9 +104,16 @@ export class GlspClientLogger extends LspLogger implements GlspLogger {
       this.logLevelOverride = options.logLevel;
    }
 
-   /** GLSP's `Logger.logLevel` contract; the framework threshold unless pinned. */
+   /**
+    * GLSP's `Logger.logLevel` contract; unless pinned, the more verbose of
+    * `Logger.getLevel()` and `Logger.getFileLevel()`. The process threshold
+    * alone drops GLSP lines a log file with its own threshold asks for.
+    */
    get logLevel(): LogLevel {
-      return this.logLevelOverride ?? glspLogLevelOf(Logger.getLevel());
+      const level = Logger.getLevel();
+      const fileLevel = Logger.getFileLevel();
+      const widest = fileLevel && LEVEL_ORDER[fileLevel] > LEVEL_ORDER[level] ? fileLevel : level;
+      return this.logLevelOverride ?? glspLogLevelOf(widest);
    }
 
    set logLevel(level: LogLevel) {
@@ -156,10 +163,10 @@ export class GlspClientLogger extends LspLogger implements GlspLogger {
       return params.length === 0 ? message : `${message} ${params.map(p => this.formatParam(p)).join(',\n')}`;
    }
 
-   /** Format a single param: errors → `message\nstack`; everything else → JSON.stringify(p, undefined, 4). */
+   /** Format a single param: errors → their stack and causes; everything else → JSON.stringify(p, undefined, 4). */
    protected formatParam(param: unknown): string {
       if (param instanceof Error) {
-         return `${param.message}\n${param.stack ?? ''}`;
+         return describeErrorWithStack(param);
       }
       try {
          return JSON.stringify(param, undefined, 4);

package/src/messages/index.ts

@@ -10,11 +10,21 @@
 /**
  * Every user-facing message `@hydranium/glsp-server` raises.
  *
- * Enumeration only: GLSP's action protocol carries no slot for a message
- * identity on any of its notification actions, so a diagram error reaches the
- * client as English by upstream constraint. The declarations still earn their
- * place — an adopter rendering their own diagram chrome can key on the code, and
- * the barrel is how they discover the codes exist.
+ * **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 { SAVE_TARGET_UNKNOWN, SOURCE_URI_MISSING } from '../storage/hydranium-glsp-storage.js';
+export {
+   DIAGRAM_READONLY_PARSE_ERROR,
+   DIAGRAM_SESSION_REFUSED,
+   SAVE_TARGET_UNKNOWN,
+   SOURCE_URI_MISSING
+} from '../storage/hydranium-glsp-storage.js';