@mui/internal-docs-infra 0.12.1-canary.43 → 0.12.1-canary.44

package/cli/runValidate.d.mts

@@ -1,4 +1,5 @@
 import type { CommandModule } from 'yargs';
+import { Worker } from 'node:worker_threads';
 type Args = {
   paths?: string[];
   command?: string;
@@ -7,5 +8,7 @@ type Args = {
   perf?: boolean;
   notableMs?: number;
 };
+export declare function shutdownWorker(worker: Worker, timeoutMs?: number): Promise<void>;
+export declare function shutdownWorkers(workers: Worker[]): Promise<void>;
 declare const runValidate: CommandModule<{}, Args>;
 export default runValidate;

package/cli/runValidate.mjs

@@ -16,6 +16,51 @@ import { ensureDemoClients } from "./ensureDemoClients.mjs";
 import { ensureDemoPages } from "./ensureDemoPages.mjs";
 const completeMessage = message => `✓ ${chalk.green(message)}`;
 const functionName = 'Run Validate';
+export async function shutdownWorker(worker, timeoutMs = 5000) {
+  if (worker.threadId === -1) {
+    return;
+  }
+  await new Promise(resolve => {
+    let handleMessage;
+    let settled = false;
+    let timeout;
+    const finish = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      worker.off('message', handleMessage);
+      worker.off('error', finish);
+      worker.off('exit', finish);
+      resolve();
+    };
+    handleMessage = result => {
+      if (result.type === 'shutdown') {
+        finish();
+      }
+    };
+    timeout = setTimeout(finish, timeoutMs);
+    worker.on('message', handleMessage);
+    worker.once('error', finish);
+    worker.once('exit', finish);
+
+    // The worker may have exited between the initial check and listener setup.
+    if (worker.threadId === -1) {
+      finish();
+      return;
+    }
+    worker.postMessage({
+      type: 'shutdown'
+    });
+  });
+  await worker.terminate();
+}
+export async function shutdownWorkers(workers) {
+  await Promise.all(workers.map(worker => shutdownWorker(worker)));
+}
 
 /**
  * Recursively find all files matching a specific name in a directory
@@ -143,6 +188,9 @@ const runValidate = {
     let taskIdCounter = 0;
     for (const worker of workers) {
       worker.on('message', result => {
+        if (result.type === 'shutdown') {
+          return;
+        }
         const resolve = pendingResults.get(result.taskId);
         if (resolve) {
           pendingResults.delete(result.taskId);
@@ -407,11 +455,11 @@ const runValidate = {
         currentMark = pagesMark;
       }
     } finally {
-      // Terminate worker pool
-      await Promise.all(workers.map(w => w.terminate()));
+      // Let each validation worker release its types-server election lock before exit.
+      await shutdownWorkers(workers);
 
       // Terminate the types meta worker manager to allow the process to exit
-      terminateWorkerManager();
+      await terminateWorkerManager();
     }
     if (observer) {
       // Flush any remaining performance entries before disconnecting

package/cli/validateWorker.d.mts

@@ -22,6 +22,9 @@ interface TypesTask {
   syncTypesOptions: Omit<SyncTypesOptions, 'typesMarkdownPath' | 'rootContext' | 'variants'>;
   rootContext: string;
 }
+export interface ShutdownTask {
+  type: 'shutdown';
+}
 interface SerializedPerfEntry {
   name: string;
   duration: number;
@@ -42,6 +45,9 @@ interface TypesResult {
   perfEntries?: SerializedPerfEntry[];
   error?: string;
 }
+export interface ShutdownResult {
+  type: 'shutdown';
+}
 export type ValidateTask = IndexTask | TypesTask;
 export type ValidateResult = IndexResult | TypesResult;
 export {};

package/cli/validateWorker.mjs

@@ -8,6 +8,7 @@ import remarkMdx from 'remark-mdx';
 import { transformMarkdownMetadata } from "../pipeline/transformMarkdownMetadata/transformMarkdownMetadata.mjs";
 import { parseCreateFactoryCall } from "../pipeline/parseCreateFactoryCall/parseCreateFactoryCall.mjs";
 import { syncTypes } from "../pipeline/syncTypes/syncTypes.mjs";
+import { terminateWorkerManager } from "../pipeline/loadServerTypesMeta/workerManager.mjs";
 function collectPerfEntries() {
   const entries = performance.getEntriesByType('measure').map(entry => ({
     name: entry.name,
@@ -22,7 +23,12 @@ if (parentPort) {
   let taskQueue = Promise.resolve();
   parentPort.on('message', task => {
     taskQueue = taskQueue.then(async () => {
-      if (task.type === 'index') {
+      if (task.type === 'shutdown') {
+        await terminateWorkerManager();
+        parentPort.postMessage({
+          type: 'shutdown'
+        });
+      } else if (task.type === 'index') {
         try {
           const processor = unified().use(remarkParse).use(remarkMdx).use(transformMarkdownMetadata, {
             extractToIndex: task.processorOptions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.12.1-canary.43",
+  "version": "0.12.1-canary.44",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -804,5 +804,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "2a2c232ded2053934aa082b335952c525c6ea88c"
+  "gitSha": "428843a303d23c4c904fc740058e33e1a8b95c85"
 }

package/pipeline/loadServerTypesMeta/socketClient.d.mts

@@ -23,15 +23,6 @@ export declare function getLockPath(): string;
  * Ensure the socket directory exists
  */
 export declare function ensureSocketDir(): Promise<void>;
