Documentation
¶
Overview ¶
Package httpreply writes what vibekit answers an HTTP request with: the named status responses, the error envelope they carry, and the request guards whose failure IS one of those responses.
Every symbol here either writes a reply or refuses a request by writing one, which is what the name claims and the whole of what the package does.
It exists because this is BEHAVIOUR, and it used to sit in internal/vibekit beside the wire and domain TYPES. That put the 405 helper every handler imports inside the one package the code generator walks for the cross-language type contract, so neither half could be read or changed without the other in view.
The mechanism is the fleet's: webhttp owns the headers, the status and the encode, and handlers call it directly for a plain body. What is vibekit's, and the only reason this package exists at all, is the error TAXONOMY: every helper here writes the bare {"error": "msg"} envelope vibekit's clients decode, leaving webhttp.ErrorResponse's Code and RequestID fields empty. A handler that hand-rolls that envelope instead is the drift these helpers exist to stop, and webhttp's own contract puts the named helpers here — it ships WriteError as the mechanism and leaves each app's taxonomy per app.
NOT httpwire, which this package was called for one commit. subflux has a package of that name for the OPPOSITE direction — bridging httpx errors while reading an UPSTREAM response — so one spelling would have named two disjoint concerns and taught a fleet reader that the name carries no information. Fleet alignment aligns concepts, not spellings: the shared concept is "the app's own HTTP boundary vocabulary", and the direction is what the name has to say out loud. NOT apireply either: internal/vibekit is the package being renamed away from api because api names nothing, so borrowing the word for its neighbour would repeat the mistake and leave a reader guessing whether the prefix means the package, the URL space, or the idea.
Index ¶
- Constants
- func BadRequest(w http.ResponseWriter, msg string)
- func Conflict(w http.ResponseWriter, msg string)
- func DecodeBody(w http.ResponseWriter, r *http.Request, v any, errMsg string) bool
- func DecodeBodyOptional(w http.ResponseWriter, r *http.Request, v any) bool
- func DecodeJSON(w http.ResponseWriter, r *http.Request, v any) bool
- func ErrorJSON(msg string) map[string]string
- func ErrorJSONWithCode(msg, code string) map[string]string
- func Forbidden(w http.ResponseWriter, msg string)
- func InternalError(w http.ResponseWriter, err error)
- func MethodNotAllowed(w http.ResponseWriter, method string, more ...string)
- func NotFound(w http.ResponseWriter, msg string)
- func RequireMethod(w http.ResponseWriter, r *http.Request, method string) bool
- func ServerError(w http.ResponseWriter, clientMsg string, err error)
- func WriteRawJSON(w http.ResponseWriter, data []byte)
Constants ¶
const JSONKeyError = "error"
JSONKeyError is the standard JSON error response key.
const JSONKeyName = "name"
JSONKeyName is the standard JSON field name for "name" in ACP wire format. Used in content blocks, command descriptors, and MCP entries.
const JSONKeyOutput = "output"
JSONKeyOutput is the standard JSON response key for successful command output. Used by git/ and server/ packages.
const MIMETypeJSON = "application/json"
MIMETypeJSON is the standard MIME type for JSON content.
Variables ¶
This section is empty.
Functions ¶
func BadRequest ¶
func BadRequest(w http.ResponseWriter, msg string)
BadRequest writes a 400 with {"error": msg}.
func Conflict ¶
func Conflict(w http.ResponseWriter, msg string)
Conflict writes a 409 with {"error": msg}.
func DecodeBody ¶
DecodeBody caps + decodes exactly one JSON value into v via webhttp.DecodeJSONInto (rejecting trailing data), returning true on success. On any decode failure it writes vibekit's bare {"error":errMsg} 400 and returns false.
func DecodeBodyOptional ¶
DecodeBodyOptional caps the body and decodes JSON into v, reporting whether the caller may proceed. An absent body (io.EOF) is legitimate and a malformed one is ignored: v keeps its zero value and the result is true, because these callers treat the body as advisory. An oversize body is the one refusal — it writes a 413 and returns false, because the server stopped reading what the client sent, so v's zero value would silently stand in for the value the body carried and the caller would act on a request nobody made.
func DecodeJSON ¶
DecodeJSON is the shared three-step JSON decode prelude: check Content-Type, cap body at webhttp.MaxJSONBody via MaxBytesReader, and distinguish an oversize request (413) from a malformed body (400). Returns true when v was populated successfully; false when an error response has already been written to w.
func ErrorJSON ¶
ErrorJSON returns the canonical error response map for JSON encoding. Use with webhttp.WriteJSONStatus to write error responses consistently.
func ErrorJSONWithCode ¶
ErrorJSONWithCode returns an error response map with an additional machine-readable "code" field. Used by forge handlers that surface a stable error code alongside the human-readable message.
func Forbidden ¶
func Forbidden(w http.ResponseWriter, msg string)
Forbidden writes a 403 with {"error": msg}.
func InternalError ¶
func InternalError(w http.ResponseWriter, err error)
InternalError writes a 500 with {"error": "internal error"} and logs the actual error at slog.Error for correlation. Never exposes internal error details to HTTP clients.
func MethodNotAllowed ¶
func MethodNotAllowed(w http.ResponseWriter, method string, more ...string)
MethodNotAllowed writes a 405 with a standard message plus the Allow header RFC 9110 §15.5.6 requires an origin server to send on every 405.
The method list is PER-RESOURCE: pass exactly the methods the addressed resource dispatches, read off its own routing and switch — never a blanket constant. An Allow that over-promises is worse than no Allow at all, because a client that trusts it retries a method that 405s again. At least one method is mandatory at the call site by construction: a resource that permits nothing is a 404, not a 405.
HEAD is deliberately NOT implied by GET. vibekit's JSON handlers compare r.Method for equality and its API routes are registered as plain paths, so net/http's ServeMux does no method matching and a HEAD request reaches the handler and lands here — listing HEAD would advertise a method that also 405s.
func NotFound ¶
func NotFound(w http.ResponseWriter, msg string)
NotFound writes a 404 with {"error": msg}.
func RequireMethod ¶
RequireMethod returns true if r.Method matches method; otherwise it writes a 405 response — with Allow set to that single method, which is by construction the resource's whole permitted set — and returns false.
func ServerError ¶
func ServerError(w http.ResponseWriter, clientMsg string, err error)
ServerError writes a 500 with a caller-specified client-visible message and logs the actual error at slog.Error. Use when the handler wants to surface a safe, specific message (e.g. "save failed") while still logging the raw error for debugging.
func WriteRawJSON ¶
func WriteRawJSON(w http.ResponseWriter, data []byte)
WriteRawJSON writes pre-marshalled JSON bytes with the standard Content-Type + X-Content-Type-Options headers. Use for pass-through of cached command replies and upstream JSON bodies (e.g. kiro-cli slash-command results) where json.Marshal would be a redundant round-trip. Write errors are best-effort (client may have hung up).
Types ¶
This section is empty.
Source Files