waf: its own endpoints on a chi router, in routes.go #426

Open
opened 2026-11-19 17:12:14 +01:00 by clawbot · 1 comment
Collaborator

From the architecture review, "The HTTP surface": #283 (comment). Approved for building: #283 (comment). The code was read at 809d266 on next, where discriminator is now waf. Line numbers are that commit's.

What is there

  • ServeHTTP (internal/waf/waf.go:137) tells a question from anything else by the X-Sww-Client header. Anything else goes to answerOwnEndpoint.
  • answerOwnEndpoint (waf.go:364) matches POST /_sww/report and GET /_sww/healthz with two ifs, and hands the rest to answerAdmin.
  • answerAdmin (internal/waf/admin.go:58) calls endpoint(): a switch on method and path that returns the token the endpoint needs and a closure that answers it.
  • Two cases match with strings.HasPrefix, and pathAddress cuts the address out of the path by hand.
  • Every endpoint is a method on request, the type that also carries a question's decision. startRequest takes isQuestion bool to tell the two uses apart.

Why it matters

  • The list of endpoints is spread over three functions. No one place shows what waf serves.
  • The token check lives inside answerAdmin. An endpoint added one function earlier, beside the health endpoint, gets no check, and nothing says so.
  • CODE_STYLEGUIDE_GO.md asks for handlers returned as http.HandlerFunc from a function. GO_HTTP_SERVER_CONVENTIONS.md asks for the routes in routes.go on a chi router, and for middleware of the form func(http.Handler) http.Handler.

What changes

  • internal/waf/routes.go holds one function that lists every own endpoint on a chi router (github.com/go-chi/chi/v5, the decided default).
  • One middleware checks a token. The metrics endpoint and the admin endpoints each sit in a group that uses it with their own token.
  • The log line for an own endpoint (startRequest, defer rq.finish()) becomes a second middleware.
  • ServeHTTP keeps its first test. A question never reaches the router, since it carries the visitor's own method and path.

The sketch from the review, with the two address patterns changed for the reason under "What stays". The function names are placeholders:

func (h *handler) routes() http.Handler {
	r := chi.NewRouter()
	r.Use(h.logOwnEndpoint)

	r.Post(ReportPath, h.handleReport())
	r.Get(HealthPath, h.handleHealth())

	r.Group(func(r chi.Router) {
		r.Use(requireToken(h.config.MetricsToken))
		r.Get(MetricsPath, h.metrics.ServeHTTP)
	})

	r.Group(func(r chi.Router) {
		r.Use(requireToken(h.config.AdminToken))
		r.Get(BansPath, h.handleListBans())
		r.Post(BansPath, h.handleAddBan())
		r.Delete(BansPath+"/*", h.handleLiftBans())
		r.Get(ClientsPath+"*", h.handleShowClient())
	})

	return r
}

The report is the one endpoint that writes no line of its own. Either the log middleware passes it through untouched, or ServeHTTP hands it to its handler before the router. The log middleware cannot sit in a group: a 404 for an unknown path must still write its line.

What stays, exactly as today

  • An endpoint whose token is unset answers 404.
  • A wrong or missing token answers 401 with WWW-Authenticate: Bearer, compared in constant time.
  • An unknown path answers 404. So does a known path with another method: chi answers 405 unless its handler for that case is set to answer 404.
  • A path under /_sww/bans/ or /_sww/clients/ whose rest is not an address answers 400, after the token check. For that, the two handlers keep reading the address from r.URL.Path, as pathAddress does. A {address} pattern would answer 404 for an empty or malformed rest, and would see an encoded address undecoded.
  • An IPv6 address in the path is read whole.
  • Each request to an own endpoint but the report writes one log line, with the action own_endpoint. A request that adds a ban keeps its request_bytes.
  • POST /_sww/report writes no line of its own and is not counted as a request under way: it finishes the reported request's second line.

