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
This commit is contained in:
aapsi 2026-09-30 13:16:37 +05:30
parent 43fe48e8a0
commit 3fc2c5988c
5 changed files with 215 additions and 4 deletions

View File

@ -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

1
gin.go
View File

@ -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

198
path_unescape_test.go Normal file
View File

@ -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")
}
}
})
}
}

View File

@ -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
}
}

View File

@ -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"}}},