From 3fc2c5988c4d238b0581aa29ea18928b019385a4 Mon Sep 17 00:00:00 2001 From: aapsi Date: Wed, 30 Sep 2026 13:16:37 +0530 Subject: [PATCH] fix(tree): preserve literal plus signs in path parameters Use path decoding for named and catch-all values in encoded-path routing modes. Add routing flag, middleware, HTTP and fuzz coverage, and document that spaces in path parameters must be encoded as %20. Fixes #3850 --- docs/doc.md | 8 ++ gin.go | 1 + path_unescape_test.go | 198 ++++++++++++++++++++++++++++++++++++++++++ tree.go | 4 +- tree_test.go | 8 +- 5 files changed, 215 insertions(+), 4 deletions(-) create mode 100644 path_unescape_test.go diff --git a/docs/doc.md b/docs/doc.md index 16102841..28339283 100644 --- a/docs/doc.md +++ b/docs/doc.md @@ -216,6 +216,14 @@ func main() { } ``` +When `UseEscapedPath` or `UseRawPath` selects an encoded path and +`UnescapePathValues` is `true`, Gin decodes path parameters using +`url.PathUnescape`. Both `+` and `%2B` represent a literal plus sign; use `%20` +for a space. This applies to named parameters (`:name`) and catch-all parameters +(`*action`). For example, `/user/first+last` gives `first+last`, while +`/user/first%20last` gives `first last`. Query strings retain their usual +behavior: `?name=first+last` gives `first last` through `c.Query("name")`. + ### Querystring parameters ```go diff --git a/gin.go b/gin.go index a1607275..803dc342 100644 --- a/gin.go +++ b/gin.go @@ -151,6 +151,7 @@ type Engine struct { UseEscapedPath bool // UnescapePathValues if true, the path value will be unescaped. + // Percent-encoded bytes are decoded with url.PathUnescape; literal '+' characters are preserved. // If UseRawPath and UseEscapedPath are false (by default), the UnescapePathValues effectively is true, // as url.Path gonna be used, which is already unescaped. UnescapePathValues bool diff --git a/path_unescape_test.go b/path_unescape_test.go new file mode 100644 index 00000000..51f358a6 --- /dev/null +++ b/path_unescape_test.go @@ -0,0 +1,198 @@ +// Copyright 2026 Gin Core Team. All rights reserved. +// Use of this source code is governed by a MIT style +// license that can be found in the LICENSE file. + +package gin + +import ( + "io" + "net/http" + "net/http/httptest" + "net/url" + "strings" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestRoutePathUnescape(t *testing.T) { + for _, mode := range []struct { + name string + raw, escaped, decode bool + }{ + {name: "default", decode: true}, + {name: "default_no_unescape"}, + {name: "raw", raw: true, decode: true}, + {name: "raw_no_unescape", raw: true}, + {name: "escaped", escaped: true, decode: true}, + {name: "escaped_no_unescape", escaped: true}, + {name: "escaped_over_raw", raw: true, escaped: true, decode: true}, + {name: "escaped_over_raw_no_unescape", raw: true, escaped: true}, + } { + t.Run(mode.name, func(t *testing.T) { + router := New() + router.UseRawPath = mode.raw + router.UseEscapedPath = mode.escaped + router.UnescapePathValues = mode.decode + router.Use(func(c *Context) { + c.Header("Middleware-Param", c.Param("value")) + c.Next() + }) + for _, route := range []string{"/single/:value/end", "/catch/*value"} { + router.GET(route, func(c *Context) { + c.Header("Matched-Route", c.FullPath()) + c.Header("Query-Value", c.Query("q")) + c.String(http.StatusOK, "%s", c.Param("value")) + }) + } + for _, tc := range []struct { + name, encoded, decoded, raw string + }{ + {name: "literal_plus", encoded: "a+b", decoded: "a+b"}, + {name: "encoded_plus", encoded: "a%2Bb", decoded: "a+b", raw: "a%2Bb"}, + {name: "lowercase_escape", encoded: "a%2bb", decoded: "a+b", raw: "a%2bb"}, + {name: "space", encoded: "a%20b", decoded: "a b"}, + {name: "plus_and_space", encoded: "a+b%20c", decoded: "a+b c"}, + {name: "plus_and_slash", encoded: "a+%2Fb", decoded: "a+/b", raw: "a+%2Fb"}, + {name: "encoded_once", encoded: "a+%252Fb", decoded: "a+%2Fb"}, + {name: "percent", encoded: "a+%25b", decoded: "a+%b"}, + {name: "reserved", encoded: "a+%3Fb%23c%26d%3De", decoded: "a+?b#c&d=e", raw: "a+%3Fb%23c%26d%3De"}, + {name: "unicode", encoded: "%E2%98%83+%F0%9F%98%80", decoded: "☃+😀"}, + } { + for _, catchAll := range []bool{false, true} { + name := tc.name + "/single" + if catchAll { + name = tc.name + "/catch_all" + } + t.Run(name, func(t *testing.T) { + prefix, suffix, route := "/single/", "/end", "/single/:value/end" + if catchAll { + prefix, suffix, route = "/catch/", "", "/catch/*value" + } + req := httptest.NewRequest(http.MethodGet, prefix+tc.encoded+suffix+"?q=a+b", nil) + originalURL := *req.URL + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + assert.Equal(t, originalURL, *req.URL) + + // The default route matcher sees decoded slashes as separators. + if !mode.raw && !mode.escaped && !catchAll && strings.Contains(tc.decoded, "/") { + assert.Equal(t, http.StatusNotFound, w.Code) + return + } + want := tc.decoded + if !mode.decode { + if mode.escaped { + want = tc.encoded + } else if mode.raw && tc.raw != "" { + want = tc.raw + } + } + if catchAll { + want = "/" + want + } + assert.Equal(t, http.StatusOK, w.Code) + assert.Equal(t, want, w.Body.String()) + assert.Equal(t, want, w.Header().Get("Middleware-Param")) + assert.Equal(t, route, w.Header().Get("Matched-Route")) + assert.Equal(t, "a b", w.Header().Get("Query-Value")) + }) + } + } + }) + } +} + +func TestRoutePathUnescapeHTTP(t *testing.T) { + for _, escaped := range []bool{false, true} { + for _, http2 := range []bool{false, true} { + name := "raw/http1" + if escaped { + name = "escaped/http1" + } + if http2 { + name = strings.TrimSuffix(name, "http1") + "http2" + } + t.Run(name, func(t *testing.T) { + router := New() + router.UseRawPath = !escaped + router.UseEscapedPath = escaped + router.GET("/item/:value", func(c *Context) { + c.String(http.StatusOK, "%s|%s", c.Param("value"), c.Query("q")) + }) + server := httptest.NewUnstartedServer(router) + server.EnableHTTP2 = http2 + if http2 { + server.StartTLS() + } else { + server.Start() + } + defer server.Close() + client := server.Client() + client.Timeout = 5 * time.Second + resp, err := client.Get(server.URL + "/item/a+%2Fb?q=a+b") + require.NoError(t, err) + defer resp.Body.Close() + body, err := io.ReadAll(resp.Body) + require.NoError(t, err) + assert.Equal(t, http.StatusOK, resp.StatusCode) + assert.Equal(t, "a+/b|a b", string(body)) + if http2 { + assert.Equal(t, 2, resp.ProtoMajor) + } else { + assert.Equal(t, 1, resp.ProtoMajor) + } + }) + } + } +} + +func FuzzRoutePathUnescape(f *testing.F) { + for _, value := range []string{"", "+", " ", "%2F", "/", "a+%2Fb", "☃+😀", "\x00\xff", "a?b#c&d=e"} { + f.Add(value) + } + router := New() + router.UseEscapedPath = true + router.GET("/single/:value/end", func(c *Context) { + c.String(http.StatusOK, "%s", c.Param("value")) + }) + router.GET("/catch/*value", func(c *Context) { + c.String(http.StatusOK, "%s", c.Param("value")) + }) + f.Fuzz(func(t *testing.T, value string) { + // Keep the parameter nonempty, including when the generated value is empty. + value = "v" + value + escaped := url.PathEscape(value) + for _, tc := range []struct{ path, want string }{ + {path: "/single/" + escaped + "/end", want: value}, + {path: "/catch/" + escaped, want: "/" + value}, + } { + w := PerformRequest(router, http.MethodGet, tc.path) + require.Equal(t, http.StatusOK, w.Code) + assert.Equal(t, tc.want, w.Body.String()) + } + }) +} + +func BenchmarkRoutePathUnescape(b *testing.B) { + for _, path := range []string{"plain", "a+b", "a%2Bb", "a%20b", "a+%2Fb"} { + b.Run(path, func(b *testing.B) { + tree := &node{} + tree.addRoute("/single/:value/end", HandlersChain{func(*Context) {}}) + params, skipped := getParams(), getSkippedNodes() + requestPath := "/single/" + path + "/end" + b.ReportAllocs() + b.ResetTimer() + for i := 0; i < b.N; i++ { + *params = (*params)[:0] + *skipped = (*skipped)[:0] + value := tree.getValue(requestPath, params, skipped, true) + if value.handlers == nil { + b.Fatal("route did not match") + } + } + }) + } +} diff --git a/tree.go b/tree.go index 6efe2e0e..88cb8027 100644 --- a/tree.go +++ b/tree.go @@ -519,7 +519,7 @@ walk: // Outer loop for walking the tree *value.params = (*value.params)[:i+1] val := path[:end] if unescape { - if v, err := url.QueryUnescape(val); err == nil { + if v, err := url.PathUnescape(val); err == nil { val = v } } @@ -572,7 +572,7 @@ walk: // Outer loop for walking the tree *value.params = (*value.params)[:i+1] val := path if unescape { - if v, err := url.QueryUnescape(path); err == nil { + if v, err := url.PathUnescape(val); err == nil { val = v } } diff --git a/tree_test.go b/tree_test.go index 23339af4..649fb37e 100644 --- a/tree_test.go +++ b/tree_test.go @@ -345,10 +345,14 @@ func TestUnescapeParameters(t *testing.T) { {"/cmd/test/", false, "/cmd/:tool/", Params{Param{Key: "tool", Value: "test"}}}, {"/cmd/test", true, "", Params{Param{Key: "tool", Value: "test"}}}, {"/src/some/file.png", false, "/src/*filepath", Params{Param{Key: "filepath", Value: "/some/file.png"}}}, - {"/src/some/file+test.png", false, "/src/*filepath", Params{Param{Key: "filepath", Value: "/some/file test.png"}}}, + {"/src/some/file+test.png", false, "/src/*filepath", Params{Param{Key: "filepath", Value: "/some/file+test.png"}}}, + {"/src/some/file%2Btest.png", false, "/src/*filepath", Params{Param{Key: "filepath", Value: "/some/file+test.png"}}}, + {"/src/some/file%20test.png", false, "/src/*filepath", Params{Param{Key: "filepath", Value: "/some/file test.png"}}}, {"/src/some/file++++%%%%test.png", false, "/src/*filepath", Params{Param{Key: "filepath", Value: "/some/file++++%%%%test.png"}}}, {"/src/some/file%2Ftest.png", false, "/src/*filepath", Params{Param{Key: "filepath", Value: "/some/file/test.png"}}}, - {"/search/someth!ng+in+ünìcodé", false, "/search/:query", Params{Param{Key: "query", Value: "someth!ng in ünìcodé"}}}, + {"/search/someth!ng+in+ünìcodé", false, "/search/:query", Params{Param{Key: "query", Value: "someth!ng+in+ünìcodé"}}}, + {"/search/a+%2Bb%20c", false, "/search/:query", Params{Param{Key: "query", Value: "a++b c"}}}, + {"/search/a+%ZZ", false, "/search/:query", Params{Param{Key: "query", Value: "a+%ZZ"}}}, {"/info/gordon/project/go", false, "/info/:user/project/:project", Params{Param{Key: "user", Value: "gordon"}, Param{Key: "project", Value: "go"}}}, {"/info/slash%2Fgordon", false, "/info/:user", Params{Param{Key: "user", Value: "slash/gordon"}}}, {"/info/slash%2Fgordon/project/Project%20%231", false, "/info/:user/project/:project", Params{Param{Key: "user", Value: "slash/gordon"}, Param{Key: "project", Value: "Project #1"}}},