FOUR-20933: Implement ETag Caching for Screens Data

ProcessMaker/Http/Kernel.php

@@ -41,7 +41,7 @@ class Kernel extends HttpKernel
             \Illuminate\Routing\Middleware\SubstituteBindings::class,
             Middleware\GenerateMenus::class,
             \Laravel\Passport\Http\Middleware\CreateFreshApiToken::class,
-            \ProcessMaker\Http\Middleware\IgnoreMapFiles::class,
+            Middleware\IgnoreMapFiles::class,
         ],
         'api' => [
             // API Middleware is defined with routeMiddleware below.
@@ -83,6 +83,7 @@ class Kernel extends HttpKernel
         'session_kill' => Middleware\SessionControlKill::class,
         'no-cache' => Middleware\NoCache::class,
         'admin' => Middleware\IsAdmin::class,
+        'etag' => Middleware\Etag\HandleEtag::class,
     ];
 
     /**

ProcessMaker/Http/Middleware/Etag/HandleEtag.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace ProcessMaker\Http\Middleware\Etag;
+
+use Closure;
+use Illuminate\Http\Request;
+use ProcessMaker\Http\Resources\Caching\EtagManager;
+use Symfony\Component\HttpFoundation\Response;
+
+class HandleEtag
+{
+    public string $middleware = 'etag';
+
+    /**
+     * Handle an incoming request.
+     */
+    public function handle(Request $request, Closure $next, ?string $scope = null): Response
+    {
+        // Save original method and support HEAD requests.
+        $originalMethod = $request->getMethod();
+        if ($request->isMethod('HEAD')) {
+            $request->setMethod('GET');
+        }
+
+        // Handle response.
+        $response = $next($request);
+
+        // Determine if the ETag should include user-specific data.
+        $includeUser = $scope === 'user';
+
+        // Generate ETag for the response.
+        $etag = EtagManager::getEtag($request, $response, $includeUser);
+        if ($etag) {
+            // Set the ETag header.
+            $response->setEtag($etag);
+
+            // Get and strip weak ETags from request headers.
+            $noneMatch = array_map([$this, 'stripWeakTags'], $request->getETags());
+
+            // Compare ETags and set response as not modified if applicable.
+            if (in_array($etag, $noneMatch)) {
+                $response->setNotModified();
+            }
+        }
+
+        // Restore original method and return the response.
+        $request->setMethod($originalMethod);
+
+        return $response;
+    }
+
+    /**
+     * Remove the weak indicator (W/) from an ETag.
+     */
+    private function stripWeakTags(string $etag): string
+    {
+        return str_replace('W/', '', $etag);
+    }
+}

ProcessMaker/Http/Resources/Caching/EtagManager.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace ProcessMaker\Http\Resources\Caching;
+
+use Closure;
+use Illuminate\Http\Request;
+use Illuminate\Support\Str;
+use Symfony\Component\HttpFoundation\Response;
+
+class EtagManager
+{
+    /**
+     * The callback used to generate the ETag.
+     */
+    protected static ?Closure $etagGenerateCallback = null;
+
+    /**
+     * Set a callback that should be used when generating the ETag.
+     */
+    public static function etagGenerateUsing(?Closure $callback): void
+    {
+        static::$etagGenerateCallback = $callback;
+    }
+
+    /**
+     * Get ETag value for this request and response.
+     */
+    public static function getEtag(Request $request, Response $response, bool $includeUser = false): string
+    {
+        $etag = static::$etagGenerateCallback
+            ? call_user_func(static::$etagGenerateCallback, $request, $response, $includeUser)
+            : static::defaultGetEtag($response, $includeUser);
+
+        return (string) Str::of($etag)->start('"')->finish('"');
+    }
+
+    /**
+     * Generate an ETag, optionally including user-specific data.
+     */
+    private static function defaultGetEtag(Response $response, bool $includeUser = false): string
+    {
+        if ($includeUser) {
+            return md5(auth()->id() . $response->getContent());
+        }
+
+        return md5($response->getContent());
+    }
+}

routes/v1_1/api.php

@@ -22,6 +22,7 @@
 
             // Route to show the screen of a task
             Route::get('/{taskId}/screen', [TaskController::class, 'showScreen'])
+                ->middleware('etag')
                 ->name('show.screen');
 
             // Route to show the interstitial screen of a task

