web

Documentation

Index

• Constants
• Variables
• func Bind(r *http.Request, v any) error
• func HTML(w http.ResponseWriter, code int, s string) error
• func Handle(fn HandlerFunc) http.HandlerFunc
• func JSON(w http.ResponseWriter, code int, v any) error
• func Render(w http.ResponseWriter, r *http.Request, statusCode int, name string, ...) error
• func RenderContent(w http.ResponseWriter, r *http.Request, statusCode int, content template.HTML, ...) error
• func RenderError(w http.ResponseWriter, r *http.Request, code int, message string)
• func RenderFragment(ctx context.Context, name string, data map[string]any) (template.HTML, error)
• func RenderTemplate(w http.ResponseWriter, r *http.Request, statusCode int, name string, ...) error
• func Text(w http.ResponseWriter, code int, s string) error
• func Validate(v any) error
• type FieldError
• type HTTPError
  • func NewHTTPError(code int, message string) *HTTPError
  • func (e *HTTPError) Error() string
• type HandlerFunc
• type ValidationError
  • func (e *ValidationError) Error() string
  • func (e *ValidationError) HasField(name string) bool
  • func (e *ValidationError) Translate(ctx context.Context, ...)

Constants

const CacheControlImmutable = "public, max-age=31536000, immutable"

CacheControlImmutable is the Cache-Control header value for content-addressed responses where the same URL is guaranteed to always return the same bytes — content-hashed static assets, content-hashed upload paths, etc. Browsers and CDNs may cache the response for a year and skip revalidation entirely.

Variables

var ErrNoTemplateExecutor = errors.New("burrow: no template executor in context")

ErrNoTemplateExecutor is returned when Render or RenderFragment is called without a TemplateExecutor in the context.

Functions

func Bind

func Bind(r *http.Request, v any) error

Bind parses the request body into the given struct and validates it.

Content-Type dispatch:

• application/json → JSON decoding
• multipart/form-data → multipart parsing + form decoding
• everything else → form-encoded parsing + form decoding

Form decoding uses "form" struct tags (falling back to "json", then field name) and supports all basic types (string, int, bool, float, slices, etc.).

After decoding, Bind calls Validate automatically. If validation fails it returns a *ValidationError with per-field errors. Structs without "validate" tags pass through unchanged.

func HTML

func HTML(w http.ResponseWriter, code int, s string) error

HTML writes an HTML response with the given status code.

func Handle

func Handle(fn HandlerFunc) http.HandlerFunc

Handle converts a HandlerFunc into a standard http.HandlerFunc with centralized error handling.

func JSON

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

JSON writes a JSON response with the given status code.

func Render

func Render(w http.ResponseWriter, r *http.Request, statusCode int, name string, data map[string]any) error

Render executes a named template and writes the result. It applies automatic layout/HTMX logic:

• HTMX request (HX-Request header) → fragment only, no layout
• Normal request + layout name in context → fragment wrapped in layout
• Normal request + no layout → fragment only

func RenderContent

func RenderContent(w http.ResponseWriter, r *http.Request, statusCode int, content template.HTML, data map[string]any) error

RenderContent writes pre-rendered HTML content, applying the same layout and HTMX logic as Render. The data map is passed to the layout template with "Content" added automatically.

This is useful when content was rendered by a separate template system (e.g., a custom renderer's templates) but still needs layout wrapping.

func RenderError

func RenderError(w http.ResponseWriter, r *http.Request, code int, message string)

RenderError writes an error response. For JSON API requests (Accept: application/json) it returns a JSON object. Otherwise it renders the "error/{code}" template through the standard Render pipeline (with layout wrapping, HTMX support, etc.).

func RenderFragment

func RenderFragment(ctx context.Context, name string, data map[string]any) (template.HTML, error)

RenderFragment renders a named template outside of an HTTP request. It retrieves the [TemplateExecutor] from ctx, so the context must have been enriched with [WithTemplateExecutor] (plus any request-scoped values the template needs, e.g., i18n.WithLocale).

Use this for background jobs, SSE broadcasts, CLI commands, or any non-HTTP code that needs to render templates.

func RenderTemplate

func RenderTemplate(w http.ResponseWriter, r *http.Request, statusCode int, name string, data map[string]any) error

Deprecated: Use Render instead.

func Text

func Text(w http.ResponseWriter, code int, s string) error

Text writes a plain text response with the given status code.

func Validate

func Validate(v any) error

Validate validates a struct using "validate" struct tags. Returns nil if v is not a struct, has no validate tags, or passes all checks.

Types

type FieldError

type FieldError struct {
	Field   string `json:"field"`
	Tag     string `json:"tag"`
	Param   string `json:"param,omitempty"`
	Value   any    `json:"value"`
	Message string `json:"message"`
}

FieldError represents a validation failure on a single field.

type HTTPError

type HTTPError struct {
	Message string
	Code    int
}

HTTPError represents an HTTP error with a status code and message.

func NewHTTPError

func NewHTTPError(code int, message string) *HTTPError

NewHTTPError creates a new HTTPError.

func (*HTTPError) Error

func (e *HTTPError) Error() string

type HandlerFunc

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

HandlerFunc is an HTTP handler that returns an error. Use Handle() to convert it to a standard http.HandlerFunc.

type ValidationError

type ValidationError struct {
	Errors []FieldError
}

ValidationError is returned by Bind()/Validate() when validation fails.

func (*ValidationError) Error

func (e *ValidationError) Error() string

func (*ValidationError) HasField

func (e *ValidationError) HasField(name string) bool

HasField reports whether the validation error contains a failure for the named field.

func (*ValidationError) Translate

func (e *ValidationError) Translate(ctx context.Context, translateData func(context.Context, string, map[string]any) string)

Translate translates field error messages using the given translation function. The translateData function receives a key and template data, and returns the translated string. Typically called with i18n.TData:

ve.Translate(ctx, i18n.TData)