Documentation
¶
Overview ¶
Package nethttp adapts api/rest route handles to net/http handlers.
Each [RouteHandle] from api/rest becomes an http.Handler via Handler. Register wires it directly onto an http.ServeMux using the Go 1.22+ method-prefixed pattern ("POST /users", "GET /users/{id}", etc.).
Typical usage:
b := rest.NewBuilder(rest.Info{Title: "User API", Version: "1.0.0"})
createUser := rest.AddRoute[CreateReq, User](b, "POST", "/users", ...)
mux := http.NewServeMux()
nethttp.Register(mux, createUser, func(ctx context.Context, req CreateReq) (User, error) {
// Access path params via the embedded request:
r, _ := nethttp.RequestFromContext(ctx)
id := r.PathValue("id")
return svc.CreateUser(ctx, req)
})
http.ListenAndServe(":8080", mux)
Error responses use the JSON body {"error":"<message>"} by default: 400 for decode/validation failures, 500 for handler or encode errors. Override by supplying a custom Options.ErrorHandler via HandlerWithOptions.
For body-less methods (GET, HEAD, DELETE) the handler function is called with the zero value of Req. Access path and query parameters through RequestFromContext.
Index ¶
- func Handler[Req, Resp any](handle *rest.RouteHandle[Req, Resp], fn HandlerFunc[Req, Resp]) http.Handler
- func HandlerWithOptions[Req, Resp any](handle *rest.RouteHandle[Req, Resp], fn HandlerFunc[Req, Resp], opts Options) http.Handler
- func Register[Req, Resp any](mux *http.ServeMux, handle *rest.RouteHandle[Req, Resp], ...)
- func RegisterWithOptions[Req, Resp any](mux *http.ServeMux, handle *rest.RouteHandle[Req, Resp], ...)
- func RequestFromContext(ctx context.Context) (*http.Request, bool)
- type HandlerFunc
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Handler ¶
func Handler[Req, Resp any](handle *rest.RouteHandle[Req, Resp], fn HandlerFunc[Req, Resp]) http.Handler
Handler wraps a rest.RouteHandle and a HandlerFunc into an http.Handler using default options (JSON error envelope, 1 MiB body limit).
For body-bearing methods (POST, PUT, PATCH) the request body is read, decoded, and validated using the route's codec before fn is called. For other methods (GET, HEAD, DELETE) fn is called with the zero value of Req.
On success the response is JSON-encoded and written with the HTTP status from the route descriptor's primary response (the first entry in Responses).
func HandlerWithOptions ¶
func HandlerWithOptions[Req, Resp any](handle *rest.RouteHandle[Req, Resp], fn HandlerFunc[Req, Resp], opts Options) http.Handler
HandlerWithOptions is like Handler but accepts Options to customise error handling.
func Register ¶
func Register[Req, Resp any](mux *http.ServeMux, handle *rest.RouteHandle[Req, Resp], fn HandlerFunc[Req, Resp])
Register registers the route on mux using its method and path from the route descriptor. It uses the Go 1.22+ enhanced ServeMux pattern "METHOD /path" so each registration is scoped to a single method.
func RegisterWithOptions ¶
func RegisterWithOptions[Req, Resp any](mux *http.ServeMux, handle *rest.RouteHandle[Req, Resp], fn HandlerFunc[Req, Resp], opts Options)
Types ¶
type HandlerFunc ¶
HandlerFunc is the typed application handler called by Handler. ctx is the request context. req is the decoded request value; for body-less methods it is the zero value of Req. Use RequestFromContext to access the underlying *http.Request for path parameters, headers, or other request metadata.
type Options ¶
type Options struct {
// ErrorHandler, when non-nil, is called instead of the default JSON error
// envelope when a request fails. status is the suggested HTTP status code
// (400 or 500). Implementations must write the response header and body.
ErrorHandler func(w http.ResponseWriter, r *http.Request, status int, err error)
}
Options configures the behaviour of HandlerWithOptions.
Source Files