🔥 feat: add SkipUnmatchedRoutes with two-tier 404/405 fast path

[gaby]

Adds a SkipUnmatchedRoutes config option that answers requests to unregistered paths with 404 (or 405 when the path exists for other methods) before the middleware chain runs, so work is not spent on bots, scanners, and bad URLs.

Rather than a single full lookahead pass over the route tree on every request (which would duplicate next()'s matching work and regress every matched route), the existence check is split into two tiers built at startup in buildTree:

• staticRouteMethods: an O(1) map from a static endpoint's prettified path to a bitmask of methods. Static hits run the normal chain with just one map lookup, and unmatched paths in buckets with no parametric/root/star/mount routes resolve to 404/405 with no scanning.
• bucketParamMethods: a per-tree-bucket bitmask used to decide when the static index is authoritative versus when a parametric scan is needed.

Only when a bucket actually contains parametric routes does a scan run, and it scans only the parametric subset, handing the matched index to next()/nextCustom() via ctx.firstMatchIndex so the endpoints already ruled out are not re-checked. The matched route is still re-matched in
next() so params are recomputed correctly even if parametric middleware ran in between. firstMatchIndex defaults to -1, making the hot path inert when the option is disabled.

Benchmarks (4-core):

• static matched +12ns (~239->251),
• parametric matched +82ns (~357->439)
• unmatched -134ns (~368->234).

The option is off by default and has no effect on existing behavior.

Replaces #4411
Fixes #4403

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Adds a SkipUnmatchedRoutes config option to Fiber. When enabled, requests with no matching route receive an immediate 404 or 405 before middleware executes. The change adds route lookup indexes, a firstMatchIndex context path, request-handler lookahead, and matching tests.

Changes

SkipUnmatchedRoutes fast-path

Layer / File(s)	Summary
Config option and App state fields app.go, docs/api/fiber.md	Adds SkipUnmatchedRoutes to Config, adds lookup/index fields to App, and documents the option in the API reference.
Context firstMatchIndex state and invalidation ctx.go, ctx_interface.go, ctx_interface_gen.go, req.go	Adds firstMatchIndex to DefaultCtx, initializes and invalidates it across request/path changes, exposes accessors, and clears stale lookahead when the request method changes. Updates CustomCtx and Ctx interfaces.
Lookup indexes and skip resolution router.go	Adds indexedRoute and buildSkipIndexes, rebuilds the lookup indexes from buildTree, resolves 404/405 outcomes with Allow data, and skips earlier non-use routes when a firstMatchIndex is present.
Routing tests and benchmarks router_test.go	Adds skip-mode routing tests, middleware and custom-context coverage, method-override invalidation checks, parity checks, and benchmarks for unmatched, matched, and 405 request paths.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• gofiber/fiber#3261: Modifies router request entrypoints and routing flow in the same area extended here with skip-unmatched lookahead.
• gofiber/fiber#3846: Also changes next/nextCustom route-skipping control flow, making it closely related to the skip-unmatched path here.
• gofiber/fiber#4426: Touches the same non-use route-skipping decision logic in router traversal.

Suggested labels

⚡️ Performance

Suggested reviewers

• sixcolors
• efectn
• ReneWerner87

🐇 I hopped past the long middleware line,
With bitmasks bright and routes aligned.
A 404 or 405 now comes with a wink,
Before the chain can even think.
Fast-path paws on the routing vine!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 49.02% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the new SkipUnmatchedRoutes 404/405 fast path.
Description check	✅ Passed	The description clearly explains the feature, implementation, benchmarks, issue reference, and examples, with only minor template omissions.
Linked Issues check	✅ Passed	The changes implement #4403 by skipping prefix/group middleware on unmatched routes while preserving 404/405 behavior and backward compatibility.
Out of Scope Changes check	✅ Passed	The added docs, tests, benchmarks, and routing internals all support the SkipUnmatchedRoutes feature and are in scope.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/fiber-404-performance-q0qh6o

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 95.72193% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.97%. Comparing base (0b57242) to head (ec7f3f8).

Files with missing lines	Patch %	Lines
router_skip.go	95.32%	3 Missing and 2 partials ⚠️
router.go	95.58%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4486      +/-   ##
==========================================
+ Coverage   92.96%   92.97%   +0.01%     
==========================================
  Files         138      139       +1     
  Lines       13609    13789     +180     
==========================================
+ Hits        12651    12820     +169     
- Misses        592      601       +9     
- Partials      366      368       +2     

Flag	Coverage Δ
unittests	92.97% <95.72%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@app.go`:
- Around line 117-121: The SkipUnmatchedRoutes bitmask handling in app.go needs
to respect the actual integer width used by staticRouteMethods and
bucketParamMethods. Update the logic around RequestMethods and the mask-building
code so the number of methods is capped or validated against the platform bit
width, or switch the masks to a fixed-width unsigned type and adjust the related
comment/doc in app.go accordingly.

In `@router_skip_test.go`:
- Line 10: The router skip tests are triggering httpNoBody lint failures because
several httptest.NewRequest calls in router_skip_test.go pass nil as the body.
Update each of the affected test cases to use http.NoBody instead of nil, and
add the net/http import alongside net/http/httptest so the http.NoBody reference
resolves; the changes should be made wherever these NewRequest calls appear in
the test file.
- Around line 352-365: The new subtests in router_skip_test.go are missing
t.Parallel() and currently share mutable state through app and called, which
makes them unsafe to run concurrently. Update the matched_runs_group_mw and
unmatched_skips_group_mw subtests to call t.Parallel() at the start, and move
any route/app setup and called initialization into each subtest so they are
fully isolated; use the existing test helpers and the app/called variables to
locate the shared setup that needs to be duplicated.

In `@router.go`:
- Line 465: The resolveSkip function signature uses unnamed return values, which
triggers the unnamedResult lint check; update resolveSkip on App to name its
three int results directly in the function signature and keep the existing
return behavior unchanged. Use the resolveSkip method as the target for the
signature change so the linter sees explicit result names.
- Around line 554-569: Reset ctx.firstMatchIndex in the Method(...) override
path so any earlier skip lookahead is discarded when the request method changes.
The issue is in the routing flow around app.resolveSkip and next(), where the
cached firstMatchIndex can be reused against the wrong method bucket after
Method(...) mutates the method; fix it by clearing that field in the same place
Path(...) and RestartRouting() already do, using the Method override logic and
ctx.firstMatchIndex as the key symbols to locate the change.
- Around line 466-467: The method bitmask logic in router.go is still using
int-based shifts in the route lookup path, so add a runtime guard in the
RequestMethods handling to enforce the documented maximum number of methods
before computing methodBit/staticMask. Update the relevant routing/method lookup
code around the bitmask construction and any Allow/SkipUnmatchedRoutes mask
usage to either validate the limit and fail fast, or switch the masks to a
fixed-width unsigned type consistently so oversized method lists cannot silently
corrupt lookups.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 1796c339-4503-4ee6-af91-2d5fc34e1e28

📥 Commits

Reviewing files that changed from the base of the PR and between 3f26054 and 2d7b871.

📒 Files selected for processing (7)

• app.go
• ctx.go
• ctx_interface.go
• ctx_interface_gen.go
• docs/api/fiber.md
• router.go
• router_skip_test.go

[coderabbitai]

🧹 Nitpick comments (1)

router_test.go (1)

3164-3229: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider a one-time correctness assertion in the benchmarks.

The three benchmarks measure throughput but never verify the handler produced the intended outcome (200 for the matched/param cases, 404 for the unmatched case). A silent routing regression would still run "successfully" and report misleading parity numbers. A single sanity check before b.Loop() cheaply protects the benchmark's intent.

♻️ Example for the matched benchmark

 		c := &fasthttp.RequestCtx{}
 		c.Request.Header.SetMethod(MethodGet)
 		c.URI().SetPath("/user/repos") // genuinely static route
+
+		// Sanity check: ensure the path actually matches before measuring.
+		appHandler(c)
+		require.Equal(b, StatusOK, c.Response.StatusCode())
 
 		b.ReportAllocs()
 		b.ResetTimer()
 		for b.Loop() {
 			appHandler(c)
 		}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@router_test.go` around lines 3164 - 3229, Add a one-time correctness sanity
check to each benchmark in Benchmark_SkipUnmatchedRoutes_Matched,
Benchmark_SkipUnmatchedRoutes_MatchedParam, and
Benchmark_SkipUnmatchedRoutes_Unmatched so the benchmark verifies the handler
outcome before measuring throughput. After calling app.Handler() and before
b.Loop(), invoke the handler once on the prepared fasthttp.RequestCtx and assert
the expected status for the route type (200 for the matched and matched-param
cases, 404 for the unmatched case). Keep the check lightweight and local to the
existing run helper so the benchmark still measures only steady-state
performance.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@router_test.go`:
- Around line 3164-3229: Add a one-time correctness sanity check to each
benchmark in Benchmark_SkipUnmatchedRoutes_Matched,
Benchmark_SkipUnmatchedRoutes_MatchedParam, and
Benchmark_SkipUnmatchedRoutes_Unmatched so the benchmark verifies the handler
outcome before measuring throughput. After calling app.Handler() and before
b.Loop(), invoke the handler once on the prepared fasthttp.RequestCtx and assert
the expected status for the route type (200 for the matched and matched-param
cases, 404 for the unmatched case). Keep the check lightweight and local to the
existing run helper so the benchmark still measures only steady-state
performance.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 0dbf62d9-f338-49d0-b67c-9801bd7ce5b6

📥 Commits

Reviewing files that changed from the base of the PR and between 2d7b871 and e0d6034.

📒 Files selected for processing (3)

• app.go
• router.go
• router_test.go

🚧 Files skipped from review as they are similar to previous changes (2)

• router.go
• app.go

[coderabbitai]

🧹 Nitpick comments (2)

router_test.go (2)

3164-3330: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Repetitive without_skip/with_skip setup across four benchmarks.

Each pair (Unmatched, Matched, 405_Middleware, 405_NMiddleware) duplicates nearly identical app/middleware/RequestCtx setup, differing only in Config.SkipUnmatchedRoutes and middleware count. A small helper (e.g. newSkipBenchApp(skip bool, middlewares int) (*fasthttp.RequestHandler, *fasthttp.RequestCtx)) parameterized by method/path would remove the duplication while keeping each benchmark isolated.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@router_test.go` around lines 3164 - 3330, The four SkipUnmatchedRoutes
benchmarks duplicate the same app, middleware, and RequestCtx setup in both
without_skip and with_skip branches. Refactor the repeated setup in the
benchmark functions Benchmark_SkipUnmatchedRoutes_Unmatched,
Benchmark_SkipUnmatchedRoutes_Matched,
Benchmark_SkipUnmatchedRoutes_405_Middleware, and
Benchmark_SkipUnmatchedRoutes_405_NMiddleware into a small helper that accepts
SkipUnmatchedRoutes, middleware count, method, and path, then returns the
configured app handler and request context so each benchmark stays isolated but
concise.

---

3333-3350: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

status field in deepScenarios is never asserted, and one scenario name has a typo.

status is populated per scenario but never read inside the benchmark loop (lines 3382-3386), so it currently serves only as documentation. Asserting it once during setup (before b.ResetTimer()) would let this table double as a regression guard if a future routing change silently changes the matched status. Separately, "Unmatched_Top_level_SBucket_WwongMethod" appears to be a typo for "WrongMethod".

💚 Proposed addition to validate `status` before timing starts

 				appHandler := app.Handler()
 
 				c := &fasthttp.RequestCtx{}
 				c.Request.Header.SetMethod(s.method)
 				c.URI().SetPath(s.path)
 
+				appHandler(c)
+				if c.Response.StatusCode() != s.status {
+					b.Fatalf("expected status %d, got %d", s.status, c.Response.StatusCode())
+				}
+
 				b.ReportAllocs()
 				b.ResetTimer()
 				for b.Loop() {
 					appHandler(c)
 				}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@router_test.go` around lines 3333 - 3350, The deepScenarios table in
router_test.go includes a status field that is never checked and a scenario name
with a typo. Update the benchmark setup in the deep routing test so each
scenario’s expected status is asserted before b.ResetTimer(), using the existing
deepScenarios entries to validate the response once during setup. Also rename
the mislabeled scenario from “Unmatched_Top_level_SBucket_WwongMethod” to
“Unmatched_Top_level_SBucket_WrongMethod” to keep the test case name accurate.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@router_test.go`:
- Around line 3164-3330: The four SkipUnmatchedRoutes benchmarks duplicate the
same app, middleware, and RequestCtx setup in both without_skip and with_skip
branches. Refactor the repeated setup in the benchmark functions
Benchmark_SkipUnmatchedRoutes_Unmatched, Benchmark_SkipUnmatchedRoutes_Matched,
Benchmark_SkipUnmatchedRoutes_405_Middleware, and
Benchmark_SkipUnmatchedRoutes_405_NMiddleware into a small helper that accepts
SkipUnmatchedRoutes, middleware count, method, and path, then returns the
configured app handler and request context so each benchmark stays isolated but
concise.
- Around line 3333-3350: The deepScenarios table in router_test.go includes a
status field that is never checked and a scenario name with a typo. Update the
benchmark setup in the deep routing test so each scenario’s expected status is
asserted before b.ResetTimer(), using the existing deepScenarios entries to
validate the response once during setup. Also rename the mislabeled scenario
from “Unmatched_Top_level_SBucket_WwongMethod” to
“Unmatched_Top_level_SBucket_WrongMethod” to keep the test case name accurate.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: b06f04bb-5375-45cb-bb59-6872ff43f0af

📥 Commits

Reviewing files that changed from the base of the PR and between 60822fc and 338b719.

📒 Files selected for processing (1)

• router_test.go

[Copilot]

Pull request overview

Adds an opt-in SkipUnmatchedRoutes router fast path to short-circuit unmatched requests (404 / 405) before middleware execution, aiming to reduce wasted work on bot/scanner traffic while keeping matched-route overhead low.

Changes:

• Introduces two-tier route-existence indexes built at startup (staticRouteMethods, bucketParamMethods, paramRoutes) and a resolveSkip / emitSkip short-circuit path.
• Plumbs firstMatchIndex through ctx/routing to avoid re-checking endpoints already ruled out by the lookahead (and optionally reuse params when safe).
• Adds extensive tests/benchmarks and documents the new config option.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
router.go	Implements SkipUnmatchedRoutes lookahead/indexing, integrates fast path into request handlers, and adds firstMatchIndex endpoint-skipping logic.
router_test.go	Adds correctness tests and benchmarks for SkipUnmatchedRoutes behavior/perf across static/param/mount/custom ctx cases.
req.go	Invalidates firstMatchIndex when Method(...) overrides the request method.
ctx.go	Stores/invalidates firstMatchIndex across Reset/Path/RestartRouting and exposes getters/setters for custom ctx plumbing.
ctx_interface.go	Extends CustomCtx internal-method set with firstMatchIndex accessors.
ctx_interface_gen.go	Extends generated Ctx interface with firstMatchIndex accessors.
app.go	Adds router indexes/state fields to App and adds Config.SkipUnmatchedRoutes.
docs/api/fiber.md	Documents SkipUnmatchedRoutes in the public config table.

Files not reviewed (1)

• ctx_interface_gen.go: Generated file

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.50.

Benchmark suite	Current: ec7f3f8	Previous: 0b57242	Ratio
Benchmark_Compress/Zstd (github.com/gofiber/fiber/v3/middleware/compress) - B/op	1 B/op	0 B/op	+∞

This comment was automatically generated by workflow using github-action-benchmark.

[ReneWerner87]

Two open questions from reviewing/optimizing this branch (0b526b0, 4c609a3):

1. Naming: SkipUnmatchedRoutes reads as "skip routes that are unmatched", but nothing route-shaped is skipped; what is skipped is the middleware chain for unmatched requests. 📝 [Proposal]: skip group/prefix middleware when no child route matches #4403 originally proposed SkipMiddlewareOnUnmatched, which is more precise and actively warns about the main sharp edge (middleware never sees these requests). Since v3 is unreleased, the rename would be free right now. Keep or rename?

2. CORS preflight: with the flag enabled, an OPTIONS request to a path registered only for other methods short-circuits to 405 without CORS headers, before cors.New() ever runs; apps rarely register explicit OPTIONS routes, so enabling the flag breaks preflight for CORS-enabled endpoints. 0b526b0 documents this (Config comment, fiber.md, whats_new.md). Should OPTIONS additionally be exempted from the short-circuit (a single method check before resolveSkip), or is documenting it enough?

Benchmarks (Apple M2 Pro, -cpu=1 -count=10, benchstat medians): 0b526b0 replaces the three-map lookahead with a per-bucket index whose bucket-0 fallback is materialized at build time, so resolveSkip does one map lookup per unmatched request and the cross-method 405 scan does none:

Scenario (350-route fixture)	flag off	before	after
Unmatched (3 middlewares)	190ns	132ns	118ns
405 (3 middlewares)	834ns	779ns	710ns
Matched parametric	242ns	247ns	248ns

All paths stay at 0 allocs/op. With the flag off there is no regression; the always-on 405 method-mask prune makes unmatched/405 requests 8-16% faster than main even then. The four copy-paste Benchmark_SkipUnmatchedRoutes_* functions were consolidated into one table-driven Benchmark_SkipUnmatchedRoutes (Unmatched/Matched/405_Middleware/405_NoMiddleware, each with and without the flag).

[gaby]

@ReneWerner87 I prefer SkipUnmatchedRoutes. The other name is too complicated.

The CORS issue is concerning. We need to fix that, since its a weird edge case to introduce just because of this flag.

[ReneWerner87]

CORS preflight exemption (ec7f3f8)

Addresses the OPTIONS/CORS-preflight gap noted for SkipUnmatchedRoutes.

Problem: with the option on, an OPTIONS preflight to a path registered only for GET/POST was short-circuited to 405 before the middleware chain ran, so the cors middleware never got to answer it - blocking every cross-origin call to that path.

Fix: both defaultRequestHandler and customRequestHandler now gate the fast path on app.skip.enabled && !ctx.IsPreflight(), reusing the existing Ctx.IsPreflight() (OPTIONS + Access-Control-Request-Method + Origin). Preflight requests flow through the normal chain so cors answers them; non-preflight OPTIONS still hit the fast 404/405, keeping the bot/scanner protection.

Benchmarks (Benchmark_SkipUnmatchedRoutes, Apple M2 Pro, -count=10, benchstat). The guard only runs when the option is on, so without_skip / NoMiddleware are controls that must not move:

scenario	base	new	delta
Unmatched / with_skip	114.0ns	117.5ns	+3.1% (p=0.005)
Matched / with_skip	247.6ns	251.5ns	~ (n.s.)
405_Middleware / with_skip	716.2ns	727.4ns	+1.6%
405_NoMiddleware / with_skip	816.4ns	818.0ns	~ (n.s.)
Unmatched / without_skip (control)	186.4ns	191.2ns	+2.6%
Matched / without_skip (control)	246.9ns	248.0ns	~ (n.s.)

0 allocs/op throughout (unchanged). The without_skip control drifting +2.6% shows ~2-3% run-to-run variance on this machine - that path provably never calls IsPreflight(), so the real added cost is a single method lookup + length-mismatch compare (a few ns) on the with_skip hot path, within the noise band. Zero cost when the option is off (short-circuit on skip.enabled).

Tests: preflight-exemption + non-preflight-405 on both the default- and custom-context handlers. Docs updated (config comment, docs/api/fiber.md, whats_new.md); also fixed a truncated doc comment on skipRouteIndex.staticMethods.

Known limitation: a real cross-origin GET/POST to a fully unregistered path still fast-404s without CORS headers (browser reports a CORS error rather than a 404). The main breakage - preflight failing - is resolved.