burrow

package module
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 15, 2026 License: EUPL-1.2 Imports: 43 Imported by: 0

README

Burrow

CI Release Go Version Go Report Card License Docs

A web framework for Go developers who want something like Django, Rails, or Flask — but with the deployment simplicity of a single static binary.

Most Go web development follows the "API backend + SPA frontend" pattern. Burrow takes a different approach: server-rendered HTML with templates, modular apps with their own routes, migrations, and middleware, and an embedded SQLite database. The result is an application you can deploy as a single file — ./myapp and you're done.

Built on Chi, Bun/SQLite, and Go's standard html/template. Ideal for self-hosted applications, internal tools, or any project where "download, start, use" is the goal.

[!TIP] Why Burrow? A burrow is a network of interconnected chambers — each with its own purpose, yet part of a larger whole. That's exactly how the framework works: pluggable apps are the rooms, and your gophers live in them.

[!NOTE] Burrow is designed for server-rendered web applications, not API-only services. If you're building a JSON API with a separate frontend, a lighter router like Chi on its own is probably a better fit.

Features

  • App-based architecture — build your application from composable, self-contained apps
  • Pure Go SQLite — no CGO required (CGO_ENABLED=0), cross-compiles anywhere
  • Per-app migrations — each app manages its own SQL migrations
  • Standard templates — Go's html/template with a global template set, per-app FuncMaps, and automatic layout wrapping
  • CSS-agnostic — bring your own CSS framework (Bootstrap, Tailwind, etc.)
  • Layout system — app layout via server, admin layout via admin package
  • CLI configuration — flags, environment variables, and TOML config via urfave/cli
  • CSRF protection — automatic token generation and validation
  • Flash messages — session-based flash message system
  • Bootstrap integration — Bootstrap 5 CSS/JS, inline SVG icons, htmx, and dark mode theme switcher
  • Contrib apps — auth (WebAuthn/passkeys), sessions, i18n, admin, CSRF, flash messages, jobs, uploads, rate limiting, healthcheck, static files

Quick Start

mkdir myapp && cd myapp
go mod init myapp
go get github.com/oliverandrich/burrow@latest

package main

import (
    "context"
    "log"
    "net/http"
    "os"

    "github.com/oliverandrich/burrow"
    "github.com/go-chi/chi/v5"
    "github.com/urfave/cli/v3"
)

// homeApp is a minimal app with a single route.
type homeApp struct{}

func (a *homeApp) Name() string                      { return "home" }
func (a *homeApp) Register(_ *burrow.AppConfig) error { return nil }
func (a *homeApp) Routes(r chi.Router) {
    r.Method("GET", "/", burrow.Handle(func(w http.ResponseWriter, r *http.Request) error {
        return burrow.Text(w, http.StatusOK, "Hello from Burrow!")
    }))
}

func main() {
    srv := burrow.NewServer(
        &homeApp{},
    )

    cmd := &cli.Command{
        Name:   "myapp",
        Flags:  srv.Flags(nil),
        Action: srv.Run,
    }

    if err := cmd.Run(context.Background(), os.Args); err != nil {
        log.Fatal(err)
    }
}

go mod tidy
go run .

See example/hello/ for a minimal hello world app, or example/notes/ for a complete example with auth, admin, i18n, and more.

Architecture

contrib/        Reusable apps
  admin/        Admin panel coordinator + ModelAdmin
  auth/         WebAuthn passkeys, recovery codes, email verification
  authmail/     Pluggable email renderer + SMTP implementation
  bootstrap/    Bootstrap 5 CSS/JS/htmx assets, theme switcher, layout
  bsicons/      Bootstrap Icons as inline SVG template functions
  csrf/         CSRF protection
  healthcheck/  Liveness and readiness probes
  htmx/         htmx static asset + request/response helpers
  i18n/         Locale detection and translations
  jobs/         SQLite-backed background job queue
  messages/     Flash messages
  ratelimit/    Per-client rate limiting
  session/      Cookie-based sessions
  staticfiles/  Static file serving with content-hashed URLs
  uploads/      File upload storage and serving
example/        Example applications (hello world, notes app)
The App Interface

