Make routing coroutine-safe by removing Route mutations

Router::match and the wildcard branch in Http::runInternal both wrote
to the shared Route singleton (setMatchedPath, path) on every request.
Under Swoole coroutines the Route is shared across in-flight requests,
so concurrent requests could observe each other's matched path.

- Router::match now returns [Route, matchedPath] instead of mutating
  the Route. A new Router::setFallback slot replaces Http::$wildcardRoute,
  so the method-agnostic catch-all flows through the same matching path
  as any other route.
- Route::matchedPath / setMatchedPath / getMatchedPath are removed.
- Http::execute takes the matched path as a parameter; runInternal
  threads it through. Public Http::match keeps its ?Route shape.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: loks0n

src/Http/Http.php

@@ -106,10 +106,11 @@ class Http
     protected ?Route $route = null;
 
     /**
-     * Wildcard route
-     * If set, this get's executed if no other route is matched
+     * Matched route key (template after placeholder substitution).
+     *
+     * Cached alongside $route for $fresh=false re-matches.
      */
-    protected static ?Route $wildcardRoute = null;
+    protected string $matchedPath = '';
 
     /**
      * Compression
@@ -242,9 +243,10 @@ public static function delete(string $url): Route
      */
     public static function wildcard(): Route
     {
-        self::$wildcardRoute = new Route('', '');
+        $route = new Route('', '');
+        Router::setFallback($route);
 
-        return self::$wildcardRoute;
+        return $route;
     }
 
     /**
@@ -545,30 +547,54 @@ public function start(): void
      * @param  bool  $fresh If true, will not match any cached route
      */
     public function match(Request $request, bool $fresh = true): ?Route
+    {
+        return $this->matchInternal($request, $fresh)[0] ?? null;
+    }
+
+    /**
+     * Match a request and return both the matched Route and the route key it
+     * matched against. Returning the matched key separately avoids mutating
+     * the shared Route instance, which would race under coroutines.
+     *
+     * @return array{0: Route, 1: string}|null
+     */
+    private function matchInternal(Request $request, bool $fresh = true): ?array
     {
         if (null !== $this->route && !$fresh) {
-            return $this->route;
+            return [$this->route, $this->matchedPath];
         }
 
         $url = parse_url($request->getURI(), PHP_URL_PATH);
         $url = \is_string($url) ? ($url === '' ? '/' : $url) : '/';
         $method = $request->getMethod();
         $method = (self::REQUEST_METHOD_HEAD === $method) ? self::REQUEST_METHOD_GET : $method;
 
-        $this->route = Router::match($method, $url);
+        $match = Router::match($method, $url);
+
+        if ($match === null) {
+            $this->route = null;
+            $this->matchedPath = '';
+            return null;
+        }
+
+        [$this->route, $this->matchedPath] = $match;
 
-        return $this->route;
+        return $match;
     }
 
     /**
-     * Execute a given route with middlewares and error handling
+     * Execute a given route with middlewares and error handling.
+     *
+     * $matchedPath is the route key this request matched against (the
+     * registered template after placeholder substitution). Pass '' for the
+     * fallback route or when path params aren't relevant.
      */
-    public function execute(Route $route, Request $request, Response $response): static
+    public function execute(Route $route, Request $request, Response $response, string $matchedPath = ''): static
     {
         $arguments = [];
         $groups = $route->getGroups();
 
-        $preparedPath = Router::preparePath($route->getMatchedPath());
+        $preparedPath = Router::preparePath($matchedPath);
         $pathValues = $route->getPathValues($request, $preparedPath[0]);
 
         try {
@@ -790,7 +816,9 @@ private function runInternal(Request $request, Response $response): static
         }
 
         $method = $request->getMethod();
-        $route = $this->match($request);
+        $match = $this->matchInternal($request);
+        $route = $match[0] ?? null;
+        $matchedPath = $match[1] ?? '';
         $groups = ($route instanceof Route) ? $route->getGroups() : [];
 
         $this->context()->set('route', fn() => $route, []);
@@ -830,17 +858,8 @@ private function runInternal(Request $request, Response $response): static
             return $this;
         }
 
