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);
+ }
+}

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);
+ }
+}

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);
+ }
+}

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);
+ }
+}

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);
+ }
+}

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);
+ }
+}

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);
+ }
+}

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);
+ }
+}