Every app implements burrow.App:

type App interface {
    Name() string
    Register(cfg *AppConfig) error
}

Apps can optionally implement additional interfaces:

Interface Purpose
Migratable Provide embedded SQL migrations
HasRoutes Register HTTP routes
HasMiddleware Contribute middleware
HasNavItems Contribute navigation items
HasTemplates Contribute .html template files
HasFuncMap Contribute static template functions
HasRequestFuncMap Contribute request-scoped template functions
Configurable Define CLI flags and read configuration
HasCLICommands Contribute CLI subcommands
Seedable Seed the database with initial data
HasAdmin Contribute admin panel routes and nav items
HasStaticFiles Contribute embedded static file assets
HasTranslations Contribute translation files
HasDependencies Declare required apps
HasJobs Register background job handlers
HasShutdown Clean up on graceful shutdown
Layouts

Layouts are template name strings. The app layout wraps user-facing pages:

srv.SetLayout("myapp/layout")

The admin layout is owned by the admin package:

admin.New(admin.WithLayout("custom/admin-layout"))

RenderTemplate renders page content, then wraps it in the layout template with .Content set to the rendered fragment. Layout templates access dynamic data via template functions:

{{ range navLinks }}...{{ end }}  {{/* filtered nav with active state */}}
{{ if currentUser }}...{{ end }}  {{/* authenticated user */}}
{{ csrfToken }}                   {{/* CSRF token for forms */}}
Configuration

Configuration is resolved in order: CLI flags > environment variables > TOML file.

Core flags include --host, --port, --database-dsn, --log-level, --log-format, --tls-mode, and more. Apps can contribute their own flags via the Configurable interface.

Migrations

Apps embed their SQL migrations and implement Migratable:

//go:embed migrations
var migrationFS embed.FS

func (a *App) MigrationFS() fs.FS {
    sub, _ := fs.Sub(migrationFS, "migrations")
    return sub
}

Migrations are tracked per-app in the _migrations table and run automatically on startup.

Development

just setup          # Check that all required dev tools are installed
just test           # Run all tests
just lint           # Run golangci-lint
just fmt            # Format code
just coverage       # Generate coverage report
just tidy           # Tidy module dependencies
just example-hello  # Run the hello world example
just example-notes  # Run the notes example application

Requires Go 1.25+. Run just setup to verify your dev environment.

Documentation

Full documentation is available in the docs/ directory.

License

Burrow is licensed under the European Union Public Licence v1.2 (EUPL-1.2). You can build any kind of software on top of Burrow — commercial, proprietary, or open source — without having to open-source your application code. See the licensing guide for details on what the EUPL means for you.

Third-party licenses are listed in THIRD_PARTY_LICENSES.md.

Documentation

Overview

Package burrow is a Go web framework built on chi, Bun/SQLite, and html/template. It provides a modular architecture where features are packaged as "apps" that plug into a shared server.

Getting Started

Create a server, register apps, and run: 

srv := burrow.NewServer(
    session.New(),
    csrf.New(),
    myapp.New(),
)
srv.SetLayout(myLayout)

app := &cli.Command{
    Name:   "mysite",
    Flags:  srv.Flags(nil),
    Action: srv.Run,
}
_ = app.Run(context.Background(), os.Args)

NewServer sorts apps by declared dependencies automatically. The boot sequence runs migrations, calls Register on each app, configures them from CLI/ENV/TOML flags, and starts the HTTP server with graceful shutdown.

Handler Functions

Burrow handlers return an error instead of silently swallowing failures: 

func listItems(w http.ResponseWriter, r *http.Request) error {
    items, err := fetchItems(r.Context())
    if err != nil {
        return err // logged and rendered as 500
    }
    return burrow.JSON(w, http.StatusOK, items)
}

Wrap them with Handle to get a standard http.HandlerFunc: 

r.Get("/items", burrow.Handle(listItems))

Return an HTTPError to control the status code and message: 

return burrow.NewHTTPError(http.StatusNotFound, "item not found")

Response Helpers

JSON, Text, and HTML write responses with correct Content-Type headers. Render writes pre-rendered template.HTML (useful for HTMX fragments). RenderTemplate executes a named template and wraps it in the layout for full-page requests, or returns the fragment alone for HTMX requests.

