Documentation
¶
Overview ¶
Package httpapi is the handler plumbing of subflux's own HTTP API: the prelude every handler opens with and the envelope every handler answers in.
It is the inbound counterpart to internal/httpwire. httpwire is subflux acting as an HTTP *client* — the byte caps it will read from a provider or an arr, and the vocabulary it classifies their responses with. This package is subflux acting as an HTTP *server* — what it accepts from its own callers (method gate, body cap, JSON decode) and what it writes back to them (the JSON payload and the {error,code,request_id} envelope). Both are "HTTP policy", but they face opposite directions and share no symbol, so one package holding both would hand every provider implementation the server's 500-writer and hand the server a subtitle-download byte cap.
The prelude and the response helpers are one concern, not two: requireMethod and DecodeJSONBody are observable only through the envelope this package defines — their whole failure output is a 405 or a 400 in that shape.
Not internal/server, where all thirteen consuming files live: twelve of them are in server *subpackages* (authhandlers, confighandlers, scanning, ...) and internal/server imports seventeen of those, so a child reaching back for the helpers would close an import cycle.
Wire format for errors:
{"error": "human message", "code": "machine_readable", "request_id": "..."}
`error` is the historical field; existing clients that read only `error` continue to work unchanged. `code` and `request_id` are additive: callers that pass a code via the (w, r, code, msg) variants populate the field. `request_id` is auto-populated from r.Context() when the request was wrapped by webhttp.Logging.
The JSON/error funnel is layered on the webhttp library (github.com/cplieger/webhttp): jsonHeaders/WriteJSON/WriteJSONStatus/Ok and the writeError envelope delegate to webhttp's mechanism, so the wire shape is defined once in the library and stays byte-identical across every consumer. subflux keeps its ~70-code taxonomy (subflux.ErrorCode, which stays in the types package because the wire generator discovers the enum there) and the BadRequestC-style named helpers on top; they just delegate now.
Hand-crafted JSON strings (`http.Error(w, ..., status)` for JSON, `fmt.Fprint(w, \`{"ok":true}\`)`, `w.Write([]byte(...))` for JSON) are forbidden. Use these helpers instead.
Index ¶
- Constants
- func BadGatewayC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)
- func BadRequestC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)
- func ConflictC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)
- func DecodeJSONBody(w http.ResponseWriter, r *http.Request, dst any, maxBytes int64) bool
- func ForbiddenC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)
- func InternalErrorC(w http.ResponseWriter, r *http.Request, err error, code subflux.ErrorCode, ...)
- func JSONErrorWithCode(w http.ResponseWriter, r *http.Request, status int, code subflux.ErrorCode, ...)
- func MethodNotAllowedC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode)
- func NotFoundC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)
- func Ok(w http.ResponseWriter)
- func PayloadTooLargeC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)
- func RequireGET(w http.ResponseWriter, r *http.Request) bool
- func RequirePOST(w http.ResponseWriter, r *http.Request) bool
- func ServiceUnavailableC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)
- func TooManyRequestsC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)
- func UnauthorizedC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)
- func WriteJSON(w http.ResponseWriter, v any)
- func WriteJSONStatus(w http.ResponseWriter, code int, v any)
Constants ¶
const MaxDefaultBodySize = webhttp.MaxJSONBody
MaxDefaultBodySize is the default JSON body size cap for most handlers (1 MiB), aliased to webhttp.MaxJSONBody so the limit has a single definition.
Variables ¶
This section is empty.
Functions ¶
func BadGatewayC ¶
BadGatewayC writes a 502 with the given code and message.
func BadRequestC ¶
BadRequestC writes a 400 with the given code and message.
func DecodeJSONBody ¶
DecodeJSONBody decodes a JSON request body into dst under a size cap, via webhttp.DecodeJSONInto (http.MaxBytesReader cap + single-value decode + trailing-data rejection): a body exceeding maxBytes, malformed JSON, or data after the first value fails the decode rather than being silently accepted. A maxBytes of 0 or less uses MaxDefaultBodySize. Writes subflux's 400 envelope (code "bad_request") and returns false on any decode failure.
func ForbiddenC ¶
ForbiddenC writes a 403 with the given code and message.
func InternalErrorC ¶
func InternalErrorC(w http.ResponseWriter, r *http.Request, err error, code subflux.ErrorCode, logAttrs ...any)
InternalErrorC writes a 500 with the given code and a generic message, and logs the raw error at ERROR level. The raw error is never echoed to the client to avoid leaking internal details.
func JSONErrorWithCode ¶
func JSONErrorWithCode(w http.ResponseWriter, r *http.Request, status int, code subflux.ErrorCode, msg string)
JSONErrorWithCode writes the error envelope with a machine-readable code. Use when the error string is safe to surface verbatim AND a stable machine- readable code is meaningful for the client. Delegates to webhttp.WriteError so the envelope and its request-id population match writeError.
SECURITY: msg is echoed verbatim to the client. Only pass an author-controlled or explicitly user-safe message. For wrapped internal errors, use InternalErrorC(w, r, err, code), which logs the raw error and returns a generic message.
func MethodNotAllowedC ¶
MethodNotAllowedC writes a 405 with the given code.
func Ok ¶
func Ok(w http.ResponseWriter)
Ok writes a 200 {"ok": true} response — the standard "action succeeded" reply for endpoints that don't return data. Delegates to webhttp.Ok so the body matches the {"ok":true} every webhttp consumer emits.
func PayloadTooLargeC ¶
PayloadTooLargeC writes a 413 with the given code and message.
func RequireGET ¶
func RequireGET(w http.ResponseWriter, r *http.Request) bool
RequireGET is sugar for requireMethod(w, r, http.MethodGet).
func RequirePOST ¶
func RequirePOST(w http.ResponseWriter, r *http.Request) bool
RequirePOST is sugar for requireMethod(w, r, http.MethodPost).
func ServiceUnavailableC ¶
func ServiceUnavailableC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)
ServiceUnavailableC writes a 503 with the given code and message.
func TooManyRequestsC ¶
TooManyRequestsC writes a 429 with the given code and message. The caller is responsible for setting the Retry-After header when appropriate.
func UnauthorizedC ¶
UnauthorizedC writes a 401 with the given code and message.
func WriteJSON ¶
func WriteJSON(w http.ResponseWriter, v any)
WriteJSON encodes v as JSON with status 200.
func WriteJSONStatus ¶
func WriteJSONStatus(w http.ResponseWriter, code int, v any)
WriteJSONStatus encodes v as JSON with the given status code. The encode failure is logged at Debug (deliberately quiet: the status line is already on the wire and an app JSON payload that fails to encode is exceptional) rather than delegating to webhttp.WriteJSONStatus, which logs at Warn.
Types ¶
This section is empty.