Package httpkit
Overview
Package httpkit is the root of a module of packages for building HTTP APIs the Funny Haha way: each endpoint is a handler around one operation, a func(context.Context, Params) (Result, error), and every error is an RFC 9457 problem.
- jsonhandler builds a JSON endpoint from an operation, with content negotiation, gzip bodies, body limits and error mapping.
- ssehandler builds a server-sent events endpoint from a streaming operation.
- problem maps an operation's declared errors to problem responses.
- server runs an API with timeouts, health checks and graceful shutdown.
- meta serves an API's build information.
- bearer protects an API as an OAuth resource server, with bearer token challenges and protected resource metadata.
- jwks verifies JWT access tokens against an authorization server's keys, for bearer.
- ratelimit limits requests per client IP or other key.
- envflag configures a binary from flags or environment variables.
- reqbody opens a request body, decoding gzip and capping its size as sent and as decoded.
Request IDs, client IPs, request logs and CORS come from chi's middleware, httplog and go-chi/cors, which the handlers work with.
This package itself has no API.
Subpackages
| Package | Description |
|---|---|
funnyhaha.technology/httpkit/bearer | Package bearer protects an API as an OAuth resource server: it takes bearer access tokens (RFC 6750), verifies them with an operation, and answers a request without a good token with the challenge that tells a client where to sign in (RFC 9728). |
funnyhaha.technology/httpkit/envflag | Package envflag sets command-line flags from environment variables, so a service can be configured either way: flags for development, and the environment in a container. |
funnyhaha.technology/httpkit/jsonhandler | Package jsonhandler builds an HTTP handler for a JSON endpoint from one operation: a func(context.Context, Params) (Result, error). |
funnyhaha.technology/httpkit/jwks | Package jwks verifies JWT access tokens (RFC 9068) with the keys an authorization server publishes as a JSON Web Key Set, using go-jose. |
funnyhaha.technology/httpkit/meta | Package meta serves what a running API knows about itself: its name, and the version and build of its binary. |
funnyhaha.technology/httpkit/problem | Package problem writes an error as an RFC 9457 problem details response, mapping the errors an operation declares to statuses and problem types. |
funnyhaha.technology/httpkit/ratelimit | Package ratelimit limits how many requests a client may make in a sliding window, as middleware, answering requests past the limit with 429 Too Many Requests (RFC 6585, Section 4) and Retry-After. |
funnyhaha.technology/httpkit/reqbody | Package reqbody opens a request’s body for reading: it removes the content codings in Content-Encoding and caps the body’s size, both as sent and as decoded. |
funnyhaha.technology/httpkit/server | Package server runs an HTTP API with the timeouts, health checks and graceful shutdown that every service needs. |
funnyhaha.technology/httpkit/ssehandler | Package ssehandler builds an HTTP handler that streams server-sent events from one streaming operation: a func(context.Context, Params) (iter.Seq2[Event, error], error). |