feat(router): add #[Stateless] attribute (#1692)

Co-authored-by: Enzo Innocenzi <enzo@innocenzi.dev>

Author: brendt

docs/1-essentials/01-routing.md

@@ -631,6 +631,23 @@ final class ErrorResponseProcessor implements ResponseProcessor
 }
 ```
 
+## Stateless routes
+
+When you're building API endpoints, RSS pages, or any other kind of page that does not require any cookie or session data, you may use the `{#[Tempest\Router\Stateless]}` attribute, which will remove all state-related logic:
+
+```php
+use Tempest\Router\Stateless;
+use Tempest\Router\Get;
+
+final readonly class JsonController
+{
+    #[Stateless]
+    #[Get('/json')]
+    public function json(string $path): Response
+    { /* … */ }
+}
+```
+
 ## Custom route attributes
 
 It is often a requirement to have a bunch of routes following the same specifications—for instance, using the same middleware, or the same URI prefix.

packages/router/src/GenericRouter.php

@@ -11,6 +11,7 @@
 use Tempest\Http\Request;
 use Tempest\Http\Response;
 use Tempest\Http\Responses\Ok;
+use Tempest\Http\Session\VerifyCsrfMiddleware;
 use Tempest\Router\Exceptions\ControllerActionHadNoReturn;
 use Tempest\Router\Exceptions\MatchedRouteCouldNotBeResolved;
 use Tempest\Router\Routing\Matching\RouteMatcher;
@@ -70,12 +71,32 @@ private function getCallable(): HttpMiddlewareCallable
         $middlewareStack = $this->routeConfig->middleware;
 
         foreach ($middlewareStack->unwrap() as $middlewareClass) {
-            $callable = new HttpMiddlewareCallable(function (Request $request) use ($middlewareClass, $callable) {
-                // We skip this middleware if it's ignored by the route
+            $callable = new HttpMiddlewareCallable(closure: function (Request $request) use ($middlewareClass, $callable) {
                 if ($this->container->has(MatchedRoute::class)) {
                     $matchedRoute = $this->container->get(MatchedRoute::class);
 
-                    if (in_array($middlewareClass->getName(), $matchedRoute->route->without, strict: true)) {
+                    // Skip the middleware if it's ignored by the route
+                    if (in_array(
+                        needle: $middlewareClass->getName(),
+                        haystack: $matchedRoute->route->without,
+                        strict: true,
+                    )) {
+                        return $callable($request);
+                    }
+
+                    // Skip middleware that sets cookies or session values when the route is stateless
+                    if (
+                        $matchedRoute->route->handler->hasAttribute(Stateless::class)
+                        && in_array(
+                            needle: $middlewareClass->getName(),
+                            haystack: [
+                                VerifyCsrfMiddleware::class,
+                                SetCurrentUrlMiddleware::class,
+                                SetCookieMiddleware::class,
+                            ],
+                            strict: true,
+                        )
+                    ) {
                         return $callable($request);
                     }
                 }

packages/router/src/Stateless.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Tempest\Router;
+
+use Attribute;
+
+/**
+ * Mark a route handler as stateless, causing all cookie- and session-related middleware to be skipped.
+ */
+#[Attribute(Attribute::TARGET_METHOD)]
+final class Stateless
+{
+}

src/Tempest/Framework/Testing/Http/TestResponseHelper.php

@@ -184,6 +184,26 @@ public function assertHasCookie(string $key, null|string|Closure $value = null):
         return $this;
     }
 
+    public function assertDoesNotHaveCookie(string $key, null|string|Closure $value = null): self
+    {
+        /** @var array<string,Cookie> */
+        $cookies = Arr\map_with_keys(
+            array: $this->response->getHeader('set-cookie')->values ?? [],
+            map: function (string $cookie) {
+                $cookie = Cookie::createFromString($cookie);
+                yield $cookie->key => $cookie;
+            },
+        );
+
+        Assert::assertArrayNotHasKey(
+            key: $key,
+            array: $cookies,
+            message: sprintf("A cookie was set for [%s], while it shouldn't have been", $key),
+        );
+
+        return $this;
+    }
+
     public function assertHasSession(string $key, ?Closure $callback = null): self
     {
         $this->assertHasContainer();

tests/Integration/Route/Fixtures/StatelessController.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Tests\Tempest\Integration\Route\Fixtures;
+
+use Tempest\Http\Responses\Ok;
+use Tempest\Router\Get;
+use Tempest\Router\Stateless;
+
+final class StatelessController
+{
+    #[Stateless]
+    #[Get('/stateless')]
+    public function __invoke(): Ok
+    {
+        return new Ok();
+    }
+}

tests/Integration/Route/RouterTest.php

@@ -11,6 +11,7 @@
 use Tempest\Database\Migrations\CreateMigrationsTable;
 use Tempest\Http\HttpRequestFailed;
 use Tempest\Http\Responses\Ok;
+use Tempest\Http\Session\VerifyCsrfMiddleware;
 use Tempest\Http\Status;
 use Tempest\Router\GenericRouter;
 use Tempest\Router\RouteConfig;
@@ -25,6 +26,7 @@
 use Tests\Tempest\Integration\FrameworkIntegrationTestCase;
 use Tests\Tempest\Integration\Route\Fixtures\HeadController;
 use Tests\Tempest\Integration\Route\Fixtures\Http500Controller;
+use Tests\Tempest\Integration\Route\Fixtures\StatelessController;
 
 /**
  * @internal
@@ -258,4 +260,15 @@ public function test_head_requests(): void
             ->assertOk()
             ->assertHasHeader('x-custom');
     }
+
+    public function test_stateless_actions(): void
+    {
+        $this->registerRoute(StatelessController::class);
+
+        $this->http
+            ->get('/stateless')
+            ->assertOk()
+            ->assertDoesNotHaveCookie('tempest_session_id')
+            ->assertDoesNotHaveCookie(VerifyCsrfMiddleware::CSRF_COOKIE_KEY);
+    }
 }