nextcloud-mcp-server/third_party/astrolabe/lib/BackgroundJob/RefreshUserTokens.php

<?php

declare(strict_types=1);

namespace OCA\Astrolabe\BackgroundJob;

use OCA\Astrolabe\Service\IdpTokenRefresher;
use OCA\Astrolabe\Service\McpTokenStorage;
use OCP\AppFramework\Utility\ITimeFactory;
use OCP\BackgroundJob\IJob;
use OCP\BackgroundJob\TimedJob;
use OCP\Lock\LockedException;
use Psr\Log\LoggerInterface;

/**
 * Background job to proactively refresh OAuth tokens before expiration.
 *
 * Runs every 15 minutes and refreshes tokens based on their actual expiration
 * time. Works with any IdP (Nextcloud OIDC, Keycloak, etc.) since it uses
 * the real token expiration rather than IdP configuration.
 *
 * Refresh strategy: Refresh when less than 50% of token lifetime remains,
 * ensuring tokens are refreshed well before expiration regardless of the
 * IdP's configured token lifetime.
 *
 * @psalm-suppress UnusedClass - Background jobs are loaded dynamically by Nextcloud
 */
class RefreshUserTokens extends TimedJob {
	/** Job runs every 15 minutes */
	private const JOB_INTERVAL_SECONDS = 900;

	/** Refresh when this percentage of token lifetime remains */
	private const REFRESH_AT_REMAINING_PERCENT = 0.5;

	/** Minimum threshold to avoid constant refresh (5 minutes) */
	private const MIN_THRESHOLD_SECONDS = 300;

	/** Default assumed token lifetime if we can't determine it (1 hour) */
	private const DEFAULT_TOKEN_LIFETIME_SECONDS = 3600;

	/** Batch size for processing users (prevents memory issues on large installations) */
	private const BATCH_SIZE = 100;

	public function __construct(
		ITimeFactory $time,
		private McpTokenStorage $tokenStorage,
		private IdpTokenRefresher $tokenRefresher,
		private LoggerInterface $logger,
	) {
		parent::__construct($time);
		$this->setInterval(self::JOB_INTERVAL_SECONDS);
		$this->setTimeSensitivity(IJob::TIME_INSENSITIVE);
	}

	protected function run(mixed $argument): void {
		$this->logger->info('RefreshUserTokens: Starting background token refresh');

		$refreshed = 0;
		$failed = 0;
		$skipped = 0;
		$offset = 0;
		$totalUsers = 0;

		// Process users in batches to prevent memory issues on large installations
		do {
			$userIds = $this->tokenStorage->getAllUsersWithTokens(self::BATCH_SIZE, $offset);
			$batchCount = count($userIds);
			$totalUsers += $batchCount;

			foreach ($userIds as $userId) {
				$result = $this->refreshUserTokenIfNeeded($userId);
				match ($result) {
					'refreshed' => $refreshed++,
					'failed' => $failed++,
					'skipped' => $skipped++,
				};
			}

			$offset += self::BATCH_SIZE;
		} while ($batchCount === self::BATCH_SIZE);

		$this->logger->info("RefreshUserTokens: Complete - total=$totalUsers, refreshed=$refreshed, failed=$failed, skipped=$skipped");
	}