Request Binding and Validation

Bind parses a request body (JSON, multipart, or form-encoded) into a struct and validates it using "validate" struct tags. On validation failure it returns a *ValidationError containing per-field errors: 

type CreateItem struct {
    Name  string `form:"name"  validate:"required"`
    Email string `form:"email" validate:"required,email"`
}

func create(w http.ResponseWriter, r *http.Request) error {
    var input CreateItem
    if err := burrow.Bind(r, &input); err != nil {
        var ve *burrow.ValidationError
        if errors.As(err, &ve) {
            return burrow.JSON(w, 422, ve.Errors)
        }
        return err
    }
    // input is valid
}

Validate can be called standalone on any struct.

App Interface

Every app implements App (Name + Register). Apps gain additional capabilities by implementing optional interfaces:

Templates

Apps contribute .html files via HasTemplates. All templates are parsed into a single global html/template.Template at boot time. Templates use {{ define "appname/templatename" }} blocks for namespacing. Apps can add template functions via HasFuncMap (static) and HasRequestFuncMap (per-request, e.g. for CSRF tokens or the current user).

Pagination

ParsePageRequest extracts limit and page from the query string. Use ApplyOffset + OffsetResult for offset-based pagination. PageResponse wraps items and pagination metadata for JSON APIs.

Contrib Apps

The contrib/ directory provides reusable apps:

  • auth — WebAuthn passkey authentication with recovery codes
  • authmail — pluggable email rendering with SMTP backend
  • session — cookie-based sessions (gorilla/sessions)
  • csrf — CSRF protection (gorilla/csrf)
  • i18n — locale detection and translations (go-i18n)
  • admin — admin panel with generic CRUD via ModelAdmin
  • bootstrap — Bootstrap 5 CSS/JS with dark mode
  • bsicons — Bootstrap Icons as inline SVG template functions
  • htmx — HTMX asset serving and request/response helpers
  • jobs — SQLite-backed in-process job queue with retry
  • uploads — pluggable file upload storage
  • messages — flash messages via session storage
  • ratelimit — per-client token bucket rate limiting
  • healthcheck — liveness and readiness probes
  • staticfiles — static file serving with content-hashed URLs

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyOffset 

func ApplyOffset(q *bun.SelectQuery, pr PageRequest) *bun.SelectQuery

ApplyOffset applies offset-based pagination to a Bun SelectQuery.

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 ContextValue 

func ContextValue[T any](ctx context.Context, key any) (T, bool)

ContextValue retrieves a typed value from the context. It is the generic counterpart to WithContextValue, used by contrib app authors to read back app-specific context values with type safety.

func CoreFlags 

func CoreFlags(configSource func(key string) cli.ValueSource) []cli.Flag

CoreFlags returns the CLI flags for core framework configuration. If configSource is provided, it is used as an additional value source (e.g. a TOML file sourcer) for each flag.

func FlagSources 

func FlagSources(configSource func(key string) cli.ValueSource, envVar, tomlKey string) cli.ValueSourceChain

FlagSources builds a cli.ValueSourceChain from an environment variable and an optional TOML key. If configSource is nil, only the env var is used. This is the standard way for contrib apps to wire up flag sources: 

src := burrow.FlagSources(configSource, "MY_ENV_VAR", "app.toml_key")

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 IsLocalhost 

func IsLocalhost(host string) bool

IsLocalhost checks if the host is a localhost address.

func JSON 

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

JSON writes a JSON response with the given status code.

func Layout 

func Layout(ctx context.Context) string

Layout retrieves the layout template name from the context.

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 RenderError added in v0.5.0 

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 RenderTemplate deprecated 

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

Deprecated: Use Render instead.

func RunAppMigrations 

func RunAppMigrations(ctx context.Context, db *bun.DB, appName string, migrations fs.FS) error

RunAppMigrations runs all unapplied .up.sql migrations from the given FS for the named app. Migrations are tracked in the _migrations table, namespaced by app name.

func TestDB added in v0.5.0 

func TestDB(t *testing.T) *bun.DB

