Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
2 changes: 1 addition & 1 deletion docs/adr/0002-stdadapter-servemux.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
26 changes: 24 additions & 2 deletions middlewares.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
}
Expand Down
56 changes: 56 additions & 0 deletions middlewares_skip_path_test.go
Original file line number Diff line number Diff line change
@@ -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())
}
})
}
}
Loading