Maintenance mode

Author: mabar

CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased](https://github.com/orisai/scheduler/compare/2.2.2...v2.x)
 
+### Added
+
+- Maintenance mode - stop running jobs during deployments
+	- `MaintenanceChecker` interface - implement to define when maintenance is active
+	- `MaintenanceManager` - orchestrates maintenance checking, run tracking, status reporting and shutdown requests
+	- `MaintenanceManager->requestShutdown()` - programmatic shutdown trigger (used by signal handlers)
+	- `RunRegistry` interface with `FileRunRegistry` (single-server) and `LockPoolRunRegistry` (multi-server)
+	  implementations - tracks active `scheduler:run` processes
+	- `MaintenanceStatus` - value object returned by `MaintenanceManager->getStatus()`
+	- `ShutdownCheck` - value object carrying shutdown check and grace period for executors
+	- `StatusCommand` (`scheduler:status`) - reports maintenance state and active runs
+- `ManagedScheduler`
+	- accepts optional `MaintenanceManager` - enables maintenance mode with two-phase shutdown
+	  (graceful wait, then force-kill after configurable grace period)
+	- `getMaintenanceManager()`
+- `RunCommand`
+	- accepts optional `MaintenanceManager` - registers signal handlers for graceful shutdown
+	- handles `SIGTERM` and `SIGINT` signals (requires `pcntl` extension, double-signal forces exit)
+	- returns exit code `2` when run was stopped due to maintenance
+- `WorkerCommand`
+	- handles `SIGTERM` and `SIGINT` signals for graceful stop (requires `pcntl` extension, double-signal forces exit)
+- `JobResultState::maintenance()` - for jobs skipped or terminated due to maintenance
+- `RunSummary->isMaintenanceActive()` - indicates whether run was affected by maintenance
+
+### Changed
+
+- `JobExecutor` (BC break)
+	- `runJobs()` accepts optional `?ShutdownCheck $shutdownCheck` parameter
+	- added `supportsJobShutdown(): bool` method
+- `RunSummary`
+	- constructor accepts optional `bool $maintenanceActive` parameter
+
 ## [2.2.2](https://github.com/orisai/scheduler/compare/2.2.1...2.2.2) - 2026-02-12
 
 ### Fixed

docs/README.md

@@ -33,6 +33,13 @@ Cron job scheduler - with locks, parallelism and more
 	- [List command - show all jobs](#list-command)
 	- [Worker command - run jobs periodically](#worker-command)
 	- [Explain command - explain cron expression syntax](#explain-command)
+- [Maintenance mode](#maintenance-mode)
+	- [Setup](#maintenance-setup)
+	- [Run tracking](#run-tracking)
+	- [Status command](#status-command)
+	- [Signal handling](#signal-handling)
+	- [Deploy integration](#deploy-integration)
+	- [Exit codes](#exit-codes)
 - [Lazy loading](#lazy-loading)
 - [Integrations and extensions](#integrations-and-extensions)
 - [Troubleshooting guide](#troubleshooting-guide)
@@ -812,6 +819,160 @@ Options:
 - `--timezone=<timezone>` (or `-tz`) - the timezone time should be displayed in
 - `--locale=<locale>` (or `-l`) - explain in specified locale
 
+## Maintenance mode
+
+During deployments, you typically want to stop running cron jobs to prevent interference. The scheduler supports
+a two-phase shutdown: first it waits for running jobs to finish naturally (graceful), then force-kills any remaining
+processes after a configurable grace period.
+
+Maintenance mode requires `ProcessJobExecutor`. `BasicJobExecutor` cannot terminate running jobs and will throw
+a `LogicException` if used with `MaintenanceManager`.
+
+### Maintenance setup
+
+Create a `MaintenanceChecker` implementation for your environment. The interface has a single method:
+
+```php
+use Orisai\Scheduler\Maintenance\MaintenanceChecker;
+
+class AppMaintenanceChecker implements MaintenanceChecker
+{
+
+    public function isMaintenance(): bool
+    {
+        // Check your app's maintenance flag (file, Redis, database, etc.)
+        return file_exists(__DIR__ . '/../../maintenance.running');
+    }
+
+}
+```
+
+Set up the scheduler with `MaintenanceManager`. Pass the manager to both the scheduler and the run command:
+
+```php
+use Orisai\Scheduler\Command\RunCommand;
+use Orisai\Scheduler\Executor\ProcessJobExecutor;
+use Orisai\Scheduler\Maintenance\FileRunRegistry;
+use Orisai\Scheduler\Maintenance\MaintenanceManager;
+use Orisai\Scheduler\SimpleScheduler;
+
+$checker = new AppMaintenanceChecker();
+$registry = new FileRunRegistry(__DIR__ . '/var/scheduler-runs');
+$manager = new MaintenanceManager($checker, $registry);
+
+$executor = new ProcessJobExecutor();
+
+$scheduler = new SimpleScheduler(
+    null,      // errorHandler
+    null,      // lockFactory
+    $executor,
+    null,      // clock
+    null,      // logger
+    $manager,
+);
+
+$runCommand = new RunCommand($scheduler, null, $manager);
+```
+
+The grace period (time before force-kill) defaults to 30 seconds. This matches the Kubernetes
+`terminationGracePeriodSeconds` default - long enough for most jobs to finish DB transactions, API calls
+and file operations, short enough to not block deploys excessively.
+
+```php
+$manager = new MaintenanceManager($checker, $registry, 60); // 60 second grace period
+```
+
+### Run tracking
+
+`RunRegistry` tracks active `scheduler:run` processes so deploy scripts can check if it's safe to proceed.
+Two implementations are provided:
+
+**FileRunRegistry** (default, single-server):
+
+```php
+use Orisai\Scheduler\Maintenance\FileRunRegistry;
+
+$registry = new FileRunRegistry(__DIR__ . '/var/scheduler-runs');
+```
+
+Writes a file per active run. Automatically cleans up stale entries older than 1 hour from crashed processes.
+
+**LockPoolRunRegistry** (multi-server):
+
+```php
+use Orisai\Scheduler\Maintenance\LockPoolRunRegistry;
+use Symfony\Component\Lock\LockFactory;
+
+$registry = new LockPoolRunRegistry($lockFactory, 10); // pool of 10 slots
+```
+
+Uses `symfony/lock` with a fixed pool of lock keys. Works with any lock store (Redis, database, etc.).
+If all pool slots are taken, throws `LogicException` - increase the pool size.
+
+### Status command
+
+Check maintenance state and active runs:
+
+```bash
+php bin/console scheduler:status
+```
+
+Output:
+
+```
+Maintenance: ACTIVE
+Active runs: 2
+  - 1712345678-a3f2b1 (started 15s ago)
+  - 1712345679-d4e5c2 (started 3s ago)
+Ready for shutdown: NO
+```
+
+Also available programmatically:
+
+```php
+$status = $manager->getStatus();
+$status->isMaintenance();      // bool
+$status->getActiveRunIds();    // list<string>
+$status->isReadyForShutdown(); // true when maintenance active AND no active runs
+```
+
+### Signal handling
+
+`RunCommand` and `WorkerCommand` handle `SIGTERM` and `SIGINT` signals using Symfony's `SignalRegistry`:
+
+- **RunCommand**: first signal triggers graceful shutdown (same as maintenance mode), second signal forces immediate exit
+- **WorkerCommand**: first signal stops spawning new `scheduler:run` processes and waits for current ones to finish, second signal forces immediate exit
+
+Signal handling in `RunCommand` requires `MaintenanceManager` to be passed to the command constructor.
+`WorkerCommand` always registers signal handlers when run through a Symfony `Application`.
+
+Signal handling requires the `pcntl` extension (available on Linux/macOS CLI, not on Windows).
+When pcntl is not available, signals are silently skipped - the `MaintenanceChecker` polling approach still works.
+
+### Deploy integration
+
+Typical deploy flow:
+
+1. Enable maintenance (create your maintenance flag)
+2. Poll `scheduler:status --fail-when-not-ready` until ready (exits with `0` when ready, `1` when not):
+
+```bash
+while ! php bin/console scheduler:status --fail-when-not-ready; do
+    sleep 1
+done
+```
+
+3. Deploy the application
+4. Disable maintenance (remove your maintenance flag)
+
+### Exit codes
+
+The `scheduler:run` command returns:
+
+- `0` - all jobs completed successfully
+- `1` - one or more jobs failed
+- `2` - maintenance shutdown (run was stopped due to maintenance)
+
 ## Lazy loading
 
 Jobs are executed only when it is their due time. To prevent initializing potentially heavy job dependencies when they

src/Command/BaseRunCommand.php

@@ -61,6 +61,10 @@ protected function renderJob(JobSummary $summary, int $terminalWidth, OutputInte
 			case JobResultState::lock():
 				$status = "<fg=yellow>$stateName</>";
 
+				break;
+			case JobResultState::maintenance():
+				$status = "<fg=yellow>$stateName</>";
+
 				break;
 		}
 

src/Command/RunCommand.php

@@ -4,6 +4,7 @@
 
 use Generator;
 use Orisai\Clock\SystemClock;
+use Orisai\Scheduler\Maintenance\MaintenanceManager;
 use Orisai\Scheduler\Scheduler;
 use Orisai\Scheduler\Status\JobResultState;
 use Orisai\Scheduler\Status\JobSummary;
@@ -12,19 +13,33 @@
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\SignalRegistry\SignalRegistry;
+use function assert;
 use function json_encode;
+use function method_exists;
 use const JSON_PRETTY_PRINT;
 use const JSON_THROW_ON_ERROR;
+use const SIGINT;
+use const SIGTERM;
 
 final class RunCommand extends BaseRunCommand
 {
 
+	private const EXIT_MAINTENANCE = 2;
+
 	private Scheduler $scheduler;
 
-	public function __construct(Scheduler $scheduler, ?ClockInterface $clock = null)
+	private ?MaintenanceManager $maintenanceManager;
+
+	public function __construct(
+		Scheduler $scheduler,
+		?ClockInterface $clock = null,
+		?MaintenanceManager $maintenanceManager = null
+	)
 	{
 		parent::__construct($clock ?? new SystemClock());
 		$this->scheduler = $scheduler;
+		$this->maintenanceManager = $maintenanceManager;
 	}
 
 	public static function getDefaultName(): string
@@ -44,13 +59,65 @@ protected function configure(): void
 
 	protected function execute(InputInterface $input, OutputInterface $output): int
 	{
-		$summary = $this->scheduler->runPromise();
+		$signalRegistry = $this->registerSignalHandlers();
+
+		try {
+			$generator = $this->scheduler->runPromise();
+
+			$success = $input->getOption('json')
+				? $this->renderJobsAsJson($output, $generator)
+				: $this->renderJobs($output, $generator);
+
+			$runSummary = $generator->getReturn();
+			assert($runSummary instanceof RunSummary);
+			if ($runSummary->isMaintenanceActive()) {
+				return self::EXIT_MAINTENANCE;
+			}
+
+			return $success ? self::SUCCESS : self::FAILURE;
+		} finally {
+			if ($signalRegistry !== null && method_exists($signalRegistry, 'popPreviousHandlers')) {
+				$signalRegistry->popPreviousHandlers();
+			}
+		}
+	}
+
+	private function registerSignalHandlers(): ?SignalRegistry
+	{
+		if ($this->maintenanceManager === null) {
+			return null;
+		}
+
+		if (!SignalRegistry::isSupported()) {
+			return null;
+		}
+
+		$application = $this->getApplication();
+		if ($application === null) {
+			return null;
+		}
+
+		$registry = $application->getSignalRegistry();
+		if (method_exists($registry, 'pushCurrentHandlers')) {
+			$registry->pushCurrentHandlers();
+		}
+
+		$maintenanceManager = $this->maintenanceManager;
+		$shutdownRequested = false;
+		$handler = static function () use ($maintenanceManager, &$shutdownRequested): void {
+			if ($shutdownRequested) {
+				// Second signal - force exit, tested via real subprocess in SignalHandlingTest
+				exit(1); // @codeCoverageIgnore
+			}
+
+			$shutdownRequested = true;
+			$maintenanceManager->requestShutdown();
+		};
 
-		$success = $input->getOption('json')
-			? $this->renderJobsAsJson($output, $summary)
-			: $this->renderJobs($output, $summary);
+		$registry->register(SIGTERM, $handler);
+		$registry->register(SIGINT, $handler);
 
-		return $success ? self::SUCCESS : self::FAILURE;
+		return $registry;
 	}
 
 	/**