fix(user_status): refresh a live status before it can be invalidated

UserLiveStatusListener only refreshed status_timestamp once it was
already older than INVALIDATE_STATUS_THRESHOLD, which is the same 15
minutes at which ClearOldStatusesBackgroundJob sweeps a status to
offline. With a five minute client interval that leaves a window, up to
one interval wide, in which a user who never stopped working is shown as
offline until their next heartbeat arrives.

The refresh now happens at REFRESH_STATUS_THRESHOLD, far enough below
the invalidation threshold to leave room for a full heartbeat interval.
Until now the sheer number of heartbeats hid the problem, because one
always landed within seconds of the cleanup job.

Signed-off-by: Git'Fellow <12234510+solracsf@users.noreply.github.com>

Author: solracsf

apps/user_status/lib/Listener/UserLiveStatusListener.php

@@ -76,9 +76,7 @@ public function handle(Event $event): void {
 
 		$needsUpdate = false;
 
-		// If the current status is older than 5 minutes,
-		// treat it as outdated and update
-		if ($userStatus->getStatusTimestamp() < ($this->timeFactory->getTime() - StatusService::INVALIDATE_STATUS_THRESHOLD)) {
+		if ($userStatus->getStatusTimestamp() < ($this->timeFactory->getTime() - StatusService::REFRESH_STATUS_THRESHOLD)) {
 			$needsUpdate = true;
 		}
 

apps/user_status/lib/Service/StatusService.php

@@ -62,6 +62,13 @@ class StatusService {
 	/** @var int */
 	public const INVALIDATE_STATUS_THRESHOLD = 15 /* minutes */ * 60 /* seconds */;
 
+	/**
+	 * Has to stay at least one client heartbeat interval below INVALIDATE_STATUS_THRESHOLD.
+	 *
+	 * @var int
+	 */
+	public const REFRESH_STATUS_THRESHOLD = 7 /* minutes */ * 60 /* seconds */;
+
 	/** @var int */
 	public const MAXIMUM_MESSAGE_LENGTH = 80;
 

apps/user_status/tests/Integration/Listener/UserLiveStatusListenerIntegrationTest.php

@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\UserStatus\Tests\Integration\Listener;
+
+use OCA\DAV\CalDAV\Status\StatusService as CalendarStatusService;
+use OCA\UserStatus\Db\UserStatusMapper;
+use OCA\UserStatus\Listener\UserLiveStatusListener;
+use OCA\UserStatus\Service\StatusService;
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\IDBConnection;
+use OCP\IUser;
+use OCP\Server;
+use OCP\User\Events\UserLiveStatusEvent;
+use OCP\UserStatus\IUserStatus;
+use Psr\Log\LoggerInterface;
+use Test\TestCase;
+use function time;
+
+#[\PHPUnit\Framework\Attributes\Group(name: 'DB')]
+class UserLiveStatusListenerIntegrationTest extends TestCase {
+
+	private const USER_ID = 'test123';
+
+	/** HEARTBEAT_INTERVAL in apps/user_status/src/services/heartbeatScheduler.ts */
+	private const CLIENT_HEARTBEAT_INTERVAL = 5 * 60;
+
+	/** ClearOldStatusesBackgroundJob::setInterval() */
+	private const CLEANUP_JOB_INTERVAL = 60;
+
+	private UserStatusMapper $mapper;
+	private StatusService $service;
+	private UserLiveStatusListener $listener;
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		$this->mapper = Server::get(UserStatusMapper::class);
+		$this->service = Server::get(StatusService::class);
+
+		$db = Server::get(IDBConnection::class);
+		$qb = $db->getQueryBuilder();
+		$qb->delete('user_status')->executeStatement();
+
+		$this->listener = new UserLiveStatusListener(
+			$this->mapper,
+			$this->service,
+			Server::get(ITimeFactory::class),
+			$this->createMock(CalendarStatusService::class),
+			$this->createMock(LoggerInterface::class),
+		);
+	}
+
+	public function testActiveUserSurvivesTheInvalidationSweep(): void {
+		$this->service->setStatus(self::USER_ID, IUserStatus::ONLINE, time(), false);
+
+		for ($minute = 1; $minute <= 30; $minute++) {
+			$this->passTime(self::CLEANUP_JOB_INTERVAL);
+			$this->runCleanupJob();
+
+			self::assertSame(
+				IUserStatus::ONLINE,
+				$this->mapper->findByUserId(self::USER_ID)->getStatus(),
+				"User went offline after $minute minutes while still sending heartbeats",
+			);
+
+			if ($minute % (self::CLIENT_HEARTBEAT_INTERVAL / self::CLEANUP_JOB_INTERVAL) === 0) {
+				$this->heartbeat();
+			}
+		}
+	}
+
+	/** Equivalent to letting time pass, without faking the clock of every collaborator. */
+	private function passTime(int $seconds): void {
+		$status = $this->mapper->findByUserId(self::USER_ID);
+		$status->setStatusTimestamp($status->getStatusTimestamp() - $seconds);
+		$this->mapper->update($status);
+	}
+
+	private function heartbeat(): void {
+		$user = $this->createMock(IUser::class);
+		$user->method('getUID')->willReturn(self::USER_ID);
+
+		$this->listener->handle(new UserLiveStatusEvent($user, IUserStatus::ONLINE, time()));
+	}
+
+	private function runCleanupJob(): void {
+		$now = time();
+		$this->mapper->clearStatusesOlderThan($now - StatusService::INVALIDATE_STATUS_THRESHOLD, $now);
+	}
+}

apps/user_status/tests/Unit/Listener/UserLiveStatusListenerTest.php

@@ -136,6 +136,9 @@ public static function handleEventWithCorrectEventDataProvider(): array {
 			['john.doe', 'online', 5000, false, 'away', 5000, true, false],
 			['john.doe', 'away', 5000, true, 'online', 5000, true, false],
 			['john.doe', 'online', 5000, true, 'away', 5000, true, false],
+			// a status older than REFRESH_STATUS_THRESHOLD is refreshed, a younger one is not
+			['john.doe', 'online', 4500, false, 'online', 5000, true, true],
+			['john.doe', 'online', 4700, false, 'online', 5000, true, false],
 		];
 	}
 }

apps/user_status/tests/Unit/Service/StatusServiceTest.php

@@ -629,6 +629,16 @@ public function testRemoveUserStatusDoesNotExist(): void {
 		$this->assertFalse($actual);
 	}
 
+	public function testRefreshThresholdLeavesRoomForAHeartbeat(): void {
+		// HEARTBEAT_INTERVAL in apps/user_status/src/services/heartbeatScheduler.ts
+		$clientHeartbeatInterval = 5 * 60;
+
+		self::assertGreaterThan(
+			$clientHeartbeatInterval,
+			StatusService::INVALIDATE_STATUS_THRESHOLD - StatusService::REFRESH_STATUS_THRESHOLD,
+		);
+	}
+
 	public function testCleanStatusAutomaticOnline(): void {
 		$status = new UserStatus();
 		$status->setStatus(IUserStatus::ONLINE);