httputil/CHANGELOG.md

Changelog

All notable changes to this module will be documented in this file.

The format is based on Keep a Changelog, and this module adheres to Semantic Versioning.

1.0.0 - 2026-05-12

Changed

• Go directive bumped from 1.25 to 1.26
• xerrors dependency bumped to v1.0.1
• valid dependency bumped to v1.0.1

Stabilization

• API committed as stable. Handle, HandleNoBody, HandleEmpty, HandlerFunc, JSON, NoContent, and Error are unchanged from v0.10.0.

0.10.0 - 2026-03-25

Changed

• Error(w http.ResponseWriter, err error) — now includes "platformCode" in the JSON error body when the *xerrors.Err carries one; omitted otherwise
• Upgraded code.nochebuena.dev/go/xerrors dependency to v0.10.0

Design Notes

• platformCode is the domain-layer error identifier introduced in xerrors v0.10.0. It travels through Error transparently — no transport-layer logic depends on it.
• Backwards-compatible: error responses without a platform code are identical to v0.9.0.

0.9.0 - 2026-03-18

Added

• Handle[Req, Res any](v valid.Validator, fn func(ctx context.Context, req Req) (Res, error)) http.HandlerFunc — decodes the JSON request body into Req, validates it with the injected Validator, calls fn, and encodes the result as JSON with HTTP 200; invalid JSON returns 400
• HandleNoBody[Res any](fn func(ctx context.Context) (Res, error)) http.HandlerFunc — no body decode or validation; calls fn and encodes the result as JSON with HTTP 200; intended for GET and DELETE endpoints
• HandleEmpty[Req any](v valid.Validator, fn func(ctx context.Context, req Req) error) http.HandlerFunc — decodes and validates the JSON request body, calls fn, returns HTTP 204 on success; intended for write endpoints with no response body
• HandlerFunc type — func(w http.ResponseWriter, r *http.Request) error; implements http.Handler; on non-nil return, routes the error through Error(w, err) for automatic status mapping
• JSON(w http.ResponseWriter, status int, v any) — encodes v as JSON and writes it with the given status code; sets Content-Type: application/json
• NoContent(w http.ResponseWriter) — writes HTTP 204 No Content
• Error(w http.ResponseWriter, err error) — maps *xerrors.Err codes to HTTP status codes and writes a {"code": "...", "message": "..."} JSON body; includes any extra fields from the error; falls back to 500 for unknown errors
• xerrors.Code to HTTP status mapping (12 codes): ErrInvalidInput → 400, ErrUnauthorized → 401, ErrPermissionDenied → 403, ErrNotFound → 404, ErrAlreadyExists → 409, ErrGone → 410, ErrPreconditionFailed → 412, ErrRateLimited → 429, ErrInternal → 500, ErrNotImplemented → 501, ErrUnavailable → 503, ErrDeadlineExceeded → 504

Design Notes

• Business functions wrapped by Handle, HandleNoBody, and HandleEmpty have no http.ResponseWriter or *http.Request in their signatures, making them callable directly in unit tests with context.Background() and a typed request value.
• Error is the single translation point from xerrors.Code to HTTP status; all handler adapters route through it, preventing fragmented status code contracts across the codebase.
• Validation is injected via valid.Validator and runs before the business function is called; an invalid request never reaches business logic.