Introduce Router\Result DTO for match results

Replace the [Route, matchedPath] tuple with a readonly Router\Result
value object so callers get named, typed access instead of positional
unpacking.

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

Author: loks0n

src/Http/Http.php

@@ -3,6 +3,7 @@
 namespace Utopia\Http;
 
 use Utopia\DI\Container;
+use Utopia\Http\Router\Result as RouterResult;
 use Utopia\Servers\Hook;
 use Utopia\Telemetry\Adapter as Telemetry;
 use Utopia\Telemetry\Adapter\None as NoTelemetry;
@@ -540,20 +541,19 @@ public function start(): void
      */
     public function match(Request $request, bool $fresh = true): ?Route
     {
-        return $this->matchInternal($request, $fresh)[0] ?? null;
+        return $this->matchInternal($request, $fresh)?->route;
     }
 
     /**
-     * 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.
+     * Match a request and return the {@see RouterResult} carrying both the
+     * Route and the route key it matched against. Returning the matched key
+     * via the Result avoids mutating the shared Route instance, which would
+     * race under coroutines.
      *
      * Caches the result in the per-request context so re-matches with
      * $fresh=false hit memory without re-running Router::match.
-     *
-     * @return array{0: Route, 1: string}|null
      */
-    private function matchInternal(Request $request, bool $fresh = true): ?array
+    private function matchInternal(Request $request, bool $fresh = true): ?RouterResult
     {
         $context = $this->context();
 
@@ -563,7 +563,7 @@ private function matchInternal(Request $request, bool $fresh = true): ?array
                 $matchedPath = $context->has('matchedPath')
                     ? (string) $context->get('matchedPath')
                     : '';
-                return [$route, $matchedPath];
+                return new RouterResult($route, $matchedPath);
             }
         }
 
@@ -572,17 +572,18 @@ private function matchInternal(Request $request, bool $fresh = true): ?array
         $method = $request->getMethod();
         $method = (self::REQUEST_METHOD_HEAD === $method) ? self::REQUEST_METHOD_GET : $method;
 
-        $match = Router::match($method, $url);
+        $result = Router::match($method, $url);
 
-        if ($match === null) {
+        if ($result === null) {
             return null;
         }
 
-        [$route, $matchedPath] = $match;
+        $route = $result->route;
+        $matchedPath = $result->matchedPath;
         $context->set('route', fn() => $route, []);
         $context->set('matchedPath', fn() => $matchedPath, []);
 
-        return $match;
+        return $result;
     }
 
     /**
@@ -823,8 +824,8 @@ private function runInternal(Request $request, Response $response): static
 
         $method = $request->getMethod();
         $match = $this->matchInternal($request);
-        $route = $match[0] ?? null;
-        $matchedPath = $match[1] ?? '';
+        $route = $match?->route;
+        $matchedPath = $match->matchedPath ?? '';
         $groups = ($route instanceof Route) ? $route->getGroups() : [];
 
         if (self::REQUEST_METHOD_HEAD === $method) {

src/Http/Router.php

@@ -3,6 +3,7 @@
 namespace Utopia\Http;
 
 use Exception;
+use Utopia\Http\Router\Result;
 
 class Router
 {
@@ -121,17 +122,16 @@ public static function setWildcard(?Route $route): void
     /**
      * 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 method-agnostic wildcard). Returning the matched key avoids
-     * mutating the shared Route instance, which would race under coroutines.
-     *
-     * @return array{0: Route, 1: string}|null
+     * Returns a {@see Result} carrying the matched Route together with the
+     * route key it matched against (the registered template after placeholder
+     * substitution, '*' for a wildcard, or '' for the method-agnostic
+     * wildcard). Returning the key separately avoids mutating the shared
+     * Route instance, which would race under coroutines.
      */
-    public static function match(string $method, string $path): ?array
+    public static function match(string $method, string $path): ?Result
     {
         if (!\array_key_exists($method, self::$routes)) {
-            return self::$wildcard !== null ? [self::$wildcard, ''] : null;
+            return self::$wildcard !== null ? new Result(self::$wildcard, '') : null;
         }
 
         $parts = array_values(array_filter(explode('/', $path), fn($segment) => $segment !== ''));
@@ -149,7 +149,7 @@ public static function match(string $method, string $path): ?array
             );
 
             if (\array_key_exists($match, self::$routes[$method])) {
-                return [self::$routes[$method][$match], $match];
+                return new Result(self::$routes[$method][$match], $match);
             }
         }
 
@@ -158,7 +158,7 @@ public static function match(string $method, string $path): ?array
          */
         $match = self::WILDCARD_TOKEN;
         if (\array_key_exists($match, self::$routes[$method])) {
-            return [self::$routes[$method][$match], $match];
+            return new Result(self::$routes[$method][$match], $match);
         }
 
         /**
@@ -168,12 +168,12 @@ public static function match(string $method, string $path): ?array
             $current = ($current ?? '') . "{$part}/";
             $match = $current . self::WILDCARD_TOKEN;
             if (\array_key_exists($match, self::$routes[$method])) {
-                return [self::$routes[$method][$match], $match];
+                return new Result(self::$routes[$method][$match], $match);
             }
         }
 
         if (self::$wildcard !== null) {
-            return [self::$wildcard, ''];
+            return new Result(self::$wildcard, '');
         }
 
         return null;

src/Http/Router/Result.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Utopia\Http\Router;
+
+use Utopia\Http\Route;
+
+/**
+ * Immutable result of {@see \Utopia\Http\Router::match()}.
+ *
+ * Carries the matched Route together with the route key it matched against
+ * (the registered template after placeholder substitution, '*' for a wildcard,
+ * or '' for the method-agnostic wildcard). Returning a value object instead of
+ * mutating the Route avoids racing the shared Route under coroutines.
+ */
+final readonly class Result
+{
+    public function __construct(
+        public Route $route,
+        public string $matchedPath,
+    ) {
+    }
+}