Merge pull request #13031 from appwrite/fix/vcs-token-refresh-lock

fix(vcs): serialize installation token refresh with a lock
This commit is contained in:
Harsh Mahajan authored and GitHub committed 2026-07-29 15:02:15 +05:30
commit 555a0ca1aa
2 files changed
+301 -85

No files matched your search

+96 -21
View File
@@ -3,7 +3,9 @@
namespace Appwrite\Vcs;
use Appwrite\Auth\OAuth2;
use Appwrite\Auth\OAuth2\Exception as OAuth2Exception;
use Appwrite\Extend\Exception;
use Utopia\Console;
use Utopia\Database\Database;
use Utopia\Database\DateTime;
use Utopia\Database\Document;
@@ -45,44 +47,110 @@ class InstallationTokens
throw new Exception(Exception::GENERAL_PROVIDER_FAILURE, 'This installation has no refresh token on file. Please reconnect it.');
}
try {
$oauth2->refreshTokens($refreshToken);
} catch (\Throwable) {
// Providers rotate refresh tokens: two requests exchanging the same one revokes the family.
// The comment lock collection is reused for simplicity: it holds nothing but ids, and the
// prefix keeps these apart from the provider comment ids stored alongside them. Ideally
// this moves to a generic lock collection.
$lock = 'installation-' . $installation->getId();
$authorization = $dbForPlatform->getAuthorization();
$acquired = false;
$retries = 0;
while ($retries < 9) {
$retries++;
try {
$authorization->skip(fn () => $dbForPlatform->createDocument('vcsCommentLocks', new Document(['$id' => $lock])));
$acquired = true;
break;
} catch (\Throwable $err) {
if ($retries >= 9) {
Console::warning('Error creating vcs installation lock for ' . $installation->getId() . ': ' . $err->getMessage());
}
\sleep(1);
}
}
if (!$acquired) {
// The holder outlasted our wait. Reuse its token if it landed, never replay ours.
$current = $this->getCurrentInstallation($dbForPlatform, $installation);
if (!$current->isEmpty() && !empty($current->getAttribute('personalAccessToken')) && !$this->isExpired($current->getAttribute('personalAccessTokenExpiry'))) {
if ($this->isUsable($current)) {
return $current;
}
throw new Exception(Exception::GENERAL_RESOURCE_LOCKED);
}
try {
// The lock holder may have refreshed already.
$current = $this->getCurrentInstallation($dbForPlatform, $installation);
if ($this->isUsable($current)) {
return $current;
}
return $this->exchange($installation, $dbForPlatform, $oauth2);
} finally {
$authorization->skip(fn () => $dbForPlatform->deleteDocument('vcsCommentLocks', $lock));
}
}
protected function exchange(Document $installation, Database $dbForPlatform, OAuth2 $oauth2): Document
{
try {
$tokens = $oauth2->refreshTokens($installation->getAttribute('personalRefreshToken'));
} catch (OAuth2Exception $err) {
$this->clear($installation, $dbForPlatform, $err->getError());
throw new Exception(Exception::GENERAL_PROVIDER_FAILURE, 'Failed to refresh OAuth2 access token. Please reconnect the installation.');
} catch (\Throwable) {
throw new Exception(Exception::GENERAL_PROVIDER_FAILURE, 'Failed to refresh OAuth2 access token. Please reconnect the installation.');
}
// GitHub answers a refused token with a 200 and an error body rather than a 4xx.
$this->clear($installation, $dbForPlatform, $tokens['error'] ?? '');
$accessToken = $oauth2->getAccessToken('');
$refreshToken = $oauth2->getRefreshToken('');
$verificationId = $oauth2->getUserID($accessToken);
if (empty($verificationId)) {
$current = $this->getCurrentInstallation($dbForPlatform, $installation);
if (!$current->isEmpty() && !empty($current->getAttribute('personalAccessToken')) && !$this->isExpired($current->getAttribute('personalAccessTokenExpiry'))) {
return $current;
}
// No token and no stated reason, so the provider may simply not have answered. Persisting
// an empty token here would replace a pair that is possibly still good.
if (empty($accessToken)) {
throw new Exception(Exception::GENERAL_PROVIDER_FAILURE, 'Failed to refresh OAuth2 access token. Please reconnect the installation.');
}
$installation = $installation
->setAttribute('personalAccessToken', $accessToken)
->setAttribute('personalRefreshToken', $refreshToken)
->setAttribute('personalAccessTokenExpiry', DateTime::addSeconds(new \DateTime(), (int)$oauth2->getAccessTokenExpiry('')));
$dbForPlatform->updateDocument('installations', $installation->getId(), new Document([
'personalAccessToken' => $installation->getAttribute('personalAccessToken'),
'personalRefreshToken' => $installation->getAttribute('personalRefreshToken'),
'personalAccessTokenExpiry' => $installation->getAttribute('personalAccessTokenExpiry'),
// The provider has already rotated the family, so persist before anything else can fail.
$installation = $dbForPlatform->updateDocument('installations', $installation->getId(), new Document([
'personalAccessToken' => $accessToken,
'personalRefreshToken' => $oauth2->getRefreshToken(''),
'personalAccessTokenExpiry' => DateTime::addSeconds(new \DateTime(), (int)$oauth2->getAccessTokenExpiry('')),
]));
if (empty($oauth2->getUserID($accessToken))) {
throw new Exception(Exception::GENERAL_PROVIDER_FAILURE, 'Failed to refresh OAuth2 access token. Please reconnect the installation.');
}
return $installation;
}
/**
* Drops the stored pair when the provider states it refused the token, so later calls stop
* replaying it. Only an explicit refusal counts: a timeout or a 5xx may pass, and clearing on
* those would force a reconnect that was never needed.
*/
protected function clear(Document $installation, Database $dbForPlatform, mixed $error): void
{
if (!\is_string($error) || !\in_array($error, ['invalid_grant', 'bad_refresh_token'], true)) {
return;
}
$dbForPlatform->updateDocument('installations', $installation->getId(), new Document([
'personalAccessToken' => '',
'personalRefreshToken' => '',
'personalAccessTokenExpiry' => null,
]));
}
protected function isExpired(?string $expiry): bool
{
if (empty($expiry)) {
@@ -96,6 +164,13 @@ class InstallationTokens
}
}
protected function isUsable(Document $installation): bool
{
return !$installation->isEmpty()
&& !empty($installation->getAttribute('personalAccessToken'))
&& !$this->isExpired($installation->getAttribute('personalAccessTokenExpiry'));
}
protected function getCurrentInstallation(Database $dbForPlatform, Document $installation): Document
{
try {
+205 -64
View File
@@ -5,18 +5,24 @@ declare(strict_types=1);
namespace Tests\Unit\Vcs;
use Appwrite\Auth\OAuth2;
use Appwrite\Auth\OAuth2\Exception as OAuth2Exception;
use Appwrite\Extend\Exception;
use Appwrite\Vcs\InstallationTokens;
use PHPUnit\Framework\TestCase;
use Utopia\Database\Database;
use Utopia\Database\DateTime;
use Utopia\Database\Document;
use Utopia\Database\Validator\Authorization;
final class InstallationTokensTest extends TestCase
{
protected function db(): Database
{
return $this->createStub(Database::class);
$db = $this->createStub(Database::class);
$db->method('getAuthorization')->willReturn(new Authorization());
$db->method('getDocument')->willReturn(new Document());
return $db;
}
public function testUnexpiredTokenIsNotRefreshed(): void
@@ -70,6 +76,30 @@ final class InstallationTokensTest extends TestCase
$this->assertSame(0, $oauth2->refreshCalls);
}
public function testClearedInstallationIsReturnedWithoutCallingTheProvider(): void
{
// The state clear() leaves behind. GitHub works from here on its app credentials, and the
// providers that need the token fail at the adapter with a definite reason.
$installation = new Document([
'$id' => 'installation1',
'personalAccessToken' => '',
'personalRefreshToken' => '',
'personalAccessTokenExpiry' => null,
]);
$db = $this->createMock(Database::class);
$db->method('getAuthorization')->willReturn(new Authorization());
$db->expects($this->never())->method('updateDocument');
$db->expects($this->never())->method('createDocument');
$oauth2 = $this->fakeOAuth2();
$result = (new InstallationTokens())->refresh($installation, $db, $oauth2);
$this->assertSame('', $result->getAttribute('personalAccessToken'));
$this->assertSame(0, $oauth2->refreshCalls);
}
public function testExpiredTokenIsRefreshedAndPersisted(): void
{
$db = $this->createMock(Database::class);
@@ -83,16 +113,9 @@ final class InstallationTokensTest extends TestCase
}))
->willReturnArgument(2);
$installation = new Document([
'$id' => 'installation1',
'personalAccessToken' => 'stale-token',
'personalRefreshToken' => 'stale-refresh',
'personalAccessTokenExpiry' => DateTime::addSeconds(new \DateTime(), -3600),
]);
$oauth2 = $this->fakeOAuth2();
$result = (new InstallationTokens())->refresh($installation, $db, $oauth2);
$result = (new InstallationTokens())->refresh($this->expired(), $db, $oauth2);
$this->assertSame('fresh-token', $result->getAttribute('personalAccessToken'));
$this->assertSame(1, $oauth2->refreshCalls);
@@ -139,87 +162,200 @@ final class InstallationTokensTest extends TestCase
public function testFailedRefreshThrows(): void
{
$installation = new Document([
'$id' => 'installation1',
'personalAccessToken' => 'stale-token',
'personalRefreshToken' => 'stale-refresh',
'personalAccessTokenExpiry' => DateTime::addSeconds(new \DateTime(), -3600),
]);
$oauth2 = $this->fakeOAuth2(emptyUserId: true);
$this->expectException(Exception::class);
$this->expectExceptionMessage('Failed to refresh OAuth2 access token');
(new InstallationTokens())->refresh($installation, $this->db(), $oauth2);
(new InstallationTokens())->refresh($this->expired(), $this->db(), $oauth2);
}
public function testFailedRefreshReturnsCurrentInstallationWhenAnotherRequestRefreshed(): void
public function testRotatedTokenIsPersistedWhenVerificationFails(): void
{
$db = $this->createMock(Database::class);
$current = new Document([
'$id' => 'installation1',
'personalAccessToken' => 'already-refreshed-token',
'personalRefreshToken' => 'already-refreshed-refresh',
'personalAccessTokenExpiry' => DateTime::addSeconds(new \DateTime(), 3600),
]);
$db->method('getAuthorization')->willReturn(new Authorization());
$db->method('getDocument')->willReturn(new Document());
// The provider rotated the family, so the new pair has to land even though the call after it failed.
$db->expects($this->once())
->method('getDocument')
->with('installations', 'installation1')
->willReturn($current);
$db->expects($this->never())->method('updateDocument');
$installation = new Document([
'$id' => 'installation1',
'personalAccessToken' => 'stale-token',
'personalRefreshToken' => 'stale-refresh',
'personalAccessTokenExpiry' => DateTime::addSeconds(new \DateTime(), -3600),
]);
->method('updateDocument')
->with('installations', 'installation1', $this->callback(function (Document $update) {
$this->assertSame('fresh-refresh', $update->getAttribute('personalRefreshToken'));
return true;
}))
->willReturnArgument(2);
$oauth2 = $this->fakeOAuth2(emptyUserId: true);
$result = (new InstallationTokens())->refresh($installation, $db, $oauth2);
$this->assertSame('already-refreshed-token', $result->getAttribute('personalAccessToken'));
try {
(new InstallationTokens())->refresh($this->expired(), $db, $oauth2);
$this->fail('Expected an Exception');
} catch (Exception $e) {
$this->assertSame(Exception::GENERAL_PROVIDER_FAILURE, $e->getType());
}
}
public function testRefreshExceptionReturnsCurrentInstallationWhenAnotherRequestRefreshed(): void
public function testRefusedRefreshTokenIsCleared(): void
{
$db = $this->createMock(Database::class);
$current = new Document([
'$id' => 'installation1',
'personalAccessToken' => 'already-refreshed-token',
'personalRefreshToken' => 'already-refreshed-refresh',
'personalAccessTokenExpiry' => DateTime::addSeconds(new \DateTime(), 3600),
]);
$db->method('getAuthorization')->willReturn(new Authorization());
$db->method('getDocument')->willReturn(new Document());
$db->expects($this->once())
->method('updateDocument')
->with('installations', 'installation1', $this->callback(function (Document $update) {
$this->assertSame('', $update->getAttribute('personalAccessToken'));
$this->assertSame('', $update->getAttribute('personalRefreshToken'));
$this->assertNull($update->getAttribute('personalAccessTokenExpiry'));
return true;
}))
->willReturnArgument(2);
$oauth2 = $this->fakeOAuth2(refresh: 'refused');
$this->expectException(Exception::class);
(new InstallationTokens())->refresh($this->expired(), $db, $oauth2);
}
public function testInvalidGrantIsCleared(): void
{
$db = $this->createMock(Database::class);
$db->method('getAuthorization')->willReturn(new Authorization());
$db->method('getDocument')->willReturn(new Document());
$db->expects($this->once())
->method('updateDocument')
->with('installations', 'installation1', $this->callback(function (Document $update) {
$this->assertSame('', $update->getAttribute('personalRefreshToken'));
return true;
}))
->willReturnArgument(2);
$oauth2 = $this->fakeOAuth2(refresh: 'invalidGrant');
$this->expectException(Exception::class);
(new InstallationTokens())->refresh($this->expired(), $db, $oauth2);
}
public function testEmptyTokenResponseIsNotPersisted(): void
{
$db = $this->createMock(Database::class);
$db->method('getAuthorization')->willReturn(new Authorization());
$db->method('getDocument')->willReturn(new Document());
// A provider that answers without a token leaves nothing worth writing, and the stored
// pair may still be good, so it has to survive.
$db->expects($this->never())->method('updateDocument');
$oauth2 = $this->fakeOAuth2(refresh: 'empty');
$this->expectException(Exception::class);
(new InstallationTokens())->refresh($this->expired(), $db, $oauth2);
}
public function testFailedRefreshCallIsNotPersisted(): void
{
$db = $this->createMock(Database::class);
$db->method('getAuthorization')->willReturn(new Authorization());
$db->method('getDocument')->willReturn(new Document());
$db->expects($this->never())->method('updateDocument');
$oauth2 = $this->fakeOAuth2(refresh: 'throw');
$this->expectException(Exception::class);
(new InstallationTokens())->refresh($this->expired(), $db, $oauth2);
}
public function testTokenRefreshedByLockHolderIsReused(): void
{
$db = $this->createMock(Database::class);
$db->method('getAuthorization')->willReturn(new Authorization());
$db->expects($this->once())
->method('getDocument')
->with('installations', 'installation1')
->willReturn($current);
->willReturn(new Document([
'$id' => 'installation1',
'personalAccessToken' => 'already-refreshed-token',
'personalRefreshToken' => 'already-refreshed-refresh',
'personalAccessTokenExpiry' => DateTime::addSeconds(new \DateTime(), 3600),
]));
$db->expects($this->never())->method('updateDocument');
$installation = new Document([
$oauth2 = $this->fakeOAuth2();
$result = (new InstallationTokens())->refresh($this->expired(), $db, $oauth2);
$this->assertSame('already-refreshed-token', $result->getAttribute('personalAccessToken'));
$this->assertSame(0, $oauth2->refreshCalls);
}
public function testRefreshIsSerializedByLock(): void
{
$db = $this->createMock(Database::class);
$db->method('getAuthorization')->willReturn(new Authorization());
$db->method('getDocument')->willReturn(new Document());
$db->method('updateDocument')->willReturnArgument(2);
$db->expects($this->once())
->method('createDocument')
->with('vcsCommentLocks', $this->callback(function (Document $lock) {
$this->assertSame('installation-installation1', $lock->getId());
return true;
}))
->willReturnArgument(1);
$db->expects($this->once())
->method('deleteDocument')
->with('vcsCommentLocks', 'installation-installation1')
->willReturn(true);
$oauth2 = $this->fakeOAuth2();
(new InstallationTokens())->refresh($this->expired(), $db, $oauth2);
$this->assertSame(1, $oauth2->refreshCalls);
}
public function testLockIsReleasedWhenRefreshFails(): void
{
$db = $this->createMock(Database::class);
$db->method('getAuthorization')->willReturn(new Authorization());
$db->method('getDocument')->willReturn(new Document());
$db->method('createDocument')->willReturnArgument(1);
$db->expects($this->once())
->method('deleteDocument')
->with('vcsCommentLocks', 'installation-installation1')
->willReturn(true);
$oauth2 = $this->fakeOAuth2(refresh: 'throw');
$this->expectException(Exception::class);
$this->expectExceptionMessage('Failed to refresh OAuth2 access token');
(new InstallationTokens())->refresh($this->expired(), $db, $oauth2);
}
protected function expired(): Document
{
return new Document([
'$id' => 'installation1',
'personalAccessToken' => 'stale-token',
'personalRefreshToken' => 'stale-refresh',
'personalAccessTokenExpiry' => DateTime::addSeconds(new \DateTime(), -3600),
]);
$oauth2 = $this->fakeOAuth2(throwOnRefresh: true);
$result = (new InstallationTokens())->refresh($installation, $db, $oauth2);
$this->assertSame('already-refreshed-token', $result->getAttribute('personalAccessToken'));
}
protected function fakeOAuth2(bool $emptyUserId = false, bool $throwOnRefresh = false)
/**
* @param string $refresh One of: ok, refused, invalidGrant, empty, throw.
*/
protected function fakeOAuth2(bool $emptyUserId = false, string $refresh = 'ok')
{
return new class ($emptyUserId, $throwOnRefresh) extends OAuth2 {
return new class ($emptyUserId, $refresh) extends OAuth2 {
public int $refreshCalls = 0;
protected array $tokens = [];
public function __construct(protected bool $emptyUserId, protected bool $throwOnRefresh)
public function __construct(protected bool $emptyUserId, protected string $refresh)
{
parent::__construct('id', 'secret', '');
}
@@ -242,15 +378,20 @@ final class InstallationTokensTest extends TestCase
public function refreshTokens(string $refreshToken): array
{
$this->refreshCalls++;
if ($this->throwOnRefresh) {
throw new \RuntimeException('refresh token already used');
}
$this->tokens = [
'access_token' => 'fresh-token',
'refresh_token' => 'fresh-refresh',
'expires_in' => 3600,
];
// GitHub states a refused token in a 200 body; GitLab and Gitea answer 400.
// A request that never completed states nothing at all.
$this->tokens = match ($this->refresh) {
'refused' => ['error' => 'bad_refresh_token'],
'invalidGrant' => throw new OAuth2Exception('{"error":"invalid_grant"}', 400),
'empty' => [],
'throw' => throw new \RuntimeException('connection timed out'),
default => [
'access_token' => 'fresh-token',
'refresh_token' => 'fresh-refresh',
'expires_in' => 3600,
],
};
return $this->tokens;
}