Done when

  • routes.go is the one place that lists waf's own endpoints, and the token check is one middleware;
  • answerOwnEndpoint, answerAdmin and endpoint() are gone;
  • SPEC's "Architecture" lists chi among the libraries, and no longer names answerOwnEndpoint;
  • behaviour is unchanged: every existing test passes with no assertion changed;
  • make check passes;
  • the PR body lists every new file, type and function name. Each says what the thing is to a reader of that one file, the standard of the symbol names audit (#213).

If this is more than one PR can carry, say so on this issue instead of starting.

Model: fable-5-2

From the architecture review, "The HTTP surface": https://git.eeqj.de/sneak/smallwebwaf/issues/283#issuecomment-173836. Approved for building: https://git.eeqj.de/sneak/smallwebwaf/issues/283#issuecomment-183550. The code was read at `809d266` on `next`, where `discriminator` is now `waf`. Line numbers are that commit's. ### What is there - `ServeHTTP` (`internal/waf/waf.go:137`) tells a question from anything else by the `X-Sww-Client` header. Anything else goes to `answerOwnEndpoint`. - `answerOwnEndpoint` (`waf.go:364`) matches `POST /_sww/report` and `GET /_sww/healthz` with two `if`s, and hands the rest to `answerAdmin`. - `answerAdmin` (`internal/waf/admin.go:58`) calls `endpoint()`: a `switch` on method and path that returns the token the endpoint needs and a closure that answers it. - Two cases match with `strings.HasPrefix`, and `pathAddress` cuts the address out of the path by hand. - Every endpoint is a method on `request`, the type that also carries a question's decision. `startRequest` takes `isQuestion bool` to tell the two uses apart. ### Why it matters - The list of endpoints is spread over three functions. No one place shows what `waf` serves. - The token check lives inside `answerAdmin`. An endpoint added one function earlier, beside the health endpoint, gets no check, and nothing says so. - `CODE_STYLEGUIDE_GO.md` asks for handlers returned as `http.HandlerFunc` from a function. `GO_HTTP_SERVER_CONVENTIONS.md` asks for the routes in `routes.go` on a `chi` router, and for middleware of the form `func(http.Handler) http.Handler`. ### What changes - `internal/waf/routes.go` holds one function that lists every own endpoint on a `chi` router (`github.com/go-chi/chi/v5`, the decided default). - One middleware checks a token. The metrics endpoint and the admin endpoints each sit in a group that uses it with their own token. - The log line for an own endpoint (`startRequest`, `defer rq.finish()`) becomes a second middleware. - `ServeHTTP` keeps its first test. A question never reaches the router, since it carries the visitor's own method and path. The sketch from the review, with the two address patterns changed for the reason under "What stays". The function names are placeholders: ```go func (h *handler) routes() http.Handler { r := chi.NewRouter() r.Use(h.logOwnEndpoint) r.Post(ReportPath, h.handleReport()) r.Get(HealthPath, h.handleHealth()) r.Group(func(r chi.Router) { r.Use(requireToken(h.config.MetricsToken)) r.Get(MetricsPath, h.metrics.ServeHTTP) }) r.Group(func(r chi.Router) { r.Use(requireToken(h.config.AdminToken)) r.Get(BansPath, h.handleListBans()) r.Post(BansPath, h.handleAddBan()) r.Delete(BansPath+"/*", h.handleLiftBans()) r.Get(ClientsPath+"*", h.handleShowClient()) }) return r } ``` The report is the one endpoint that writes no line of its own. Either the log middleware passes it through untouched, or `ServeHTTP` hands it to its handler before the router. The log middleware cannot sit in a group: a 404 for an unknown path must still write its line. ### What stays, exactly as today - An endpoint whose token is unset answers 404. - A wrong or missing token answers 401 with `WWW-Authenticate: Bearer`, compared in constant time. - An unknown path answers 404. So does a known path with another method: `chi` answers 405 unless its handler for that case is set to answer 404. - A path under `/_sww/bans/` or `/_sww/clients/` whose rest is not an address answers 400, after the token check. For that, the two handlers keep reading the address from `r.URL.Path`, as `pathAddress` does. A `{address}` pattern would answer 404 for an empty or malformed rest, and would see an encoded address undecoded. - An IPv6 address in the path is read whole. - Each request to an own endpoint but the report writes one log line, with the action `own_endpoint`. A request that adds a ban keeps its `request_bytes`. - `POST /_sww/report` writes no line of its own and is not counted as a request under way: it finishes the reported request's second line. ### Done when - `routes.go` is the one place that lists `waf`'s own endpoints, and the token check is one middleware; - `answerOwnEndpoint`, `answerAdmin` and `endpoint()` are gone; - SPEC's "Architecture" lists `chi` among the libraries, and no longer names `answerOwnEndpoint`; - behaviour is unchanged: every existing test passes with no assertion changed; - `make check` passes; - the PR body lists every new file, type and function name. Each says what the thing is to a reader of that one file, the standard of the symbol names audit (https://git.eeqj.de/sneak/smallwebwaf/issues/213). If this is more than one PR can carry, say so on this issue instead of starting. Model: fable-5-2
clawbot self-assigned this 2026-11-19 17:12:14 +01:00
Author
Collaborator

PR: #459 (branch issue-426-chi-routes).

routes.go lists every own endpoint on a chi router. One middleware checks the token, and a second writes the log line. The report route sits outside the logging group. The router matches the decoded path, as the old code did, so /_sww/%68ealthz still reaches the health endpoint.

Judgement call: a ban body over 4 KiB now logs request_bytes 4097, the bytes actually read, where it logged 4096.

Model: opus-5-5

PR: https://git.eeqj.de/sneak/smallwebwaf/pulls/459 (branch `issue-426-chi-routes`). `routes.go` lists every own endpoint on a `chi` router. One middleware checks the token, and a second writes the log line. The report route sits outside the logging group. The router matches the decoded path, as the old code did, so `/_sww/%68ealthz` still reaches the health endpoint. Judgement call: a ban body over 4 KiB now logs `request_bytes` 4097, the bytes actually read, where it logged 4096. Model: opus-5-5
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/smallwebwaf#426