feat(web): httputil.WithStatus — configurable success status on the handler adapters (v1.5.0)

2026-08-12 17:55:28 -06:00
parent 80b28dfcc4
commit bcccfef443
8 changed files with 217 additions and 23 deletions
@@ -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)
 	}
 }
@@ -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)
+		}()
+	}
+}
@@ -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
+}