From b7bc589baac3ee040b3c45606d2115010721d382 Mon Sep 17 00:00:00 2001 From: Nicolas Joubert Date: Tue, 3 Nov 2026 10:33:36 +0100 Subject: [PATCH] #396 - Make the process fail when a finalization fails, stop the running sub-processes of process_launcher when the process fails Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 1 + docs/02-task_types.md | 4 +- docs/reference/tasks/process_launcher_task.md | 7 ++- src/Manager/ProcessManager.php | 17 ++++++ src/Task/Process/ProcessLauncherTask.php | 26 +++++++++- .../ProcessManagerFinalizationTest.php | 52 +++++++++++++++++++ .../Task/Process/ProcessLauncherTaskTest.php | 33 ++++++++++++ 7 files changed, 137 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 40dd5258..73519523 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ Latest * [#392](https://github.com/cleverage/process-bundle/issues/392) Documentation: reset of the process configurations between two messages of a worker (`kernel.reset`, #355), permissions of the JSON buffer of `process_launcher`, `ProcessManager` subclasses in `UPGRADE.md` (v5.5), broken link in the CHANGELOG. ## Fixes +* [#396](https://github.com/cleverage/process-bundle/issues/396) A failure of `finalize()` on a process that has succeeded makes the process fail with a `ProcessFailedException`, once every task is finalized: the process was flagged and logged as failed, but ended successfully (`cleverage_process.end` event, the command exiting with `0`, a parent process going on). `ProcessLauncherTask` is finalizable: the sub-processes still running when the process fails or is stopped are stopped (a warning is logged) and the JSON buffers not output yet are removed, instead of going on with their side effects after the end of the process. Update documentation, add tests. * [#394](https://github.com/cleverage/process-bundle/issues/394) `ProcessManager::execute()`: an exception thrown by a listener of `cleverage_process.fail` (`ProcessEvent::EVENT_PROCESS_FAILED`) is logged as an error and no longer replaces the error of the process, which is rethrown to the command, the parent process or Messenger. The debug message "has error outputs but it's error strategy 'stop' implies they will never be reached" is removed: the error branch of a task with the `stop` strategy is executed before the process stops. Update documentation, add tests. * [#388](https://github.com/cleverage/process-bundle/issues/388) The temporary files of `file_splitter`, `csv_splitter` and of the JSON buffer of `process_launcher` (#343) are created with the `0077` umask: they are no longer readable by other users before their permissions are set to `0600`. Add tests. * [#390](https://github.com/cleverage/process-bundle/issues/390) `cleverage:process:execute` with `--output-format=json-stream` and STDOUT (#353): the invalid UTF-8 sequences of the output are replaced, and an output that still cannot be encoded as JSON (e.g. `NAN`) is reported on the error output instead of throwing a `JsonException` that made the command fail after the execution and skipped the next processes. `UPGRADE.md` (v5.5): the `dump` format without `symfony/var-dumper` and the unknown formats make the command fail before any execution. Update documentation, add tests. diff --git a/docs/02-task_types.md b/docs/02-task_types.md index 2578e90d..6d139d9d 100644 --- a/docs/02-task_types.md +++ b/docs/02-task_types.md @@ -160,7 +160,9 @@ On the opposite, some tasks may require cleanup work at the very end of the proc temporary folder, log some statistics). Finalizable tasks implement `CleverAge\ProcessBundle\Model\FinalizableTaskInterface`. Their `finalize` method is -called once all tasks are resolved, for every task of the process, in the order they are configured. +called once all tasks are resolved, for every task of the process, in the order they are configured. An exception +thrown by `finalize` is logged as critical, the next tasks are still finalized, then the process fails with a +`ProcessFailedException`. A process stopped without exception (e.g. by the [StopTask](reference/tasks/stop_task.md)) is finalized the same way. diff --git a/docs/reference/tasks/process_launcher_task.md b/docs/reference/tasks/process_launcher_task.md index 44a908b4..9bd641c4 100644 --- a/docs/reference/tasks/process_launcher_task.md +++ b/docs/reference/tasks/process_launcher_task.md @@ -34,6 +34,10 @@ it must run with the same user. Without `json_buffering`, the task outputs nothi If a sub-process exits with a non-zero code, its error output is logged as critical, all running sub-processes are stopped and a `RuntimeException` is thrown. +When the process fails or is stopped (stop request, [StopTask](stop_task.md)) while sub-processes are still running, +they are stopped when the task is finalized (a warning is logged), and the JSON stream files not output yet are removed: +the sub-processes no longer go on with their side effects after the end of the process. + Options ------- @@ -73,5 +77,6 @@ Notes environment as the current one (`--env`), the arguments of the service. * The JSON stream files output by the task are not removed by it: remove them once read (e.g. with a [file remover](file_remover_task.md) task). The task only removes the files it does not output: empty ones, and - those of a failed sub-process and of the still running sub-processes stopped because of it. + those of a failed sub-process and of the still running sub-processes stopped because of it or at the end of the + process. * The incremental error output (stderr) of the running sub-processes is echoed directly. diff --git a/src/Manager/ProcessManager.php b/src/Manager/ProcessManager.php index fde61a16..c8241ac6 100644 --- a/src/Manager/ProcessManager.php +++ b/src/Manager/ProcessManager.php @@ -249,10 +249,27 @@ protected function doExecute(string $processCode, mixed $input = null, array $co } // Finalize the process in a linear way + $finalizationError = null; foreach ($processConfiguration->getTaskConfigurations() as $taskConfiguration) { // Never finalized twice, even if the process fails after this point unset($tasksToFinalize[spl_object_id($taskConfiguration)]); + $state = $taskConfiguration->getState(); + // Already failed (initialization failure of a task never reached): not a finalization failure + $failedBefore = $state->isStopped() && $state->getException() instanceof \Throwable; $this->finalize($taskConfiguration); + if (!$failedBefore && !$finalizationError instanceof \Throwable + && $state->isStopped() && $state->getException() instanceof \Throwable) { + $finalizationError = ProcessFailedException::create( + $processCode, + $taskConfiguration->getCode(), + $state->getException() + ); + } + } + // After the finalization of every task: a finalization failure makes the process fail (it ended as + // succeeded, while flagged and logged as failed) + if ($finalizationError instanceof \Throwable) { + throw $finalizationError; } $this->endProcess($processHistory); diff --git a/src/Task/Process/ProcessLauncherTask.php b/src/Task/Process/ProcessLauncherTask.php index 6840ce2e..7b02afe1 100644 --- a/src/Task/Process/ProcessLauncherTask.php +++ b/src/Task/Process/ProcessLauncherTask.php @@ -16,6 +16,7 @@ use CleverAge\ProcessBundle\Exception\InvalidArgumentException; use CleverAge\ProcessBundle\Exception\RuntimeException; use CleverAge\ProcessBundle\Model\AbstractConfigurableTask; +use CleverAge\ProcessBundle\Model\FinalizableTaskInterface; use CleverAge\ProcessBundle\Model\FlushableTaskInterface; use CleverAge\ProcessBundle\Model\IterableTaskInterface; use CleverAge\ProcessBundle\Model\ProcessState; @@ -32,7 +33,7 @@ * * @final since 5.4 */ -class ProcessLauncherTask extends AbstractConfigurableTask implements FlushableTaskInterface, IterableTaskInterface +class ProcessLauncherTask extends AbstractConfigurableTask implements FlushableTaskInterface, IterableTaskInterface, FinalizableTaskInterface { /** * @var SubprocessInstance[] @@ -138,6 +139,29 @@ public function next(ProcessState $state): bool return false; } + /** + * Stop the sub-processes still running at the end of the process, and remove the buffers that will never be + * output. Only when the process has failed or has been stopped: otherwise, the task has waited for every + * sub-process. The sub-processes went on with their side effects, their error output no longer read. + */ + public function finalize(ProcessState $state): void + { + $running = 0; + foreach ($this->launchedProcesses as $process) { + if (!$process->getProcess()->isTerminated()) { + ++$running; + } + $process->stop(5); + $process->removeBuffer(); + } + if ($running > 0) { + $this->logger->warning("{$running} sub-process(es) still running at the end of the process have been stopped"); + } + $this->launchedProcesses = []; + $this->finishedBuffers = new \SplQueue(); + $this->flushMode = false; + } + protected function handleInput(ProcessState $state): void { $options = $this->getOptions($state); diff --git a/tests/Manager/ProcessManagerFinalizationTest.php b/tests/Manager/ProcessManagerFinalizationTest.php index 93f3b505..683c4be0 100644 --- a/tests/Manager/ProcessManagerFinalizationTest.php +++ b/tests/Manager/ProcessManagerFinalizationTest.php @@ -206,6 +206,58 @@ public function testAFinalizationFailureIsLoggedAndDoesNotHideTheErrorOfTheProce self::assertContains(['critical', 'Finalization failed', 'throwing'], $this->taskLogs); } + /** + * A finalization failure makes the process fail: it was flagged and logged as failed, but ended as succeeded (end + * event, the command exiting with 0, a parent process going on). + */ + public function testAFinalizationFailureMakesTheProcessFail(): void + { + $events = []; + $this->eventDispatcher->addListener(ProcessEvent::EVENT_PROCESS_ENDED, static function () use (&$events): void { + $events[] = 'end'; + }); + $this->eventDispatcher->addListener(ProcessEvent::EVENT_PROCESS_FAILED, static function () use (&$events): void { + $events[] = 'fail'; + }); + + $error = $this->executeFailing([ + 'throwing' => $this->createTaskConfiguration('@test.finalizable_throwing', ['second']), + 'second' => $this->createTaskConfiguration('@test.finalizable_second'), + ]); + + self::assertInstanceOf(ProcessFailedException::class, $error); + self::assertSame("Process test.process has failed during process throwing with message: 'Finalization failed'.\n", $error->getMessage()); + // Every task is finalized, once + self::assertSame(['throwing (throwing)', 'second (second)'], $this->finalized); + self::assertSame(['fail'], $events); + self::assertNull($this->processManager->getTaskConfiguration()); + } + + public function testAFinalizationFailureOfASubProcessMakesItsParentTaskFail(): void + { + $this->createProcessManager([ + 'test.process' => [ + 'sub_process' => $this->createTaskConfiguration('@test.sub_process', ['second'], ['process' => 'test.child']), + 'second' => $this->createTaskConfiguration('@test.finalizable_second'), + ], + 'test.child' => [ + 'throwing' => $this->createTaskConfiguration('@test.finalizable_throwing'), + ], + ]); + + try { + $this->processManager->execute('test.process'); + self::fail('The process should have failed'); + } catch (ProcessFailedException $error) { + self::assertInstanceOf(ProcessFailedException::class, $error->getPrevious()); + self::assertSame('Finalization failed', $error->getPrevious()->getPrevious()?->getMessage()); + } + + // The parent process does not go on with the next task + self::assertSame(['throwing (throwing)', 'second (second)'], $this->finalized); + self::assertSame([false, true], $this->failedAtFinalization); + } + public function testTheTasksAreNotFinalizedTwiceWhenTheProcessFailsAfterTheirFinalization(): void { $this->failingProcessLog = 'Process test.process succeed'; diff --git a/tests/Task/Process/ProcessLauncherTaskTest.php b/tests/Task/Process/ProcessLauncherTaskTest.php index b31d81af..940dd798 100644 --- a/tests/Task/Process/ProcessLauncherTaskTest.php +++ b/tests/Task/Process/ProcessLauncherTaskTest.php @@ -176,6 +176,39 @@ public function testJsonBufferOfATerminatedSubprocessIsKeptWhenAnotherSubprocess unlink($bufferPath); } + /** + * The process has failed or has been stopped: the sub-processes still running are stopped (they went on with their + * side effects), and the buffers that will never be output are removed. + */ + public function testTheSubprocessesAreStoppedWhenTheTaskIsFinalized(): void + { + [$task, $state, $runningBufferPath] = $this->launch('sleep', wait: false); + [, , $terminatedBufferPath] = $this->launch('write', $task, $state); + $launchedProcesses = (new \ReflectionProperty($task, 'launchedProcesses'))->getValue($task); + $this->assertIsArray($launchedProcesses); + $runningSubprocess = reset($launchedProcesses); + $this->assertInstanceOf(SubprocessInstance::class, $runningSubprocess); + $this->assertTrue($runningSubprocess->getProcess()->isRunning()); + + $task->finalize($state); + + $this->assertFalse($runningSubprocess->getProcess()->isRunning()); + $this->assertFileDoesNotExist($runningBufferPath); + $this->assertFileDoesNotExist($terminatedBufferPath); + $this->assertSame([], (new \ReflectionProperty($task, 'launchedProcesses'))->getValue($task)); + // Nothing left to output + $this->assertFalse($task->next($state)); + } + + public function testFinalizeWithoutSubprocess(): void + { + $task = $this->createTask(); + + $task->finalize($this->createState(['process' => 'child'])); + + $this->assertSame([], (new \ReflectionProperty($task, 'launchedProcesses'))->getValue($task)); + } + protected function tearDown(): void { if (isset($this->consoleDir)) {