feat(storage): cache temporary S3 URLs

app/Shared/Storage/Services/TemporaryUrlService.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace App\Shared\Storage\Services;
+
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Storage;
+use InvalidArgumentException;
+
+class TemporaryUrlService
+{
+    protected const REFRESH_MARGIN_SECONDS = 60;
+
+    /**
+     * @return array{temporary_url: string, temporary_url_expires_at: string}
+     */
+    public function generate(string $path, int $expiresInMinutes = 10): array
+    {
+        if ($expiresInMinutes < 1) {
+            throw new InvalidArgumentException('The temporary URL expiration must be at least one minute.');
+        }
+
+        $cacheTtlInSeconds = max(
+            1,
+            ($expiresInMinutes * 60) - self::REFRESH_MARGIN_SECONDS,
+        );
+
+        return Cache::remember(
+            $this->cacheKey($path, $expiresInMinutes),
+            now()->addSeconds($cacheTtlInSeconds),
+            function () use ($path, $expiresInMinutes): array {
+                $expiresAt = now()->addMinutes($expiresInMinutes);
+
+                return [
+                    'temporary_url' => Storage::disk('s3')->temporaryUrl(
+                        $path,
+                        $expiresAt,
+                        [
+                            'ResponseCacheControl' => 'private, max-age='.($expiresInMinutes * 60),
+                        ],
+                    ),
+                    'temporary_url_expires_at' => $expiresAt->toIso8601String(),
+                ];
+            },
+        );
+    }
+
+    public function forget(string $path, int $expiresInMinutes = 10): void
+    {
+        Cache::forget($this->cacheKey($path, $expiresInMinutes));
+    }
+
+    protected function cacheKey(string $path, int $expiresInMinutes): string
+    {
+        return sprintf(
+            's3:temporary-url:%s:%d',
+            hash('sha256', $path),
+            $expiresInMinutes,
+        );
+    }
+}

tests/Unit/Storage/TemporaryUrlServiceTest.php

@@ -0,0 +1,85 @@
+<?php
+
+namespace Tests\Unit\Storage;
+
+use App\Shared\Storage\Services\TemporaryUrlService;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Storage;
+use Mockery;
+use Tests\TestCase;
+
+class TemporaryUrlServiceTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        Cache::flush();
+        $this->travelTo(Carbon::parse('2026-09-22 12:00:00', 'UTC'));
+    }
+
+    protected function tearDown(): void
+    {
+        Cache::flush();
+        $this->travelBack();
+
+        parent::tearDown();
+    }
+
+    public function test_it_reuses_the_signed_url_and_its_original_expiration(): void
+    {
+        $disk = Mockery::mock();
+
+        Storage::shouldReceive('disk')
+            ->once()
+            ->with('s3')
+            ->andReturn($disk);
+        $disk->shouldReceive('temporaryUrl')
+            ->once()
+            ->with(
+                'images/product.png',
+                Mockery::on(fn ($expiration): bool => $expiration->equalTo(now()->addMinutes(10))),
+                ['ResponseCacheControl' => 'private, max-age=600'],
+            )
+            ->andReturn('https://s3.example.test/product.png?signed=first');
+
+        $service = app(TemporaryUrlService::class);
+        $first = $service->generate('images/product.png', 10);
+
+        $this->travel(5)->minutes();
+
+        $second = $service->generate('images/product.png', 10);
+
+        $this->assertSame($first, $second);
+        $this->assertSame('https://s3.example.test/product.png?signed=first', $second['temporary_url']);
+        $this->assertSame('2026-09-22T12:10:00+00:00', $second['temporary_url_expires_at']);
+    }
+
+    public function test_it_refreshes_the_signed_url_before_it_expires(): void
+    {
+        $disk = Mockery::mock();
+
+        Storage::shouldReceive('disk')
+            ->twice()
+            ->with('s3')
+            ->andReturn($disk);
+        $disk->shouldReceive('temporaryUrl')
+            ->twice()
+            ->andReturn(
+                'https://s3.example.test/product.png?signed=first',
+                'https://s3.example.test/product.png?signed=second',
+            );
+
+        $service = app(TemporaryUrlService::class);
+        $first = $service->generate('images/product.png', 10);
+
+        $this->travel(9)->minutes();
+        $this->travel(1)->seconds();
+
+        $second = $service->generate('images/product.png', 10);
+
+        $this->assertNotSame($first['temporary_url'], $second['temporary_url']);
+        $this->assertSame('2026-09-22T12:19:01+00:00', $second['temporary_url_expires_at']);
+    }
+}