burrow

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Mar 11, 2026 License: EUPL-1.2 Imports: 40 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/  /healthz endpoint
  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

The app layout wraps user-facing pages:

srv.SetLayout(appLayout)

The admin layout is owned by the admin package:

admin.New(admin.WithLayout(layout), admin.WithDashboardRenderer(dashboardRenderer))

A LayoutFunc receives the response writer, request, status code, rendered content, and template data:

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

Layouts access framework values from the request context:

burrow.NavItems(ctx)    // Navigation items from all apps
burrow.Layout(ctx)      // App layout function
csrf.Token(ctx)         // 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

See LICENSE. 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, cursor, and page from the query string. Use ApplyCursor + TrimCursorResults + CursorResult for cursor-based pagination, or ApplyOffset + OffsetResult for traditional page numbers. 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 — /healthz endpoint
  • staticfiles — static file serving with content-hashed URLs

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyCursor 

func ApplyCursor(q *bun.SelectQuery, pr PageRequest, orderColumn string) *bun.SelectQuery

ApplyCursor applies cursor-based pagination to a Bun SelectQuery. It orders by orderColumn DESC and fetches limit+1 rows to detect whether more items exist. Use TrimCursorResults to trim the extra item.

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.

Example 
package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/oliverandrich/burrow"
)

func main() {
	type Input struct {
		Name  string `json:"name" validate:"required"`
		Email string `json:"email" validate:"required,email"`
	}

	body := `{"name":"Alice","email":"alice@example.com"}`
	r := httptest.NewRequestWithContext(context.Background(), http.MethodPost, "/", strings.NewReader(body))
	r.Header.Set("Content-Type", "application/json")

	var input Input
	err := burrow.Bind(r, &input)

	fmt.Println(err)
	fmt.Println(input.Name, input.Email)
}

Output:

<nil>
Alice alice@example.com
Example (ValidationError) 
package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/oliverandrich/burrow"
)

func main() {
	type Input struct {
		Email string `json:"email" validate:"required,email"`
	}

	body := `{"email":"not-an-email"}`
	r := httptest.NewRequestWithContext(context.Background(), http.MethodPost, "/", strings.NewReader(body))
	r.Header.Set("Content-Type", "application/json")

	var input Input
	err := burrow.Bind(r, &input)

	fmt.Println(err)
}

Output:

validation failed: email is email

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.

Example 
package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/oliverandrich/burrow"
)

func main() {
	handler := burrow.Handle(func(w http.ResponseWriter, r *http.Request) error {
		return burrow.Text(w, http.StatusOK, "hello")
	})

	w := httptest.NewRecorder()
	r := httptest.NewRequestWithContext(context.Background(), http.MethodGet, "/", nil)
	handler(w, r)

	fmt.Println(w.Code)
	fmt.Println(strings.TrimSpace(w.Body.String()))
}

Output:

200
hello
Example (Error) 
package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/oliverandrich/burrow"
)

func main() {
	handler := burrow.Handle(func(w http.ResponseWriter, r *http.Request) error {
		return burrow.NewHTTPError(http.StatusNotFound, "item not found")
	})

	w := httptest.NewRecorder()
	r := httptest.NewRequestWithContext(context.Background(), http.MethodGet, "/items/42", nil)
	handler(w, r)

	fmt.Println(w.Code)
	fmt.Println(strings.TrimSpace(w.Body.String()))
}

Output:

404
item not found

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.

Example 
package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/oliverandrich/burrow"
)

func main() {
	w := httptest.NewRecorder()
	_ = burrow.JSON(w, http.StatusOK, map[string]string{"status": "ok"})

	fmt.Println(w.Header().Get("Content-Type"))
	fmt.Println(strings.TrimSpace(w.Body.String()))
}

Output:

application/json
{"status":"ok"}

func Render 

func Render(w http.ResponseWriter, r *http.Request, statusCode int, content template.HTML) error

Render writes pre-rendered HTML content to the response. Used for raw HTML output, HTMX fragments, or special cases where content is already rendered.

func RenderTemplate 

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

RenderTemplate 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 + LayoutFunc in context → fragment wrapped in layout
  • Normal request + no layout → fragment only

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 Text 

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

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

func TrimCursorResults 

func TrimCursorResults[T any](items []T, limit int) ([]T, bool)

TrimCursorResults trims a result slice that was fetched with limit+1. It returns the trimmed slice and whether more items exist beyond the limit.

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.

Example 
package main

import (
	"fmt"

	"github.com/oliverandrich/burrow"
)

func main() {
	type User struct {
		Name string `validate:"required"`
		Age  int    `validate:"gte=0,lte=150"`
	}

	err := burrow.Validate(&User{Name: "Alice", Age: 30})
	fmt.Println("valid:", err)

	err = burrow.Validate(&User{Name: "", Age: -1})
	fmt.Println("invalid:", err)
}

Output:

valid: <nil>
invalid: validation failed: Name is required; Age is gte

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, fn LayoutFunc) context.Context

