httpapi

package
v0.8.0-dev.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: AGPL-3.0 Imports: 6 Imported by: 0

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

View Source
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

func BadGatewayC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)

BadGatewayC writes a 502 with the given code and message.

func BadRequestC

func BadRequestC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)

BadRequestC writes a 400 with the given code and message.

func ConflictC

func ConflictC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)

ConflictC writes a 409 with the given code and message.

func DecodeJSONBody

func DecodeJSONBody(w http.ResponseWriter, r *http.Request, dst any, maxBytes int64) bool

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

func ForbiddenC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)

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

func MethodNotAllowedC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode)

MethodNotAllowedC writes a 405 with the given code.

func NotFoundC

func NotFoundC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)

NotFoundC writes a 404 with the given code and message.

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

func PayloadTooLargeC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)

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

func TooManyRequestsC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)

TooManyRequestsC writes a 429 with the given code and message. The caller is responsible for setting the Retry-After header when appropriate.

func UnauthorizedC

func UnauthorizedC(w http.ResponseWriter, r *http.Request, code subflux.ErrorCode, msg string)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL