refactor: use shared utilities in parallel processing classes

- Replace blocking pcntl_waitpid with ProcessManager timeout (300s)
- Replace tempnam with ProcessManager secure temp files (0600)
- Replace duplicated detectCpuCount with CpuDetector

Affected classes:
- ForkingRenderer
- ParallelCompiler
- ParallelParseDirectoryHandler
- SingleForkPipeline

This fixes HIGH severity issues: stuck builds now timeout after 5min,
and temp files are no longer world-readable.

Author: CybotTM

packages/typo3-guides-extension/src/Compiler/ParallelCompiler.php

@@ -15,6 +15,9 @@
 use phpDocumentor\Guides\Nodes\DocumentTree\ExternalEntryNode;
 use Psr\Log\LoggerInterface;
 use SplPriorityQueue;
+use T3Docs\GuidesExtension\Compiler\Cache\IncrementalBuildCache;
+use T3Docs\GuidesExtension\Util\CpuDetector;
+use T3Docs\GuidesExtension\Util\ProcessManager;
 
 use function array_chunk;
 use function count;
@@ -23,14 +26,8 @@
 use function function_exists;
 use function iterator_to_array;
 use function pcntl_fork;
-use function pcntl_waitpid;
-use function pcntl_wexitstatus;
-use function pcntl_wifexited;
 use function serialize;
 use function sprintf;
