fix(routing): close three byte-identity gaps in the URL generator (review)

A deep parity review (+ two adversarial audits) of the route() fast path against
vanilla's full RouteUrlGenerator::to() found three issues. All proven against a
vanilla oracle before/after, and regression-tested.

1. Empty-string param value (BYTE-IDENTITY): route('u', ['user' => '']) returned
   /api/users; vanilla treats '' as a *missing* named param (leaves {user} literal)
   and throws UrlGenerationException. Now defers on $value === ''.

2. Duplicate parameter names (BYTE-IDENTITY): {a}/{a} positional returned /api/5/6;
   vanilla fills the first {a} and throws on the second. greaseCompileEntry now
   returns false for routes with duplicate param names (never indexed).

3. forceRootUrl()/useOrigin() with a path, relative URL (BYTE-IDENTITY): the
   relative shortcut never consulted formatRoot(), dropping a forced root path
   ('/app/...' -> '/...'). The relative branch now derives from the full absolute
   URI and applies vanilla's exact root+base-path strip, so forced-root paths and
   subdirectory base paths are preserved (and the prior subdirectory defer is gone —
   broader coverage, all byte-identical).

4. Prewarm seed wiped under route:cache (PERF, not correctness): the framework's
   booted-phase cached-routes load rebinds 'routes' -> setRoutes() -> flush, which
   wiped a boot()-time URL-index seed. Seeding now runs on an app->booted() callback
   (registered after RouteServiceProvider's), so it lands after the route load and
   survives into requests. (Lazy fallback was already byte-identical; this restores
   the intended FPM/Octane prewarm.)

Provider rebind, signed URLs, Octane persistence, command enumeration, and L10-13
container semantics all audited clean (no breaking changes).

Tests: +3 regressions (empty/dup throw-like-vanilla, forced-root parity,
seed-survives-rebind). 638 tests / 1810 assertions green; Pint + docs build clean.

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

Author: serpentblade

CHANGELOG.md

@@ -17,20 +17,25 @@ All notable changes to `grease` are documented here. The format is based on
   **−93% per call**, and because the assembly cost is fixed while the model tiers shrink everything
   else, **~−26% of an already-greased API-Resource response** (−84.7% full-stack on a 500-row ×
   ~5-link payload). Byte-identical to vanilla or it defers — domain routes, optional `{param?}` /
-  scoped `{param:field}` bindings, route-level defaults, extra params (query string), signed /
-  absolute-in-a-subdirectory URLs, and any `URL::defaults()` / `formatHostUsing()` /
-  `formatPathUsing()` customization all fall through to `parent::`. Absolute (the `route()` default)
-  and relative are both accelerated. Verified by `UrlGeneratorParityTest` (oracle = vanilla across
-  absolute/relative, every defer case, special-char encoding, the missing-param exception, secure
-  scheme, subdirectory apps, and prewarm-seed parity).
+  scoped `{param:field}` bindings, route-level defaults, duplicate parameter names, extra params
+  (query string), arity mismatches, empty-string / non-scalar values, signed URLs, and any
+  `URL::defaults()` / `formatHostUsing()` / `formatPathUsing()` customization all fall through to
+  `parent::`. Absolute (the `route()` default) and relative are both accelerated; the relative path
+  derives from the full absolute URI and strips exactly what vanilla strips, so a `forceRootUrl()` /
+  `useOrigin()` root path and a subdirectory base path are preserved. Verified by
+  `UrlGeneratorParityTest` (oracle = vanilla across absolute/relative, every defer case,
+  special-char encoding, the missing-param exception, secure scheme, subdirectory + forced-root
+  apps, and prewarm-seed parity).
 - **`Grease\Routing\GreaseRoutingServiceProvider` now swaps the `url` singleton** for the greased
   generator (no `bootstrap/app.php` edit — unlike the kernel-injected router, `url` is resolved
   lazily, so a provider rebind is in time; the framework's session/key resolvers and `routes`
   rebinding survive it, so signed URLs and route-cache rebinding are unchanged).
 - **`grease:route-cache` now also writes an opcache-interned URL shape index** (`name =>
   [segments, params]`) alongside the middleware index, via the same `greaseCompileEntry()` the lazy
   path uses, so a pre-seeded entry is byte-identical to one compiled on first `route()`. The
-  provider loads it under the same freshness check. The prewarm's payoff is FPM cold-build
+  provider loads it under the same freshness check, on a `booted` callback — after the framework's
+  cached-routes load (which rebinds `routes` → `setRoutes()` → flushes the index), so the seed
+  survives into requests rather than being wiped. The prewarm's payoff is FPM cold-build
   elimination (sub-ms, scales with route count) and Octane build-once-ever — not a per-response
   render win (the lazy index self-warms on first call); the −26% comes from the assembly collapse,
   which lands cold or warm.

docs/guide/url-generator.md

@@ -47,14 +47,18 @@ result is provably the exact string vanilla would build. Anything else falls str
 - a route with a **domain** (it assembles a host),
 - an **optional** `{param?}` or **scoped** `{param:field}` binding (different replacement
   semantics),
-- a route carrying its own **`$defaults`**.
+- a route carrying its own **`$defaults`**,
+- a **duplicate parameter name** (`{a}/{a}`) — malformed; vanilla fills the first and throws on
+  the second.
 
 **Not fast-pathable** (decided per call):
 
 - **extra parameters** — they become a query string,
 - an **arity mismatch** — too few is vanilla's `UrlGenerationException`, which must still throw,
 - a **non-scalar** value (after `UrlRoutable::getRouteKey()`) — `null`/`bool`/`float`/array have
   distinct vanilla semantics,
+- an **empty-string** value — vanilla treats it as a *missing* parameter (leaves `{name}` literal)
+  and throws,
 - a value that would inject a literal `{…}` — vanilla treats that as a missing parameter and throws,
 - a **subdirectory app** for a *relative* URL (non-empty `Request::getBaseUrl()`),
 - any **`URL::defaults()`**, **`formatHostUsing()`**, or **`formatPathUsing()`** customization in

src/Routing/GreaseRoutingServiceProvider.php

@@ -56,7 +56,16 @@ public function boot(): void
         }
 
         $this->loadMiddlewareIndex();
