diff --git a/CHANGELOG.md b/CHANGELOG.md index 2024a4c..cf05c91 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,27 @@ This module adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html --- +## [1.5.0] — 2026-08-09 + +Minor — configurable success status on the httputil handler adapters. + +### Added + +- **`httputil.WithStatus(code int) Option`** and variadic `opts ...Option` on `Handle`, + `HandleNoBody` and `HandleEmpty`. Override the success status — e.g. `WithStatus(201)` on a + resource-creating POST, `WithStatus(202)` on an async `HandleEmpty`. Non-breaking: existing + calls keep their defaults (200 / 200 / 204). + +### Changed + +- Bumped `contracts`, `core` to v1.5.0. + +### Notes + +- `WithStatus` is success-only: the adapters own only the happy path, so the code must be 2xx. + A non-2xx code panics at wiring (the service fails to boot) rather than emitting a wrong + status at runtime. Error status stays separate — resolved from the returned xerror by `Error`. + ## [1.4.0] — 2026-08-09 Minor — resolvable request IDs, plus a dependency refresh. diff --git a/README.md b/README.md index d767763..278d4c2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # einherjar/web -[![version](https://img.shields.io/badge/version-v1.4.0-5C4EE5?style=flat-square)](https://code.nochebuena.dev/einherjar/web) +[![version](https://img.shields.io/badge/version-v1.5.0-5C4EE5?style=flat-square)](https://code.nochebuena.dev/einherjar/web) [![license](https://img.shields.io/badge/license-AGPL--3.0-22863A?style=flat-square)](LICENSE) [![go](https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat-square&logo=go&logoColor=white)](https://go.dev) @@ -150,26 +150,33 @@ type CreateUserRes struct { v := valid.New() -// POST /users — decode body → validate → call service → encode response -srv.Post("/users", httputil.Handle(v, func(ctx context.Context, req CreateUserReq) (CreateUserRes, error) { +// POST /users — decode → validate → call → encode. WithStatus makes it 201 Created. +srv.Post("/users", httputil.Handle(v, logger, func(ctx context.Context, req CreateUserReq) (CreateUserRes, error) { id, err := userService.Create(ctx, req.Email, req.Name) if err != nil { return CreateUserRes{}, err } return CreateUserRes{ID: id}, nil -})) +}, httputil.WithStatus(http.StatusCreated))) -// GET /users/{id} — no request body -srv.Get("/users/{id}", httputil.HandleNoBody(func(ctx context.Context) (CreateUserRes, error) { +// GET /users/{id} — no request body (defaults to 200) +srv.Get("/users/{id}", httputil.HandleNoBody(logger, func(ctx context.Context) (CreateUserRes, error) { // ... })) -// DELETE /users/{id} — no response body -srv.Delete("/users/{id}", httputil.HandleEmpty(v, func(ctx context.Context, req DeleteReq) error { +// DELETE /users/{id} — no response body (defaults to 204) +srv.Delete("/users/{id}", httputil.HandleEmpty(v, logger, func(ctx context.Context, req DeleteReq) error { return userService.Delete(ctx, req.ID) })) ``` +**Success status** defaults to 200 for the body-returning adapters and 204 for `HandleEmpty`; +override it with `httputil.WithStatus(code)` — e.g. `WithStatus(http.StatusCreated)` on a POST, or +`WithStatus(http.StatusAccepted)` for an async `HandleEmpty`. The code must be 2xx (these adapters +own only the success path); a non-2xx code panics at wiring, so the service fails to start rather +than emit a wrong status at runtime. **Error status is separate** — return the right `*xerrors.Err` +and `Error` maps it (full 16-code table below). + Validation failures return 400 with a structured JSON error. All `*xerrors.Err` values are mapped to their canonical HTTP status codes (full 16-code table below). diff --git a/docs/adr/index.md b/docs/adr/index.md index 1326df2..bfe93f1 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -20,3 +20,4 @@ Decisions worth noting (not ADR-worthy individually): | `observability.Checkable` not redefined | Imported from contracts | Starters implement contracts directly; no web import needed by db/cache starters | | Background goroutine for in-memory eviction | `time.Ticker` goroutine | Avoids `worker` module dependency; in-memory store is self-contained | | `mw.RequestIDFrom` resolver sees the request (v1.4.0) | New entry point takes `func(*http.Request) string`; `RequestID` becomes a request-ignoring wrapper over it | An inbound correlation id must be able to survive this boundary, but acceptability is per-service — a typed audit column rejects what an opaque log accepts. The framework provides plumbing only (context + header, once per request); the app owns policy (which header, validation, generation fallback). An empty resolver result attaches nothing rather than a silently-empty value | +| `httputil` success status is configurable (v1.5.0) | `Handle`/`HandleNoBody`/`HandleEmpty` take `opts ...Option`; `WithStatus(code)` overrides the default (200 / 200 / 204) | 201 Created / 202 Accepted are common and were only reachable by hand-rolling the handler (losing decode+validate+error-mapping). Variadic options are non-breaking and future-extensible (headers, etc.). `WithStatus` is success-only (2xx) and panics at wiring on a non-2xx code — a wrong status is a routing mistake that should fail to boot, not surface at runtime; error status stays separate, resolved from the xerror by `Error` | diff --git a/go.mod b/go.mod index 47a7df1..911bcf1 100644 --- a/go.mod +++ b/go.mod @@ -3,8 +3,8 @@ module code.nochebuena.dev/einherjar/web go 1.26 require ( - code.nochebuena.dev/einherjar/contracts v1.4.0 - code.nochebuena.dev/einherjar/core v1.4.0 + code.nochebuena.dev/einherjar/contracts v1.5.0 + code.nochebuena.dev/einherjar/core v1.5.0 github.com/go-chi/chi/v5 v5.3.1 github.com/google/uuid v1.6.0 golang.org/x/time v0.15.0 diff --git a/go.sum b/go.sum index ad9975c..daab723 100644 --- a/go.sum +++ b/go.sum @@ -1,7 +1,7 @@ -code.nochebuena.dev/einherjar/contracts v1.4.0 h1:rv/93dGXmXvO90G0uxCu8y3+5+EobkVvcoxh/BywIFk= -code.nochebuena.dev/einherjar/contracts v1.4.0/go.mod h1:ccltUtrFb5+MEJdkx2VVEUL+xC5pupVlVVsMM8AlCWI= -code.nochebuena.dev/einherjar/core v1.4.0 h1:YBRFzgeWNh8BCHueNYGo+V754BjzvJvq2CddJcc5ZjQ= -code.nochebuena.dev/einherjar/core v1.4.0/go.mod h1:dILfAATF++TBeLOwUTQsYci+Ft7yK5ivt00iRYctfGk= +code.nochebuena.dev/einherjar/contracts v1.5.0 h1:vDlpLXtVZ4Q4l3AR02qLQhnKnEDq2vE8+mydwg85hUU= +code.nochebuena.dev/einherjar/contracts v1.5.0/go.mod h1:ccltUtrFb5+MEJdkx2VVEUL+xC5pupVlVVsMM8AlCWI= +code.nochebuena.dev/einherjar/core v1.5.0 h1:LXVyHaite+NHL8LIGj/NvCVqgCrkpVMfm2VaIZ9aAU8= +code.nochebuena.dev/einherjar/core v1.5.0/go.mod h1:lxiRdCVLl1/XnbCsHbeZJIFNXZ29QaSl2lMGZm3CQjM= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/gabriel-vasile/mimetype v1.4.15 h1:05iP/CYtZ/w455R/KZM6rZ5ieAdh99UPtd+d3YzLmaI= diff --git a/httputil/handle.go b/httputil/handle.go index 7c6fe01..075ff70 100644 --- a/httputil/handle.go +++ b/httputil/handle.go @@ -14,9 +14,11 @@ import ( // - Decodes the JSON request body into Req. // - Validates Req using the provided [valid.Validator]. // - Calls fn with the request context and decoded Req. -// - Encodes Res as JSON with HTTP 200 on success. +// - Encodes Res as JSON on success — HTTP 200 by default, or the code given via +// [WithStatus] (e.g. WithStatus(http.StatusCreated) for a resource-creating POST). // - On error: logs via [Error] (level derived from HTTP status) and writes the standardized JSON body. -func Handle[Req, Res any](v valid.Validator, logger logging.Logger, fn func(ctx context.Context, req Req) (Res, error)) http.HandlerFunc { +func Handle[Req, Res any](v valid.Validator, logger logging.Logger, fn func(ctx context.Context, req Req) (Res, error), opts ...Option) http.HandlerFunc { + status := resolveStatus(http.StatusOK, opts) return func(w http.ResponseWriter, r *http.Request) { var req Req if err := json.NewDecoder(r.Body).Decode(&req); err != nil { @@ -32,28 +34,33 @@ func Handle[Req, Res any](v valid.Validator, logger logging.Logger, fn func(ctx Error(logger, w, r, err) return } - JSON(w, http.StatusOK, res) + JSON(w, status, res) } } // HandleNoBody adapts a typed function with no request body (GET, HEAD). -// Calls fn with the request context; encodes the result as JSON with HTTP 200. +// Calls fn with the request context; encodes the result as JSON — HTTP 200 by +// default, or the code given via [WithStatus]. // On error: logs via [Error] and writes the standardized JSON body. -func HandleNoBody[Res any](logger logging.Logger, fn func(ctx context.Context) (Res, error)) http.HandlerFunc { +func HandleNoBody[Res any](logger logging.Logger, fn func(ctx context.Context) (Res, error), opts ...Option) http.HandlerFunc { + status := resolveStatus(http.StatusOK, opts) return func(w http.ResponseWriter, r *http.Request) { res, err := fn(r.Context()) if err != nil { Error(logger, w, r, err) return } - JSON(w, http.StatusOK, res) + JSON(w, status, res) } } // HandleEmpty adapts a typed function with a request body but no response body. -// Decodes and validates Req, calls fn, returns 204 No Content on success. +// Decodes and validates Req, calls fn, and writes a body-less success — 204 No +// Content by default, or the code given via [WithStatus] (e.g. +// WithStatus(http.StatusAccepted) for async processing). // On error: logs via [Error] and writes the standardized JSON body. -func HandleEmpty[Req any](v valid.Validator, logger logging.Logger, fn func(ctx context.Context, req Req) error) http.HandlerFunc { +func HandleEmpty[Req any](v valid.Validator, logger logging.Logger, fn func(ctx context.Context, req Req) error, opts ...Option) http.HandlerFunc { + status := resolveStatus(http.StatusNoContent, opts) return func(w http.ResponseWriter, r *http.Request) { var req Req if err := json.NewDecoder(r.Body).Decode(&req); err != nil { @@ -68,6 +75,6 @@ func HandleEmpty[Req any](v valid.Validator, logger logging.Logger, fn func(ctx Error(logger, w, r, err) return } - NoContent(w) + w.WriteHeader(status) } } diff --git a/httputil/handle_test.go b/httputil/handle_test.go new file mode 100644 index 0000000..483df18 --- /dev/null +++ b/httputil/handle_test.go @@ -0,0 +1,118 @@ +package httputil + +import ( + "context" + "io" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "code.nochebuena.dev/einherjar/contracts/logging" + "code.nochebuena.dev/einherjar/core/logz" + "code.nochebuena.dev/einherjar/core/valid" +) + +type tReq struct { + Name string `json:"name" validate:"required"` +} +type tRes struct { + ID string `json:"id"` +} + +func discardLogger() logging.Logger { return logz.New(logz.Config{Writer: io.Discard}) } + +// Default: Handle writes 200 with the JSON payload (regression — no opts). +func TestHandle_Default200(t *testing.T) { + h := Handle(valid.New(), discardLogger(), func(context.Context, tReq) (tRes, error) { + return tRes{ID: "x"}, nil + }) + rec := httptest.NewRecorder() + h(rec, httptest.NewRequest(http.MethodPost, "/", strings.NewReader(`{"name":"a"}`))) + if rec.Code != http.StatusOK { + t.Fatalf("status = %d, want 200", rec.Code) + } + if got := strings.TrimSpace(rec.Body.String()); got != `{"id":"x"}` { + t.Errorf("body = %q, want {\"id\":\"x\"}", got) + } +} + +// WithStatus(201) makes a resource-creating Handle return 201 Created + the body. +func TestHandle_WithStatusCreated(t *testing.T) { + h := Handle(valid.New(), discardLogger(), func(context.Context, tReq) (tRes, error) { + return tRes{ID: "x"}, nil + }, WithStatus(http.StatusCreated)) + rec := httptest.NewRecorder() + h(rec, httptest.NewRequest(http.MethodPost, "/", strings.NewReader(`{"name":"a"}`))) + if rec.Code != http.StatusCreated { + t.Fatalf("status = %d, want 201", rec.Code) + } + if got := strings.TrimSpace(rec.Body.String()); got != `{"id":"x"}` { + t.Errorf("body = %q, want the payload", got) + } +} + +func TestHandleNoBody_WithStatus(t *testing.T) { + h := HandleNoBody(discardLogger(), func(context.Context) (tRes, error) { + return tRes{ID: "y"}, nil + }, WithStatus(http.StatusAccepted)) + rec := httptest.NewRecorder() + h(rec, httptest.NewRequest(http.MethodGet, "/", nil)) + if rec.Code != http.StatusAccepted { + t.Fatalf("status = %d, want 202", rec.Code) + } +} + +// Default: HandleEmpty writes 204 with no body. +func TestHandleEmpty_Default204(t *testing.T) { + h := HandleEmpty(valid.New(), discardLogger(), func(context.Context, tReq) error { return nil }) + rec := httptest.NewRecorder() + h(rec, httptest.NewRequest(http.MethodPost, "/", strings.NewReader(`{"name":"a"}`))) + if rec.Code != http.StatusNoContent { + t.Fatalf("status = %d, want 204", rec.Code) + } + if rec.Body.Len() != 0 { + t.Errorf("expected empty body, got %q", rec.Body.String()) + } +} + +// WithStatus on a body-less adapter changes the code but keeps the empty body. +func TestHandleEmpty_WithStatusAccepted_NoBody(t *testing.T) { + h := HandleEmpty(valid.New(), discardLogger(), func(context.Context, tReq) error { return nil }, WithStatus(http.StatusAccepted)) + rec := httptest.NewRecorder() + h(rec, httptest.NewRequest(http.MethodPost, "/", strings.NewReader(`{"name":"a"}`))) + if rec.Code != http.StatusAccepted { + t.Fatalf("status = %d, want 202", rec.Code) + } + if rec.Body.Len() != 0 { + t.Errorf("expected empty body, got %q", rec.Body.String()) + } +} + +// A non-2xx code is a wiring mistake: WithStatus panics at construction so the +// service fails to boot rather than emitting a wrong status at request time. +func TestWithStatus_PanicsOnNon2xx(t *testing.T) { + for _, code := range []int{0, 100, 199, 300, 404, 500, 1000} { + func() { + defer func() { + if recover() == nil { + t.Errorf("WithStatus(%d) did not panic", code) + } + }() + _ = WithStatus(code) + }() + } +} + +func TestWithStatus_Allows2xx(t *testing.T) { + for _, code := range []int{200, 201, 202, 204, 299} { + func() { + defer func() { + if r := recover(); r != nil { + t.Errorf("WithStatus(%d) panicked: %v", code, r) + } + }() + _ = WithStatus(code) + }() + } +} diff --git a/httputil/options.go b/httputil/options.go new file mode 100644 index 0000000..32afa0a --- /dev/null +++ b/httputil/options.go @@ -0,0 +1,40 @@ +package httputil + +import "fmt" + +// Option configures a Handle* adapter. With no options each adapter writes its +// default success status (200 for the body-returning adapters, 204 for +// [HandleEmpty]). Options are applied once at wiring time, not per request. +type Option func(*options) + +type options struct { + status int +} + +// WithStatus overrides the success status an adapter writes — e.g. +// WithStatus(http.StatusCreated) for a POST that creates a resource, or +// WithStatus(http.StatusAccepted) for an async [HandleEmpty]. +// +// It exists because the Handle* adapters own only the happy path: they always +// write a success response, so the status is theirs to set, while error statuses +// are derived separately from the returned xerror by [Error]. The code must +// therefore be 2xx — anything else is a routing mistake, since an error status +// never belongs on the success path. WithStatus panics on a non-2xx code, and +// because routes are wired at startup that panic surfaces at boot: the service +// fails to start rather than emitting a wrong status at request time. (mw.Recover +// guards requests, so it does not catch a wiring-time panic — which is the point.) +func WithStatus(code int) Option { + if code < 200 || code > 299 { + panic(fmt.Sprintf("httputil.WithStatus: success status must be 2xx, got %d", code)) + } + return func(o *options) { o.status = code } +} + +// resolveStatus folds opts over the adapter's default success status. +func resolveStatus(def int, opts []Option) int { + o := options{status: def} + for _, opt := range opts { + opt(&o) + } + return o.status +}