[stable34] Background jobs improvements

core/Command/Background/RunningJobs.php

@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OC\Core\Command\Background;
+
+use OC\BackgroundJob\JobRuns;
+use OC\Core\Command\Base;
+use OCP\IConfig;
+use Override;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+final class RunningJobs extends Base {
+	public function __construct(
+		private readonly JobRuns $jobRuns,
+		private IConfig $config,
+	) {
+		parent::__construct();
+	}
+
+	#[Override]
+	protected function configure(): void {
+		parent::configure();
+
+		$help = <<<EOF
+			Display all currently running background jobs.
+
+			You can find the following informations:
+			  - <info>Run ID:</info> job identifier a found in database (Snowflake ID)
+			  - <info>Class:</info> class of the job
+			  - <info>Started at:</info> start time of the job
+			  - <info>Server ID:</info> server ID as defined in <options=bold>config.php</> (see `serverid`). Highlighted if it’s running on current server.
+			  - <info>PID:</info> PID of process executing the job
+			  - <info>Running since:</info> human readable elapsed time since job started
+
+			EOF;
+
+		$this
+			->setName('background-job:running')
+			->setDescription('Show currently running jobs')
+			->setHelp($help)
+			->addOption('limit', 'l', InputOption::VALUE_REQUIRED, 'Maximum number of results returned by the command', 200);
+	}
+
+	#[Override]
+	protected function execute(InputInterface $input, OutputInterface $output): int {
+		$limit = (int)$input->getOption('limit');
+		$jobs = $this->jobRuns->runningJobs($limit);
+		$this->writeStreamingTableInOutputFormat($input, $output, $this->formatLine($jobs), 20);
+
+		return Base::SUCCESS;
+	}
+
+	private function formatLine(iterable $jobs): \Generator {
+		$now = time();
+		$currentServerId = $this->config->getSystemValueInt('serverid', -1);
+		foreach ($jobs as $job) {
+			yield [
+				'Run ID' => $job->runId,
+				'Class' => $job->className,
+				'Started at' => $job->startedAt->format('Y-m-d H:i:s'),
+				'Server ID' => $job->serverId === $currentServerId ? '<info>' . $job->serverId . '</info>' : $job->serverId,
+				'PID' => $job->pid,
+				'Running since' => $this->formatDuration($now - $job->startedAt->format('U')),
+			];
+		}
+	}
+
+	/**
+	 * TODO Move this function to utils class with better formatting (plural, i18n…)
+	 */
+	private function formatDuration(int $seconds): string {
+		if ($seconds < 60) {
+			return sprintf('%d seconds', $seconds);
+		}
+		if ($seconds < 3600) {
+			return sprintf('%d minutes', $seconds / 60);
+		}
+		if ($seconds < (3600 * 24)) {
+			return sprintf('> %d hours', $seconds / 3600);
+		}
+
+		return sprintf('> %d days', $seconds / (3600 * 24));
+	}
+}

core/Migrations/Version34000Date20260518163022.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OC\Core\Migrations;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\Migration\Attributes\AddIndex;
+use OCP\Migration\Attributes\CreateTable;
+use OCP\Migration\Attributes\IndexType;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+use Override;
+
+#[CreateTable(table: 'job_classes_registry', columns: ['class_id', 'class_name'], description: 'New table to map job class name to an ID')]
+#[AddIndex(table: 'job_classes_registry', type: IndexType::PRIMARY)]
+#[AddIndex(table: 'job_classes_registry', type: IndexType::UNIQUE, description: 'Ensure each class is registered only once')]
+class Version34000Date20260518163022 extends SimpleMigrationStep {
+	#[Override]
+	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
+		/** @var ISchemaWrapper $schema */
+		$schema = $schemaClosure();
+
+		if (!$schema->hasTable('job_classes_registry')) {
+			$table = $schema->createTable('job_classes_registry');
+			$table->addColumn('class_id', Types::BIGINT, [
+				'autoincrement' => true,
+				'notnull' => true,
+				'unsigned' => true,
+			]);
+			$table->addColumn('class_name', Types::STRING, ['notnull' => true, 'length' => 255]);
+			$table->setPrimaryKey(['class_id']);
+			$table->addUniqueConstraint(['class_name'], 'class_index');
+
+			return $schema;
+		}
+
+		return null;
+	}
+}