-        $this->loadUrlIndex();
+
+        // Seed the URL index on a `booted` callback, NOT here. A cached-routes load
+        // (`RouteServiceProvider`'s own booted callback) re-binds `routes`, firing the
+        // framework's `rebinding('routes')` → `UrlGenerator::setRoutes()`, which flushes the
+        // index. That runs in the booted phase, strictly after every provider's `boot()` — so a
+        // seed here would be wiped. Registered now (after `RouteServiceProvider::boot()` queued
+        // its callback), this fires after the route load, so the seed survives into requests.
+        // The middleware index has no such hazard: `setCompiledRoutes()` swaps the route
+        // collection without touching the router's resolved-middleware cache.
+        $this->app->booted(fn () => $this->loadUrlIndex());
     }
 
     /**

src/Routing/UrlGenerator.php

@@ -133,6 +133,12 @@ public static function greaseCompileEntry($route)
         $segments = preg_split('/\{[^}]+\}/', $uri);
         preg_match_all('/\{([^}]+)\}/', $uri, $matches);
 
+        // A duplicate parameter name is malformed: vanilla fills the first `{x}` and leaves the
+        // second in place, throwing. Never index it — let vanilla own that behaviour.
+        if (count($matches[1]) !== count(array_unique($matches[1]))) {
+            return false;
+        }
+
         return ['segments' => $segments, 'params' => $matches[1]];
     }
 
@@ -175,8 +181,10 @@ protected function greaseFastToRoute($route, array $entry, $parameters, bool $ab
                 $value = $value->getRouteKey();
             }
 
-            if (! is_string($value) && ! is_int($value)) {
-                return null; // null/bool/float/array have distinct vanilla semantics
+            if ((! is_string($value) && ! is_int($value)) || $value === '') {
+                // null/bool/float/array have distinct vanilla semantics; an empty string is a
+                // *missing* named parameter to vanilla (it leaves `{name}` in place and throws).
+                return null;
             }
 
             $path .= $value.$segments[$i + 1];
@@ -189,19 +197,23 @@ protected function greaseFastToRoute($route, array $entry, $parameters, bool $ab
 
         $dontEncode = $this->greaseDontEncode ??= $this->routeUrl()->dontEncode;
 
-        if ($absolute) {
-            $scheme = $route->httpOnly() ? 'http://' : ($route->httpsOnly() ? 'https://' : $this->formatScheme());
+        $scheme = $route->httpOnly() ? 'http://' : ($route->httpsOnly() ? 'https://' : $this->formatScheme());
+        $uri = strtr(rawurlencode(trim($this->formatRoot($scheme).'/'.trim($path, '/'), '/')), $dontEncode);
 
-            return strtr(rawurlencode(trim($this->formatRoot($scheme).'/'.trim($path, '/'), '/')), $dontEncode);
+        if ($absolute) {
+            return $uri;
         }
 
-        // Relative: vanilla strips the root and the request base path. The simple form below is
-        // byte-identical only at the document root; a subdirectory app defers.
-        if ($this->request->getBaseUrl() !== '') {
-            return null;
+        // Relative: build the absolute URI (so a forced root path from forceRootUrl()/useOrigin()
+        // is included), then strip scheme+host and the request base path — a verbatim copy of
+        // RouteUrlGenerator::to()'s relative tail, byte-identical for every root shape.
+        $uri = preg_replace('#^(//|[^/?])+#', '', $uri);
+
+        if ($base = $this->request->getBaseUrl()) {
+            $uri = preg_replace('#^'.$base.'#i', '', $uri);
         }
 
-        return '/'.ltrim(strtr(rawurlencode($path), $dontEncode), '/');
+        return '/'.ltrim($uri, '/');
     }
 
     /**

tests/Routing/GreaseRoutingServiceProviderTest.php

@@ -8,7 +8,9 @@
 use Illuminate\Contracts\Console\Kernel;
 use Illuminate\Foundation\Application;
 use Illuminate\Foundation\Configuration\ApplicationBuilder;
+use Illuminate\Http\Request;
 use Orchestra\Testbench\TestCase as Orchestra;
+use ReflectionMethod;
 use ReflectionProperty;
 
 /**
@@ -92,7 +94,7 @@ public function test_url_generator_is_greased_and_still_signs(): void
         $signed = $url->signedRoute('things.show', ['id' => 5]);
         $this->assertStringContainsString('signature=', $signed);
 
-        $request = \Illuminate\Http\Request::create($signed);
+        $request = Request::create($signed);
         $this->assertTrue($url->hasValidSignature($request));
     }
 
@@ -124,6 +126,44 @@ public function test_url_index_round_trips_and_seeds_the_generator(): void
         @unlink($routesCache);
     }
 
+    /**
+     * The hazard the booted-callback seeding guards against: a cached-routes load re-binds
+     * `routes`, firing the framework's `rebinding('routes')` → `UrlGenerator::setRoutes()`, which
+     * flushes the URL index. Seeding in `boot()` would be wiped by that later booted-phase load;
+     * the provider instead seeds on a `booted` callback (after the route load), so loading the
+     * index AFTER a `setRoutes()` flush correctly repopulates it. Regression for a prewarm bug
+     * caught in review.
+     */
+    public function test_url_index_seed_survives_a_routes_rebind(): void
+    {
+        $url = $this->app->make('url');
+
+        $path = GreaseRoutingServiceProvider::urlIndexPath($this->app);
+        $routesCache = $this->app->getCachedRoutesPath();
+        @mkdir(dirname($path), 0777, true);
+        file_put_contents($routesCache, '<?php return [];'.PHP_EOL);
+        touch($routesCache, time() - 10);
+        $entries = ['things.show' => ['segments' => ['things/', ''], 'params' => ['id']]];
+        file_put_contents($path, '<?php return '.var_export($entries, true).';'.PHP_EOL);
+        touch($path, time());
+
+        $indexProp = new ReflectionProperty(GreasedUrlGenerator::class, 'greaseRouteUrlIndex');
+
+        // A boot()-time seed would be wiped here: the compiled-routes load rebinds 'routes'.
+        $url->useGreaseRouteUrlIndex($entries);
+        $url->setRoutes($this->app['router']->getRoutes());
+        $this->assertSame([], $indexProp->getValue($url), 'sanity: a routes rebind flushes the index');
+
+        // The provider seeds on app->booted(), which fires AFTER that load — replay its body.
+        (new ReflectionMethod(GreaseRoutingServiceProvider::class, 'loadUrlIndex'))
+            ->invoke(new GreaseRoutingServiceProvider($this->app));
+
+        $this->assertArrayHasKey('things.show', $indexProp->getValue($url), 'seed must land after the route load');
+
+        @unlink($path);
+        @unlink($routesCache);
+    }
+
     public function test_index_freshness_guard(): void
     {
         $dir = sys_get_temp_dir().'/grease_rt_'.getmypid();

tests/Routing/UrlGeneratorParityTest.php

@@ -31,6 +31,7 @@ class UrlGeneratorParityTest extends TestCase
         'root' => '/',                                       // root
         'posts.optional' => 'api/posts/{post}/{slug?}',      // optional → defer
         'posts.scoped' => 'api/posts/{post:slug}',           // scoped binding → defer
+        'posts.dup' => 'api/dup/{a}/{a}',                    // duplicate param name → defer (vanilla throws)
         'admin.dash' => 'dashboard',                         // for a domain variant below
     ];
 