-/**
- * Wait for the IPC endpoint to become available.
- * On Unix: Polls the filesystem for the socket file to appear. We avoid
- * `fs.watch` here because on macOS it does not reliably fire events when a
- * unix domain socket file is created.
- * On Windows: Polls by attempting to connect to the named pipe.
- * @param timeoutMs - Timeout in milliseconds (default: 5000)
- */
-export declare function waitForSocketFile(timeoutMs?: number): Promise<void>;
 /**
  * Try to acquire the server lock using proper-lockfile
  * Returns true if successfully acquired (this worker should be server)
@@ -42,8 +33,7 @@ export declare function tryAcquireServerLock(): Promise<boolean>;
  */
 export declare function releaseServerLock(): Promise<void>;
 /**
- * Check if there's an existing worker socket file
- * Note: The socket server will clean up stale sockets on startup
+ * Check whether a types server is accepting connections, retrying for up to 500ms.
  */
 export declare function hasExistingWorker(): Promise<boolean>;
 /**
@@ -55,9 +45,10 @@ export declare class SocketClient {
   private pendingRequests;
   private buffer;
   /**
-   * Connect to the worker socket with retry logic
+   * Connect to the worker socket, retrying while the server starts or named-pipe
+   * instances are temporarily busy.
    */
-  connect(retryCount?: number, maxRetries?: number, retryDelay?: number): Promise<void>;
+  connect(timeoutMs?: number, retryDelay?: number): Promise<void>;
   /**
    * Attempt to connect to the socket
    */

package/pipeline/loadServerTypesMeta/socketClient.mjs

@@ -9,7 +9,7 @@
  */
 
 import { connect } from 'node:net';