core/Migrations/Version34000Date20260521110333.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OC\Core\Migrations;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\Migration\Attributes\AddIndex;
+use OCP\Migration\Attributes\CreateTable;
+use OCP\Migration\Attributes\IndexType;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+use Override;
+
+#[CreateTable(
+	table: 'job_runs',
+	columns: ['class_id', 'pid', 'status', 'duration', 'ram_peak_usage'],
+	description: 'New table to store executions of background jobs',
+)]
+#[AddIndex(table: 'job_runs', type: IndexType::PRIMARY)]
+#[AddIndex(table: 'job_runs', type: IndexType::INDEX, description: 'Allows to search on job status')]
+class Version34000Date20260521110333 extends SimpleMigrationStep {
+	#[Override]
+	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
+		/** @var ISchemaWrapper $schema */
+		$schema = $schemaClosure();
+
+		if (!$schema->hasTable('job_runs')) {
+			$table = $schema->createTable('job_runs');
+			$table->addColumn('run_id', Types::BIGINT, [
+				'notnull' => true,
+				'unsigned' => true,
+			]);
+			$table->addColumn('class_id', Types::BIGINT, ['notnull' => true]);
+			$table->addColumn('pid', Types::INTEGER, ['notnull' => true]); // Should be MEDIUMINT
+			$table->addColumn('status', Types::SMALLINT, ['notnull' => true]); // Should be TINYINT
+			$table->addColumn('duration', Types::INTEGER, ['notnull' => true, 'default' => 0]);
+			$table->addColumn('ram_peak_usage', Types::INTEGER, ['notnull' => true, 'default' => 0]); // Should be MEDIUMINT
+			$table->setPrimaryKey(['run_id']);
+			$table->addIndex(['status'], 'status');
+
+			return $schema;
+		}
+
+		return null;
+	}
+}

core/Service/CronService.php

@@ -13,6 +13,8 @@
 
 use OC;
 use OC\Authentication\LoginCredentials\Store;
+use OC\BackgroundJob\JobClassesRegistry;
+use OC\BackgroundJob\JobRuns;
 use OC\DB\Connection;
 use OC\Security\CSRF\TokenStorage\SessionStorage;
 use OC\Session\CryptoWrapper;
