rest

Overview ¶

Package rest is a tiny typed-handler layer over net/http.

A HandlerFunc returns an Encoder — a value that knows how to serialize itself — instead of writing to the ResponseWriter directly. This keeps response encoding and error handling in one place (Respond), makes handlers trivial to unit-test (assert on the returned value, not a recorded response), and lets a handler signal failure by returning an *errs.Error, which Respond maps to the right HTTP status. Mount these handlers with the router package.

Encoders and status ¶

An Encoder reports its body and content type; if it also implements an HTTPStatus() int method it sets the response status (otherwise 200, or 204 for a nil Encoder). JSON and JSONStatus wrap any value as a JSON Encoder, and *errs.Error is itself an Encoder, so a handler returns one uniform type for both success and failure.

Usage ¶

func getWidget(ctx context.Context, r *http.Request) rest.Encoder {
	var in CreateWidget
	if err := rest.Decode(r, &in); err != nil {
		return err.(*errs.Error) // InvalidArgument -> 400
	}
	w, err := store.Find(ctx, in.ID)
	if err != nil {
		return errs.New(errs.NotFound, err) // -> 404
	}
	return rest.JSON(w) // -> 200 application/json
}

// Compose cross-cutting behavior, outermost first:
h := rest.ChainMiddleware(getWidget, authMid, logMid)
resp := h(ctx, r)
_ = rest.Respond(ctx, w, resp)

API ¶

• HandlerFunc: func(ctx, *http.Request) Encoder — the typed handler shape.
• MidFunc / ChainMiddleware: wrap a HandlerFunc; mw[0] is the outermost layer.
• Respond: write an Encoder to an http.ResponseWriter (nil -> 204; encode failure -> 500 with a generic body; cancelled ctx -> returns ctx.Err).
• JSON / JSONStatus: wrap a value as a JSON Encoder (status 200, or explicit).
• Decode: read and validate a JSON request body (DisallowUnknownFields + errs.Check), returning an *errs.Error (InvalidArgument) on bad input.