-        if (null === $route && null !== self::$wildcardRoute) {
-            $route = self::$wildcardRoute;
-            $this->route = $route;
-            $path = parse_url($request->getURI(), PHP_URL_PATH);
-            $path = \is_string($path) ? ($path === '' ? '/' : $path) : '/';
-            $route->path($path);
-
-            $this->context()->set('route', fn() => $route, []);
-        }
         if (null !== $route) {
-            return $this->execute($route, $request, $response);
+            return $this->execute($route, $request, $response, $matchedPath);
         }
 
         if (self::REQUEST_METHOD_OPTIONS === $method) {
@@ -923,6 +942,5 @@ public static function reset(): void
         self::$options = [];
         self::$startHooks = [];
         self::$requestHooks = [];
-        self::$wildcardRoute = null;
     }
 }

src/Http/Route.php

@@ -38,8 +38,6 @@ class Route extends Hook
      */
     protected int $order;
 
-    protected string $matchedPath = '';
-
     public function __construct(string $method, string $path)
     {
         parent::__construct();
@@ -48,17 +46,6 @@ public function __construct(string $method, string $path)
         $this->order = ++self::$counter;
     }
 
-    public function setMatchedPath(string $path): self
-    {
-        $this->matchedPath = $path;
-        return $this;
-    }
-
-    public function getMatchedPath(): string
-    {
-        return $this->matchedPath;
-    }
-
     /**
      * Get Route Order ID
      */

src/Http/Router.php

@@ -14,6 +14,11 @@ class Router
 
     protected static bool $allowOverride = false;
 
+    /**
+     * Fallback route used when no method-specific route matches. Method-agnostic.
+     */
+    protected static ?Route $fallback = null;
+
     /**
      * @var array<string,Route[]>
      */
@@ -105,13 +110,28 @@ public static function addRouteAlias(string $path, Route $route): void
         self::$routes[$route->getMethod()][$alias] = $route;
     }
 
+    /**
+     * Set the method-agnostic fallback route used when nothing else matches.
+     */
+    public static function setFallback(?Route $route): void
+    {
+        self::$fallback = $route;
+    }
+
     /**
      * Match route against the method and path.
+     *
+     * Returns the matched Route together with the route key it matched against
+     * (the registered template after placeholder substitution, or '*' for a
+     * wildcard, or '' for the fallback). Returning the matched key avoids
+     * mutating the shared Route instance, which would race under coroutines.
+     *
+     * @return array{0: Route, 1: string}|null
      */
-    public static function match(string $method, string $path): ?Route
+    public static function match(string $method, string $path): ?array
     {
         if (!\array_key_exists($method, self::$routes)) {
-            return null;
+            return self::$fallback !== null ? [self::$fallback, ''] : null;
         }
 
         $parts = array_values(array_filter(explode('/', $path), fn($segment) => $segment !== ''));
@@ -129,9 +149,7 @@ public static function match(string $method, string $path): ?Route
             );
 
             if (\array_key_exists($match, self::$routes[$method])) {
-                $route = self::$routes[$method][$match];
-                $route->setMatchedPath($match);
-                return $route;
+                return [self::$routes[$method][$match], $match];
             }
         }
 
@@ -140,9 +158,7 @@ public static function match(string $method, string $path): ?Route
          */
         $match = self::WILDCARD_TOKEN;
         if (\array_key_exists($match, self::$routes[$method])) {
-            $route = self::$routes[$method][$match];
-            $route->setMatchedPath($match);
-            return $route;
+            return [self::$routes[$method][$match], $match];
         }
 
         /**
@@ -152,12 +168,14 @@ public static function match(string $method, string $path): ?Route
             $current = ($current ?? '') . "{$part}/";
             $match = $current . self::WILDCARD_TOKEN;
             if (\array_key_exists($match, self::$routes[$method])) {
-                $route = self::$routes[$method][$match];
-                $route->setMatchedPath($match);
-                return $route;
+                return [self::$routes[$method][$match], $match];
             }
         }
 
+        if (self::$fallback !== null) {
+            return [self::$fallback, ''];
+        }
+
         return null;
     }
 
@@ -219,6 +237,7 @@ public static function preparePath(string $path): array
     public static function reset(): void
     {
         self::$params = [];
+        self::$fallback = null;
         self::$routes = [
             Http::REQUEST_METHOD_GET => [],
             Http::REQUEST_METHOD_POST => [],