	/**
	 * Refresh a user's token if it's nearing expiration.
	 *
	 * Calculates the refresh threshold based on the token's actual lifetime,
	 * refreshing when less than 50% of the lifetime remains.
	 *
	 * Uses locking to prevent race conditions with on-demand refresh in
	 * getAccessToken(). If lock cannot be acquired, skips this user since
	 * on-demand refresh is already handling it.
	 *
	 * @return string 'refreshed', 'failed', or 'skipped'
	 */
	private function refreshUserTokenIfNeeded(string $userId): string {
		$token = $this->tokenStorage->getUserToken($userId);

		if ($token === null) {
			return 'skipped';
		}

		$expiresAt = (int)($token['expires_at'] ?? 0);
		$issuedAt = isset($token['issued_at']) ? (int)$token['issued_at'] : null;
		$timeRemaining = $expiresAt - time();

		// Calculate token lifetime from stored data or use default
		if ($issuedAt !== null) {
			$tokenLifetime = $expiresAt - $issuedAt;
		} else {
			// Fallback: use default lifetime assumption
			$tokenLifetime = self::DEFAULT_TOKEN_LIFETIME_SECONDS;
		}

		// Calculate threshold: refresh when 50% of lifetime remains
		$threshold = max(
			(int)($tokenLifetime * self::REFRESH_AT_REMAINING_PERCENT),
			self::MIN_THRESHOLD_SECONDS
		);

		if ($timeRemaining > $threshold) {
			// Token still has plenty of time, skip
			return 'skipped';
		}

		// Token is expiring soon, attempt refresh with lock
		try {
			return $this->tokenStorage->withTokenLock($userId, function () use ($userId) {
				// Re-check token after acquiring lock (double-check pattern)
				// Another process may have refreshed while we waited for lock
				$currentToken = $this->tokenStorage->getUserToken($userId);

				if ($currentToken === null) {
					return 'skipped';
				}

				// Recalculate threshold with current token data
				$currentExpiresAt = (int)($currentToken['expires_at'] ?? 0);
				$currentIssuedAt = isset($currentToken['issued_at']) ? (int)$currentToken['issued_at'] : null;
				$currentTimeRemaining = $currentExpiresAt - time();

				if ($currentIssuedAt !== null) {
					$currentTokenLifetime = $currentExpiresAt - $currentIssuedAt;
				} else {
					$currentTokenLifetime = self::DEFAULT_TOKEN_LIFETIME_SECONDS;
				}

				$currentThreshold = max(
					(int)($currentTokenLifetime * self::REFRESH_AT_REMAINING_PERCENT),
					self::MIN_THRESHOLD_SECONDS
				);

				if ($currentTimeRemaining > $currentThreshold) {
					// Token was refreshed by another process while we waited
					$this->logger->debug("RefreshUserTokens: Token already refreshed for user $userId while waiting for lock");
					return 'skipped';
				}

				// Still needs refresh, proceed
				if (!isset($currentToken['refresh_token'])) {
					$this->logger->warning("RefreshUserTokens: User $userId has no refresh token");
					return 'failed';
				}

				$this->logger->debug("RefreshUserTokens: Refreshing token for user $userId (remaining={$currentTimeRemaining}s, threshold={$currentThreshold}s)");

				/** @var string $refreshToken */
				$refreshToken = $currentToken['refresh_token'];
				$newTokenData = $this->tokenRefresher->refreshAccessToken($refreshToken);

				if ($newTokenData === null) {
					$this->logger->warning("RefreshUserTokens: Refresh returned null for user $userId");
					// Don't delete token here - let on-demand refresh handle cleanup
					return 'failed';
				}

				// Calculate new expiration and store issued_at for future calculations
				$expiresIn = (int)($newTokenData['expires_in'] ?? self::DEFAULT_TOKEN_LIFETIME_SECONDS);
				$now = time();

				/** @var string $accessToken */
				$accessToken = $newTokenData['access_token'];
				/** @var string $newRefreshToken */
				$newRefreshToken = $newTokenData['refresh_token'] ?? $refreshToken;

				$this->tokenStorage->storeUserToken(
					$userId,
					$accessToken,
					$newRefreshToken,
					$now + $expiresIn,
					$now  // issued_at
				);

				$this->logger->debug("RefreshUserTokens: Successfully refreshed token for user $userId");
				return 'refreshed';
			});
		} catch (LockedException $e) {
			// Lock held by on-demand refresh - expected, not an error
			$this->logger->debug("RefreshUserTokens: Lock held for user $userId, skipping");
			return 'skipped';
		} catch (\Exception $e) {
			$this->logger->error("RefreshUserTokens: Failed to refresh for user $userId: " . $e->getMessage());
			return 'failed';
		}
	}
}