Documentation
¶
Index ¶
- Variables
- func BuildOpenAPI(title, version string) openAPISchema
- func HealthHandler() http.Handler
- func InitAuth(key []byte)
- func IssueToken(sub string, exp time.Time) (string, error)
- func NewMux() *http.ServeMux
- func OpenAPIHandler() http.Handler
- func Register(r Route)
- func Reset()
- func Serve(addr string) error
- func StatusHandler() http.Handler
- func Subject(ctx context.Context) (string, bool)
- func UserMeHandler() http.Handler
- type Endpoint
- type Route
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotFound = errors.New("not found") ErrBadRequest = errors.New("bad request") ErrForbidden = errors.New("forbidden") )
Sentinel errors that handlers can return to produce specific HTTP status codes.
Functions ¶
func BuildOpenAPI ¶
func BuildOpenAPI(title, version string) openAPISchema
BuildOpenAPI constructs the OpenAPI spec from all registered routes. Exported so the codegen command can call it directly to write openapi.json.
func HealthHandler ¶
HealthHandler returns an http.Handler that reports the health of the service and database. GET /api/health → {"status":"ok","db":"ok"} or {"status":"error","db":"error: ..."}
func InitAuth ¶
func InitAuth(key []byte)
InitAuth sets the HMAC-SHA256 signing key used for JWT verification. Called by the schemaf app after migrations run and the key is loaded from _schemaf_config.
func IssueToken ¶
IssueToken creates a signed JWT for the given subject. exp=0 means no expiry.
func NewMux ¶
NewMux builds and returns the http.ServeMux with all framework defaults and registered routes. Useful for testing with httptest.NewServer.
func OpenAPIHandler ¶
OpenAPIHandler returns an http.Handler that serves an OpenAPI 3.0 JSON document reflecting all registered routes.
func Serve ¶
Serve starts the HTTP server on the given address using the registered routes. addr should be in the form ":7001".
func StatusHandler ¶
StatusHandler returns an http.Handler for GET /api/status. Reports service uptime. Always open (no auth required).
func Subject ¶
Subject returns the authenticated subject (user ID) from the context. Returns ("", false) if the request was not authenticated.
func UserMeHandler ¶
UserMeHandler returns an http.Handler for GET /api/user/me. Requires a valid JWT — returns the authenticated user's UUID from the sub claim.
Types ¶
type Endpoint ¶
type Endpoint[Req, Resp any] interface { Method() string // HTTP method: "GET", "POST", "PUT", "DELETE", etc. Path() string // Route path, e.g. "/api/todos/{id}" Auth() bool // Whether the endpoint requires JWT authentication Handle(ctx context.Context, req Req) (Resp, error) }
Endpoint is the interface that all schemaf API endpoints must implement. Req is the request type (decoded from JSON body or path/query params). Resp is the response type (encoded as JSON).
Document your endpoint with a Go doc comment on the struct:
// ListTodosEndpoint returns all todo items ordered by creation date.
// Returns an empty array if no todos exist.
type ListTodosEndpoint struct{}
The first line becomes the OpenAPI summary; subsequent lines the description. Both are extracted by codegen — no annotations required.
type Route ¶
type Route struct {
Method string // "GET", "POST", "PUT", "DELETE", etc.
Path string // e.g. "/api/todos", "/api/todos/{id}"
Auth bool // whether JWT auth is required
Summary string // first line of endpoint struct doc comment
Description string // remaining lines of endpoint struct doc comment
Handler http.Handler
ReqType any // pointer to zero-value request type (for OpenAPI reflection)
RespType any // pointer to zero-value response type (for OpenAPI reflection)
}
Route describes a single HTTP route registered with the framework.
Source Files