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.
• 'route' injection is frame-local. No \$this->route property, no context['route'] slot. Each dispatch frame carries its own matched Route as a parameter through getArguments; nested execute() calls (sub-request dispatch) can't trample each other.

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 and pure: returns ?RouteMatch, writes nothing.
• 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. `execute()` now manages the dispatch frame for you; nested calls don't leak.

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

Wildcard handlers

Previously the wildcard route's getPath() returned the current request's URL (e.g. /unknown/path) because Http::runInternal mutated the shared wildcard Route on every request. That mutation was the original race. It's gone, so wildcard handlers reading \$route->getPath() now see '' (the route's registration template, which is empty by construction).

If you have a wildcard handler that needs the matched URL, switch to:

```php
Http::wildcard()
->inject('request')
->action(function ($request) {
$url = $request->getURI();
});
```

The matched URL is a per-request concern and belongs on the Request, not the Route.

For OTel: wildcard / no-match telemetry now correctly emits http.route as unset (rather than as an empty string) per OTel semantic conventions.

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 — 102 tests, 238 assertions, 0 failures (only the docker-required e2e tests error, unrelated)
• Regression test: testSubrequestRestoresOuterRoute covers nested execute() not leaking the inner match
• 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
8253 req/s	577879	0%	4.83 ms	11.02 ms

[greptile-apps]

Greptile Summary

This PR makes routing coroutine-safe by eliminating all in-place mutation of shared state during request dispatch: Route::setMatchedPath is removed, the wildcard route is moved into Router, and $this->route / context('route') are replaced with a frame-local $locals array inside getArguments. The new RouteMatch value object carries the matched route and already-resolved path params, and execute(Request, Response) becomes a fully self-contained, re-entrant dispatch primitive.

• Router::match now returns ?RouteMatch instead of mutating the shared Route; both RouterTest and HttpTest are updated to unpack ?->route from the result.
• execute(Request, Response) replaces execute(Route, Request, Response): it does its own match, handles HEAD/OPTIONS/404 internally, and passes the matched Route as a frame-local injection rather than writing to shared context — preventing sub-request dispatch from clobbering the outer request's route injection.
• Wildcard registration moved from Http::$wildcardRoute to Router::$wildcard, so Router::match handles it as the final fallback in one unified code path; Router::reset() clears it along with the route table.

Confidence Score: 4/5

The change is safe to merge; the coroutine-safety fix is well-targeted and the new test covers the sub-request isolation guarantee.

The rewrite is large but focused — the core dispatch path, the wildcard fallback, and all test call-sites were updated consistently. The one inconsistency found (bare -> vs ?-> in the OPTIONS group-hooks branch) is a readability issue only; it cannot cause a null dereference at runtime because the enclosing foreach already guarantees $match is non-null. The public API break on Router::match and Http::match return types is intentional and documented, and all in-tree callers were updated.

No files require special attention beyond the single null-safety inconsistency on line 555 of src/Http/Http.php.

Important Files Changed

Filename	Overview
src/Http/Http.php	Core dispatch rewrite: removes $this->route and context('route') mutation in favour of frame-local route injection; execute() now does its own match; run() re-calls match() post-dispatch for telemetry. One minor null-safety inconsistency in the OPTIONS group-hooks branch.
src/Http/Router.php	match() return type changed from ?Route to ?RouteMatch; wildcard slot moved here from Http; setMatchedPath mutation removed; reset() now clears the wildcard. Clean and correct.
src/Http/RouteMatch.php	New final readonly value object carrying the matched Route and resolved path params. Straightforward and correctly immutable.
src/Http/Route.php	Removes matchedPath mutation; renames getPathValues(Request) to resolveParams(string, string), taking a URL string directly. Clean simplification.
tests/HttpTest.php	Tests updated to new API (execute(Request, Response), match() returns ?RouteMatch); adds testSubrequestRestoresOuterRoute and params-injection tests; removes now-deleted getRoute/setRoute test.
tests/RouterTest.php	All assertions updated to unpack ?->route from the new RouteMatch return type. No logic changes.

_{Reviews (10): Last reviewed commit: "Rename frameLocals to locals" | Re-trigger Greptile}