WithLayout stores the app layout function 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 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.

Example 
package main

import (
	"fmt"
	"net/http"

	"github.com/oliverandrich/burrow"
)

func main() {
	err := burrow.NewHTTPError(http.StatusForbidden, "access denied")
	fmt.Println(err.Code)
	fmt.Println(err.Error())
}

Output:

403
access denied

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 LayoutFunc 

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

LayoutFunc wraps page content in a layout template. The layout reads framework values (nav items, user, locale, CSRF) from the request context via helper functions.

func Layout 

func Layout(ctx context.Context) LayoutFunc

Layout retrieves the app layout function from the context.

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 PageRequest 

type PageRequest struct {
	Limit  int    // items per page (default 20, max 100)
	Cursor string // opaque cursor for cursor-based pagination (empty = first page)
	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. If both cursor and page are present, cursor takes precedence.

Example 
package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/oliverandrich/burrow"
)

func main() {
	r := httptest.NewRequestWithContext(context.Background(), http.MethodGet, "/?page=2&limit=10", nil)
	pr := burrow.ParsePageRequest(r)

	fmt.Println("page:", pr.Page)
	fmt.Println("limit:", pr.Limit)
	fmt.Println("offset:", pr.Offset())
}

Output:

page: 2
limit: 10
offset: 10

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 CursorResult or OffsetResult to populate the Pagination field: 

items, hasMore := burrow.TrimCursorResults(rows, pr.Limit)
return burrow.PageResponse[Item]{
    Items:      items,
    Pagination: burrow.CursorResult(items[len(items)-1].ID, hasMore),
}
Example 
package main

import (
	"encoding/json"
	"fmt"

	"github.com/oliverandrich/burrow"
)

func main() {
	resp := burrow.PageResponse[string]{
		Items:      []string{"alice", "bob"},
		Pagination: burrow.OffsetResult(burrow.PageRequest{Limit: 2, Page: 1}, 5),
	}

	data, _ := json.Marshal(resp)
	fmt.Println(string(data))
}

Output:

{"items":["alice","bob"],"pagination":{"has_more":true,"page":1,"total_pages":3,"total_count":5}}

type PageResult 

type PageResult struct {
	NextCursor string `json:"next_cursor,omitempty"` // cursor for next page (empty = no more)
	PrevCursor string `json:"prev_cursor,omitempty"` // cursor for previous page (empty = first page)
	HasMore    bool   `json:"has_more"`              // convenience: NextCursor != ""
	// Offset-based fields (only populated when using offset pagination):
	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 CursorResult 

func CursorResult(lastCursor string, hasMore bool) PageResult

CursorResult builds a PageResult for cursor-based pagination. lastCursor is the cursor value of the last item in the current page. hasMore indicates whether there are more items after this page.

Example 
package main

import (
	"fmt"

	"github.com/oliverandrich/burrow"
)

func main() {
	items := []string{"a", "b", "c", "d", "e", "extra"}
	items, hasMore := burrow.TrimCursorResults(items, 5)
	result := burrow.CursorResult(items[len(items)-1], hasMore)

	fmt.Println("items:", len(items))
	fmt.Println("has_more:", result.HasMore)
	fmt.Println("next_cursor:", result.NextCursor)
}

Output:

items: 5
has_more: true
next_cursor: e

func OffsetResult 

func OffsetResult(pr PageRequest, totalCount int) PageResult

OffsetResult builds a PageResult for offset-based pagination.

Example 
package main

import (
	"fmt"

	"github.com/oliverandrich/burrow"
)

func main() {
	pr := burrow.PageRequest{Limit: 10, Page: 2}
	result := burrow.OffsetResult(pr, 25)

	fmt.Println("page:", result.Page)
	fmt.Println("total_pages:", result.TotalPages)
	fmt.Println("total_count:", result.TotalCount)
	fmt.Println("has_more:", result.HasMore)
}

Output:

page: 2
total_pages: 3
total_count: 25
has_more: true

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 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(fn LayoutFunc)

SetLayout configures the app layout function.

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 TemplateExecutorFromContext 

func TemplateExecutorFromContext(ctx context.Context) TemplateExecutor

TemplateExecutorFromContext retrieves the template executor from the context.

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.

Example 
package main

import (
	"errors"
	"fmt"

	"github.com/oliverandrich/burrow"
)

func main() {
	type Form struct {
		Email string `validate:"required,email"`
		Name  string `validate:"required"`
	}

	err := burrow.Validate(&Form{})

	var ve *burrow.ValidationError
	if errors.As(err, &ve) {
		fmt.Println("has Email error:", ve.HasField("Email"))
		fmt.Println("has Age error:", ve.HasField("Age"))
	}
}

Output:

has Email error: true
has Age error: false

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.
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 a minimal health check app for burrow.
 Package healthcheck provides a minimal health check app 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 request-path middleware for active nav link highlighting.
 Package pages provides the example app's static pages (homepage), layout rendering, and request-path middleware for active nav link highlighting.
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.