@@ -49,6 +51,8 @@ public function __construct(
 		private readonly ITempManager $tempManager,
 		private readonly IAppConfig $appConfig,
 		private readonly IJobList $jobList,
+		private readonly JobRuns $jobRuns,
+		private readonly JobClassesRegistry $jobClassesRegistry,
 		private readonly ISetupManager $setupManager,
 		private readonly bool $isCLI,
 	) {
@@ -185,20 +189,27 @@ private function runCli(string $appMode, ?array $jobClasses): void {
 				break;
 			}
 
-			$jobDetails = get_class($job) . ' (id: ' . $job->getId() . ', arguments: ' . json_encode($job->getArgument()) . ')';
+			$jobClass = get_class($job);
+			$jobDetails = $jobClass . ' (id: ' . $job->getId() . ', arguments: ' . json_encode($job->getArgument()) . ')';
 			$this->logger->debug('CLI cron call has selected job ' . $jobDetails, ['app' => 'cron']);
 
 			$this->verboseOutput('Starting job ' . $jobDetails);
 
-			$startTime = microtime(true);
 			$referenceMemory = memory_get_usage();
 			memory_reset_peak_usage();
 
+			$jobClassId = $this->jobClassesRegistry->getId($jobClass);
+			$jobRunId = $this->jobRuns->started($jobClassId);
+			$startTime = microtime(true);
 			$job->start($this->jobList);
 
 			$memoryIncrease = memory_get_usage() - $referenceMemory;
 			$timeSpent = microtime(true) - $startTime;
-			$jobMemoryPeak = memory_get_peak_usage() - $referenceMemory;
+			$jobMemoryPeak = memory_get_peak_usage();
+			// TODO Job failure will never be caught here because exceptions are caught within $job->start method
+			// The error will only be visible in server logs.
+			// It should be a temporary state until a proper job runner is implemented.
+			$this->jobRuns->finished($jobRunId, (int)($timeSpent * 1000), (int)($jobMemoryPeak / 1024));
 
 			$cronInterval = 5 * 60;
 			if ($timeSpent > $cronInterval) {

core/register_command.php

@@ -20,6 +20,7 @@
 use OC\Core\Command\Background\JobWorker;
 use OC\Core\Command\Background\ListCommand;
 use OC\Core\Command\Background\Mode;
+use OC\Core\Command\Background\RunningJobs;
 use OC\Core\Command\Broadcast\Test;
 use OC\Core\Command\Check;
 use OC\Core\Command\Config\App\DeleteConfig;
@@ -144,6 +145,7 @@
 	$application->add(Server::get(ListCommand::class));
 	$application->add(Server::get(Delete::class));
 	$application->add(Server::get(JobWorker::class));
+	$application->add(Server::get(RunningJobs::class));
 
 	$application->add(Server::get(Test::class));
 

lib/composer/composer/autoload_classmap.php

@@ -200,8 +200,11 @@
     'OCP\\AutoloadNotAllowedException' => $baseDir . '/lib/public/AutoloadNotAllowedException.php',
     'OCP\\BackgroundJob\\IJob' => $baseDir . '/lib/public/BackgroundJob/IJob.php',
     'OCP\\BackgroundJob\\IJobList' => $baseDir . '/lib/public/BackgroundJob/IJobList.php',
+    'OCP\\BackgroundJob\\IJobRuns' => $baseDir . '/lib/public/BackgroundJob/IJobRuns.php',
     'OCP\\BackgroundJob\\IParallelAwareJob' => $baseDir . '/lib/public/BackgroundJob/IParallelAwareJob.php',
     'OCP\\BackgroundJob\\Job' => $baseDir . '/lib/public/BackgroundJob/Job.php',
+    'OCP\\BackgroundJob\\JobRun' => $baseDir . '/lib/public/BackgroundJob/JobRun.php',
+    'OCP\\BackgroundJob\\JobStatus' => $baseDir . '/lib/public/BackgroundJob/JobStatus.php',
     'OCP\\BackgroundJob\\QueuedJob' => $baseDir . '/lib/public/BackgroundJob/QueuedJob.php',
     'OCP\\BackgroundJob\\TimedJob' => $baseDir . '/lib/public/BackgroundJob/TimedJob.php',
     'OCP\\BeforeSabrePubliclyLoadedEvent' => $baseDir . '/lib/public/BeforeSabrePubliclyLoadedEvent.php',
@@ -1250,7 +1253,9 @@
     'OC\\Avatar\\GuestAvatar' => $baseDir . '/lib/private/Avatar/GuestAvatar.php',
     'OC\\Avatar\\PlaceholderAvatar' => $baseDir . '/lib/private/Avatar/PlaceholderAvatar.php',
     'OC\\Avatar\\UserAvatar' => $baseDir . '/lib/private/Avatar/UserAvatar.php',
+    'OC\\BackgroundJob\\JobClassesRegistry' => $baseDir . '/lib/private/BackgroundJob/JobClassesRegistry.php',
     'OC\\BackgroundJob\\JobList' => $baseDir . '/lib/private/BackgroundJob/JobList.php',
+    'OC\\BackgroundJob\\JobRuns' => $baseDir . '/lib/private/BackgroundJob/JobRuns.php',
     'OC\\BinaryFinder' => $baseDir . '/lib/private/BinaryFinder.php',
     'OC\\Blurhash\\Listener\\GenerateBlurhashMetadata' => $baseDir . '/lib/private/Blurhash/Listener/GenerateBlurhashMetadata.php',
     'OC\\Broadcast\\Events\\BroadcastEvent' => $baseDir . '/lib/private/Broadcast/Events/BroadcastEvent.php',
@@ -1333,6 +1338,7 @@
     'OC\\Core\\Command\\Background\\JobWorker' => $baseDir . '/core/Command/Background/JobWorker.php',
     'OC\\Core\\Command\\Background\\ListCommand' => $baseDir . '/core/Command/Background/ListCommand.php',
     'OC\\Core\\Command\\Background\\Mode' => $baseDir . '/core/Command/Background/Mode.php',
+    'OC\\Core\\Command\\Background\\RunningJobs' => $baseDir . '/core/Command/Background/RunningJobs.php',
     'OC\\Core\\Command\\Base' => $baseDir . '/core/Command/Base.php',
     'OC\\Core\\Command\\Broadcast\\Test' => $baseDir . '/core/Command/Broadcast/Test.php',
     'OC\\Core\\Command\\Check' => $baseDir . '/core/Command/Check.php',
@@ -1607,6 +1613,8 @@
     'OC\\Core\\Migrations\\Version33000Date20260126120000' => $baseDir . '/core/Migrations/Version33000Date20260126120000.php',
     'OC\\Core\\Migrations\\Version34000Date20260318095645' => $baseDir . '/core/Migrations/Version34000Date20260318095645.php',
     'OC\\Core\\Migrations\\Version34000Date20260415161745' => $baseDir . '/core/Migrations/Version34000Date20260415161745.php',
+    'OC\\Core\\Migrations\\Version34000Date20260518163022' => $baseDir . '/core/Migrations/Version34000Date20260518163022.php',
+    'OC\\Core\\Migrations\\Version34000Date20260521110333' => $baseDir . '/core/Migrations/Version34000Date20260521110333.php',
     'OC\\Core\\Notification\\CoreNotifier' => $baseDir . '/core/Notification/CoreNotifier.php',
     'OC\\Core\\ResponseDefinitions' => $baseDir . '/core/ResponseDefinitions.php',
     'OC\\Core\\Service\\CronService' => $baseDir . '/core/Service/CronService.php',

lib/composer/composer/autoload_static.php

@@ -241,8 +241,11 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\AutoloadNotAllowedException' => __DIR__ . '/../../..' . '/lib/public/AutoloadNotAllowedException.php',
         'OCP\\BackgroundJob\\IJob' => __DIR__ . '/../../..' . '/lib/public/BackgroundJob/IJob.php',
         'OCP\\BackgroundJob\\IJobList' => __DIR__ . '/../../..' . '/lib/public/BackgroundJob/IJobList.php',
+        'OCP\\BackgroundJob\\IJobRuns' => __DIR__ . '/../../..' . '/lib/public/BackgroundJob/IJobRuns.php',
         'OCP\\BackgroundJob\\IParallelAwareJob' => __DIR__ . '/../../..' . '/lib/public/BackgroundJob/IParallelAwareJob.php',
         'OCP\\BackgroundJob\\Job' => __DIR__ . '/../../..' . '/lib/public/BackgroundJob/Job.php',
+        'OCP\\BackgroundJob\\JobRun' => __DIR__ . '/../../..' . '/lib/public/BackgroundJob/JobRun.php',
+        'OCP\\BackgroundJob\\JobStatus' => __DIR__ . '/../../..' . '/lib/public/BackgroundJob/JobStatus.php',
         'OCP\\BackgroundJob\\QueuedJob' => __DIR__ . '/../../..' . '/lib/public/BackgroundJob/QueuedJob.php',
         'OCP\\BackgroundJob\\TimedJob' => __DIR__ . '/../../..' . '/lib/public/BackgroundJob/TimedJob.php',
         'OCP\\BeforeSabrePubliclyLoadedEvent' => __DIR__ . '/../../..' . '/lib/public/BeforeSabrePubliclyLoadedEvent.php',
@@ -1291,7 +1294,9 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OC\\Avatar\\GuestAvatar' => __DIR__ . '/../../..' . '/lib/private/Avatar/GuestAvatar.php',
         'OC\\Avatar\\PlaceholderAvatar' => __DIR__ . '/../../..' . '/lib/private/Avatar/PlaceholderAvatar.php',
         'OC\\Avatar\\UserAvatar' => __DIR__ . '/../../..' . '/lib/private/Avatar/UserAvatar.php',
+        'OC\\BackgroundJob\\JobClassesRegistry' => __DIR__ . '/../../..' . '/lib/private/BackgroundJob/JobClassesRegistry.php',
         'OC\\BackgroundJob\\JobList' => __DIR__ . '/../../..' . '/lib/private/BackgroundJob/JobList.php',
+        'OC\\BackgroundJob\\JobRuns' => __DIR__ . '/../../..' . '/lib/private/BackgroundJob/JobRuns.php',
         'OC\\BinaryFinder' => __DIR__ . '/../../..' . '/lib/private/BinaryFinder.php',
         'OC\\Blurhash\\Listener\\GenerateBlurhashMetadata' => __DIR__ . '/../../..' . '/lib/private/Blurhash/Listener/GenerateBlurhashMetadata.php',
         'OC\\Broadcast\\Events\\BroadcastEvent' => __DIR__ . '/../../..' . '/lib/private/Broadcast/Events/BroadcastEvent.php',
@@ -1374,6 +1379,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OC\\Core\\Command\\Background\\JobWorker' => __DIR__ . '/../../..' . '/core/Command/Background/JobWorker.php',
         'OC\\Core\\Command\\Background\\ListCommand' => __DIR__ . '/../../..' . '/core/Command/Background/ListCommand.php',
         'OC\\Core\\Command\\Background\\Mode' => __DIR__ . '/../../..' . '/core/Command/Background/Mode.php',
+        'OC\\Core\\Command\\Background\\RunningJobs' => __DIR__ . '/../../..' . '/core/Command/Background/RunningJobs.php',
         'OC\\Core\\Command\\Base' => __DIR__ . '/../../..' . '/core/Command/Base.php',
         'OC\\Core\\Command\\Broadcast\\Test' => __DIR__ . '/../../..' . '/core/Command/Broadcast/Test.php',
         'OC\\Core\\Command\\Check' => __DIR__ . '/../../..' . '/core/Command/Check.php',
@@ -1648,6 +1654,8 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OC\\Core\\Migrations\\Version33000Date20260126120000' => __DIR__ . '/../../..' . '/core/Migrations/Version33000Date20260126120000.php',
         'OC\\Core\\Migrations\\Version34000Date20260318095645' => __DIR__ . '/../../..' . '/core/Migrations/Version34000Date20260318095645.php',
         'OC\\Core\\Migrations\\Version34000Date20260415161745' => __DIR__ . '/../../..' . '/core/Migrations/Version34000Date20260415161745.php',
+        'OC\\Core\\Migrations\\Version34000Date20260518163022' => __DIR__ . '/../../..' . '/core/Migrations/Version34000Date20260518163022.php',
+        'OC\\Core\\Migrations\\Version34000Date20260521110333' => __DIR__ . '/../../..' . '/core/Migrations/Version34000Date20260521110333.php',
         'OC\\Core\\Notification\\CoreNotifier' => __DIR__ . '/../../..' . '/core/Notification/CoreNotifier.php',
         'OC\\Core\\ResponseDefinitions' => __DIR__ . '/../../..' . '/core/ResponseDefinitions.php',
         'OC\\Core\\Service\\CronService' => __DIR__ . '/../../..' . '/core/Service/CronService.php',