-import { mkdir, stat } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -92,22 +92,10 @@ export async function ensureSocketDir() {
 }
 
 /**
- * Check if a file exists
- */
-async function fileExists(path) {
-  try {
-    await stat(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Try to connect to a named pipe (Windows)
+ * Try to connect to an IPC endpoint.
  * @returns true if connection succeeded, false otherwise
  */
-function tryConnectToPipe(socketPath) {
+function tryConnectToSocket(socketPath) {
   return new Promise(resolve => {
     const socket = connect(socketPath);
     socket.on('connect', () => {
@@ -130,42 +118,25 @@ function sleep(ms) {
 }
 
 /**
- * Wait for the IPC endpoint to become available.
- * On Unix: Polls the filesystem for the socket file to appear. We avoid
- * `fs.watch` here because on macOS it does not reliably fire events when a
- * unix domain socket file is created.
- * On Windows: Polls by attempting to connect to the named pipe.
- * @param timeoutMs - Timeout in milliseconds (default: 5000)
+ * Poll an IPC endpoint until it accepts a connection or the timeout expires.
  */
-export async function waitForSocketFile(timeoutMs = 5000) {
-  const socketPath = getSocketPath();
+async function waitForSocketConnection(socketPath, timeoutMs) {
   const pollInterval = 50;
   const startTime = Date.now();
-  if (isWindows) {
-    while (Date.now() - startTime < timeoutMs) {
-      // eslint-disable-next-line no-await-in-loop
-      if (await tryConnectToPipe(socketPath)) {
-        return;
-      }
-      // eslint-disable-next-line no-await-in-loop
-      await sleep(pollInterval);
-    }
-    throw new Error(`Named pipe did not become available within ${timeoutMs}ms`);
-  }
-
-  // Ensure the directory exists so the first stat doesn't fail spuriously
-  await mkdir(getEffectiveSocketDir(), {
-    recursive: true
-  });
-  while (Date.now() - startTime < timeoutMs) {
+  do {
     // eslint-disable-next-line no-await-in-loop
-    if (await fileExists(socketPath)) {
-      return;
+    if (await tryConnectToSocket(socketPath)) {
+      return true;
+    }
+    const remainingTime = timeoutMs - (Date.now() - startTime);
+    if (remainingTime <= 0) {
+      return false;
     }
+
     // eslint-disable-next-line no-await-in-loop
-    await sleep(pollInterval);
-  }
-  throw new Error(`Socket file did not appear within ${timeoutMs}ms`);
+    await sleep(Math.min(pollInterval, remainingTime));
+  } while (Date.now() - startTime < timeoutMs);
+  return false;
 }
 
 // Store the release function globally so we can call it when needed
@@ -182,14 +153,27 @@ export async function tryAcquireServerLock() {
   await ensureSocketDir();
   try {
     // Try to acquire the lock with no retries (immediate check)
-    // Stale locks will be detected after 3 seconds (server should start quickly)
+    // Allow enough time for a server worker to start even when validation workers
+    // saturate the CPU and delay the lock heartbeat.
     lockReleaseFunction = await lockfile.lock(lockPath, {
       retries: 0,
       // Don't retry, just check once
-      stale: 3000,
-      // Consider lock stale after 3 seconds
-      realpath: false // Don't resolve symlinks (file doesn't need to exist)
+      stale: 30_000,
+      realpath: false,
+      // Don't resolve symlinks (file doesn't need to exist)
+      onCompromised: error => {
+        console.error('[SocketClient] Server lock compromised:', error);
+        lockReleaseFunction = null;
+      }
     });
+
+    // A worker that initialized earlier may have released the election lock after
+    // starting the server. Check the endpoint while holding the lock so late
+    // workers reuse that server instead of trying to listen on the same address.
+    if (await hasExistingWorker()) {
+      await releaseServerLock();
+      return false;
+    }
     return true;
   } catch (error) {
     // Lock is already held by another worker
@@ -205,10 +189,11 @@ export async function tryAcquireServerLock() {
  * Release the server lock
  */
 export async function releaseServerLock() {
-  if (lockReleaseFunction) {
+  const release = lockReleaseFunction;
+  lockReleaseFunction = null;
+  if (release) {
     try {
-      await lockReleaseFunction();
-      lockReleaseFunction = null;
+      await release();
     } catch (error) {
       // Ignore errors during cleanup
     }
@@ -216,11 +201,12 @@ export async function releaseServerLock() {
 }
 
 /**
- * Check if there's an existing worker socket file
- * Note: The socket server will clean up stale sockets on startup
+ * Check whether a types server is accepting connections, retrying for up to 500ms.
  */
 export async function hasExistingWorker() {
-  return fileExists(getSocketPath());
+  // The election lock may have been released immediately before the server
+  // becomes connectable. Retry briefly before deciding to start another server.
+  return waitForSocketConnection(getSocketPath(), 500);
 }
 
 /**
@@ -233,25 +219,25 @@ export class SocketClient {
   buffer = '';
 
   /**
-   * Connect to the worker socket with retry logic
+   * Connect to the worker socket, retrying while the server starts or named-pipe
+   * instances are temporarily busy.
    */
-  async connect(retryCount = 0, maxRetries = 10, retryDelay = 50) {
+  async connect(timeoutMs = 30_000, retryDelay = 50) {
     const socketPath = getSocketPath();
-    try {
-      await this.attemptConnect(socketPath);
-    } catch (error) {
-      // If we've exhausted retries, throw the error
-      if (retryCount >= maxRetries - 1) {
-        throw error;
+    const startTime = Date.now();
+    while (true) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await this.attemptConnect(socketPath);
+        return;
+      } catch (error) {
+        if (Date.now() - startTime >= timeoutMs) {
+          throw error;
+        }
       }
 
-      // Wait before retrying
-      await new Promise(resolve => {
-        setTimeout(resolve, retryDelay);
-      });
-
-      // Recursive retry
-      await this.connect(retryCount + 1, maxRetries, retryDelay);
+      // eslint-disable-next-line no-await-in-loop
+      await sleep(retryDelay);
     }
   }
 

package/pipeline/loadServerTypesMeta/workerManager.d.mts

@@ -4,7 +4,7 @@ import type { WorkerRequest, WorkerResponse } from "./worker.mjs";
  */
 export interface TypesProcessor {
   processTypes(request: WorkerRequest): Promise<WorkerResponse>;
-  terminate(): void;
+  terminate(): Promise<void>;
 }
 export declare function getWorkerManager(): TypesProcessor;
-export declare function terminateWorkerManager(): void;
+export declare function terminateWorkerManager(): Promise<void>;

package/pipeline/loadServerTypesMeta/workerManager.mjs

@@ -5,7 +5,7 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 // eslint-disable-next-line n/prefer-node-protocol
 import { isMainThread, Worker } from 'worker_threads';
-import { SocketClient, tryAcquireServerLock, releaseServerLock, waitForSocketFile } from "./socketClient.mjs";
+import { SocketClient, tryAcquireServerLock, releaseServerLock } from "./socketClient.mjs";
 
 /**
  * Shared interface for types processing managers.
@@ -73,9 +73,9 @@ class TypesMetaWorkerManager {
       });
     });
   }
-  terminate() {
+  async terminate() {
     if (this.worker) {
-      this.worker.terminate();
+      await this.worker.terminate();
       this.worker = null;
     }
     this.pendingRequests.clear();
@@ -85,8 +85,7 @@ class TypesMetaWorkerManager {
 /**
  * Types processor for validate worker threads.
  * On first processTypes() call, races to acquire the server lock:
- * - Winner: releases the lock, spawns a bare worker (which acquires the lock
- *   naturally and becomes the socket server via existing worker.ts logic)
+ * - Winner: holds the lock and spawns a bare worker that becomes the socket server
  * - Losers: skip spawning
  *
  * All workers then connect to the socket server as clients.
@@ -121,36 +120,43 @@ class WorkerThreadTypesProcessor {
       this.serverWorker.on('error', error => {
         console.error('[WorkerThreadTypesProcessor] Server worker error:', error);
       });
+    }
+    this.socketClient = new SocketClient();
+    try {
+      // Establish the persistent client connection directly. A separate probe
+      // can consume an available Windows named-pipe instance and make the real
+      // connection fail under high concurrency.
+      await this.socketClient.connect();
+    } catch (error) {
+      this.socketClient?.close();
+      this.socketClient = null;
       try {
-        // Wait for the socket file to appear, then release the lock.
-        await waitForSocketFile(30_000);
-      } catch (error) {
-        // Server worker crashed before creating the socket — release the lock
-        // so another worker can become the server on a subsequent attempt.
-        await releaseServerLock();
-        throw error;
+        if (this.serverWorker) {
+          await this.serverWorker.terminate();
+        }
+      } finally {
+        this.serverWorker = null;
+        if (isServer) {
+          await releaseServerLock();
+        }
       }
-      await releaseServerLock();
-    } else {
-      // Another worker is the server — wait for the socket file.
-      await waitForSocketFile(30_000);
+      throw error;
     }
-    this.socketClient = new SocketClient();
-    await this.socketClient.connect();
   }
   async processTypes(request) {
     await this.ensureInit();
     return this.socketClient.sendRequest(request);
   }
-  terminate() {
+  async terminate() {
     if (this.socketClient) {
       this.socketClient.close();
       this.socketClient = null;
     }
     if (this.serverWorker) {
-      this.serverWorker.terminate();
+      await this.serverWorker.terminate();
       this.serverWorker = null;
     }
+    await releaseServerLock();
   }
 }
 
@@ -171,10 +177,10 @@ export function getWorkerManager() {
   }
   return processObj[WORKER_MANAGER_KEY];
 }
-export function terminateWorkerManager() {
+export async function terminateWorkerManager() {
   const processObj = process;
   if (processObj[WORKER_MANAGER_KEY]) {
-    processObj[WORKER_MANAGER_KEY].terminate();
+    await processObj[WORKER_MANAGER_KEY].terminate();
     processObj[WORKER_MANAGER_KEY] = undefined;
   }
 }