tests/Feature/Etag/EtagManagerTest.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace ProcessMaker\Tests\Feature\Etag;
+
+use Illuminate\Http\Request;
+use ProcessMaker\Http\Resources\Caching\EtagManager;
+use Symfony\Component\HttpFoundation\Response;
+use Tests\TestCase;
+
+class EtagManagerTest extends TestCase
+{
+    private string $response = 'OK';
+
+    public function tearDown(): void
+    {
+        EtagManager::etagGenerateUsing(null);
+    }
+
+    public function testGetDefaultEtag()
+    {
+        $request = Request::create('/', 'GET');
+        $response = response($this->response, 200);
+
+        $this->assertEquals('"e0aa021e21dddbd6d8cecec71e9cf564"', EtagManager::getEtag($request, $response));
+    }
+
+    public function testGetEtagWithCallbackMd5()
+    {
+        $request = Request::create('/', 'GET');
+        $response = response($this->response, 200);
+
+        EtagManager::etagGenerateUsing(function (Request $request, Response $response) {
+            return md5($response->getContent());
+        });
+
+        $this->assertEquals('"e0aa021e21dddbd6d8cecec71e9cf564"', EtagManager::getEtag($request, $response));
+    }
+
+    public function testGetEtagWithCallbackSha256()
+    {
+        $request = Request::create('/', 'GET');
+        $response = response($this->response, 200);
+
+        EtagManager::etagGenerateUsing(function (Request $request, Response $response) {
+            return hash('sha256', $response->getContent());
+        });
+
+        $expectedHash = hash('sha256', $this->response);
+        $this->assertEquals("\"$expectedHash\"", EtagManager::getEtag($request, $response));
+    }
+}

tests/Feature/Etag/HandleEtagTest.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace ProcessMaker\Tests\Feature\Etag;
+
+use Illuminate\Support\Facades\Route;
+use ProcessMaker\Http\Middleware\Etag\HandleEtag;
+use ProcessMaker\Http\Resources\Caching\EtagManager;
+use ProcessMaker\Models\User;
+use Tests\TestCase;
+
+class HandleEtagTest extends TestCase
+{
+    private string $response = 'OK';
+
+    private const TEST_ROUTE = '/_test/handle-etag';
+
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        // Define a route that uses the HandleEtag middleware.
+        Route::middleware(HandleEtag::class)->any(self::TEST_ROUTE, function () {
+            return response($this->response, 200);
+        });
+    }
+
+    public function testMiddlewareSetsEtagHeader()
+    {
+        $response = $this->get(self::TEST_ROUTE);
+        $response->assertHeader('ETag');
+    }
+
+    public function testEtagHeaderHasCorrectValue()
+    {
+        $expectedEtag = '"' . md5($this->response) . '"';
+        $response = $this->get(self::TEST_ROUTE);
+        $response->assertHeader('ETag', $expectedEtag);
+    }
+
+    public function testRequestReturns200WhenIfNoneMatchDoesNotMatch()
+    {
+        $noneMatch = '"' . md5($this->response . 'NoneMatch') . '"';
+        $response = $this
+            ->withHeaders(['If-None-Match' => $noneMatch])
+            ->get(self::TEST_ROUTE);
+
+        $response->assertStatus(200);
+        $response->assertHeader('ETag');
+    }
+
+    public function testRequestReturns304WhenIfNoneMatchMatches()
+    {
+        $matchingEtag = '"' . md5($this->response) . '"';
+        $response = $this
+            ->withHeaders(['If-None-Match' => $matchingEtag])
+            ->get(self::TEST_ROUTE);
+
+        $response->assertStatus(304);
+        $response->assertHeader('ETag', $matchingEtag);
+    }
+
+    public function testRequestIgnoresWeakEtagsInIfNoneMatch()
+    {
+        $weakEtag = 'W/"' . md5($this->response) . '"';
+        $response = $this
+            ->withHeaders(['If-None-Match' => $weakEtag])
+            ->get(self::TEST_ROUTE);
+
+        $response->assertStatus(304);
+        $response->assertHeader('ETag', '"' . md5($this->response) . '"');
+    }
+
+    public function testDefaultGetEtagGeneratesCorrectEtagWithUser()
+    {
+        $user = User::factory()->create();
+        $this->actingAs($user);
+
+        Route::middleware('etag:user')->any(self::TEST_ROUTE, function () {
+            return response($this->response, 200);
+        });
+
+        $response = $this->get(self::TEST_ROUTE);
+
+        $expectedEtag = '"' . md5($user->id . $this->response) . '"';
+        $response->assertHeader('ETag', $expectedEtag);
+    }
+}