@hydranium/core 1.0.0-next.117 → 1.0.0-next.123

package/src/documents/client-session-registry.ts

@@ -8,25 +8,28 @@
  ********************************************************************************/
 
 import { type CanonicalUri, FRAMEWORK_CLIENT_IDS } from '@hydranium/protocol';
-import { Emitter, type Event } from 'vscode-languageserver';
+import { type Disposable, Emitter, type Event } from 'vscode-languageserver';
 import { INTEGRITY_CLIENT_ID } from '../langium/integrity/integrity-rule.js';
 import { DuplicateClientIdError, SessionClosedError } from './client-session-errors.js';
 
 /**
- * What a client session states about one of its opens, kept per
- * `(session, uri)` for as long as that open lasts.
+ * What a client session states about one of its opens, kept by the session
+ * and readable only while that open lasts.
  *
  * Any object type: an adopter declares the fields its own open path reads and
- * passes that type as a session's `TOpenOptions`. Stored per open rather than
+ * passes that type as a session's `TOpenOptions`. Kept per open rather than
  * per document, so two sessions opening one document with different options
  * each keep their own.
  */
 export type OpenOptions = object;
 
 /**
- * `'closing'` covers the span in which a session's opens are being closed. The
- * id is still taken then, and the session can open nothing more, so an open
- * issued from a close listener cannot outlive the session that made it.
+ * A session is `'live'` from its registration, which is synchronous, so no
+ * state comes before it. `'closing'` covers the span in which the session's
+ * opens are being closed: the id is still taken, and the session can open
+ * nothing more, so an open issued from a close listener cannot outlive the
+ * session that made it. An id with no state has no session: it was never
+ * registered, or has closed.
  */
 export type ClientSessionState = 'live' | 'closing';
 
@@ -35,6 +38,15 @@ export interface ClientSessionClosedEvent {
    readonly clientId: string;
 }
 
+/**
+ * Why a close happened. `'lost'` is a close caused by the client's connection
+ * going away rather than by the client, and only such a last close waits out
+ * the store's revert grace: a client that closed or ended on purpose has
+ * discarded its unsaved edits, while one that lost its connection may be about
+ * to register again and open the document once more.
+ */
+export type SessionEndCause = 'closed' | 'lost';
+
 /**
  * The ids no client session may be started under: the wire's well-known ids and
  * the integrity author. Each names a framework participant rather than a
@@ -48,11 +60,11 @@ export const RESERVED_CLIENT_IDS: readonly string[] = [...FRAMEWORK_CLIENT_IDS,
  * sessions — the open facts every head shares, composed by
  * `HydraniumTextDocuments`.
  *
- * Opens are recorded for every client id, registered or not. An id that was
- * never registered is a client that predates sessions and writes through the
- * flat `clientId` calls; its opens are tracked exactly as a session's are, and
- * only the session table ignores it. Requiring registration before an open
- * would refuse every such client.
+ * Opens are recorded for every client id, registered or not. The language
+ * client opens under its reserved id without a session, over the LSP
+ * connection, and its opens are tracked exactly as a session's are; only the
+ * session table ignores it. Requiring registration before an open would refuse
+ * the editor.
  *
  * One open per `(client, uri)`, with no reference count: a repeat open changes
  * nothing, and one close ends it.
@@ -64,10 +76,16 @@ export const RESERVED_CLIENT_IDS: readonly string[] = [...FRAMEWORK_CLIENT_IDS,
 export class ClientSessionRegistry {
    protected readonly sessions = new Map<string, ClientSessionState>();
    protected readonly clientsByUri = new Map<CanonicalUri, Set<string>>();
-   /** Each client's opens, with the options it opened them with. */
-   protected readonly opensByClient = new Map<string, Map<CanonicalUri, OpenOptions | undefined>>();
+   protected readonly opensByClient = new Map<string, Set<CanonicalUri>>();
    protected readonly reservedIds: ReadonlySet<string> = new Set(RESERVED_CLIENT_IDS);
    protected readonly sessionClosedEmitter = new Emitter<ClientSessionClosedEvent>();