-use function sys_get_temp_dir;
-use function tempnam;
-use function unlink;
 use function unserialize;
 
 /**
@@ -85,6 +82,7 @@ public function __construct(
         private readonly Compiler $sequentialCompiler,
         iterable $passes,
         NodeTransformerFactory $nodeTransformerFactory,
+        private readonly ?IncrementalBuildCache $incrementalCache = null,
         private readonly ?LoggerInterface $logger = null,
         ?int $workerCount = null,
     ) {
@@ -218,7 +216,7 @@ private function runCollectionPhase(array $documents, CompilerContext $compilerC
                 continue;
             }
 
-            $tempFile = tempnam(sys_get_temp_dir(), 'compile_collect_' . $workerId . '_');
+            $tempFile = ProcessManager::createSecureTempFile('compile_collect_' . $workerId . '_');
             if ($tempFile === false) {
                 $this->logger?->error('Failed to create temp file, falling back to sequential');
                 return [$this->runSequentially($documents, $compilerContext), []];
@@ -230,7 +228,7 @@ private function runCollectionPhase(array $documents, CompilerContext $compilerC
             if ($pid === -1) {
                 $this->logger?->error('pcntl_fork failed, falling back to sequential');
                 foreach ($tempFiles as $tf) {
-                    @unlink($tf);
+                    ProcessManager::cleanupTempFile($tf);
                 }
                 return [$this->runSequentially($documents, $compilerContext), []];
             }
@@ -244,18 +242,14 @@ private function runCollectionPhase(array $documents, CompilerContext $compilerC
             $childPids[$workerId] = $pid;
         }
 
-        // Wait for children and collect results
+        // Wait for children with timeout and collect results
+        $waitResult = ProcessManager::waitForChildrenWithTimeout($childPids);
         $allDocuments = [];
         $allResults = [];
 
         foreach ($childPids as $workerId => $pid) {
-            $status = 0;
-            pcntl_waitpid($pid, $status);
-
-            // pcntl_waitpid always sets $status to an int
-            assert(is_int($status));
-
-            if (pcntl_wifexited($status) && pcntl_wexitstatus($status) === 0) {
+            // Only read results from successful workers
+            if (in_array($workerId, $waitResult['successes'], true)) {
                 $serialized = file_get_contents($tempFiles[$workerId]);
                 if ($serialized !== false && $serialized !== '') {
                     $data = unserialize($serialized);
@@ -274,7 +268,14 @@ private function runCollectionPhase(array $documents, CompilerContext $compilerC
                 }
             }
 
-            @unlink($tempFiles[$workerId]);
+            ProcessManager::cleanupTempFile($tempFiles[$workerId]);
+        }
+
+        // Log any failures
+        if ($waitResult['failures'] !== []) {
+            foreach ($waitResult['failures'] as $workerId => $reason) {
+                $this->logger?->warning(sprintf('Collection worker %d failed: %s', $workerId, $reason));
+            }
         }
 
         // Preserve document order
@@ -468,7 +469,7 @@ private function runResolutionPhase(array $documents, CompilerContext $compilerC
                 continue;
             }
 
-            $tempFile = tempnam(sys_get_temp_dir(), 'compile_resolve_' . $workerId . '_');
+            $tempFile = ProcessManager::createSecureTempFile('compile_resolve_' . $workerId . '_');
             if ($tempFile === false) {
                 return $this->runResolutionSequentially($documents, $compilerContext);
             }
@@ -478,7 +479,7 @@ private function runResolutionPhase(array $documents, CompilerContext $compilerC
 
             if ($pid === -1) {
                 foreach ($tempFiles as $tf) {
-                    @unlink($tf);
+                    ProcessManager::cleanupTempFile($tf);
                 }
                 return $this->runResolutionSequentially($documents, $compilerContext);
             }
@@ -491,30 +492,61 @@ private function runResolutionPhase(array $documents, CompilerContext $compilerC
             $childPids[$workerId] = $pid;
         }
 
-        // Collect results
+        // Wait for children with timeout and collect results
+        $waitResult = ProcessManager::waitForChildrenWithTimeout($childPids);
         $allDocuments = [];
-        foreach ($childPids as $workerId => $pid) {
-            $status = 0;
-            pcntl_waitpid($pid, $status);
+        $cacheStates = [];
 
-            // pcntl_waitpid always sets $status to an int
-            assert(is_int($status));
-
-            if (pcntl_wifexited($status) && pcntl_wexitstatus($status) === 0) {
+        foreach ($childPids as $workerId => $pid) {
+            // Only read results from successful workers
+            if (in_array($workerId, $waitResult['successes'], true)) {
                 $serialized = file_get_contents($tempFiles[$workerId]);
                 if ($serialized !== false && $serialized !== '') {
-                    $batchResult = unserialize($serialized);
-                    if (is_array($batchResult)) {
-                        foreach ($batchResult as $doc) {
-                            if ($doc instanceof DocumentNode) {
-                                $allDocuments[$doc->getFilePath()] = $doc;
+                    $data = unserialize($serialized);
+                    if (is_array($data)) {
+                        // New format with cache state
+                        if (isset($data['documents'])) {
+                            foreach ($data['documents'] as $doc) {
+                                if ($doc instanceof DocumentNode) {
+                                    $allDocuments[$doc->getFilePath()] = $doc;
+                                }
+                            }
+                            // Collect cache state for merging
+                            if (isset($data['cacheState']) && is_array($data['cacheState'])) {
+                                $cacheStates[] = $data['cacheState'];
+                            }
+                        } else {
+                            // Legacy format (just documents array)
+                            foreach ($data as $doc) {
+                                if ($doc instanceof DocumentNode) {
+                                    $allDocuments[$doc->getFilePath()] = $doc;
+                                }
                             }
                         }
                     }
                 }
             }
 
-            @unlink($tempFiles[$workerId]);
+            ProcessManager::cleanupTempFile($tempFiles[$workerId]);
+        }
+
+        // Log any failures
+        if ($waitResult['failures'] !== []) {
+            foreach ($waitResult['failures'] as $workerId => $reason) {
+                $this->logger?->warning(sprintf('Resolution worker %d failed: %s', $workerId, $reason));
+            }
+        }
+
+        // Merge cache states from all children
+        if ($this->incrementalCache !== null && $cacheStates !== []) {
+            foreach ($cacheStates as $state) {
+                $this->incrementalCache->mergeState($state);
+            }
+            $this->logger?->debug(sprintf(
+                'Merged cache states from %d workers, now have %d exports',
+                count($cacheStates),
+                count($this->incrementalCache->getAllExports())
+            ));
         }
 
         // Preserve order
@@ -541,7 +573,13 @@ private function processResolutionBatch(
             $batch = $pass->run($batch, $compilerContext);
         }
 
-        file_put_contents($tempFile, serialize($batch));
+        // Serialize documents and cache state (if cache is available)
+        $data = [
+            'documents' => $batch,
+            'cacheState' => $this->incrementalCache?->extractState() ?? [],
+        ];
+
+        file_put_contents($tempFile, serialize($data));
     }
 
     /**
@@ -698,25 +736,7 @@ private function shouldFork(int $documentCount): bool
 
     private function detectCpuCount(): int
     {
-        if (is_file('/proc/cpuinfo')) {
-            $cpuinfo = file_get_contents('/proc/cpuinfo');
-            if ($cpuinfo !== false) {
-                $count = substr_count($cpuinfo, 'processor');
-                if ($count > 0) {
-                    return min($count, 8);
-                }
-            }
-        }
-
-        $nproc = @shell_exec('nproc 2>/dev/null');
-        if ($nproc !== null && $nproc !== false) {
-            $count = (int) trim($nproc);
-            if ($count > 0) {
-                return min($count, 8);
-            }
-        }
-
-        return 4;
+        return CpuDetector::detectCores();
     }
 
     public function setParallelEnabled(bool $enabled): void

packages/typo3-guides-extension/src/Parser/ParallelParseDirectoryHandler.php

@@ -17,6 +17,8 @@
 use phpDocumentor\Guides\Settings\SettingsManager;
 use Psr\EventDispatcher\EventDispatcherInterface;
 use Psr\Log\LoggerInterface;
+use T3Docs\GuidesExtension\Util\CpuDetector;
+use T3Docs\GuidesExtension\Util\ProcessManager;
 
 use function array_chunk;
 use function array_map;
@@ -28,13 +30,7 @@
 use function file_put_contents;
 use function function_exists;
 use function pcntl_fork;
-use function pcntl_waitpid;
-use function pcntl_wifexited;
-use function pcntl_wexitstatus;
 use function serialize;
-use function sys_get_temp_dir;
-use function tempnam;
-use function unlink;
 use function unserialize;
 
 /**
@@ -165,8 +161,8 @@ private function parseInParallel(ParseDirectoryCommand $command, array $files, s
                 continue;
             }
 
-            // Create temp file for this worker's results
-            $tempFile = tempnam(sys_get_temp_dir(), 'parse_' . $workerId . '_');
+            // Create secure temp file for this worker's results
+            $tempFile = ProcessManager::createSecureTempFile('parse_' . $workerId . '_');
             if ($tempFile === false) {
                 $this->logger?->error('Failed to create temp file, falling back to sequential');
                 return $this->parseSequentially($command, $files, $indexName);
@@ -179,7 +175,7 @@ private function parseInParallel(ParseDirectoryCommand $command, array $files, s
                 // Fork failed - clean up and fall back
                 $this->logger?->error('pcntl_fork failed, falling back to sequential parsing');
                 foreach ($tempFiles as $tf) {
-                    @unlink($tf);
+                    ProcessManager::cleanupTempFile($tf);
                 }
                 return $this->parseSequentially($command, $files, $indexName);
             }
@@ -194,20 +190,14 @@ private function parseInParallel(ParseDirectoryCommand $command, array $files, s
             $childPids[$workerId] = $pid;
         }
 
-        // Parent: wait for all children and collect results
+        // Parent: wait for all children with timeout and collect results
+        $waitResult = ProcessManager::waitForChildrenWithTimeout($childPids);
         $documents = [];
-        $failures = [];
 
         foreach ($childPids as $workerId => $pid) {
-            $status = 0;
-            pcntl_waitpid($pid, $status);
-
-            // pcntl_waitpid always sets $status to an int
-            assert(is_int($status));
-            if (pcntl_wifexited($status) && pcntl_wexitstatus($status) === 0) {
-                // Read results from temp file
-                $tempFile = $tempFiles[$workerId];
-                $serialized = file_get_contents($tempFile);
+            // Only read results from successful workers
+            if (in_array($workerId, $waitResult['successes'], true)) {
+                $serialized = file_get_contents($tempFiles[$workerId]);
                 if ($serialized !== false && $serialized !== '') {
                     $batchDocs = unserialize($serialized);
                     if (is_array($batchDocs)) {
@@ -218,19 +208,16 @@ private function parseInParallel(ParseDirectoryCommand $command, array $files, s
                         }
                     }
                 }
-            } else {
-                $failures[] = $workerId;
             }
 
             // Clean up temp file
-            @unlink($tempFiles[$workerId]);
+            ProcessManager::cleanupTempFile($tempFiles[$workerId]);
         }
 
-        if ($failures !== []) {
-            $this->logger?->warning(sprintf(
-                'Parallel parsing: %d workers failed',
-                count($failures)
-            ));
+        if ($waitResult['failures'] !== []) {
+            foreach ($waitResult['failures'] as $workerId => $reason) {
+                $this->logger?->warning(sprintf('Parse worker %d failed: %s', $workerId, $reason));
+            }
         }
 
         $this->logger?->info(sprintf(
@@ -333,24 +320,6 @@ private function getDirectoryIndexFile(ParseDirectoryCommand $command): string
 
     private function detectCpuCount(): int
     {
-        if (is_file('/proc/cpuinfo')) {
-            $cpuinfo = file_get_contents('/proc/cpuinfo');
-            if ($cpuinfo !== false) {
-                $count = substr_count($cpuinfo, 'processor');
-                if ($count > 0) {
-                    return min($count, 8);
-                }
-            }
-        }
-
-        $nproc = @shell_exec('nproc 2>/dev/null');
-        if ($nproc !== null && $nproc !== false) {
-            $count = (int) trim($nproc);
-            if ($count > 0) {
-                return min($count, 8);
-            }
-        }
-
-        return 4;
+        return CpuDetector::detectCores();
     }
 }