volt

Documentation

Overview

Package volt is the runtime for code generated by the volt CLI: the handler shim with its error spine, the reverse-URL building blocks, the route-table types, and a minimal middleware set.

The package is deliberately small and stdlib-only (nao's rt contract, D03, applied to the router): generated code imports the standard library and this package, nothing else. Middleware everywhere uses the ecosystem contract func(http.Handler) http.Handler (R8); controller methods carry the one non-stdlib shape in the system, func(http.ResponseWriter, *volt.Request, params...) error (R3).

Index

• Variables
• func Chain(h http.Handler, mw ...func(http.Handler) http.Handler) http.Handler
• func DefaultErrorHandler(w http.ResponseWriter, r *Request, err error)
• func Error(code int, msg string) error
• func Handler(route string, h HandlerFunc, eh ErrorHandler) http.Handler
• func JSON(w http.ResponseWriter, v any) error
• func Logger(next http.Handler) http.Handler
• func ParseInt(s string) (int, bool)
• func ParseInt32(s string) (int32, bool)
• func ParseInt64(s string) (int64, bool)
• func RequestID(next http.Handler) http.Handler
• func Seg(s string) string
• func SegInt(v int64) string
• func SegWild(s string) string
• func URL(path string, opts ...URLOption) string
• type ErrorHandler
• type HTTPError
• type HandlerFunc
• type Request
  • func (r *Request) Committed() bool
  • func (r *Request) Route() string
• type Route
• type RouteParam
• type URLOption
  • func Query(k, v string) URLOption

Variables

var (
	ErrNotFound   = Error(http.StatusNotFound, "not found")
	ErrBadRequest = Error(http.StatusBadRequest, "bad request")
	ErrForbidden  = Error(http.StatusForbidden, "forbidden")
)

Sentinels for the common cases. ErrNotFound is also what generated shims return when a typed path parameter fails to parse (R6: a parse failure is that route's 404, never a fallthrough).

Functions

func Chain

func Chain(h http.Handler, mw ...func(http.Handler) http.Handler) http.Handler

Chain composes middleware around h: the first element is outermost, matching pipeline declaration order.

func DefaultErrorHandler

func DefaultErrorHandler(w http.ResponseWriter, r *Request, err error)

DefaultErrorHandler maps HTTPError to its status and message and everything else to a generic 500, logging the underlying error. On a committed response it only logs.

func Error

func Error(code int, msg string) error

Error builds an HTTPError with the given status code and message.

func Handler

func Handler(route string, h HandlerFunc, eh ErrorHandler) http.Handler

Handler adapts a HandlerFunc plus an ErrorHandler into a std http.Handler; generated registrations wrap every route through it.

func JSON

func JSON(w http.ResponseWriter, v any) error

JSON writes v as a JSON response with the right Content-Type. Copy-paste and customize freely — like nao's rt.JSON, it is a convenience, not a framework.

func Logger

func Logger(next http.Handler) http.Handler

Logger writes one slog line per request: method, path, status, bytes elided, duration.

func ParseInt

func ParseInt(s string) (int, bool)

ParseInt parses a decimal int path parameter.

func ParseInt32

func ParseInt32(s string) (int32, bool)

ParseInt32 parses a decimal int32 path parameter.

func ParseInt64

func ParseInt64(s string) (int64, bool)

ParseInt64 parses a decimal int64 path parameter.

func RequestID

func RequestID(next http.Handler) http.Handler

RequestID ensures an X-Request-ID header on request and response, generating a random one when the client sent none.

func Seg

func Seg(s string) string

Seg escapes one string path parameter. "." and ".." escape to their %2E forms: PathEscape leaves dots alone, but as whole segments they would change the path shape under cleaning (and ServeMux redirects unclean paths), so a built URL must never contain them literally.

func SegInt

func SegInt(v int64) string

SegInt renders an integer path parameter.

func SegWild

func SegWild(s string) string

SegWild escapes a rest-of-path value, preserving its '/' separators. Each element gets Seg's treatment, dot segments included.

func URL

func URL(path string, opts ...URLOption) string

URL finishes a generated path: it appends the encoded query built from opts. The path itself is assembled by the generated helper with the Seg/SegInt/SegWild builders below.

Types

type ErrorHandler

type ErrorHandler func(http.ResponseWriter, *Request, error)

ErrorHandler consumes a handler error. When Request.Committed() is true it must not write status or body.

type HTTPError

type HTTPError interface {
	error
	StatusCode() int
}

HTTPError is the error-to-status contract: a handler error carrying its own response code. DefaultErrorHandler and user error handlers map it via errors.As-compatible assertion.

type HandlerFunc

type HandlerFunc func(http.ResponseWriter, *Request) error

HandlerFunc is the controller-side shape after parameter binding.

type Request

type Request struct {
	*http.Request
	// contains filtered or unexported fields
}

Request wraps *http.Request with route identity. It is passed to controller methods; everything else about the request is the embedded stdlib value.

func (*Request) Committed

func (r *Request) Committed() bool

Committed reports whether the response header has been written. An error returned after commit reaches the error handler in log-only mode (§4.1 of the router spec).

func (*Request) Route

func (r *Request) Route() string

Route returns the matched route's ServeMux pattern (metrics-safe cardinality, ROUTE-19 parity).

type Route

type Route struct {
	Method     string // "" for the any-verb
	Pattern    string // ServeMux pattern
	Spelled    string // DSL spelling
	Controller string
	Action     string
	Helper     string // reverse-URL function name, "" when none
	Params     []RouteParam
}

Route is one row of the generated route table (volt_routes.go).

type RouteParam

type RouteParam struct {
	Name string
	Type string // int, int32, int64, string
	Wild bool
}

RouteParam describes one captured parameter of a table row.

type URLOption

type URLOption interface {
	// contains filtered or unexported methods
}

URLOption augments a generated reverse-URL helper, today with query parameters: paths.User(42, volt.Query("tab", "posts")).

func Query

func Query(k, v string) URLOption

Query adds one query parameter to a reverse URL.