+   /**
+    * The documents whose last open closed with a lost connection and whose
+    * revert is deferred, each with the timer that runs it. Any open of such a
+    * document cancels its timer; the store decides whether the opener keeps the
+    * unsaved text.
+    */
+   protected readonly pendingReverts = new Map<CanonicalUri, Disposable>();
 
    /** Fires once a session has been removed from the table, after all its opens closed. */
    get onDidCloseSession(): Event<ClientSessionClosedEvent> {
@@ -116,7 +134,7 @@ export class ClientSessionRegistry {
    }
 
    /**
-    * Record that `clientId` opened `uri`, with no options. Returns `false` when
+    * Record that `clientId` opened `uri`. Returns `false` when
     * it already had it open, in which case nothing changes.
     *
     * Throws {@link SessionClosedError} for a session that is closing.
@@ -130,10 +148,10 @@ export class ClientSessionRegistry {
          return false;
       }
       if (!opens) {
-         opens = new Map();
+         opens = new Set();
          this.opensByClient.set(clientId, opens);
       }
-      opens.set(uri, undefined);
+      opens.add(uri);
       let clients = this.clientsByUri.get(uri);
       if (!clients) {
          clients = new Set();
@@ -177,7 +195,7 @@ export class ClientSessionRegistry {
 
    /** The URIs `clientId` has open, in the order it opened them. */
    opensOf(clientId: string): CanonicalUri[] {
-      return [...(this.opensByClient.get(clientId)?.keys() ?? [])];
+      return [...(this.opensByClient.get(clientId) ?? [])];
    }
 
    /** Every document open in at least one client, with the clients that have it open. */
@@ -185,21 +203,25 @@ export class ClientSessionRegistry {
       return [...this.clientsByUri].map(([uri, clients]) => ({ uri, clients: [...clients] }));
    }
 
-   /** The options `clientId` opened `uri` with, or `undefined` when it gave none or does not have it open. */
-   openOptions(uri: CanonicalUri, clientId: string): OpenOptions | undefined {
-      return this.opensByClient.get(clientId)?.get(uri);
+   /** Record `timer` as the deferred revert of `uri`. */
+   deferRevert(uri: CanonicalUri, timer: Disposable): void {
+      this.pendingReverts.set(uri, timer);
    }
 
-   /** Replace the options of an existing open. Does nothing when `clientId` does not have `uri` open. */
-   setOpenOptions(uri: CanonicalUri, clientId: string, options: OpenOptions | undefined): void {
-      const opens = this.opensByClient.get(clientId);
-      if (opens?.has(uri)) {
-         opens.set(uri, options);
-      }
+   /** Whether the revert of `uri` is deferred. */
+   isRevertPending(uri: CanonicalUri): boolean {
+      return this.pendingReverts.has(uri);
+   }
+
+   /** Cancel the deferred revert of `uri`, if one is pending. */
+   cancelRevert(uri: CanonicalUri): void {
+      this.pendingReverts.get(uri)?.dispose();
+      this.pendingReverts.delete(uri);
    }
 
    /**
-    * Forget every session and open without announcing anything. Subscriptions
+    * Forget every session, open and deferred revert without announcing
+    * anything, for a test double that resets between tests. Subscriptions
     * stay, so a listener registered before the clear hears the sessions that
     * end after it.
     */
@@ -207,5 +229,9 @@ export class ClientSessionRegistry {
       this.sessions.clear();
       this.clientsByUri.clear();
       this.opensByClient.clear();
+      for (const timer of this.pendingReverts.values()) {
+         timer.dispose();
+      }
+      this.pendingReverts.clear();
    }
 }

package/src/documents/file-system-task-queue.ts

@@ -0,0 +1,68 @@
+/********************************************************************************
+ * 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 CanonicalUri } from '@hydranium/protocol';
+import { type ServerSharedServices } from '../langium/module.js';
+import { type DocumentUriPolicy } from '../langium/workspace/document-uri-policy.js';
+
+/**
+ * One queue of file-system tasks per file, shared by every server-side reader
+ * and writer of a file whose accesses must not interleave with its saves.
+ *
+ * Two writes of one file that bypass the queue can land in either order, and
+ * the older text then stays on disk. Tasks of different files run in
+ * parallel.
+ */
+export interface FileSystemTaskQueue {
+   /**
+    * Run `task` once every task already enqueued for `uri` has settled, and
+    * before any enqueued after it. `uri` is keyed by its canonical identity, so
+    * every spelling of one file shares a queue. A task that has nothing to do
+    * still resolves once the tasks before it have settled.
+    *
+    * A task must not await a build, nor a save, another task or an open of a
+    * document no client has open, all of the same file: a build's integrity
+    * repair enqueues its own write and the build waits for it, and such an
+    * open reads the file here, so a task waiting on either never resolves,
+    * which wedges the file's queue for good.
+    */
+   enqueue<T>(uri: string, task: () => Promise<T>): Promise<T>;
+}
+
+export class DefaultFileSystemTaskQueue implements FileSystemTaskQueue {
+   /**
+    * Per canonical URI, the settling of the last task enqueued for it; the next
+    * task chains behind it. An entry leaves once its file's queue is idle. Kept
+    * outside the workspace lock, whose `write` cancels the write before it: a
+    * save cancelled that way reports success for text it never wrote.
+    */
+   protected readonly queues = new Map<CanonicalUri, Promise<void>>();
+
+   protected readonly uriPolicy: DocumentUriPolicy;
+
+   constructor(services: { readonly workspace: Pick<ServerSharedServices['workspace'], 'DocumentUriPolicy'> }) {
+      this.uriPolicy = services.workspace.DocumentUriPolicy;
+   }
+
+   enqueue<T>(uri: string, task: () => Promise<T>): Promise<T> {
+      const key = this.uriPolicy.canonicalUri(uri);
+      const result = (this.queues.get(key) ?? Promise.resolve()).then(task);
+      const settled = result.then(
+         () => undefined,
+         () => undefined
+      );
+      this.queues.set(key, settled);
+      void settled.then(() => {
+         if (this.queues.get(key) === settled) {
+            this.queues.delete(key);
+         }
+      });
+      return result;
+   }
+}