@@ -136,6 +137,39 @@ public function test_missing_required_parameter_throws_like_vanilla(): void
         $greased->route('posts.show', [], true);
     }
 
+    /**
+     * Values vanilla treats as a *missing* parameter (an empty string, which it leaves as a
+     * literal `{name}`) and malformed duplicate-name routes must throw `UrlGenerationException`
+     * just like vanilla — the fast path must NOT silently build a URL. Regression for two
+     * byte-identity divergences caught in review.
+     */
+    public function test_empty_string_and_duplicate_param_throw_like_vanilla(): void
+    {
+        [$vanilla, $greased] = $this->generators();
+
+        $cases = [
+            'empty named value' => ['posts.show', ['post' => '']],
+            'empty mid-segment' => ['posts.comments', ['post' => '', 'comment' => 5]],
+            'duplicate param positional' => ['posts.dup', [5, 6]],
+        ];
+
+        foreach ($cases as $label => [$name, $params]) {
+            $this->assertTrue($this->throws($vanilla, $name, $params), "sanity: vanilla throws for $label");
+            $this->assertTrue($this->throws($greased, $name, $params), "greased must throw like vanilla for $label");
+        }
+    }
+
+    private function throws(VanillaUrlGenerator $url, string $name, $params): bool
+    {
+        try {
+            $url->route($name, $params);
+
+            return false;
+        } catch (UrlGenerationException) {
+            return true;
+        }
+    }
+
     public function test_prewarmed_index_matches_lazy(): void
     {
         [$vanilla, $greased] = $this->generators();
@@ -214,4 +248,27 @@ public function test_subdirectory_app_relative_matches(): void
             'subdir relative'
         );
     }
+
+    /**
+     * forceRootUrl()/useOrigin() inject a root that may carry a *path* component
+     * (`https://example.com/app`) which a relative URL must keep — `/app/...`. Regression for a
+     * byte-identity divergence caught in review (the relative fast path now derives from the full
+     * absolute URI and strips exactly what vanilla strips, so the forced root path survives).
+     */
+    public function test_forced_root_url_with_path_matches(): void
+    {
+        foreach (['https://example.com/app', 'https://cdn.example.com'] as $root) {
+            [$vanilla, $greased] = $this->generators();
+            $vanilla->forceRootUrl($root);
+            $greased->forceRootUrl($root);
+
+            foreach ([true, false] as $absolute) {
+                $this->assertSame(
+                    $vanilla->route('posts.show', ['post' => 5], $absolute),
+                    $greased->route('posts.show', ['post' => 5], $absolute),
+                    "$root absolute=".var_export($absolute, true)
+                );
+            }
+        }
+    }
 }