🔥 feat: Route Domain() func for host-based routing

[Copilot]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>🚀 [Feature]: Route Domain() func</issue_title>
<issue_description>### Feature Description

In projects using multiple domains, the easy-to-use Domain() function can be added.

Additional Context (optional)

I know there are manual solutions, but they are not easy to use.

Code Snippet (optional)

package main

import "github.com/gofiber/fiber/v2"
import "log"

func main() {
  app := fiber.New()

  app.Domain(":username.blog.example.com").Get("/*path", func(c *fiber.Ctx) error {
    username := c.Params("username")
    return c.SendString(username + "'s blog page")
  })

  log.Fatal(app.Listen(":3000"))
}

Checklist:

• I agree to follow Fiber's Code of Conduct.
• I have checked for existing issues that describe my suggestion prior to opening this one.
• I understand that improperly formatted feature requests may be closed without explanation.</issue_description>

<agent_instructions>- Document the feature properly with examples

• Add a section in whats_new.md
• This can probably go in domain.go and tests in domain_test.go
• Test coverage should be at least 90%
• Router performance is critical</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@ReneWerner87 nice idea related: https://github.com//issues/750 https://github.com//issues/1409 @ReneWerner87 would not want to mix the routing of the paths and this feature, more like in the proposal @gaby @joey1123455 Did you ever get anywhere with this? @gaby @vhespanha Give it a try, I'm not sure how will this be implemented without affecting router performance. @gaby @KeyzarRasya We looked at it, but it will impact router performance for everyone which is not ideal.

• Fixes 🚀 [Feature]: Route Domain() func #2620

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[codecov]

Codecov Report

❌ Patch coverage is 95.39007% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.17%. Comparing base (785d2ce) to head (f02fee6).
⚠️ Report is 36 commits behind head on main.

Files with missing lines	Patch %	Lines
domain.go	95.23%	7 Missing and 6 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4100      +/-   ##
==========================================
+ Coverage   91.07%   91.17%   +0.10%     
==========================================
  Files         122      123       +1     
  Lines       11550    11832     +282     
==========================================
+ Hits        10519    10788     +269     
- Misses        651      658       +7     
- Partials      380      386       +6     

Flag	Coverage Δ
unittests	91.17% <95.39%> (+0.10%)	⬆️

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

☔ View full report in Codecov by Sentry.
📢 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.

