httpstatus linter
This linter imposes constraints on use of http status codes, targeted mainly at JSON APIs. The goal is to discourage use of non-typical status codes.
A "typical" status code is one which:
- is commonly used
- is significantly differentiated from all other "typical" status codes (i.e., there should never be more than one plausible choice of which code to return)
- programmers are expected to have it memorized.
These constraints impose a natural limit on how many "typical" status codes you can have.
A certain list of "typical" status codes is a config parameter. By default it includes:
- 200, 204
- Notes: 201 is disallowed. Use 200 instead
- 302
- Notes: all other 300-series are situationally valid, as they directly affect browser / cache behavior, but are less frequently used in JSON APIs. For this reason,
http.Redirect()calls are exempt from the "restrict" rule.
- Notes: all other 300-series are situationally valid, as they directly affect browser / cache behavior, but are less frequently used in JSON APIs. For this reason,
- 400, 401, 403, 404, 429
- 409, 410 and 422 are disallowed; use 400 instead.
- Notes: explicit 405 is disallowed; router should return one automatically
- 502, 504
- Notes: explicit 500 is disallowed. Use panic instead
- All other status codes are considered "non-typical"
Status codes in the "typical" list require use of "magic numbers" (the opposite of staticcheck's ST1013 check, on purpose); using http.StatusBlahBlah is disallowed. Only non-typical status codes are permitted to use the named net/http constants. "Magic numbers" are shorter and-- for typical status codes-- more readable.
If the optional "restrict" config value is set to "true", then setting non-typical status codes in HTTP handlers is also disallowed. As noted above, http.Redirect() and the 300-series is exempt from this.
Implementation clarifications
- Check every reference to a
net/httpStatus*constant, regardless of context. A typical constant is disallowed even in a declaration such asconst ok = http.StatusOK. - Inspect only status codes supplied to
http.Errorand theWriteHeadermethod declared byhttp.ResponseWriter. Do not inspect fixed-status helpers such ashttp.NotFound()orResponseWriter.Write(). - Do not diagnose a runtime value such as
w.WriteHeader(code)whencodeis a variable. - With
restrict: true, reject statically known non-typical codes passed tohttp.Errororhttp.ResponseWriter.WriteHeader. http.Redirectis exempt fromrestrictfor 300-series codes. Its use of a named typicalnet/httpstatus constant remains disallowed by the general constant rule.- A configured typical-status-code list replaces the default list.