diff --git a/docs/api/app.md b/docs/api/app.md index 06b83628cc1..fdff919a7cb 100644 --- a/docs/api/app.md +++ b/docs/api/app.md @@ -581,14 +581,20 @@ matched path tail; delimiters such as `?` and `#` remain parameter data instead of restructuring the generated URL. [`GetRouteURL`](./ctx.md#getrouteurl) and [`Redirect().Route`](./redirect.md#route) apply the same encoding. -These take the value as data, not as URL text, so the same call yields the same -URL under any configuration. With `UnescapePath` off (the default) `c.Params` +These take the value as data, not as URL text. Representable values use the same +encoding under any configuration. With `UnescapePath` off (the default) `c.Params` returns the value still percent-encoded, so forwarding it straight back encodes the `%` a second time. Turn `UnescapePath` on, or decode with [`url.PathUnescape`](https://pkg.go.dev/net/url#PathUnescape) first. An app with `UnescapePath` enabled decodes `%2F` before route matching, so an -ordinary parameter holding a `/` cannot round-trip as one segment. Use a greedy -(`*` or `+`) parameter for values that may contain slashes. +ordinary single-segment parameter holding a `/` cannot round-trip and returns +`ErrRouteNotRepresentable`. Greedy (`*` or `+`), adjacent single-byte parameters +and parameters with a single-byte non-slash terminator retain their existing +slash-matching rules. +Dot-containing values are also rejected when the composed path has a `.` or +`..` segment that would be removed during normalization. Surrounding route +constants are considered: `:name.txt` with `name="."` remains representable. +Pass a different value or use a route that can represent it; do not pre-encode it. ::: ### GetRoutes diff --git a/docs/api/ctx.md b/docs/api/ctx.md index 322edd3aed3..53d2ba3b1bf 100644 --- a/docs/api/ctx.md +++ b/docs/api/ctx.md @@ -331,14 +331,20 @@ tail; delimiters such as `?` and `#` remain parameter data instead of adding a query or fragment. [`Route.URL`](./app.md#getroute) and [`Redirect().Route`](./redirect.md#route) apply the same encoding. -These take the value as data, not as URL text, so the same call yields the same -URL under any configuration. With `UnescapePath` off (the default) `c.Params` +These take the value as data, not as URL text. Representable values use the same +encoding under any configuration. With `UnescapePath` off (the default) `c.Params` returns the value still percent-encoded, so forwarding it straight back encodes the `%` a second time. Turn `UnescapePath` on, or decode with [`url.PathUnescape`](https://pkg.go.dev/net/url#PathUnescape) first. An app with `UnescapePath` enabled decodes `%2F` before route matching, so an -ordinary parameter holding a `/` cannot round-trip as one segment. Use a greedy -(`*` or `+`) parameter for values that may contain slashes. +ordinary single-segment parameter holding a `/` cannot round-trip and returns +`ErrRouteNotRepresentable`. Greedy (`*` or `+`), adjacent single-byte parameters +and parameters with a single-byte non-slash terminator retain their existing +slash-matching rules. +Dot-containing values are also rejected when the composed path has a `.` or +`..` segment that would be removed during normalization. Surrounding route +constants are considered: `:name.txt` with `name="."` remains representable. +Pass a different value or use a route that can represent it; do not pre-encode it. ::: ### Hijack diff --git a/docs/api/redirect.md b/docs/api/redirect.md index 896831b8ba3..bad2b9ed295 100644 --- a/docs/api/redirect.md +++ b/docs/api/redirect.md @@ -95,14 +95,20 @@ query or fragment, and cannot absorb or discard `Queries`. [`Route.URL`](./app.md#getroute) and [`GetRouteURL`](./ctx.md#getrouteurl) apply the same encoding. -These take the value as data, not as URL text, so the same call yields the same -URL under any configuration. With `UnescapePath` off (the default) `c.Params` +These take the value as data, not as URL text. Representable values use the same +encoding under any configuration. With `UnescapePath` off (the default) `c.Params` returns the value still percent-encoded, so forwarding it straight back encodes the `%` a second time. Turn `UnescapePath` on, or decode with [`url.PathUnescape`](https://pkg.go.dev/net/url#PathUnescape) first. An app with `UnescapePath` enabled decodes `%2F` before route matching, so an -ordinary parameter holding a `/` cannot round-trip as one segment. Use a greedy -(`*` or `+`) parameter for values that may contain slashes. +ordinary single-segment parameter holding a `/` cannot round-trip and returns +`ErrRouteNotRepresentable`. Greedy (`*` or `+`), adjacent single-byte parameters +and parameters with a single-byte non-slash terminator retain their existing +slash-matching rules. +Dot-containing values are also rejected when the composed path has a `.` or +`..` segment that would be removed during normalization. Surrounding route +constants are considered: `:name.txt` with `name="."` remains representable. +Pass a different value or use a route that can represent it; do not pre-encode it. ::: ### Back diff --git a/docs/whats_new.md b/docs/whats_new.md index fcd4e0119e0..5e68e744c39 100644 --- a/docs/whats_new.md +++ b/docs/whats_new.md @@ -365,10 +365,12 @@ The router normalizes every request path before matching, as [RFC 3986 Section 6 ### Generated route URLs -`Route.URL`, `GetRouteURL` and `Redirect().Route` percent-encode each parameter value with URL path-segment rules. A value is data, so the same call composes the same URL under any configuration. Previously the value was written into the path as given: `a/b` under `/user/:name` produced `/user/a/b`, which matched no route; `a?b` produced `/user/a?b`, whose tail became a query and truncated the value; and `100%` produced `/user/100%`, which Go's own URL parser rejects. Greedy parameters (`*` and `+`) keep the `/` of the matched path tail. +`Route.URL`, `GetRouteURL` and `Redirect().Route` percent-encode each parameter value with URL path-segment rules. A value is data, so a representable value composes the same URL under any configuration. Previously the value was written into the path as given: `a/b` under `/user/:name` produced `/user/a/b`, which matched no route; `a?b` produced `/user/a?b`, whose tail became a query and truncated the value; and `100%` produced `/user/100%`, which Go's own URL parser rejects. Greedy parameters (`*` and `+`) keep the `/` of the matched path tail. Because the value is data, one that already carries escapes is encoded again. With `UnescapePath` off, which is the default, `c.Params` returns the value as the request spelled it, so forwarding it into a generated URL turns `M%C3%BCller` into `M%25C3%25BCller`. Decode it first, or turn `UnescapePath` on. +A value the router could not match back returns `ErrRouteNotRepresentable` instead of a URL: one that forms a `.` or `..` segment, which clients and the router remove (`/user/:name` with `..`), and, with `UnescapePath` on, a `/` in an ordinary single-segment parameter, which the router decodes before matching. Greedy parameters keep accepting slashes. + ### Handler compatibility Fiber now ships with a routing adapter (see `adapter.go`) that understands native Fiber handlers alongside `net/http` and `fasthttp` handlers. Route registration helpers accept a required `handler` argument plus optional additional `handlers`, all typed as `any`, and the adapter transparently converts supported handler styles so you can keep using the ecosystem functions you're familiar with. diff --git a/route_url_test.go b/route_url_test.go new file mode 100644 index 00000000000..2460da0a2a9 --- /dev/null +++ b/route_url_test.go @@ -0,0 +1,170 @@ +package fiber + +import ( + "fmt" + "io" + "net/http" + "net/http/httptest" + "net/url" + "testing" + + "github.com/stretchr/testify/require" + "github.com/valyala/fasthttp" +) + +// Test_Route_URL_ParameterRepresentability checks rejection through all URL +// entry points and verifies that accepted values round-trip through routing. +func Test_Route_URL_ParameterRepresentability(t *testing.T) { + t.Parallel() + cases := []struct { + name, pattern, key, value, want string + unescape, reject bool + }{ + {name: "plain dot", pattern: "/user/:value", key: "value", value: ".", reject: true}, + {name: "plain parent", pattern: "/user/:value", key: "value", value: "..", reject: true}, + {name: "greedy parent", pattern: "/files/*", key: "*", value: "a/../b", reject: true}, + {name: "greedy trailing dot", pattern: "/files/*", key: "*", value: "a/.", reject: true}, + {name: "dot completed by prefix", pattern: "/p/.:value", key: "value", value: ".", reject: true}, + {name: "dot completed by suffix", pattern: "/p/:value.", key: "value", value: ".", reject: true}, + {name: "dot with extension", pattern: "/p/:value.txt", key: "value", value: ".", want: "/p/..txt"}, + {name: "dotted value after a constant dot", pattern: "/p/.:value", key: "value", value: "a.b", want: "/p/.a.b"}, + {name: "parent after a constant dot", pattern: "/p/.:value", key: "value", value: "..", want: "/p/..."}, + {name: "greedy dot after a constant dot", pattern: "/p/.*", key: "*", value: "./x", reject: true}, + {name: "hidden file", pattern: "/files/*", key: "*", value: ".config/name.txt", want: "/files/.config/name.txt"}, + {name: "three dots", pattern: "/user/:value", key: "value", value: "...", want: "/user/..."}, + {name: "encoded slash remains data", pattern: "/user/:value", key: "value", value: "a/b", want: "/user/a%2Fb"}, + {name: "decoded plain slash", pattern: "/user/:value", key: "value", value: "a/b", unescape: true, reject: true}, + {name: "decoded slash before constant", pattern: "/p/:value/end", key: "value", value: "a/b", unescape: true, reject: true}, + {name: "decoded greedy slash", pattern: "/files/*", key: "*", value: "a/b", unescape: true, want: "/files/a/b"}, + {name: "decoded plus slash", pattern: "/files/+", key: "+", value: "a/b", unescape: true, want: "/files/a/b"}, + {name: "single byte terminator consumes slash", pattern: "/p/:value-", key: "value", value: "a/b", unescape: true, want: "/p/a%2Fb-"}, + {name: "adjacent parameter consumes slash", pattern: "/p/:value:tail", key: "value", value: "/", unescape: true, want: "/p/%2Fb"}, + {name: "adjacent parameter cannot consume middle slash", pattern: "/p/:value:tail", key: "value", value: "a/b", unescape: true, reject: true}, + {name: "adjacent parameter cannot consume leading slash", pattern: "/p/:value:tail", key: "value", value: "/a", unescape: true, reject: true}, + {name: "adjacent parameter cannot consume trailing slash", pattern: "/p/:value:tail", key: "value", value: "a/", unescape: true, reject: true}, + {name: "adjacent parameter cannot consume multibyte slash value", pattern: "/p/:value:tail", key: "value", value: "é/", unescape: true, reject: true}, + {name: "encoded parent stays in one segment", pattern: "/p/:value-", key: "value", value: "a/../b", want: "/p/a%2F..%2Fb-"}, + {name: "decoded parent before terminator", pattern: "/p/:value-", key: "value", value: "a/../b", unescape: true, reject: true}, + {name: "decoded slash splits constant dot before", pattern: "/p/.:value-", key: "value", value: "/x", unescape: true, reject: true}, + {name: "decoded slash splits constant dot after", pattern: "/p/:value.", key: "value", value: "a/", unescape: true, reject: true}, + {name: "literal percent encoded dot", pattern: "/user/:value", key: "value", value: "%2e", unescape: true, want: "/user/%252e"}, + {name: "literal percent before real dot", pattern: "/files/*", key: "*", value: "%2e/name.txt", unescape: true, want: "/files/%252e/name.txt"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + app := New(Config{UnescapePath: tc.unescape}) + app.Get(tc.pattern, func(c Ctx) error { return c.SendString(c.Params(tc.key)) }).Name("target") + ctx := app.AcquireCtx(&fasthttp.RequestCtx{}) + defer app.ReleaseCtx(ctx) + params := Map{tc.key: tc.value, "tail": "b"} + location, routeErr := app.GetRoute("target").URL(params) + ctxLocation, ctxErr := ctx.GetRouteURL("target", params) + redirectErr := ctx.Redirect().Route("target", RedirectConfig{Params: params}) + if tc.reject { + require.ErrorIs(t, routeErr, ErrRouteNotRepresentable) + require.ErrorIs(t, ctxErr, ErrRouteNotRepresentable) + require.ErrorIs(t, redirectErr, ErrRouteNotRepresentable) + require.Empty(t, location) + require.Empty(t, ctxLocation) + require.Empty(t, ctx.Response().Header.Peek(HeaderLocation)) + return + } + require.NoError(t, routeErr) + require.NoError(t, ctxErr) + require.NoError(t, redirectErr) + require.Equal(t, tc.want, location) + require.Equal(t, location, ctxLocation) + require.Equal(t, location, string(ctx.Response().Header.Peek(HeaderLocation))) + response, err := app.Test(httptest.NewRequest(MethodGet, location, http.NoBody)) + require.NoError(t, err) + defer func() { require.NoError(t, response.Body.Close()) }() + require.Equal(t, StatusOK, response.StatusCode) + body, err := io.ReadAll(response.Body) + require.NoError(t, err) + value := string(body) + if !tc.unescape { + value, err = url.PathUnescape(value) + require.NoError(t, err) + } + require.Equal(t, tc.value, value) + }) + } +} + +// Test_Route_URL_MountedRepresentabilityConfig verifies that mounted routes +// and their automatic HEAD copies validate using the parent's decoding policy. +func Test_Route_urlHasDotSegment(t *testing.T) { + t.Parallel() + route := &Route{} + for path, want := range map[string]bool{ + "": false, ".": true, "..": true, "...": false, "/.": true, "/..": true, "/...": false, + "/a/./b": true, "/a/../b": true, "/a/.../b": false, "./a": true, "../a": true, + "/.a": false, "/a.": false, "/a./b": false, "/..a/b": false, "/a/b.c": false, + "/a/b/.": true, "/a/b/..": true, "//.": true, "/a//../b": true, "/%2e/": true, "/%2E%2e/x": true, + } { + require.Equal(t, want, route.urlHasDotSegment([]byte(path)), path) + } +} + +func Test_Route_URL_MountedRepresentabilityConfig(t *testing.T) { + t.Parallel() + for _, parentUnescape := range []bool{false, true} { + for _, domain := range []bool{false, true} { + t.Run(fmt.Sprintf("unescape=%t/domain=%t", parentUnescape, domain), func(t *testing.T) { + t.Parallel() + parent := New(Config{UnescapePath: parentUnescape}) + child := New(Config{UnescapePath: !parentUnescape}) + child.Get("/user/:value", emptyHandler).Name("target") + if domain { + parent.Domain("example.com").Use("/api", child) + } else { + parent.Use("/api", child) + } + parent.startupProcess() + matched := 0 + for _, route := range parent.GetRoutes() { + if route.Name != "target" { + continue + } + matched++ + location, err := route.URL(Map{"value": "a/b"}) + if parentUnescape { + require.ErrorIs(t, err, ErrRouteNotRepresentable) + require.Empty(t, location) + } else { + require.NoError(t, err) + require.Equal(t, "/api/user/a%2Fb", location) + } + } + require.Equal(t, 2, matched, "GET and its automatic HEAD copy must retain the parent config") + }) + } + } +} + +// Benchmark_Route_URL_Representability measures conditional validation costs +// for static, ordinary, escaped, greedy, dotted, and terminated route values. +func Benchmark_Route_URL_Representability(b *testing.B) { + for _, tc := range []struct{ name, pattern, value string }{ + {"static", "/health", ""}, + {"plain", "/user/:value", "fiber"}, + {"escaped", "/user/:value", "a/b?c#d"}, + {"greedy", "/files/*", "docs/readme"}, + {"dotted", "/files/*", "docs/readme.md"}, + {"terminator", "/p/:value-", "fiber"}, + } { + b.Run(tc.name, func(b *testing.B) { + app := New() + app.Get(tc.pattern, emptyHandler).Name("target") + route := app.GetRoute("target") + params := Map{"value": tc.value, "*": tc.value} + b.ReportAllocs() + for b.Loop() { + if _, err := route.URL(params); err != nil { + b.Fatal(err) + } + } + }) + } +} diff --git a/router.go b/router.go index 5d7b2f8860f..314451ec2de 100644 --- a/router.go +++ b/router.go @@ -5,9 +5,11 @@ package fiber import ( + "bytes" "fmt" "math/bits" "slices" + "strings" "sync/atomic" "github.com/gofiber/fiber/v3/internal/urlnorm" @@ -104,6 +106,7 @@ type Route struct { // betteralign:ignore - see below root bool // Path equals '/' autoHead bool // Automatically generated HEAD route caseSensitive bool // Whether parameter matching is case-sensitive + unescapePath bool // Whether request routing decodes escaped slashes routeParser routeParser // Parameter parser @@ -260,6 +263,8 @@ func (t *routeTree) lookup(hash int) (routes []*Route, filter *bucketFilter) { // Parameter matching respects the app's CaseSensitive configuration: // case-insensitive by default, case-sensitive when CaseSensitive is true. // Parameter values are percent-encoded using URL path-segment rules. +// Dot-containing values that form a dot-only path segment, and slashes that +// UnescapePath would decode outside a parameter's match, return ErrRouteNotRepresentable. // // Example: // @@ -310,6 +315,7 @@ func buildRouteURL(route *Route, params Map) (string, error) { buf := bytebufferpool.Get() defer bytebufferpool.Put(buf) + checkDotSegments := false for _, segment := range route.routeParser.segs { if !segment.IsParam { @@ -352,17 +358,78 @@ func buildRouteURL(route *Route, params Map) (string, error) { } if found { + value := utils.ToString(val) + if !checkDotSegments { + if segment.IsGreedy { + checkDotSegments = strings.IndexByte(value, '.') >= 0 + } else { + // Its slashes get escaped, so it stays inside one segment and only + // "." or ".." can be or complete a dot segment. + checkDotSegments = value == "." || value == ".." + } + } + if route.unescapePath && strings.IndexByte(value, '/') >= 0 { + if route.slashLeavesParam(segment, value) { + return "", ErrRouteNotRepresentable + } + // A slash in the value can split a constant dot into its own segment. + checkDotSegments = true + } if segment.IsGreedy { - buf.B = utils.AppendPathSegmentsEscape(buf.B, utils.ToString(val)) + buf.B = utils.AppendPathSegmentsEscape(buf.B, value) continue } - buf.B = utils.AppendPathEscape(buf.B, utils.ToString(val)) + buf.B = utils.AppendPathEscape(buf.B, value) } } + if checkDotSegments && route.urlHasDotSegment(buf.B) { + return "", ErrRouteNotRepresentable + } return urlnorm.RootedPath(buf.String()), nil } +// slashLeavesParam reports whether a decoded slash in value ends up outside the parameter. +// It mirrors the slash-consuming branches of findParamLen, including adjacent parameters +// (which consume exactly one byte) and single-byte non-slash terminators. +func (*Route) slashLeavesParam(segment *routeSegment, value string) bool { + return !segment.IsGreedy && + (segment.IsLast || (segment.Length == 1 && len(value) > 1) || + (segment.Length != 1 && (len(segment.ComparePart) != 1 || segment.ComparePart[0] == slashDelimiter))) +} + +// urlHasDotSegment checks the composed path, since constants can complete or +// disambiguate a parameter's dots. Decode once, just as request routing does; +// an escaped slash is a boundary only with UnescapePath enabled. +func (r *Route) urlHasDotSegment(path []byte) bool { + if bytes.IndexByte(path, '%') != -1 { + path = slices.Clone(path) + if r.unescapePath { + path = unescapePath(path) + } else { + path = unescapeSafePath(path) + } + } + // Jump from dot to dot: a dot segment starts after a '/' and ends at a '/' or the end. + for i := bytes.IndexByte(path, '.'); i >= 0; { + if i == 0 || path[i-1] == '/' { + j := i + 1 + if j < len(path) && path[j] == '.' { + j++ + } + if j == len(path) || path[j] == '/' { + return true + } + } + next := bytes.IndexByte(path[i+1:], '.') + if next < 0 { + break + } + i += next + 1 + } + return false +} + // preferredGreedyParameters returns the generic greedy fallback lookup order // for a route parameter name. // Parameter names starting with '+' prefer '+' before '*', names starting with @@ -1031,6 +1098,7 @@ func (app *App) addPrefixToRoute(prefix string, route *Route, regexHandler any, route.root = false route.star = false route.caseSensitive = app.config.CaseSensitive + route.unescapePath = app.config.UnescapePath // buildTree recomputes this for every route, but this function rewrites the // path and parser a filter is derived from, so refresh it here too rather // than depend on a caller marking the routes refreshed. @@ -1065,6 +1133,7 @@ func (*App) copyRoute(route *Route) *Route { root: route.root, autoHead: route.autoHead, caseSensitive: route.caseSensitive, + unescapePath: route.unescapePath, // Path data path: route.path, @@ -1229,6 +1298,7 @@ func (app *App) register(methods []string, pathRaw string, group *Group, handler star: isStar, root: isRoot, caseSensitive: app.config.CaseSensitive, + unescapePath: app.config.UnescapePath, id: routeID, latestID: routeID,