diff --git a/README.md b/README.md index e2e4790..c052a6e 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ func main() { - assigns an [event ID](#trace-ids) and logs the request and the response (on an `api.New` instance only through its `api.WithLogger` logger, and nothing without one; on the default instance through `slog.Default`; see [Logging](#logging)); - stores the request context, replaces `r.Body` with the endpoint content, and answers 500 if the handler panics (a panic with `http.ErrAbortHandler` is re-panicked, so `net/http` aborts the response). - Use `api.MiddlewaresChain(...)` to compose it with your own middlewares. `api.AddSkipPath(api.GenSkipPath(method, path), true)` makes it pass a route through untouched. + Use `api.MiddlewaresChain(...)` to compose it with your own middlewares. `api.AddSkipPath(api.GenSkipPath(method, path), true)` makes it pass a route through untouched. A skip path matches the decoded path only when the request path is sent exactly as Go's canonical encoding of it (an empty `URL.RawPath`): `/health%2Flive` (or `%2f`, or an escaped letter such as `/health/%6Cive`) is processed even with the skip path `GET:/health/live`, since ServeMux may route it to another handler such as `GET /{tenant}`. Since v1.1.2 a raw `!`, `'`, `(`, `)` or `*`, which Go escapes in a path, makes a request processed too: the key `GET:/a(b)` matches `/a%28b%29`, not `/a(b)`. 3. **The handler** reads the content, then writes one [response](#responses) or [error](#writing-errors). 4. **The formatter** shapes the response according to the [response mode](#request-and-response-modes) and adds the event ID, code and token (a token only when the handler sets `SecurityToken`; the request token is never echoed). diff --git a/docs/adr/0002-stdadapter-servemux.md b/docs/adr/0002-stdadapter-servemux.md index 028c2fa..f25b2ff 100644 --- a/docs/adr/0002-stdadapter-servemux.md +++ b/docs/adr/0002-stdadapter-servemux.md @@ -18,7 +18,7 @@ Behavior changes: 3. An escaped `%2F` inside a segment matches a wildcard (`/files/a%2Fb` matches `/files/{name}` with `name` = `a/b`), because ServeMux matches on the escaped path. A wildcard value can therefore contain `/` and `..` (`/one/..%2F..%2Fetc` gives `name` = `../../etc`; v0.10.0 answered 404). Handlers must validate it before using it in a file path; the README security notes say so. 4. Wildcard names must be Go identifiers (`{user_id}`, not `{user-id}`) and whole segments (`/files/{name}`, not `/files/{name}.json`). `{name}` is the only supported wildcard: ServeMux's `{name...}` and `{$}` panic at registration, because `doc` would publish them as invalid OpenAPI paths and no route needs them yet (YAGNI). The method must be an upper-case RFC 9110 token: `""` would register a method-less catch-all, `GE T` a pattern that never matches, and `get` a route that does not match its documentation, so all three panic. 5. 405 is decided by the whole mux and carries an `Allow` header (`GET, HEAD, PUT`). A catch-all `/` on the caller's mux takes those requests instead, so they get its answer, not 405. -6. A GET route also answers HEAD. Method-keyed logic sees `HEAD`: the skip path `GET:/health` (`api.GenSkipPath`) does not cover `HEAD /health`. +6. A GET route also answers HEAD. Method-keyed logic sees `HEAD`: the skip path `GET:/health` (`api.GenSkipPath`) does not cover `HEAD /health`. *(Amended in v1.1.2: because of item 3, a skip path matches only a request path sent as Go's canonical encoding of its decoded path (an empty `URL.RawPath`; a raw `!`, `'`, `(`, `)` or `*` is not canonical either); `GET /health%2Flive` is processed, not skipped by `GET:/health/live`, since it may be routed to `/{tenant}`.)* 7. Unclean paths (`//tasks`, `/a/../tasks`) keep ServeMux's redirect to the cleaned path (307); this did not change, though earlier notes said 301. 8. `GODEBUG=httpmuxgo121=1` turns off pattern matching and breaks every route, and it also turns off the conflict panic. It can come from the environment, a `//go:debug httpmuxgo121=1` directive, or a `godebug` line in the main module's `go.mod`. The adapter requires the Go 1.22 mux and does not try to detect the setting. diff --git a/middlewares.go b/middlewares.go index 08e4fe9..03332f1 100644 --- a/middlewares.go +++ b/middlewares.go @@ -197,6 +197,15 @@ type SkipPath string // SkipPaths holds the routes ProcessRequest skips: a request whose method and // URL path match a key is not parsed and goes straight to the next handler. // Only presence counts; the bool value is ignored. +// +// Only a request path sent exactly as Go's canonical encoding of its decoded +// path (an empty r.URL.RawPath) can match. Any other spelling is processed +// even when its decoded form is a key: an escaped slash (/health%2Flive, +// %2f), an escaped unreserved character (/health/%6Cive), and the raw +// characters ! ' ( ) * that Go escapes in a path (/a(b) is processed, while +// /a%28b%29 matches the key /a(b)). A router that matches the escaped path +// may route an escaped slash to another handler (GET /{tenant}), which must +// not lose its processing. var SkipPaths map[SkipPath]bool // AddSkipPath adds path to SkipPaths. ProcessRequest skips path whatever skip @@ -218,11 +227,24 @@ func DeleteSkipPath(path SkipPath) { } // GenSkipPath returns the SkipPath of method and path, as matched against the -// request method and URL path (no query). +// request method and decoded URL path (no query) of a request whose path has +// Go's canonical encoding (see SkipPaths). func GenSkipPath(method string, path string) SkipPath { return SkipPath(fmt.Sprintf("%s:%s", method, path)) } +// skipsRequest reports whether r matches a SkipPaths key. A non-empty +// RawPath means the request path is not the canonical encoding of Path (an +// escaped slash, for one), so the decoded path may not be the path the router +// matched; such a request is never skipped. +func skipsRequest(r *http.Request) bool { + if r.URL.RawPath != "" { + return false + } + _, exists := SkipPaths[GenSkipPath(r.Method, r.URL.Path)] + return exists +} + // ProcessRequest process request information. // // The proxiedIPAddress info value is the first X-Forwarded-For header line up @@ -236,7 +258,7 @@ func ProcessRequest(next http.HandlerFunc) http.HandlerFunc { start := time.Now() a := instanceFrom(r) - if _, exists := SkipPaths[GenSkipPath(r.Method, r.URL.Path)]; exists { + if skipsRequest(r) { next.ServeHTTP(w, r) return } diff --git a/middlewares_skip_path_test.go b/middlewares_skip_path_test.go new file mode 100644 index 0000000..79cfc10 --- /dev/null +++ b/middlewares_skip_path_test.go @@ -0,0 +1,56 @@ +package api + +import ( + "net/http" + "net/http/httptest" + "testing" +) + +// TestProcessRequestSkipPathsIgnoreNonCanonicalEscapes checks that a skip +// path matches only a path with no non-canonical escape, so an escaped slash +// routed to another handler is still processed. +func TestProcessRequestSkipPathsIgnoreNonCanonicalEscapes(t *testing.T) { + t.Cleanup(func() { SkipPaths = make(map[SkipPath]bool) }) + SkipPaths = make(map[SkipPath]bool) + AddSkipPath(GenSkipPath(http.MethodGet, "/health/live"), true) + AddSkipPath(GenSkipPath(http.MethodGet, "/status page"), true) + AddSkipPath(GenSkipPath(http.MethodGet, "/report(1)"), true) + + tests := []struct { + name string + target string + wantRoute string + wantSkipped bool + }{ + {name: "skip path", target: "/health/live", wantRoute: "health", wantSkipped: true}, + {name: "skip path with query", target: "/health/live?verbose=1", wantRoute: "health", wantSkipped: true}, + {name: "canonically escaped space", target: "/status%20page", wantRoute: "tenant", wantSkipped: true}, + {name: "escaped slash", target: "/health%2Flive", wantRoute: "tenant", wantSkipped: false}, + {name: "lower-case escaped slash", target: "/health%2flive", wantRoute: "tenant", wantSkipped: false}, + {name: "double-encoded slash", target: "/health%252Flive", wantRoute: "tenant", wantSkipped: false}, + {name: "escaped letter", target: "/health/%6Cive", wantRoute: "health", wantSkipped: false}, + {name: "canonically escaped sub-delims", target: "/report%281%29", wantRoute: "tenant", wantSkipped: true}, + {name: "raw sub-delims are not canonical", target: "/report(1)", wantRoute: "tenant", wantSkipped: false}, + {name: "other route", target: "/acme", wantRoute: "tenant", wantSkipped: false}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + logger, buf := newRecordingLogger() + var route string + mux := http.NewServeMux() + mux.HandleFunc("GET /health/live", func(w http.ResponseWriter, r *http.Request) { route = "health" }) + mux.HandleFunc("GET /{tenant}", func(w http.ResponseWriter, r *http.Request) { route = "tenant" }) + handler := New(WithLogger(logger)).Handler(ProcessRequest(mux.ServeHTTP)) + + handler.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, tt.target, nil)) + + if route != tt.wantRoute { + t.Fatalf("route = %q, want %q", route, tt.wantRoute) + } + skipped := buf.Len() == 0 + if skipped != tt.wantSkipped { + t.Fatalf("skipped = %v, want %v (log %q)", skipped, tt.wantSkipped, buf.String()) + } + }) + } +}