TestDB returns an in-memory SQLite database wrapped in a bun.DB. The database is automatically closed when the test finishes.

func TestErrorExecContext added in v0.5.0 

func TestErrorExecContext(ctx context.Context) context.Context

TestErrorExecContext returns a context with a minimal TemplateExecutor that renders error templates as "<code>: <message>". Use this in tests that trigger error responses through Handle or RenderError.

func TestErrorExecMiddleware added in v0.5.0 

func TestErrorExecMiddleware(next http.Handler) http.Handler

TestErrorExecMiddleware is an HTTP middleware that injects TestErrorExecContext into the request context. Use this in tests that need error rendering support.

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.

func WithAuthChecker added in v0.4.0 

func WithAuthChecker(ctx context.Context, checker AuthChecker) context.Context

WithAuthChecker stores an AuthChecker in the context. This is typically called by auth middleware to make authentication state available to the core template functions without an import cycle.

func WithContextValue 

func WithContextValue(ctx context.Context, key, val any) context.Context

WithContextValue returns a new context with the given key-value pair. This is a convenience wrapper around context.WithValue used primarily by contrib app authors to store app-specific values in the request context. Application developers typically use typed helpers like WithLayout or contrib-specific functions (e.g. csrf.WithToken) instead.

func WithLayout 

func WithLayout(ctx context.Context, name string) context.Context

WithLayout stores the layout template name in the context.

func WithNavItems 

func WithNavItems(ctx context.Context, items []NavItem) context.Context

WithNavItems stores navigation items in the context.

func WithTemplateExecutor 

func WithTemplateExecutor(ctx context.Context, exec TemplateExecutor) context.Context

WithTemplateExecutor stores the template executor in the context.

Types

type App 

type App interface {
	Name() string
	Register(cfg *AppConfig) error
}

App is the required interface that all apps must implement. An app has a unique name and a Register method that receives the shared configuration needed to wire into the framework.

type AppConfig 

type AppConfig struct {
	DB         *bun.DB
	Registry   *Registry
	Config     *Config
	WithLocale func(ctx context.Context, lang string) context.Context
}

AppConfig is passed to each app's Register method, providing access to shared framework resources.

type AuthChecker added in v0.4.0 

type AuthChecker struct {
	IsAuthenticated func() bool
	IsAdmin         func() bool
}

AuthChecker provides authentication and authorization checks via closures. This allows the core framework to filter nav items by auth state without importing contrib/auth. Auth apps inject an AuthChecker into the context; the framework reads it when building NavLinks.

type Config 

type Config struct {
	TLS      TLSConfig
	Database DatabaseConfig
	Server   ServerConfig
	I18n     I18nConfig
}

Config holds core framework configuration.

func NewConfig 

func NewConfig(cmd *cli.Command) *Config

NewConfig creates a Config from a parsed CLI command.

func (*Config) ResolveBaseURL 

func (c *Config) ResolveBaseURL() string

ResolveBaseURL computes the base URL from server and TLS config if BaseURL is not explicitly set.

func (*Config) ValidateTLS 

func (c *Config) ValidateTLS(cmd *cli.Command) error

ValidateTLS checks that the TLS configuration is consistent. Call this early (before opening the database) to fail fast on misconfigurations.

type Configurable 

type Configurable interface {
	Flags(configSource func(key string) cli.ValueSource) []cli.Flag
	Configure(cmd *cli.Command) error
}

Configurable is implemented by apps that define CLI flags and need to read their configuration from the CLI command. The configSource parameter enables TOML file sourcing; it may be nil when only ENV/CLI sources are used.

type DatabaseConfig 

type DatabaseConfig struct {
	DSN string
}

DatabaseConfig holds database settings.

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 HasAdmin 

type HasAdmin interface {
	AdminRoutes(r chi.Router)
	AdminNavItems() []NavItem
}

HasAdmin is implemented by apps that contribute admin panel routes and navigation items. AdminRoutes receives a chi router already prefixed with /admin and protected by auth middleware.

type HasCLICommands 

type HasCLICommands interface {
	CLICommands() []*cli.Command
}

HasCLICommands is implemented by apps that contribute subcommands.