[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: 694cabf	Previous: 92ada8a	Ratio
BenchmarkDecoderedirectionMsgs - MB/s	114.43 MB/s	47.86 MB/s	2.39

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

[gaby]

@copilot

• Add documentation for the new feature with detailed examples. Follow the same formatting as other docs.
• The benchmark for Benchmark_NewError shows a regression from 42ns/op to 78ns/op
• In domain.go make sure to use fiber utils. For example strings.ToLower should be using the fiber util which is more performant.

[Copilot]

@copilot

• Add documentation for the new feature with detailed examples. Follow the same formatting as other docs.
• The benchmark for Benchmark_NewError shows a regression from 42ns/op to 78ns/op
  ...

Addressed in ed8cbb8:

• Fiber utils: Replaced strings.ToLower with utilsstrings.ToLower from github.com/gofiber/utils/v2/strings in domain.go (both parseDomainPattern and match).
• Documentation: Added Domain and DomainParam sections to docs/api/app.md following the same formatting as Group, Route, and RouteChain.
• Benchmark_NewError: Confirmed no regression from our changes — the NewError function is untouched by this PR. Local benchmarks show ~28ns/op across 3 runs, consistent with baseline. The CI regression is likely environment noise.

[gaby]

@copilot

• Replace strings.TrimSpace with utils.TrimSpace in domain.go
• In domain.go function match() you call make using the len of params without any bound limits. This could cause a OOM in the future. Set a reasonable limit. Check the code in the regular router.go and app.go and use the same limit defined there.

[Copilot]

@copilot

• Replace strings.TrimSpace with utils.TrimSpace in domain.go
• In domain.go function match() you call make using the len of params without any bound limits. This could cause a OOM in the ...

Addressed in 1f1dbd7:

• Replaced strings.TrimSpace with utils.TrimSpace from github.com/gofiber/utils/v2.
• Added maxParams (30) bound check in parseDomainPattern() — panics if the domain pattern exceeds the limit, consistent with the path parser in path.go:250. Since the check is at registration time, match() is already bounded by the validated m.paramIdx slice length.

[gaby]

/gemini review

[gemini-code-assist]

Code Review

This is an excellent pull request that introduces host-based routing, a highly requested feature. The implementation is clean, non-intrusive, and aligns well with Fiber's existing API and performance goals. The "zero impact" on non-domain routes is a key achievement, and the comprehensive test suite, including benchmarks, provides strong confidence in the changes. The documentation is also very thorough. I have a couple of minor suggestions to improve code and documentation clarity.

[Claude]

@claude[agent]

• Make sure the Domain router is feature complete in comparison to the other routers.
• Make sure the Domain router documentation matches the code implementation. This is critical fo...

✅ Domain router review complete (commit 5f151ee):

Feature Completeness:

• All 17 Router interface methods implemented and tested
• Sub-app mounting via Domain(...).Use(*fiber.App) fully functional with domain filtering
• 54+ domain tests passing including 14 comprehensive security tests

Documentation:

• Updated docs/api/app.md with sub-app mounting example
• Updated docs/whats_new.md with sub-app mounting example
• TrustProxy behavior documented with security warnings
• All features match implementation

Security:

• DoS protections: RFC 1035 limits (253 char hostname, 63 char labels, max 16 parts)
• ASCII-only validation for patterns and runtime hostnames
• Empty label rejection, character validation
• Two-pass matching to defer param allocation until constants match
• All security tests passing

[Copilot]

Pull request overview

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

[gaby]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

All review items from the thread addressed in f45eb20 and 35d3784:

1. mount() no longer mutates sub-app in-place — Routes are cloned into a wrapper app with domain-wrapped handlers. The same sub-app can safely be mounted on multiple domains without double-wrapping. Added Test_Domain_UseMountReusable.
2. Proper mutex locking — subApp.mutex.Lock() with defer Unlock() while cloning routes to prevent data races.
3. RFC 1035 pattern length limits — parseDomainPattern() now enforces <=253 chars total and <=63 chars per constant label. Added Test_Domain_Security_PatternLengthLimits.
4. TrustProxy doc — app.go now mentions TrustProxyConfig (trusted proxy IPs/ranges) alongside TrustProxy.
5. Routes-after-mount test — Test_Domain_UseMountRoutesAfterMount documents that routes added after mount are not cloned. Documentation updated in both docs/api/app.md and docs/whats_new.md.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• exampleretry.com
  • Triggering command: /tmp/go-build3099809254/b307/client.test /tmp/go-build3099809254/b307/client.test -test.paniconexit0 -test.v=test2json -test.timeout=10m0s -test.count=1 -test.shuffle=on GO111MODULE ux-amd64/pkg/tool/linux_amd64/compile GOINSECURE GOMOD l/linux_amd64/as-unreachable=false ux-amd64/pkg/too/tmp/go-build3099809254/b107/vet.cfg env rg/toolchain@v0.-goversion GO111MODULE ux-amd64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD mpile ux-amd64/pkg/too-buildtags (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[gaby]

@claude[agent]

• Add tests in app_integration_test.go using the new domain router.

[gaby]

@claude[agent] Is it feasible to reduce code duplication within the domain.go file compared to other router implementations, while ensuring the same functionality is maintained?

[Claude]

@claude[agent] Is it feasible to reduce code duplication within the domain.go file compared to other router implementations, while ensuring the same functionality is maintained?

The code duplication in domain.go is intentional and follows the established pattern in Fiber's codebase:

Why the duplication exists:

1. Type Safety - Each router type (App/Group/domainRouter) implements Router independently without reflection
2. Performance - Direct method calls avoid interface boxing overhead in hot paths
3. Documentation - Each method has godocs specific to domain routing behavior
4. Consistency - Matches the existing pattern in app.go and group.go

What's actually duplicated:

• HTTP method handlers (Get/Post/etc) - 3 lines each, just delegate to Add()
• Use() argument parsing - necessary since each router type wraps/processes handlers differently
• Group() method - similar structure but domain-specific (carries matcher forward)

What's NOT duplicated:

• Core logic is in Add() which properly wraps handlers for domain checking
• Domain matching/validation logic is unique to domain.go
• mount() implementation is domain-specific (clones routes with wrapped handlers)

The current approach prioritizes performance and maintainability over DRY. Refactoring to reduce duplication would require either:

1. Reflection (performance cost)
2. Code generation (added complexity)
3. Helper functions (less clear stack traces)

All Fiber router implementations follow this same pattern. The duplication is minimal (< 100 lines for all HTTP methods) and keeps the code fast, clear, and debuggable.