@hydranium/core 1.0.0-next.269 → 1.0.0-next.270

package/src/documents/document-release-handler.ts

@@ -22,6 +22,13 @@ import { isConnectionGoneError } from '../util/connection-liveness.js';
  */
 export interface ReleasedDocument {
    readonly uri: CanonicalUri;
+   /**
+    * Whether the store last knew a file behind the document: `false` for one
+    * created from a session's text and never saved, or whose file a reload
+    * found gone; any other open counts as on disk. Unlike the queries, a
+    * snapshot taken at the release, since the store forgets it there.
+    */
+   readonly wasOnDisk: boolean;
    /** Whether `uri` names this document, under the store's own keying. */
    isFor(uri: string): boolean;
    /**
@@ -102,20 +109,22 @@ export type DocumentReleaseOutcome =
 /**
  * Rebuilds a released document from the file system provider, so the build
  * stops carrying the unsaved text of its last client. Override
- * `decideRelease` or `applyReleaseDecision` to change the policy and keep the
- * locking and the wait for the build.
+ * `decideRelease`, `redecideRelease` or `applyReleaseDecision` to change the
+ * policy and keep the locking and the wait for the build.
  *
- * The provider decides, for every scheme, by `exists`: a document it can
- * serve is rebuilt from its text, and any other — an editor's `untitled:`
- * buffer, a file never saved, or one deleted meanwhile — is removed
- * from the workspace. A `virtual:` document survives, since the framework's
- * provider for that scheme serves it from the index, whatever provider the
- * host passes as `context.fileSystemProvider`; an edited one therefore keeps
- * its last client's text, and keeping it read-only is the client's job.
+ * The provider decides, for every scheme, by `exists`, with a miss confirmed
+ * by `existsSettled`: a document it can serve is rebuilt from its text, and
+ * any other — an editor's `untitled:` buffer, a file never saved, or one
+ * deleted meanwhile — is removed from the workspace. A `virtual:` document
+ * survives, since the framework's provider for that scheme serves it from the
+ * index, whatever provider the host passes as `context.fileSystemProvider`;
+ * an edited one therefore keeps its last client's text, and keeping it
+ * read-only is the client's job.
  *
  * The answer is read in the document's disk queue, so the rebuild follows
  * any save still queued rather than reverting past it; a file that goes
- * after that read is removed when its rebuild finds none.
+ * after that read is removed when its rebuild finds none and the provider
+ * confirms it gone.
  *
  * Whether the document is still released is checked again inside the write
  * lock, as its holder: checked only before waiting for the lock, a client that
@@ -181,9 +190,13 @@ export class DefaultDocumentReleaseHandler implements DocumentReleaseHandler {
 
    /**
     * Decide, then carry the decision out under the write lock unless a client
-    * holds the document again. Answers how that went; a parse of the document
-    * seen meanwhile counts even when the build was cancelled after it, since
-    * the build it yields to does not parse again.
+    * holds the document again. A rebuild that finds no file is redecided by
+    * {@link redecideRelease} within the same lock section: the build has
+    * already reset the document, so a build let in meanwhile would read the
+    * missing file and fail. Its answer is carried out unless a client
+    * reclaimed the document meanwhile. Answers how that went; a parse of the
+    * document seen meanwhile counts even when the build was cancelled after
+    * it, since the build it yields to does not parse again.
     */
    protected async runRelease(released: ReleasedDocument, target: URI): Promise<DocumentReleaseOutcome> {
       const workspace = this.services.workspace;
@@ -211,7 +224,26 @@ export class DefaultDocumentReleaseHandler implements DocumentReleaseHandler {
                parsed ||= released.isFor(document.uri.toString());
             });
             progress = 'building';
-            await this.applyReleaseDecision(target, decided, token);
+            let applied = decided;
+            for (let misses = 1; ; misses++) {
+               try {
+                  await this.applyReleaseDecision(target, applied, token);
+                  break;
+               } catch (err: unknown) {
+                  if (applied !== 'rebuild' || !isFileNotFound(err, target)) {
+                     throw err;
+                  }
+                  applied = await this.redecideRelease(released, target, misses);
+                  if (released.isReclaimed()) {
+                     progress = 'reclaimed';
+                     return;
+                  }
+                  decision = applied;
+                  this.tracer
+                     .with(released.uri)
+                     .debug(`Revert found no file; ${applied === 'rebuild' ? 'rebuilding again' : 'removing the document instead'}`);
+               }
+            }
             progress = 'built';
          });
          // A cancelled build throws inside the write, and the lock resolves.
@@ -219,12 +251,12 @@ export class DefaultDocumentReleaseHandler implements DocumentReleaseHandler {
             return { kind: 'reclaimed' };
          }
          if (progress === 'queued') {
-            return { kind: 'discarded', decision: decided };
+            return { kind: 'discarded', decision };
          }
          if (progress === 'building') {
-            return { kind: 'cancelled', decision: decided, parsed };
+            return { kind: 'cancelled', decision, parsed };
          }