type HasDependencies 

type HasDependencies interface {
	Dependencies() []string
}

HasDependencies is implemented by apps that require other apps to be registered first. Dependencies() returns the names of required apps; registration panics if any are missing.

type HasFuncMap 

type HasFuncMap interface {
	FuncMap() template.FuncMap
}

HasFuncMap is implemented by apps that provide static template functions. These are added once at boot time and available in all templates.

type HasJobs 

type HasJobs interface {
	RegisterJobs(q Queue)
}

HasJobs is implemented by apps that register background job handlers. Called by the Queue implementation during Configure(), before workers start.

type HasMiddleware 

type HasMiddleware interface {
	Middleware() []func(http.Handler) http.Handler
}

HasMiddleware is implemented by apps that contribute HTTP middleware.

type HasNavItems 

type HasNavItems interface {
	NavItems() []NavItem
}

HasNavItems is implemented by apps that contribute navigation items.

type HasRequestFuncMap 

type HasRequestFuncMap interface {
	RequestFuncMap(r *http.Request) template.FuncMap
}

HasRequestFuncMap is implemented by apps that provide request-scoped template functions (e.g., CSRF tokens, current user, translations). These are added per request via middleware using template.Clone().

type HasRoutes 

type HasRoutes interface {
	Routes(r chi.Router)
}

HasRoutes is implemented by apps that register HTTP routes.

type HasShutdown 

type HasShutdown interface {
	Shutdown(ctx context.Context) error
}

HasShutdown is implemented by apps that need to perform cleanup during graceful shutdown (e.g., stopping background goroutines, flushing buffers). Called in reverse registration order before the HTTP server stops.

type HasStaticFiles 

type HasStaticFiles interface {
	StaticFS() (prefix string, fsys fs.FS)
}

HasStaticFiles is implemented by apps that contribute static file assets. The returned prefix namespaces the files under the static URL path (e.g., prefix "admin" serves files at /static/admin/...).

type HasTemplates 

type HasTemplates interface {
	TemplateFS() fs.FS
}

HasTemplates is implemented by apps that provide HTML template files. The returned fs.FS should contain .html files with {{ define "appname/..." }} blocks. Templates are parsed once at boot time into the global template set.

type HasTranslations 

type HasTranslations interface {
	TranslationFS() fs.FS
}

HasTranslations is implemented by apps that contribute translation files. The returned fs.FS must contain a "translations/" directory with TOML files (e.g., "translations/active.en.toml").

type I18nConfig 

type I18nConfig struct {
	DefaultLanguage    string
	SupportedLanguages string // comma-separated
}

I18nConfig holds internationalization settings.

type JobConfig 

type JobConfig struct {
	MaxRetries int
}

JobConfig holds per-handler configuration.

type JobHandlerFunc 

type JobHandlerFunc func(ctx context.Context, payload []byte) error

JobHandlerFunc is the signature for job handler functions. The context carries a deadline from the worker's shutdown timeout. Payload is the raw JSON bytes that were passed to Enqueue.

type JobOption 

type JobOption func(*JobConfig)

JobOption configures job handler registration.

func WithMaxRetries 

func WithMaxRetries(n int) JobOption

WithMaxRetries sets the maximum number of retries for a job type.

type Migratable 

type Migratable interface {
	MigrationFS() fs.FS
}

Migratable is implemented by apps that provide database migrations. 

type NavItem struct {
	Label     string
	LabelKey  string // i18n message ID; translated at render time, falls back to Label
	URL       string
	Icon      template.HTML
	Position  int
	AuthOnly  bool
	AdminOnly bool
}

NavItem represents a navigation entry contributed by an app. 

func NavItems(ctx context.Context) []NavItem

NavItems retrieves the navigation items from the context. 

type NavLink struct {
	Label    string
	URL      string
	Icon     template.HTML
	IsActive bool
}

NavLink is a template-ready navigation item with pre-computed active state. It is produced by the navLinks template function from the registered NavItems, filtered by the current user's authentication/authorization state.

type PageRequest 

type PageRequest struct {
	Limit int // items per page (default 20, max 100)
	Page  int // 1-based page number for offset-based pagination (0 = not used)
}

