Make routing coroutine-safe and tighten the routing API

[loks0n]

Summary

Routing on this branch was unsafe under coroutines: Router::match wrote setMatchedPath onto the shared Route on every request, the wildcard branch in Http::runInternal called \$route->path() per request, and \$this->route lived as a property on the shared Http instance. Two requests in flight at once could observe each other's matched path.

This PR makes the entire routing path immutable at runtime and lands a smaller, sharper API along the way.

Routing changes

• Router::match returns ?RouteMatch. A final readonly value object carrying (Route \$route, array \$params) — the matched Route and path params already resolved from the request URL. No more in-place mutation of Route to record the matched template.
• No more Route::matchedPath / setMatchedPath / getMatchedPath. Path-param resolution moved to Route::resolveParams(string \$url, string \$matchedTemplate), called once at match time by Router::match.
• The wildcard catch-all flows through Router. Http::wildcard() now registers via Router::setWildcard(\$route). The special-case fallback branch in Http::runInternal is gone; Router::match consults the wildcard slot as a final fallback so wildcard requests follow the same dispatch path as any other route.
• Per-request state lives in \$http->context(). \$this->route and \$this->matchedPath properties on Http are gone. The matched route is set in the per-request context ('route' key) for the ->inject('route') API and for telemetry.

API changes

• Http::execute(Request, Response) is now the dispatch primitive: match + handler + hooks, plus OPTIONS/HEAD handling and 404 fallback. Public — safe to call from inside a handler for sub-request dispatch (e.g. GraphQL resolvers synthesizing API calls). Skips request-level setup that belongs to Http::run().
• Http::run(Request, Response) stays the top-level request entry point: compression setup, request hooks, static files, dispatch, telemetry. Wired into the server adapter as before.
• Http::match(Request) stateless: re-runs the lookup every call, no \$fresh flag, no context cache.
• Removed: Http::setRoute(), Http::getRoute(), Http::matchInternal(), the \$fresh parameter on match(), Route::setMatchedPath/getMatchedPath. The supported way to consume the matched route inside a hook/action is the 'route' injection.
• Route::getPathValues(Request) → Route::resolveParams(string \$url, string \$matchedTemplate). Takes a URL string instead of a Request — it never needed anything else from the Request.

Downstream migration

This breaks the Appwrite GraphQL resolver pattern (`Resolvers::resolve` in `Appwrite\GraphQL\Resolvers`). The migration is small but not zero:

• `$utopia->match($request, fresh: true)` → `$utopia->match($request)?->route`
• `$utopia->execute($route, $request, $response)` → `$utopia->execute($request, $response)`
• `$utopia->getRoute()` / `$utopia->setRoute($original)` save-restore — drop, or replace with direct context manipulation if telemetry accuracy on the outer request matters.

The new GraphQL flow is shorter than the old one — execute does its own match, no need to thread the Route through.

Known follow-ups (out of scope)

• Hook::setParamValue mutates static hooks per request. Same bug class as the Route mutation we fixed. Hooks live in self::\$init / \$shutdown / \$errors etc., shared across coroutines. Worth a separate PR.
• Static route registration is not enforced as boot-only. Router::\$routes, \$wildcard, Http::\$init etc. mutate via static methods. Fine at boot, race city if anyone calls Http::get(...) mid-request. Worth a class-doc note and possibly a frozen-after-start flag.

Test plan

• vendor/bin/phpstan analyse clean
• vendor/bin/phpunit --exclude-group e2e — 101 tests, 237 assertions, 0 failures (only the docker-required e2e tests error, unrelated)
• Swoole e2e tests (require docker)
• Sanity-check downstream GraphQL migration in Appwrite

🤖 Generated with Claude Code

[github-actions]

k6 benchmark

Throughput	Requests	Fail rate	p50	p95
7878 req/s	551543	0%	4.79 ms	12.62 ms

[greptile-apps]

Greptile Summary

This PR makes the routing path coroutine-safe by eliminating all per-request mutations on shared objects: Route::setMatchedPath is gone, $this->route on Http is gone, and the wildcard route is no longer stamped with the actual request URL mid-flight. The new RouteMatch value object carries the matched route and resolved params immutably from lookup to dispatch, and ->inject('route') is now resolved directly in getArguments rather than through shared context.

• Router::match returns ?RouteMatch instead of ?Route; Http::execute now takes (Request, Response) and does its own match internally, making it safe to call re-entrantly from handlers.
• Route::resolveParams(string $url, string $matchedTemplate) replaces getPathValues(Request, string), decoupling param resolution from the Request object and incidentally fixing a latent bug where query-string content leaked into path-param values.
• The wildcard catch-all is registered via Router::setWildcard and flows through the same Router::match path as all other routes, removing the special-case branch in runInternal.

Confidence Score: 3/5

Mostly safe to merge, but wildcard-route handlers that read getPath() to discover the matched URL will silently receive an empty string after this change.

The wildcard route is now created as Route('', '') and its path is never updated to the actual request URL — the old $route->path($path) mutation was removed as part of the coroutine-safety work. Any handler that injects the route and calls getPath() to discover which URL hit the wildcard will now always get ''. This is a concrete behavioral regression not covered by the test suite and not mentioned in the migration guide.

src/Http/Http.php — specifically the wildcard() method and execute() dispatch path for wildcard routes; the telemetry block in run() also warrants a second look.

Important Files Changed

Filename	Overview
src/Http/Http.php	Core dispatch rewrite: removes shared mutable $route/$wildcardRoute state, introduces execute(Request, Response) as re-entrant primitive, and passes route directly through getArguments to make ->inject('route') frame-local. The wildcard route no longer has its path stamped to the actual URL (regression for handlers using $route->getPath()), and run() performs a redundant match() call for telemetry.
src/Http/Router.php	Return type changed from ?Route to ?RouteMatch; wildcard slot moved here from Http; setMatchedPath mutation eliminated. Logic is clean and tests cover the key paths.
src/Http/RouteMatch.php	New final readonly value object carrying a matched Route and its resolved path params — straightforward and correct.
src/Http/Route.php	Removes matchedPath mutation and renames getPathValues(Request, string) to resolveParams(string, string) — decoupling from Request is an improvement and also fixes a latent bug where query-string content was included in path-param values.
tests/HttpTest.php	Tests updated to use execute(Request, Response) and match()?->route; new testSubrequestRestoresOuterRoute validates re-entrant dispatch isolation. testWildcardRoute doesn't assert getPath() on the wildcard route, so the behavior regression there isn't caught.
tests/RouterTest.php	Tests updated to unpack ?->route from the new ?RouteMatch return type; all existing match-path and match-method assertions are preserved.

_{Reviews (7): Last reviewed commit: "Make 'route' injection frame-local inste..." | Re-trigger Greptile}

[greptile-apps]

Wildcard route's getPath() now returns '' — undocumented behavior change

The old code called $route->path($path) to stamp the actual request URL onto the shared wildcard route before dispatch, so handlers that did ->inject('route') and read $route->getPath() would receive the real URL (e.g. /unknown/path). That mutation was coroutine-unsafe and is correctly removed here, but the replacement leaves getPath() returning '' for every wildcard match. Any downstream handler that used $route->getPath() to discover the wildcard-matched URL will silently receive '' instead. The migration guide does not mention this change; consider noting that handlers should switch to ->inject('request') and read $request->getURI() instead.