Use storage-backed bearer auth to keep refreshed tokens and add coverage for StorageAwareAuthenticationPlugin

Author: Surfoo

src/Options.php

@@ -8,6 +8,7 @@
 use Geocaching\Enum\Environment;
 use Geocaching\Plugin\CircuitBreakerPlugin;
 use Geocaching\Plugin\GeocachingHttpLoggerPlugin;
+use Geocaching\Plugin\StorageAwareAuthenticationPlugin;
 use Geocaching\Plugin\ReliabilityPlugin;
 use Geocaching\Plugin\RetryPlugin;
 use Geocaching\Reliability\CircuitBreaker;
@@ -58,7 +59,7 @@ public function __construct(array $options = [])
         $this->getClientBuilder()->setBaseUri($baseUri->value);
 
         $this->getClientBuilder()->addPlugin(new BaseUriPlugin($this->getUri()));
-        $this->getClientBuilder()->addPlugin(new AuthenticationPlugin(new Bearer($this->getAccessToken())));
+        $this->addAuthenticationPlugin();
     }
 
     private function configureOptions(OptionsResolver $resolver): void
@@ -68,6 +69,8 @@ private function configureOptions(OptionsResolver $resolver): void
             [
                 'client_builder' => new ClientBuilder(),
                 'uri_factory'    => Psr17FactoryDiscovery::findUriFactory(),
+                'token_storage'  => null,
+                'reference_code' => null,
             ]
         );
 
@@ -76,6 +79,8 @@ private function configureOptions(OptionsResolver $resolver): void
         $resolver->setAllowedTypes('client_builder', ClientBuilder::class);
         $resolver->setAllowedTypes('uri_factory', UriFactoryInterface::class);
         $resolver->setAllowedTypes('uri', 'string');
+        $resolver->setAllowedTypes('token_storage', [TokenStorageInterface::class, 'null']);
+        $resolver->setAllowedTypes('reference_code', ['string', 'null']);
     }
 
     public function getClientBuilder(): ClientBuilder
@@ -97,6 +102,31 @@ public function getAccessToken(): string
     {
         return $this->options['access_token'];
     }
+
+    /**
+     * Register an authentication plugin that always uses the freshest token.
+     *
+     * If a TokenStorage is provided, we pull the current token from storage so
+     * retries after refresh use the updated access token. Otherwise we fall
+     * back to a static Bearer token.
+     */
+    private function addAuthenticationPlugin(): void
+    {
+        $storage       = $this->options['token_storage'];
+        $referenceCode = $this->options['reference_code'];
+
+        if ($storage && $referenceCode) {
+            $plugin = new StorageAwareAuthenticationPlugin(
+                $storage,
+                $referenceCode,
+                $this->getAccessToken()
+            );
+        } else {
+            $plugin = new AuthenticationPlugin(new Bearer($this->getAccessToken()));
+        }
+
+        $this->getClientBuilder()->addPlugin($plugin);
+    }
 
     /**
      * Enable HTTP logging for all API requests/responses with a pre-configured logger.

src/Plugin/StorageAwareAuthenticationPlugin.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Geocaching\Plugin;
+
+use Http\Client\Common\Plugin;
+use Http\Message\Authentication\Bearer;
+use Http\Promise\Promise;
+use League\OAuth2\Client\Token\TokenStorageInterface;
+use Psr\Http\Message\RequestInterface;
+
+/**
+ * Authentication plugin that always applies the freshest token from storage.
+ *
+ * Falls back to the initially configured access token when storage is empty.
+ */
+final class StorageAwareAuthenticationPlugin implements Plugin
+{
+    public function __construct(
+        private TokenStorageInterface $storage,
+        private string $referenceCode,
+        private string $fallbackAccessToken
+    ) {
+    }
+
+    public function handleRequest(RequestInterface $request, callable $next, callable $first): Promise
+    {
+        $tokens = $this->storage->getTokens($this->referenceCode);
+
+        if ($tokens) {
+            $request = $request->withHeader('Authorization', $tokens->getAuthorizationHeader());
+        } else {
+            // Fall back to the original token so the first call still works
+            $request = (new Bearer($this->fallbackAccessToken))->authenticate($request);
+        }
+
+        return $next($request);
+    }
+}

tests/Plugin/StorageAwareAuthenticationPluginTest.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Plugin;
+
+use Geocaching\Plugin\StorageAwareAuthenticationPlugin;
+use Http\Promise\FulfilledPromise;
+use League\OAuth2\Client\Token\TokenSet;
+use League\OAuth2\Client\Token\TokenStorageInterface;
+use Nyholm\Psr7\Request;
+use PHPUnit\Framework\TestCase;
+
+final class StorageAwareAuthenticationPluginTest extends TestCase
+{
+    public function testUsesTokenFromStorageWhenAvailable(): void
+    {
+        $tokens = TokenSet::create('fresh-access', 'refresh-token', 3600);
+
+        $storage = $this->createMock(TokenStorageInterface::class);
+        $storage->expects($this->once())
+            ->method('getTokens')
+            ->with('user-123')
+            ->willReturn($tokens);
+
+        $plugin = new StorageAwareAuthenticationPlugin($storage, 'user-123', 'fallback-access');
+
+        $capturedRequest = null;
+        $next = function ($request) use (&$capturedRequest) {
+            $capturedRequest = $request;
+            return new FulfilledPromise('ok');
+        };
+
+        $plugin->handleRequest(new Request('GET', 'https://example.com'), $next, $next)->wait();
+
+        self::assertSame(
+            'Bearer fresh-access',
+            $capturedRequest->getHeaderLine('Authorization'),
+            'Should apply authorization header from storage tokens'
+        );
+    }
+
+    public function testFallsBackToProvidedAccessTokenWhenStorageEmpty(): void
+    {
+        $storage = $this->createMock(TokenStorageInterface::class);
+        $storage->expects($this->once())
+            ->method('getTokens')
+            ->with('user-123')
+            ->willReturn(null);
+
+        $plugin = new StorageAwareAuthenticationPlugin($storage, 'user-123', 'fallback-access');
+
+        $capturedRequest = null;
+        $next = function ($request) use (&$capturedRequest) {
+            $capturedRequest = $request;
+            return new FulfilledPromise('ok');
+        };
+
+        $plugin->handleRequest(new Request('GET', 'https://example.com'), $next, $next)->wait();
+
+        self::assertSame(
+            'Bearer fallback-access',
+            $capturedRequest->getHeaderLine('Authorization'),
+            'Should fall back to initial bearer when storage has no tokens'
+        );
+    }
+}