PageRequest holds pagination parameters parsed from a query string.

func ParsePageRequest 

func ParsePageRequest(r *http.Request) PageRequest

ParsePageRequest extracts pagination parameters from the request query string.

func (PageRequest) Offset 

func (pr PageRequest) Offset() int

Offset returns the SQL OFFSET for the current page. Page 0 and 1 both return offset 0.

type PageResponse 

type PageResponse[T any] struct {
	Items      []T        `json:"items"`
	Pagination PageResult `json:"pagination"`
}

PageResponse wraps items with pagination metadata for JSON APIs. Use with OffsetResult to populate the Pagination field: 

return burrow.PageResponse[Item]{
    Items:      items,
    Pagination: burrow.OffsetResult(pr, totalCount),
}

type PageResult 

type PageResult struct {
	HasMore    bool `json:"has_more"`              // convenience: more pages exist
	Page       int  `json:"page,omitempty"`        // current page number (1-based)
	TotalPages int  `json:"total_pages,omitempty"` // total number of pages
	TotalCount int  `json:"total_count,omitempty"` // total number of items
}

PageResult holds pagination metadata returned alongside items.

func OffsetResult 

func OffsetResult(pr PageRequest, totalCount int) PageResult

OffsetResult builds a PageResult for offset-based pagination.

type Queue 

type Queue interface {
	Handle(typeName string, fn JobHandlerFunc, opts ...JobOption)
	Enqueue(ctx context.Context, typeName string, payload any) (string, error)
	EnqueueAt(ctx context.Context, typeName string, payload any, runAt time.Time) (string, error)
	Dequeue(ctx context.Context, id string) error
}

Queue provides job handler registration, enqueueing, and cancellation. contrib/jobs provides a SQLite-backed implementation.

type ReadinessChecker added in v0.4.0 

type ReadinessChecker interface {
	ReadinessCheck(ctx context.Context) error
}

ReadinessChecker is implemented by apps that contribute to the readiness probe. ReadinessCheck returns nil when the app is ready to serve traffic, or an error describing what is not ready.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds registered apps in insertion order and provides methods to collect capabilities (routes, middleware, flags, etc.) from all apps. Application code typically does not interact with Registry directly — Server manages it internally. Contrib app authors may use Registry.Get to look up sibling apps during Register.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates an empty Registry.

func (*Registry) Add 

func (r *Registry) Add(app App)

Add registers an app. It panics if an app with the same name has already been registered or if a declared dependency is missing (programming errors caught at startup).

func (*Registry) AllAdminNavItems 

func (r *Registry) AllAdminNavItems() []NavItem

AllAdminNavItems collects AdminNavItems from all HasAdmin apps and returns them sorted by Position (stable sort preserves insertion order for equal positions).

func (*Registry) AllCLICommands 

func (r *Registry) AllCLICommands() []*cli.Command

AllCLICommands collects CLI subcommands from all HasCLICommands apps.

func (*Registry) AllFlags 

func (r *Registry) AllFlags(configSource func(key string) cli.ValueSource) []cli.Flag

AllFlags collects CLI flags from all Configurable apps. Pass configSource to enable TOML file sourcing (or nil for ENV-only).

func (*Registry) AllNavItems 

func (r *Registry) AllNavItems() []NavItem

AllNavItems collects NavItems from all HasNavItems apps and returns them sorted by Position (stable sort preserves insertion order for equal positions).

func (*Registry) Apps 

func (r *Registry) Apps() []App

Apps returns all registered apps in the order they were added.

func (*Registry) Configure 

func (r *Registry) Configure(cmd *cli.Command) error

Configure calls Configure on each Configurable app. It stops and returns on the first error.

func (*Registry) Get 

func (r *Registry) Get(name string) (App, bool)

Get returns the app with the given name, or false if not found.

func (*Registry) RegisterAll 

func (r *Registry) RegisterAll(db *bun.DB) error

RegisterAll calls Register on each app in order, passing a partial AppConfig (DB + Registry only, no Config/migrations/seeds). This is a test convenience; the real boot sequence lives in Server.bootstrap().

func (*Registry) RegisterMiddleware 

