diff --git a/CHANGELOG.md b/CHANGELOG.md index c6edc6e..eb81ac9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## Unreleased +### Added + +- [crunzphp#83] Add `output_realtime` config option to stream task output to its destination (log file or console) as it is produced instead of only after the task finishes + ## [v3.7.0] - 2024-08-12 ### Changed @@ -556,6 +560,7 @@ In `v2` this will result in exception. [crunzphp#77]: https://github.com/crunzphp/crunz/pull/77 [crunzphp#78]: https://github.com/crunzphp/crunz/pull/78 [crunzphp#79]: https://github.com/crunzphp/crunz/pull/79 +[crunzphp#83]: https://github.com/crunzphp/crunz/issues/83 [v1.5.1]: https://github.com/crunzphp/crunz/compare/v1.5.0...v1.5.1 [v1.6.0]: https://github.com/crunzphp/crunz/compare/v1.5.1...v1.6.0 [v1.6.1]: https://github.com/crunzphp/crunz/compare/v1.6.0...v1.6.1 diff --git a/README.md b/README.md index aaf90eb..3fa8a4a 100644 --- a/README.md +++ b/README.md @@ -555,6 +555,58 @@ Method `appendOutputTo()` **appends** the output to the specified file. To overr It is also possible to send the errors as emails to a group of recipients by setting `email_output` and `mailer` settings in the configuration file. +## Realtime Output + +By default a task's output is buffered and only emitted once the task has +finished. For long-running tasks (for example a worker that polls a queue in a +loop) this means no output is visible until the task ends, which makes +monitoring and debugging difficult, especially when logs are collected from +the process' standard output (e.g. Docker/CloudWatch). + +Setting `output_realtime` to `true` streams each task's output to its +configured destination as soon as it is produced, instead of buffering it until +the task finishes: + +```yaml +# Configuration settings + +## ... +output_realtime: true +## ... +``` + +The output is streamed to the same destination it would normally be written to +at the end of the job, resolved in the usual order: + +1. a per-event log file, if the task uses `sendOutputTo()`/`appendOutputTo()`; +2. otherwise the global `output_log_file`, if `log_output` is enabled; +3. otherwise the console (`stdout` for standard output, `stderr` for errors). + +So a task logging to a file gets that file written **live** (line by line as it +runs), and a task whose output goes to `stdout` (e.g. for Docker/CloudWatch) +gets it streamed to `stdout` live. The output is forwarded **verbatim** — the +live stream is the raw task output, not the framed `[date] crunz.INFO: ...` +record that buffered mode writes. Because the destination receives the live +stream, the end-of-job framed record to that same destination is not written +again (it would duplicate the stream). + +`email_output` is unaffected: it still sends the complete output once the task +finishes. The error reporting sinks (`log_errors` → `errors_log_file`, +`email_errors`) are also unaffected. + +> Notes: +> +> - Realtime mode changes **when and in what form** output is written, not how +> much is held in memory: the output is still buffered internally so +> `email_output` can send the complete output at the end. +> - Only the task process' own output is streamed. Output echoed by +> `before()`/`then()` callbacks is still sent via `email_output` but is not +> part of the live stream. +> - If two sinks resolve to the same underlying stream — for example +> `output_log_file: php://stdout` together with a separate consumer of the +> runner's stdout — the output can appear twice on that stream. Point the log +> at a real file, or disable it, when you rely on the live stream. + ## Error Handling Crunz makes error handling easy by logging and also allowing you add a set of callbacks in case of an error. @@ -861,6 +913,12 @@ errors_log_file: # Set this to true if you want to keep the outputs log_output: false +# By default a task's output is buffered and only emitted once the task +# finishes. Set this to true to stream the output to the console (stdout for +# standard output, stderr for error output) as soon as it is produced. Useful +# for long-running tasks whose logs would otherwise be invisible until they end. +output_realtime: false + # This is the absolute path to the global output log file # The events which have dedicated log files (defined with them), won't be # logged to this file though. diff --git a/resources/config/crunz.yml b/resources/config/crunz.yml index c3e316b..acd1965 100644 --- a/resources/config/crunz.yml +++ b/resources/config/crunz.yml @@ -34,6 +34,18 @@ errors_log_file: ~ # Set this to true if you want to keep the outputs log_output: false +# By default a task's output is buffered and only emitted once the task +# finishes. Set this to true to stream the output to its destination as soon as +# it is produced, instead of buffering it. The output is streamed to wherever it +# would normally be written: a per-event log file (sendOutputTo), else the +# global output_log_file (when log_output is true), else the console (stdout for +# standard output, stderr for errors). The live stream is the raw task output +# (not the framed "[date] crunz.INFO:" record), and it replaces the end-of-job +# record for that destination. email_output and error reporting are unaffected. +# Useful for long-running tasks whose logs would otherwise be invisible until +# completion (e.g. when monitored via Docker/CloudWatch). +output_realtime: false + # This is the absolute path to the global output log file # The events which have dedicated log files (defined with them), won't be # logged to this file though. diff --git a/src/Configuration/Definition.php b/src/Configuration/Definition.php index 3a7a44d..589ed18 100644 --- a/src/Configuration/Definition.php +++ b/src/Configuration/Definition.php @@ -59,6 +59,14 @@ public function getConfigTreeBuilder(): TreeBuilder ->info('Flag for logging output' . PHP_EOL) ->end() + ->booleanNode('output_realtime') + ->defaultFalse() + ->info( + 'Stream task output to the console as it is produced' + . ' instead of only after the task finishes.' . PHP_EOL + ) + ->end() + ->scalarNode('output_log_file') ->defaultValue('/dev/null') ->info('Path to output logs' . PHP_EOL) diff --git a/src/Event.php b/src/Event.php index ce3aeb5..f8982da 100644 --- a/src/Event.php +++ b/src/Event.php @@ -171,6 +171,13 @@ class Event implements PingableInterface private ?LockFactory $lockFactory = null; /** @var string[] */ private array $wholeOutput = []; + /** + * Optional sink invoked with each output chunk as it is produced, used to + * stream output in realtime instead of only after the process exits. + * + * @var \Closure(string, string):void|null + */ + private ?\Closure $realtimeCallback = null; /** @var Lock */ private $lock; /** @var \Closure[] */ @@ -295,6 +302,20 @@ public function wholeOutput() return \implode('', $this->wholeOutput); } + /** + * Register a sink that receives each output chunk as it is produced. + * + * The sink is invoked from the process output callback with the Symfony + * Process output type ('out'/'err') and the chunk content, enabling + * realtime streaming of output while it is still being generated. + * + * @param \Closure(string, string):void|null $callback + */ + public function setRealtimeCallback(?\Closure $callback): void + { + $this->realtimeCallback = $callback; + } + /** * Start the event execution. * @@ -309,6 +330,10 @@ public function start() $this->getProcess()->start( function ($type, $content): void { $this->wholeOutput[] = $content; + + if (null !== $this->realtimeCallback) { + ($this->realtimeCallback)($type, $content); + } } ); diff --git a/src/EventRunner.php b/src/EventRunner.php index 7e5fcfb..02404c8 100644 --- a/src/EventRunner.php +++ b/src/EventRunner.php @@ -10,7 +10,9 @@ use Crunz\Logger\Logger; use Crunz\Logger\LoggerFactory; use Crunz\Pinger\PingableInterface; +use Symfony\Component\Console\Output\ConsoleOutputInterface; use Symfony\Component\Console\Output\OutputInterface; +use Symfony\Component\Process\Process as SymfonyProcess; class EventRunner { @@ -19,6 +21,14 @@ class EventRunner /** @var Logger|null */ protected $logger; private ?OutputInterface $output = null; + /** + * Open stream handles used to stream realtime output to a file/stream + * destination, keyed by the event's object id. Closed once the event is + * handled. + * + * @var array + */ + private array $realtimeStreams = []; public function __construct( protected Invoker $invoker, @@ -75,6 +85,13 @@ protected function start(Event $event): void $event->logger = $this->loggerFactory->createEvent($event->output); } + // When realtime output is enabled, stream the task's output to its + // resolved destination (per-event file, global log file, or the console) + // as it is produced instead of only after the process exits. + if ($this->realtimeOutputEnabled()) { + $event->setRealtimeCallback($this->createRealtimeCallback($event)); + } + $this->consoleLogger ->debug("Invoke Event's ping before."); @@ -132,6 +149,9 @@ protected function manageStartedEvents(): void $this->consoleLogger ->debug("Task {$id} status: {$runStatus}."); + // Close any realtime file stream opened for this event. + $this->closeRealtimeStream($event); + // Dismiss the event if it's finished $schedule->dismissEvent($eventKey); } @@ -174,6 +194,17 @@ protected function invoke(array $callbacks = [], array $parameters = []) protected function handleOutput(Event $event): void { + // In realtime mode the task's output has already been streamed, as it + // was produced, to its resolved destination (per-event file, global log + // file, or the console). The end-of-job framed emission to that same + // destination is replaced by the live stream, so it is skipped here. + // email_output is additive and still sends from the retained buffer. + if ($this->realtimeOutputEnabled()) { + $this->emailOutput($event); + + return; + } + $logged = false; $logOutput = $this->configuration ->get('log_output') @@ -195,15 +226,7 @@ protected function handleOutput(Event $event): void $this->display($event->getOutputStream()); } - $emailOutput = $this->configuration - ->get('email_output') - ; - if ($emailOutput && !empty($event->getOutputStream())) { - $this->mailer->send( - 'Crunz: output for event: ' . ($event->description ?? $event->getId()), - $this->formatEventOutput($event) - ); - } + $this->emailOutput($event); } protected function handleError(Event $event): void @@ -219,7 +242,10 @@ protected function handleError(Event $event): void $this->logger() ->error($this->formatEventError($event)) ; - } else { + } elseif (!$this->realtimeOutputEnabled()) { + // Without log_errors, a failed task's output is written straight to + // the runner's console here. In realtime mode that output already + // streamed live, so suppress this write to avoid duplicating it. $output = $event->wholeOutput(); $this->output @@ -269,6 +295,26 @@ protected function display($output): void ; } + /** + * Email the event's output when email_output is enabled. + * + * Kept separate from the logging/display logic so it can run unchanged in + * realtime mode, where the live stream replaces the end-of-job logging but + * the retained buffer is still emailed. + */ + private function emailOutput(Event $event): void + { + $emailOutput = $this->configuration + ->get('email_output') + ; + if ($emailOutput && !empty($event->getOutputStream())) { + $this->mailer->send( + 'Crunz: output for event: ' . ($event->description ?? $event->getId()), + $this->formatEventOutput($event) + ); + } + } + private function pingBefore(PingableInterface $schedule): void { if (!$schedule->hasPingBefore()) { @@ -311,4 +357,95 @@ private function logger(): Logger return $this->logger; } + + /** Whether realtime output streaming is enabled via configuration. */ + private function realtimeOutputEnabled(): bool + { + return (bool) $this->configuration + ->get('output_realtime') + ; + } + + /** + * Build a sink that writes each output chunk to the event's resolved output + * destination as it is produced. When the destination is a file/stream path + * (a per-event `sendOutputTo()` target or the global `output_log_file`), the + * raw chunks are appended to that path. Otherwise output is written to the + * runner console, with standard output going to the main stream and error + * output to the error stream (when available). Chunks are written raw and + * without an added newline so task output is forwarded verbatim. + * + * @return \Closure(string, string):void + */ + private function createRealtimeCallback(Event $event): \Closure + { + $path = $this->realtimeStreamPath($event); + if (null !== $path) { + $stream = @\fopen($path, 'ab'); + if (false !== $stream) { + $this->realtimeStreams[\spl_object_id($event)] = $stream; + + return static function (string $type, string $content) use ($stream): void { + \fwrite($stream, $content); + }; + } + } + + $output = $this->output; + if (null === $output) { + return static function (): void {}; + } + + $errorOutput = $output instanceof ConsoleOutputInterface + ? $output->getErrorOutput() + : $output + ; + + return static function (string $type, string $content) use ($output, $errorOutput): void { + $stream = SymfonyProcess::ERR === $type + ? $errorOutput + : $output + ; + $stream->write($content, false, OutputInterface::OUTPUT_RAW); + }; + } + + /** + * Resolve the file/stream path a task's realtime output should be streamed + * to, mirroring the success-path routing precedence: a dedicated per-event + * output file first, then the global output log file. Returns null when the + * output is not directed at a file/stream and should go to the console. + */ + private function realtimeStreamPath(Event $event): ?string + { + if (!$event->nullOutput()) { + return $event->output; + } + + $logOutput = (bool) $this->configuration + ->get('log_output') + ; + if ($logOutput) { + $logFile = $this->configuration + ->get('output_log_file') + ; + if (\is_string($logFile) && '' !== $logFile) { + return $logFile; + } + } + + return null; + } + + /** Close and forget any realtime stream opened for the given event. */ + private function closeRealtimeStream(Event $event): void + { + $id = \spl_object_id($event); + if (!isset($this->realtimeStreams[$id])) { + return; + } + + \fclose($this->realtimeStreams[$id]); + unset($this->realtimeStreams[$id]); + } } diff --git a/tests/EndToEnd/RealtimeOutputTest.php b/tests/EndToEnd/RealtimeOutputTest.php new file mode 100644 index 0000000..f32091a --- /dev/null +++ b/tests/EndToEnd/RealtimeOutputTest.php @@ -0,0 +1,165 @@ +createEnvironmentBuilder() + ->addTask('RealtimeOutputTasks') + ->withConfig(['output_realtime' => true]) + ; + $environment = $envBuilder->createEnvironment(); + + $process = $environment->runCrunzCommand('schedule:run --force', wait: false); + + // The task emits the first marker, sleeps 3s, then emits the second. + // In realtime mode each chunk is streamed as produced, so there is a + // window where the first marker is visible but the second is not yet. + $streamedIncrementally = $this->sawFirstMarkerBeforeSecond($process); + + $process->wait(); + + self::assertTrue( + $streamedIncrementally, + 'The first marker should be streamed before the second is produced (realtime streaming).' + ); + // Sanity check: both markers are present once the task completes. + self::assertStringContainsString('REALTIME_FIRST', $process->getOutput()); + self::assertStringContainsString('REALTIME_SECOND', $process->getOutput()); + } + + public function test_output_is_not_streamed_when_realtime_disabled(): void + { + $envBuilder = $this->createEnvironmentBuilder() + ->addTask('RealtimeOutputTasks') + ->withConfig( + [ + 'output_realtime' => false, + // Route the end-of-job output to stdout so we can confirm it + // arrives all at once at the end, not streamed during the run. + 'log_output' => true, + 'output_log_file' => 'php://stdout', + ] + ) + ; + $environment = $envBuilder->createEnvironment(); + + $process = $environment->runCrunzCommand('schedule:run --force', wait: false); + + // With realtime off, both markers are buffered and written together in a + // single end-of-job record, so the "first without second" window never + // exists. + $streamedIncrementally = $this->sawFirstMarkerBeforeSecond($process); + + $process->wait(); + + self::assertFalse( + $streamedIncrementally, + 'With realtime disabled the markers must be emitted together at the end, not streamed.' + ); + // The output is still emitted at the end of the job. + self::assertStringContainsString('REALTIME_FIRST', $process->getOutput()); + self::assertStringContainsString('REALTIME_SECOND', $process->getOutput()); + } + + public function test_output_is_streamed_to_file_before_task_finishes(): void + { + $envBuilder = $this->createEnvironmentBuilder() + ->addTask('RealtimeFileOutputTasks') + ->withConfig(['output_realtime' => true]) + ; + $environment = $envBuilder->createEnvironment(); + $logPath = $environment->rootDirectory() . DIRECTORY_SEPARATOR . 'realtime.log'; + + $process = $environment->runCrunzCommand('schedule:run --force', wait: false); + + // The task (configured with appendOutputTo('realtime.log')) emits the + // first marker, sleeps 3s, then emits the second. With realtime output + // the file receives the first marker before the second is produced. + $streamedIncrementally = $this->fileSawFirstMarkerBeforeSecond($logPath, $process); + + $process->wait(); + + self::assertTrue( + $streamedIncrementally, + 'The log file should receive the first marker before the second is produced (realtime file streaming).' + ); + // Both markers are present in the file once the task completes, and the + // raw output is streamed (not wrapped in the framed log record). + $contents = (string) \file_get_contents($logPath); + self::assertStringContainsString('FILE_FIRST', $contents); + self::assertStringContainsString('FILE_SECOND', $contents); + self::assertStringNotContainsString('crunz.INFO', $contents); + } + + /** + * Poll the process output while it runs, returning true if we ever observe + * the first marker present while the second is still absent. That transient + * state only occurs when output is streamed incrementally; when output is + * buffered, both markers appear together in one write and the state is never + * observed. + */ + private function sawFirstMarkerBeforeSecond(Process $process): bool + { + $deadline = \microtime(true) + self::POLL_TIMEOUT_SECONDS; + + while ($process->isRunning()) { + $output = $process->getOutput(); + if ( + \str_contains($output, 'REALTIME_FIRST') + && !\str_contains($output, 'REALTIME_SECOND') + ) { + return true; + } + + if (\microtime(true) > $deadline) { + break; + } + + \usleep(50000); // 50 ms + } + + return false; + } + + /** + * Poll a log file while the process runs, returning true if we ever observe + * the first marker written to the file while the second is still absent — + * proving the file is written incrementally rather than only at the end. + */ + private function fileSawFirstMarkerBeforeSecond(string $logPath, Process $process): bool + { + $deadline = \microtime(true) + self::POLL_TIMEOUT_SECONDS; + + while ($process->isRunning()) { + $contents = \is_file($logPath) + ? (string) \file_get_contents($logPath) + : '' + ; + if ( + \str_contains($contents, 'FILE_FIRST') + && !\str_contains($contents, 'FILE_SECOND') + ) { + return true; + } + + if (\microtime(true) > $deadline) { + break; + } + + \usleep(50000); // 50 ms + } + + return false; + } +} diff --git a/tests/TestCase/FakeConfiguration.php b/tests/TestCase/FakeConfiguration.php index d2d0f7b..a33087b 100644 --- a/tests/TestCase/FakeConfiguration.php +++ b/tests/TestCase/FakeConfiguration.php @@ -18,6 +18,7 @@ final class FakeConfiguration implements ConfigurationInterface 'errors_log_file' => null, 'logger_factory' => PsrStreamLoggerFactory::class, 'log_output' => false, + 'output_realtime' => false, 'output_log_file' => null, 'log_allow_line_breaks' => false, 'log_ignore_empty_context' => false, diff --git a/tests/TestCase/SpyConsoleOutput.php b/tests/TestCase/SpyConsoleOutput.php new file mode 100644 index 0000000..c0e5ad6 --- /dev/null +++ b/tests/TestCase/SpyConsoleOutput.php @@ -0,0 +1,49 @@ +stderr = new BufferedOutput(); + } + + public function getErrorOutput(): OutputInterface + { + return $this->stderr; + } + + public function setErrorOutput(OutputInterface $error): void + { + // Not needed for tests. + } + + public function section(): ConsoleSectionOutput + { + throw new \BadMethodCallException('section() is not supported by the test double.'); + } + + /** Return everything written to the error (stderr) stream. */ + public function fetchErrorOutput(): string + { + return $this->stderr + ->fetch(); + } +} diff --git a/tests/Unit/EventRunnerTest.php b/tests/Unit/EventRunnerTest.php index a955208..ae9cd63 100644 --- a/tests/Unit/EventRunnerTest.php +++ b/tests/Unit/EventRunnerTest.php @@ -12,7 +12,9 @@ use Crunz\Mailer; use Crunz\Schedule; use Crunz\Tests\TestCase\FakeConfiguration; +use Crunz\Tests\TestCase\SpyConsoleOutput; use PHPUnit\Framework\TestCase; +use Symfony\Component\Console\Output\BufferedOutput; use Symfony\Component\Console\Output\OutputInterface; use Symfony\Component\Lock\BlockingStoreInterface; use Symfony\Component\Lock\StoreInterface; @@ -49,6 +51,229 @@ public function url_is_pinged_after(): void $eventRunner->handle($output, [$schedule]); } + public function test_realtime_output_is_streamed_raw_and_once(): void + { + // Output contains a Symfony style tag. The realtime path writes raw, so + // the tag survives verbatim; the end-of-job display() path runs through + // the output formatter, which would strip the tag. Asserting the literal + // tag survives proves the realtime path produced the output. + $taskOutput = 'RUNNER_REALTIME_MARKER'; + $command = "php -r \"echo '{$taskOutput}';\""; + + $schedule = new Schedule(); + $schedule->run($command) + ->everyMinute() + ; + + $output = new BufferedOutput(); + $eventRunner = $this->createEventRunner( + realInvoker: true, + configuration: new FakeConfiguration(['output_realtime' => true]), + ); + + $eventRunner->handle($output, [$schedule]); + + $captured = $output->fetch(); + + // Streamed verbatim (raw), not formatter-stripped. + self::assertStringContainsString($taskOutput, $captured); + // Exactly once: the realtime stream replaces the end-of-job console + // emission, so display() must not also write the same output. + self::assertSame( + 1, + \mb_substr_count($captured, 'RUNNER_REALTIME_MARKER'), + 'Realtime output must not be duplicated by the end-of-job emission.' + ); + } + + public function test_output_is_not_streamed_raw_when_realtime_disabled(): void + { + $taskOutput = 'RUNNER_BUFFERED_MARKER'; + $command = "php -r \"echo '{$taskOutput}';\""; + + $schedule = new Schedule(); + $schedule->run($command) + ->everyMinute() + ; + + $output = new BufferedOutput(); + $eventRunner = $this->createEventRunner( + realInvoker: true, + configuration: new FakeConfiguration(['output_realtime' => false]), + ); + + $eventRunner->handle($output, [$schedule]); + + $captured = $output->fetch(); + + // With realtime off, output still reaches the console once, via the + // existing end-of-job display() path (which strips the style tag). + self::assertStringContainsString('RUNNER_BUFFERED_MARKER', $captured); + self::assertStringNotContainsString($taskOutput, $captured); + self::assertSame(1, \mb_substr_count($captured, 'RUNNER_BUFFERED_MARKER')); + } + + public function test_realtime_output_streams_to_global_log_file(): void + { + // With log_output enabled, realtime streams the raw output to the global + // output_log_file as it is produced (replacing the end-of-job framed + // record), so a file target is written live, not dropped. + $logFile = \tempnam(\sys_get_temp_dir(), 'crunz_rt_global_'); + self::assertIsString($logFile); + + try { + $command = "php -r \"echo 'GLOBAL_FILE_OUTPUT';\""; + + $schedule = new Schedule(); + $schedule->run($command) + ->everyMinute() + ; + + $eventRunner = $this->createEventRunner( + realInvoker: true, + configuration: new FakeConfiguration( + [ + 'output_realtime' => true, + 'log_output' => true, + 'output_log_file' => $logFile, + ] + ), + ); + + $eventRunner->handle(new BufferedOutput(), [$schedule]); + + $contents = (string) \file_get_contents($logFile); + self::assertStringContainsString('GLOBAL_FILE_OUTPUT', $contents); + // Streamed raw, not as the framed end-of-job log record. + self::assertStringNotContainsString('crunz.INFO', $contents); + } finally { + @\unlink($logFile); + } + } + + public function test_realtime_output_streams_to_per_event_log_file(): void + { + // A task with sendOutputTo()/appendOutputTo() streams its raw output to + // that dedicated file as it is produced. + $logFile = \tempnam(\sys_get_temp_dir(), 'crunz_rt_per_event_'); + self::assertIsString($logFile); + + try { + $command = "php -r \"echo 'PER_EVENT_FILE_OUTPUT';\""; + + $schedule = new Schedule(); + $schedule->run($command) + ->everyMinute() + ->appendOutputTo($logFile) + ; + + $eventRunner = $this->createEventRunner( + realInvoker: true, + configuration: new FakeConfiguration(['output_realtime' => true]), + ); + + $eventRunner->handle(new BufferedOutput(), [$schedule]); + + $contents = (string) \file_get_contents($logFile); + self::assertStringContainsString('PER_EVENT_FILE_OUTPUT', $contents); + self::assertStringNotContainsString('crunz.INFO', $contents); + } finally { + @\unlink($logFile); + } + } + + public function test_realtime_output_still_sends_email(): void + { + $command = "php -r \"echo 'MAIL_BODY';\""; + + $schedule = new Schedule(); + $schedule->run($command) + ->everyMinute() + ; + + $mailer = $this->createMock(Mailer::class); + $mailer->expects(self::once()) + ->method('send') + ; + + $eventRunner = new EventRunner( + new Invoker(), + new FakeConfiguration( + [ + 'output_realtime' => true, + 'email_output' => true, + ] + ), + $mailer, + $this->createMock(LoggerFactory::class), + $this->createMock(HttpClientInterface::class), + $this->createMock(ConsoleLoggerInterface::class) + ); + + $eventRunner->handle(new BufferedOutput(), [$schedule]); + } + + public function test_realtime_routes_stderr_to_error_stream(): void + { + // With a real console output, stdout chunks go to the main stream and + // stderr chunks to the error stream. + $command = "php -r \"echo 'OUTCHUNK'; fwrite(STDERR, 'ERRCHUNK');\""; + + $schedule = new Schedule(); + $schedule->run($command) + ->everyMinute() + ; + + $output = new SpyConsoleOutput(); + $eventRunner = $this->createEventRunner( + realInvoker: true, + configuration: new FakeConfiguration(['output_realtime' => true]), + ); + + $eventRunner->handle($output, [$schedule]); + + $stdout = $output->fetch(); + $stderr = $output->fetchErrorOutput(); + + self::assertStringContainsString('OUTCHUNK', $stdout); + self::assertStringNotContainsString('ERRCHUNK', $stdout); + self::assertStringContainsString('ERRCHUNK', $stderr); + } + + public function test_realtime_output_does_not_duplicate_failed_task_output(): void + { + // A failing task streams its output live; handleError must NOT also write + // the blob in realtime mode, otherwise the output appears twice. + $command = "php -r \"fwrite(STDERR, 'BOOM'); exit(1);\""; + + $schedule = new Schedule(); + $schedule->run($command) + ->everyMinute() + ; + + $output = new BufferedOutput(); + $eventRunner = $this->createEventRunner( + realInvoker: true, + configuration: new FakeConfiguration( + [ + 'output_realtime' => true, + 'log_errors' => false, + ] + ), + ); + + $eventRunner->handle($output, [$schedule]); + + $captured = $output->fetch(); + + self::assertStringContainsString('BOOM', $captured); + self::assertSame( + 1, + \mb_substr_count($captured, 'BOOM'), + 'Failed task output must not be duplicated by handleError in realtime mode.' + ); + } + public function test_event_logging_configuration(): void { $logTarget = 'event.log'; @@ -130,8 +355,10 @@ private function createEventRunnerForPing($url) ); } - private function createEventRunner(bool $realInvoker = false): EventRunner - { + private function createEventRunner( + bool $realInvoker = false, + ?FakeConfiguration $configuration = null, + ): EventRunner { $invoker = true === $realInvoker ? new Invoker() : $this->createMock(Invoker::class) @@ -143,7 +370,7 @@ private function createEventRunner(bool $realInvoker = false): EventRunner return new EventRunner( $invoker, - new FakeConfiguration(), + $configuration ?? new FakeConfiguration(), $mailer, $loggerFactory, $httpClient, diff --git a/tests/Unit/EventTest.php b/tests/Unit/EventTest.php index 2144e5d..eb72b04 100644 --- a/tests/Unit/EventTest.php +++ b/tests/Unit/EventTest.php @@ -402,6 +402,32 @@ public function whole_output_catches_stdout_and_stderr(): void ); } + /** @test */ + public function realtime_callback_receives_output_as_it_is_produced(): void + { + $command = "php -r \"echo 'Realtime output';\""; + $event = new Event(\uniqid('c', true), $command); + + $collected = ''; + $event->setRealtimeCallback( + static function (string $type, string $content) use (&$collected): void { + $collected .= $content; + } + ); + + $event->start(); + $process = $event->getProcess(); + + while ($process->isRunning()) { + \usleep(20000); // wait 20 ms + } + + self::assertStringContainsString('Realtime output', $collected); + // The callback must observe exactly the same bytes that populate the + // in-memory buffer, so streaming and buffering never diverge. + self::assertSame($event->wholeOutput(), $collected); + } + /** @test */ public function task_will_prevent_overlapping_with_default_store(): void { diff --git a/tests/resources/tasks/RealtimeFileOutputTasks.php b/tests/resources/tasks/RealtimeFileOutputTasks.php new file mode 100644 index 0000000..1a11a30 --- /dev/null +++ b/tests/resources/tasks/RealtimeFileOutputTasks.php @@ -0,0 +1,28 @@ +run( + static function (): void { + // Emit the first marker and flush it, then sleep before emitting the + // second. With realtime output the chunks are written to the log file + // as they are produced, so the first marker reaches the file before + // the task finishes. + echo 'FILE_FIRST' . PHP_EOL; + \flush(); + + \sleep(3); + + echo 'FILE_SECOND' . PHP_EOL; + } + ) + ->description('Realtime file streaming task') + ->everyMinute() + ->appendOutputTo('realtime.log') +; + +return $scheduler; diff --git a/tests/resources/tasks/RealtimeOutputTasks.php b/tests/resources/tasks/RealtimeOutputTasks.php new file mode 100644 index 0000000..3387841 --- /dev/null +++ b/tests/resources/tasks/RealtimeOutputTasks.php @@ -0,0 +1,27 @@ +run( + static function (): void { + // Emit the first marker and flush it immediately, then sleep before + // emitting the second marker. This creates a window during which the + // first marker has been produced but the task has not yet finished, + // letting the test observe whether output is streamed in realtime. + echo 'REALTIME_FIRST' . PHP_EOL; + \flush(); + + \sleep(3); + + echo 'REALTIME_SECOND' . PHP_EOL; + } + ) + ->description('Realtime streaming task') + ->everyMinute() +; + +return $scheduler;