Cache verified external payload fetches

Author: durable-workflow-ops

src/V2/Support/ExternalPayloadStorage.php

@@ -10,6 +10,19 @@
 
 final class ExternalPayloadStorage
 {
+    private const MAX_CACHE_ENTRIES = 128;
+
+    private const MAX_CACHE_BYTES = 16777216;
+
+    /**
+     * @var array<string, array{data: string, bytes: int, used_at: int}>
+     */
+    private static array $verifiedCache = [];
+
+    private static int $verifiedCacheBytes = 0;
+
+    private static int $verifiedCacheSequence = 0;
+
     public static function store(
         ExternalPayloadStorageDriver $driver,
         string $data,
@@ -24,6 +37,13 @@ public static function store(
 
     public static function fetch(ExternalPayloadStorageDriver $driver, ExternalPayloadReference $reference): string
     {
+        $cacheKey = self::cacheKey($reference);
+        if (isset(self::$verifiedCache[$cacheKey])) {
+            self::$verifiedCache[$cacheKey]['used_at'] = ++self::$verifiedCacheSequence;
+
+            return self::$verifiedCache[$cacheKey]['data'];
+        }
+
         $data = $driver->get($reference->uri);
 
         if (strlen($data) !== $reference->sizeBytes) {
@@ -34,6 +54,73 @@ public static function fetch(ExternalPayloadStorageDriver $driver, ExternalPaylo
             throw new ExternalPayloadIntegrityException('External payload hash does not match its reference.');
         }
 
+        self::rememberVerified($cacheKey, $data);
+
         return $data;
     }
+
+    public static function flushVerifiedCache(): void
+    {
+        self::$verifiedCache = [];
+        self::$verifiedCacheBytes = 0;
+        self::$verifiedCacheSequence = 0;
+    }
+
+    private static function cacheKey(ExternalPayloadReference $reference): string
+    {
+        return implode("\n", [
+            $reference->uri,
+            $reference->sha256,
+            (string) $reference->sizeBytes,
+            $reference->codec,
+        ]);
+    }
+
+    private static function rememberVerified(string $cacheKey, string $data): void
+    {
+        $bytes = strlen($data);
+        if ($bytes > self::MAX_CACHE_BYTES) {
+            return;
+        }
+
+        if (isset(self::$verifiedCache[$cacheKey])) {
+            self::$verifiedCacheBytes -= self::$verifiedCache[$cacheKey]['bytes'];
+        }
+
+        self::$verifiedCache[$cacheKey] = [
+            'data' => $data,
+            'bytes' => $bytes,
+            'used_at' => ++self::$verifiedCacheSequence,
+        ];
+        self::$verifiedCacheBytes += $bytes;
+
+        self::evictVerifiedCache();
+    }
+
+    private static function evictVerifiedCache(): void
+    {
+        while (
+            count(self::$verifiedCache) > self::MAX_CACHE_ENTRIES
+            || self::$verifiedCacheBytes > self::MAX_CACHE_BYTES
+        ) {
+            $oldestKey = null;
+            $oldestUsedAt = PHP_INT_MAX;
+
+            foreach (self::$verifiedCache as $key => $entry) {
+                if ($entry['used_at'] < $oldestUsedAt) {
+                    $oldestKey = $key;
+                    $oldestUsedAt = $entry['used_at'];
+                }
+            }
+
+            if ($oldestKey === null) {
+                self::$verifiedCacheBytes = 0;
+
+                return;
+            }
+
+            self::$verifiedCacheBytes -= self::$verifiedCache[$oldestKey]['bytes'];
+            unset(self::$verifiedCache[$oldestKey]);
+        }
+    }
 }

tests/Unit/V2/ExternalPayloadStorageTest.php

@@ -9,6 +9,7 @@
 use League\Flysystem\Filesystem;
 use League\Flysystem\Local\LocalFilesystemAdapter;
 use PHPUnit\Framework\TestCase;
+use Workflow\V2\Contracts\ExternalPayloadStorageDriver;
 use Workflow\V2\Exceptions\ExternalPayloadIntegrityException;
 use Workflow\V2\Support\ExternalPayloadReference;
 use Workflow\V2\Support\ExternalPayloadStorage;
@@ -21,6 +22,8 @@ final class ExternalPayloadStorageTest extends TestCase
 
     protected function tearDown(): void
     {
+        ExternalPayloadStorage::flushVerifiedCache();
+
         if ($this->storageRoot !== null) {
             $this->removeDirectory($this->storageRoot);
             $this->storageRoot = null;
@@ -75,6 +78,42 @@ public function testLocalFilesystemDriverStoresFetchesAndDeletesVerifiedBytes():
         $driver->get($reference->uri);
     }
 
+    public function testFetchCachesVerifiedBytesByReference(): void
+    {
+        $localDriver = new LocalFilesystemExternalPayloadStorage($this->makeStorageRoot());
+        $driver = new class($localDriver) implements ExternalPayloadStorageDriver {
+            public int $getCalls = 0;
+
+            public function __construct(
+                private readonly ExternalPayloadStorageDriver $inner
+            ) {
+            }
+
+            public function put(string $data, string $sha256, string $codec): string
+            {
+                return $this->inner->put($data, $sha256, $codec);
+            }
+
+            public function get(string $uri): string
+            {
+                $this->getCalls++;
+
+                return $this->inner->get($uri);
+            }
+
+            public function delete(string $uri): void
+            {
+                $this->inner->delete($uri);
+            }
+        };
+
+        $reference = ExternalPayloadStorage::store($driver, 'encoded-payload', 'avro');
+
+        $this->assertSame('encoded-payload', ExternalPayloadStorage::fetch($driver, $reference));
+        $this->assertSame('encoded-payload', ExternalPayloadStorage::fetch($driver, $reference));
+        $this->assertSame(1, $driver->getCalls);
+    }
+
     public function testFetchRejectsMutatedPayloadBytes(): void
     {
         $driver = new LocalFilesystemExternalPayloadStorage($this->makeStorageRoot());