-         return { kind: 'completed', decision: decided, parsed };
+         return { kind: 'completed', decision, parsed };
       } catch (error: unknown) {
          // A revert that finishes after the LSP peer went away fails its
          // diagnostics publish, and one that runs after its workspace was torn
@@ -254,34 +286,47 @@ export class DefaultDocumentReleaseHandler implements DocumentReleaseHandler {
    /**
     * The policy: rebuild a document the file system provider can serve, and
     * remove any other. Read in the document's disk queue, so it follows any
-    * save still queued rather than deciding past it.
+    * save still queued rather than deciding past it. A miss is settled outside
+    * the queue, so waiting it out holds up no write to the file, and only for
+    * a document the store knew on disk: one with no file has none to replace.
     */
-   protected decideRelease(released: ReleasedDocument, target: URI): Promise<DocumentReleaseDecision> {
+   protected async decideRelease(released: ReleasedDocument, target: URI): Promise<DocumentReleaseDecision> {
       const workspace = this.services.workspace;
-      return workspace.FileSystemTaskQueue.enqueue(released.uri, async () =>
-         (await workspace.FileSystemProvider.exists(target)) ? 'rebuild' : 'remove'
-      );
+      const fileSystem = workspace.FileSystemProvider;
+      const served = await workspace.FileSystemTaskQueue.enqueue(released.uri, () => fileSystem.exists(target));
+      if (served || !released.wasOnDisk) {
+         return served ? 'rebuild' : 'remove';
+      }
+      return ((await fileSystem.existsSettled?.(target)) ?? false) ? 'rebuild' : 'remove';
    }
 
    /**
-    * Carry `decision` out under the write lock; a file gone since the decision
-    * is removed instead. An override must rebuild or remove the document:
-    * release settlement waits for its parse or removal, and one that does
-    * neither is followed by a recovery build that rebuilds it.
+    * The policy for a rebuild that found no file, the `misses`-th of this
+    * release: what to carry out instead. Runs inside the release's write, so
+    * every build waits on it. The default settles the first miss through the
+    * provider's `existsSettled`, rebuilding again when the file is back, and
+    * removes the document on any later one. An override answering `rebuild`
+    * on every miss rebuilds for as long as the file stays missing.
+    */
+   protected async redecideRelease(_released: ReleasedDocument, target: URI, misses: number): Promise<DocumentReleaseDecision> {
+      if (misses > 1) {
+         return 'remove';
+      }
+      const fileSystem = this.services.workspace.FileSystemProvider;
+      return (await (fileSystem.existsSettled?.(target) ?? fileSystem.exists(target))) ? 'rebuild' : 'remove';
+   }
+
+   /**
+    * Carry `decision` out under the write lock. A rebuild that finds no file
+    * rejects with that error, and {@link redecideRelease} answers what to
+    * carry out instead. An override must rebuild or remove the document: release settlement
+    * waits for its parse or removal, and one that does neither is followed by a
+    * recovery build that rebuilds it.
     */
    protected async applyReleaseDecision(target: URI, decision: DocumentReleaseDecision, token: CancellationToken): Promise<void> {
       const builder = this.services.workspace.DocumentBuilder;
       builder.markNextReason(HYDRANIUM_BUILD_REASONS.didRelease);
-      try {
-         await (decision === 'rebuild' ? builder.update([target], [], token) : builder.update([], [target], token));
-      } catch (err: unknown) {
-         if (decision !== 'rebuild' || !isFileNotFound(err, target)) {
-            throw err;
-         }
-         this.tracer.with(target.toString()).debug('Revert found no file; removing the document instead');
-         builder.markNextReason(HYDRANIUM_BUILD_REASONS.didRelease);
-         await builder.update([], [target], token);
-      }
+      await (decision === 'rebuild' ? builder.update([target], [], token) : builder.update([], [target], token));
    }
 
    /** The build in place of a release that stopped short; rejects with its error when it was given up. */

package/src/documents/hydranium-text-documents.ts

@@ -600,6 +600,8 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       // reopening client's declared id.
       this.textLedger.record(uri, syncedDocument);
       this.textLedger.clearAuthors(uri);
+      // Before the tracker's release, which forgets whether a file was behind it.
+      const released = this.toReleasedDocument(uri);
       const cleanAnnouncement = this.dirtyStateTracker.release(uri);
       this.__syncedDocuments.delete(uri);
       this.__openedVersions.delete(uri);
@@ -608,7 +610,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       this.__pendingContent.delete(uri);
       this.documentReleaseScheduler.clearLosses(uri);
       this.documentReleasedEmitter.fire(Object.freeze({ uri }));
-      this.handOverRelease(this.toReleasedDocument(uri), cleanAnnouncement);
+      this.handOverRelease(released, cleanAnnouncement);
    }
 
    /**
@@ -660,6 +662,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    protected toReleasedDocument(uri: CanonicalUri): ReleasedDocument {
       return {
          uri,
+         wasOnDisk: this.dirtyStateTracker.hasDiskBaseline(uri),
          isFor: other => this.documentKey(other) === uri,
          isReclaimed: () => this.isOpenInAnyClient(uri) || this.__syncedDocuments.has(uri)
       };
@@ -1192,20 +1195,29 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    /**
     * Read the file behind `uri` through its disk queue and take it as the
     * baseline. A file that cannot be read counts as none, the side that
-    * leaves the document dirty.
+    * leaves the document dirty, once `existsSettled` confirms it gone: a file
+    * it finds is read again. That wait runs outside the queue, so it holds up
+    * no write to the file.
     */
    async reloadDiskBaseline(uri: DocumentUri): Promise<void> {
       const key = this.documentKey(uri);
       if (!this.__syncedDocuments.has(key)) {
          return;
       }
-      let onDisk: string | undefined;
-      try {
-         onDisk = await this.services.workspace.FileSystemTaskQueue.enqueue(key, () =>
-            this.services.workspace.FileSystemProvider.readFile(UriUtils.toUri(key))
-         );
-      } catch (err: unknown) {
-         this.tracer.with(key).debug(`Disk baseline: the file cannot be read. ${describeError(err)}`);
+      const workspace = this.services.workspace;
+      const fileSystem = workspace.FileSystemProvider;
+      const target = UriUtils.toUri(key);
+      const read = async (): Promise<string | undefined> => {
+         try {
+            return await workspace.FileSystemTaskQueue.enqueue(key, () => fileSystem.readFile(target));
+         } catch (err: unknown) {
+            this.tracer.with(key).debug(`Disk baseline: the file cannot be read. ${describeError(err)}`);
+            return undefined;
+         }
+      };
+      let onDisk = await read();
+      if (onDisk === undefined && (await (fileSystem.existsSettled?.(target) ?? fileSystem.exists(target)))) {
+         onDisk = await read();
       }
       this.setDiskBaseline(key, onDisk);
    }

package/src/langium/workspace/file-system-provider.ts

@@ -61,6 +61,17 @@ export interface WritableFileSystemProvider extends FileSystemProvider {
     * browser-neutral (no `node:fs` import).
     */
    realpath?(uri: URI): URI | undefined;
+   /**
+    * Whether a file is at `uri`, where a miss counts only once it has lasted:
+    * on a disk where replacing a file can hide its name for a moment, a single
+    * {@link exists} cannot tell that from a deletion. Ask this before acting on
+    * a miss as a deletion; a caller expecting a miss, such as a create, asks
+    * {@link exists}, since here a real miss costs the whole wait.
+    *
+    * Optional: a provider whose misses are always final omits it, and a caller
+    * takes the answer of {@link exists} as settled.
+    */
+   existsSettled?(uri: URI): Promise<boolean>;
    /** Registry the provider records its own writes against. Optional — providers without watcher integration may omit. */
    readonly selfSaveRegistry?: SelfSaveRegistry;
 }
@@ -152,10 +163,10 @@ export interface FileSystemProviderRegistryOptions<
  * A directory is listed by the provider of its own scheme, so a workspace
  * root's tree comes from that provider alone.
  *
- * `realpath` and `mtimeMs` are always present and forward to the scheme's
- * provider. Where that provider lacks one, `realpath` returns the URI unchanged
- * and `mtimeMs` returns `undefined`: the answers `RealpathDocumentUriPolicy`
- * and the self-save filter already give a provider without them.
+ * `realpath`, `mtimeMs` and `existsSettled` are always present and forward to
+ * the scheme's provider. Where that provider lacks one, `realpath` returns the
+ * URI unchanged, `mtimeMs` returns `undefined` and `existsSettled` answers as
+ * `exists`: the answers their callers already give a provider without them.
  */
 export class DefaultFileSystemProviderRegistry<
    THost extends WritableFileSystemProvider = WritableFileSystemProvider
@@ -198,6 +209,11 @@ export class DefaultFileSystemProviderRegistry<
       return provider.realpath ? provider.realpath(uri) : uri;
    }
 
+   async existsSettled(uri: URI): Promise<boolean> {
+      const provider = this.providerFor(uri);
+      return provider.existsSettled ? provider.existsSettled(uri) : provider.exists(uri);
+   }
+
    async stat(uri: URI): Promise<FileSystemNode> {
       return this.providerFor(uri).stat(uri);
    }

package/src/node/node-file-system-provider.ts

@@ -15,7 +15,7 @@ import { realpathSync } from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import { type WritableFileSystemProvider } from '../langium/workspace/file-system-provider.js';
 import { type SelfSaveRegistry } from '../langium/workspace/self-save-registry.js';
-import { renameOverOpenReaders } from './rename-over-open-readers.js';
+import { RENAME_GAP_BUDGET_MS, renameOverOpenReaders } from './rename-over-open-readers.js';
 import { type LogNameOptions } from '../langium/diagnostics/logger.js';
 import { serverSharedFactory, type ServerSharedServicesMinimal } from '../langium/shared-services.js';
 import { NO_SUCH_FILE, NO_SUCH_PATH, UNSUPPORTED_WRITE } from '../langium/workspace/in-memory-file-system-provider.js';
@@ -122,6 +122,32 @@ export class DefaultFileSystemProvider extends NodeFileSystemProvider implements
       return this.servesFromDisk(uri) ? super.existsSync(uri) : false;
    }
 
+   /**
+    * On Windows a miss is polled for up to {@link RENAME_GAP_BUDGET_MS}, since a
+    * replacing rename there can hide the name from a reader for a while; it
+    * answers `true` as soon as the file is back. Elsewhere a miss is final.
+    */
+   async existsSettled(uri: URI): Promise<boolean> {
+      if (await this.exists(uri)) {
+         return true;
+      }
+      if (!this.servesFromDisk(uri) || process.platform !== 'win32') {
+         return false;
+      }
+      // A stopwatch, not two `now()` readings: a wall-clock jump would end the
+      // wait early, removing a file that is only being replaced.
+      const waited = this.services.Clock.stopwatch();
+      while (waited.elapsedMs < RENAME_GAP_BUDGET_MS) {
+         // Not `clock.setTimer`: it unrefs its timer, so a process with only
+         // this check pending could exit mid-wait.
+         await new Promise(resolve => setTimeout(resolve, 10));
+         if (await this.exists(uri)) {
+            return true;
+         }
+      }
+      return false;
+   }
+
    // A URI this provider cannot reach on disk has no children rather than an
    // error: a workspace walk enumerates folders it was handed, and failing one
    // aborts the walk where an empty listing simply contributes nothing.
@@ -146,8 +172,9 @@ export class DefaultFileSystemProvider extends NodeFileSystemProvider implements
     * good revision. On Windows the replacing rename also leaves the name
     * unresolvable for a moment, so a reader there can find the file missing
     * (`ENOENT`) or refused (`EPERM`), never torn, and must not take either for
-    * a deletion. It does NOT serialise writers: two writers still race, and
-    * the loser's content is replaced wholesale rather than interleaved.
+    * a deletion; {@link existsSettled} waits that moment out. It does NOT
+    * serialise writers: two writers still race, and the loser's content is
+    * replaced wholesale rather than interleaved.
     *
     * The destination is the RESOLVED path, via {@link realpath}: a `rename`
     * onto a symlink replaces the link itself with a regular file and leaves the

package/src/node/rename-over-open-readers.ts

@@ -34,6 +34,14 @@ export const RENAME_CONTENTION_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
  */
 export const RENAME_BUDGET_MS = 10_000;
 
+/**
+ * How long a miss is waited out on Windows before it counts as an absence,
+ * since a replacing rename there can hide the name from a reader for a while.
+ * Bounded: a real deletion differs only by never ending, so it pays the whole
+ * budget. The figure is a judgement, not an established bound.
+ */
+export const RENAME_GAP_BUDGET_MS = 2_000;
+
 /** Seams for the test, which cannot make a real rename fail on demand. */
 export interface RenameOverOpenReadersOptions {
    readonly rename?: (from: string, to: string) => Promise<void>;
@@ -63,14 +71,17 @@ export async function renameOverOpenReaders(
 ): Promise<void> {
    const rename = options.rename ?? fsp.rename;
    const clock = options.clock ?? new SystemClock();
-   const deadline = clock.now() + (options.budgetMs ?? RENAME_BUDGET_MS);
+   const budgetMs = options.budgetMs ?? RENAME_BUDGET_MS;
+   // A stopwatch, not two `now()` readings: a wall-clock jump would end the
+   // budget early or stretch it.
+   const waited = clock.stopwatch();
    for (let attempt = 0; ; attempt++) {
       try {
          await rename(staging, destination);
          return;
       } catch (err: unknown) {
          const code = err instanceof Error && 'code' in err ? String((err as NodeJS.ErrnoException).code) : undefined;
-         if (code === undefined || !RENAME_CONTENTION_CODES.has(code) || clock.now() >= deadline) {
+         if (code === undefined || !RENAME_CONTENTION_CODES.has(code) || waited.elapsedMs >= budgetMs) {
             throw err;
          }
          // Backs off to keep a long contention window from spinning, capped so