chore: import upstream snapshot with attribution

2026-07-13 13:32:57 +08:00
commit cd420f9332
4811 changed files with 884702 additions and 0 deletions
@@ -0,0 +1,101 @@
+# Patches
+
+This directory holds [pnpm patches](https://pnpm.io/cli/patch) applied on install via
+`pnpm.patchedDependencies` in the root `package.json`. Each `.patch` is a diff against the
+published package. Most are small and self-explanatory from the diff; the non-obvious ones
+are documented below.
+
+---
+
+## `@remix-run/router@1.23.2` — route-matching memoization
+
+**File:** `patches/@remix-run__router@1.23.2.patch` (patches `dist/router.cjs.js`)
+
+### What it does
+
+Three changes to `matchRoutesImpl` / `compilePath`, all pure memoization of work that
+depends only on the **static** route manifest:
+
+1. **Cache flattened + ranked branches per route-tree** (`WeakMap` keyed by the `routes`
+   ref). `flattenRoutes()` + `rankRouteBranches()` were recomputed on *every* `matchRoutes`
+   call across all ~436 webapp routes.
+2. **Hoist `decodePath(pathname)` out of the branch-match loop** — it's loop-invariant but
+   was recomputed once per branch.
+3. **Memoize `compilePath` compiled regexes** by `path|caseSensitive|end` (bounded `Map`,
+   cap 2000). The matcher RegExp was rebuilt on every `matchPath` call.
+
+### Why
+
+Profiling the realtime runs feed under load (100 concurrent tag feeds, ~425 req/s) found
+**~68% of webapp CPU was spent in react-router's `matchRoutes`** — re-flattening,
+re-ranking, and re-compiling the entire route table on every request. It is **not** a dev
+artifact: there is no `NODE_ENV` gate, and a `NODE_ENV=production` profile was identical
+(67.9% vs 68.3%). The realtime feed's high request rate (each long-poll returns fast and
+immediately re-polls) just amplifies a latent per-request cost that large route tables pay
+everywhere.
+
+Measured on a single instance, same load, before vs after this patch:
+
+| | before | after |
+|---|---|---|
+| active CPU (self-time / window) | 28.3s | 18.5s (**−34%**) |
+| route-matching self-time | 19.2s | 7.5s (**−61%**) |
+| event-loop lag p99 | 322ms | 113ms (**−65%**) |
+| idle headroom | 26% | 52% |
+
+The realtime machinery itself (router/hydrate/serialize/diff) was ~0% — the bottleneck was
+entirely generic Remix request overhead.
+
+### Upstream status (why we patch instead of upgrade)
+
+This is a known, acknowledged inefficiency, and it is **only partially fixed in React
+Router v7** — which we can't adopt without a full Remix 2 → RR7 framework migration.
+
+- [Issue #8653 "Performance issues"](https://github.com/remix-run/react-router/issues/8653)
+  reported it (a user with 12k routes, ~67ms per match) and was closed as a dup of the
+  route-ranking discussion [remix#4786](https://github.com/remix-run/remix/discussions/4786).
+- [PR #14866 "Optimize route matching performance with caching"](https://github.com/remix-run/react-router/pull/14866)
+  implemented *exactly this patch* (hoist `decodePath`, cache `compilePath`, cache
+  flatten/rank), claiming **~80% route-matching CPU reduction on a 400+ route app**. It was
+  **closed, not merged.**
+- [PR #14967 "perf: cache flattened/ranked route branches"](https://github.com/remix-run/react-router/pull/14967)
+  is the partial fix that *did* ship (in v7): it caches only the branches, threaded via a
+  `precomputedBranches` param through the framework's server-runtime (~15% SSR gain). It
+  does **not** cache `compilePath` — that regex rebuild remains even on `main`.
+  ([PR #14971](https://github.com/remix-run/react-router/pull/14971) added client-side wins.)
+
+The maintainer's reasoning for closing the fuller PR (#14866), verbatim:
+
+> "This is great as a `patch-package` optimization for those who want it, but we are
+> actively working on integrating the more performant route-pattern library from Remix 3 so
+> we'd rather just do the right 'fix' and ship the new algorithm instead of trying to
+> band-aide perf improvements to the existing algorithm which was written with a very
+> different set of constraints. Those constraints come from early v6 when it was only
+> declarative mode so route trees were defined at render time and thus had to be
+> re-flattened/re-ranked/re-compiled every time."
+
+So: the re-compute-everything design is a holdover from early React Router v6 declarative
+mode (route trees defined at render time, so recomputing was correct then). The maintainer
+**explicitly endorsed patch-package as the interim approach** and is betting on the Remix 3
+route-pattern rewrite for the real fix. This patch is that sanctioned stopgap — and it also
+includes the `compilePath` cache the merged PR left on the table.
+
+### Safety
+
+Pure memoization of deterministic, internal-only values:
+
+- `flattenRoutes`/`rankRouteBranches` and the compiled regexes depend solely on the static
+  route manifest; the cached values are never returned to or mutated by the framework.
+- The compiled `RegExp` has no `/g` flag, so `.exec()` carries no cross-call state — safe to
+  share under concurrency.
+- The branch cache is a `WeakMap` (collected with its route tree); the compile cache is
+  bounded at 2000 entries (route patterns are a static set; the cap only guards any dynamic
+  `matchPath()` use).
+- Targets the **CJS** build (`dist/router.cjs.js`), which the webapp server loads at runtime
+  (`@remix-run/router` is not bundled into the server build).
+
+### When to remove
+
+Drop this patch if/when the webapp moves to React Router v7+ (which threads
+`precomputedBranches` itself) or the Remix 3 route-pattern matcher lands. Re-profile at that
+point — the `compilePath` cache may still be worth keeping since upstream never added it.