func (r *Registry) RegisterMiddleware(router chi.Router)

RegisterMiddleware applies middleware from all HasMiddleware apps to the chi router, in app registration order.

func (*Registry) RegisterRoutes 

func (r *Registry) RegisterRoutes(router chi.Router)

RegisterRoutes calls Routes on each HasRoutes app, allowing apps to register their HTTP handlers.

func (*Registry) RunMigrations 

func (r *Registry) RunMigrations(ctx context.Context, db *bun.DB) error

RunMigrations runs migrations for all Migratable apps in registration order.

func (*Registry) Seed 

func (r *Registry) Seed(ctx context.Context) error

Seed calls Seed on each Seedable app in order. It stops and returns on the first error.

func (*Registry) Shutdown 

func (r *Registry) Shutdown(ctx context.Context) error

Shutdown calls Shutdown on each HasShutdown app in reverse registration order. Errors are collected but do not prevent other apps from shutting down.

type Seedable 

type Seedable interface {
	Seed(ctx context.Context) error
}

Seedable is implemented by apps that can seed the database with initial data.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server is the main framework entry point that orchestrates the full application lifecycle. Typical usage:

  1. Create with NewServer (registers apps, sorts by dependencies)
  2. Configure the layout with Server.SetLayout
  3. Collect CLI flags with Server.Flags
  4. Start with Server.Run (opens DB, migrates, bootstraps, serves HTTP)

func NewServer 

func NewServer(apps ...App) *Server

NewServer creates a Server and registers the given apps. Apps are automatically sorted so that dependencies are registered before the apps that need them. The relative order of independent apps is preserved. NewServer panics if a dependency is missing from the input or if there is a dependency cycle.

func (*Server) Flags 

func (s *Server) Flags(configSource func(key string) cli.ValueSource) []cli.Flag

Flags returns all CLI flags: core framework flags merged with flags from all Configurable apps. Pass a configSource to enable TOML file sourcing (or nil for ENV-only).

func (*Server) Registry 

func (s *Server) Registry() *Registry

Registry returns the server's app registry.

func (*Server) Run 

func (s *Server) Run(ctx context.Context, cmd *cli.Command) error

Run is a cli.ActionFunc that boots and starts the server. It opens the database, runs migrations, bootstraps apps, configures apps, and starts the HTTP server with graceful shutdown.

func (*Server) SetLayout 

func (s *Server) SetLayout(name string)

SetLayout configures the layout template name used for all pages.

type ServerConfig 

type ServerConfig struct {
	Host            string
	BaseURL         string
	PIDFile         string
	Port            int
	MaxBodySize     int // in MB
	ShutdownTimeout int // in seconds
}

ServerConfig holds HTTP server settings.

type TLSConfig 

type TLSConfig struct {
	Mode     string // auto, acme, selfsigned, manual, off
	CertDir  string
	Email    string
	CertFile string
	KeyFile  string
}

TLSConfig holds TLS settings.

type TemplateExecutor 

type TemplateExecutor func(r *http.Request, name string, data map[string]any) (template.HTML, error)

TemplateExecutor executes a named template with the given data and returns the rendered HTML. It is stored in the request context by the template middleware and used by RenderTemplate.

func TemplateExec added in v0.5.0 

func TemplateExec(ctx context.Context) TemplateExecutor

TemplateExec retrieves the template executor from the context.

func TemplateExecutorFromContext 

func TemplateExecutorFromContext(ctx context.Context) TemplateExecutor

TemplateExecutorFromContext is a deprecated alias for TemplateExec.

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)

Source Files

View all Source files

Directories

Path Synopsis
contrib
admin
Package admin provides the admin panel coordinator as a burrow contrib app.
 Package admin provides the admin panel coordinator as a burrow contrib app.
admin/modeladmin
Package modeladmin provides a generic, Django-style ModelAdmin for auto-generating CRUD admin views from Bun models.
 Package modeladmin provides a generic, Django-style ModelAdmin for auto-generating CRUD admin views from Bun models.
admin/modeladmin/templates
Package templates provides the default HTML template renderer for modeladmin CRUD views.
 Package templates provides the default HTML template renderer for modeladmin CRUD views.
auth
Package auth provides authentication as a burrow contrib app.
 Package auth provides authentication as a burrow contrib app.
auth/authtest
Package authtest provides test helpers for creating auth-migrated databases and test users, following the convention of net/http/httptest.
 Package authtest provides test helpers for creating auth-migrated databases and test users, following the convention of net/http/httptest.
authmail
Package authmail defines the Renderer interface for auth email templates.
 Package authmail defines the Renderer interface for auth email templates.
authmail/smtpmail
Package smtpmail provides an SMTP-based implementation of auth.EmailService with pluggable email templates via authmail.Renderer.
 Package smtpmail provides an SMTP-based implementation of auth.EmailService with pluggable email templates via authmail.Renderer.
bootstrap
Package bootstrap provides a design system contrib app using Bootstrap 5, Bootstrap Icons, and htmx.
 Package bootstrap provides a design system contrib app using Bootstrap 5, Bootstrap Icons, and htmx.
bsicons
Package bsicons provides all Bootstrap Icons as inline SVG template.HTML values.
 Package bsicons provides all Bootstrap Icons as inline SVG template.HTML values.
bsicons/internal/generate command
Command generate reads Bootstrap Icons SVG files and outputs a Go source file containing the icon data and named accessor functions.
 Command generate reads Bootstrap Icons SVG files and outputs a Go source file containing the icon data and named accessor functions.
csrf
Package csrf provides CSRF protection as a burrow contrib app.
 Package csrf provides CSRF protection as a burrow contrib app.
healthcheck
Package healthcheck provides liveness and readiness probes for burrow.
 Package healthcheck provides liveness and readiness probes for burrow.
htmx
Package htmx provides request detection and response helpers for htmx, inspired by django-htmx.
 Package htmx provides request detection and response helpers for htmx, inspired by django-htmx.
jobs
Package jobs provides an in-process, SQLite-backed background job queue as a burrow contrib app.
 Package jobs provides an in-process, SQLite-backed background job queue as a burrow contrib app.
messages
Package messages provides flash message support as a burrow contrib app.
 Package messages provides flash message support as a burrow contrib app.
ratelimit
Package ratelimit provides per-client rate limiting as a burrow contrib app.
 Package ratelimit provides per-client rate limiting as a burrow contrib app.
secure
Package secure provides security response headers as a burrow contrib app.
 Package secure provides security response headers as a burrow contrib app.
session
Package session provides cookie-based session management as a burrow contrib app.
 Package session provides cookie-based session management as a burrow contrib app.
staticfiles
Package staticfiles provides static file serving as a burrow contrib app.
 Package staticfiles provides static file serving as a burrow contrib app.
uploads
Package uploads provides file upload storage as a burrow contrib app.
 Package uploads provides file upload storage as a burrow contrib app.
example
hello command
Command hello is a minimal burrow application that serves a single "Hello, World!" page with Bootstrap styling and i18n support.
 Command hello is a minimal burrow application that serves a single "Hello, World!" page with Bootstrap styling and i18n support.
notes/cmd/server command
Command server demonstrates how to build an application using the burrow framework with contrib apps.
 Command server demonstrates how to build an application using the burrow framework with contrib apps.
notes/internal/notes
Package notes is an example custom app demonstrating the burrow framework.
 Package notes is an example custom app demonstrating the burrow framework.
notes/internal/pages
Package pages provides the example app's static pages (homepage), layout rendering, and icon template functions.
 Package pages provides the example app's static pages (homepage), layout rendering, and icon template functions.
Package forms provides Django-style form structs for creation, binding, validation, and field metadata extraction.
 Package forms provides Django-style form structs for creation, binding, validation, and field metadata extraction.
Package i18n provides internationalization as core framework infrastructure.
 Package i18n provides internationalization as core framework infrastructure.
internal
cryptokey
Package cryptokey provides shared utilities for resolving and decoding hex-encoded 32-byte cryptographic keys used by contrib apps (csrf, session).
 Package cryptokey provides shared utilities for resolving and decoding hex-encoded 32-byte cryptographic keys used by contrib apps (csrf, session).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.