server

Documentation

Index

• func OpenDB(ctx context.Context, dsn string, opts ...den.Option) (*den.DB, error)
• type Server
  • func New(apps ...burrowapp.App) *Server
  • func (s *Server) CLICommands() []*cli.Command
  • func (s *Server) Flags(configSource func(key string) cli.ValueSource) []cli.Flag
  • func (s *Server) Registry() *registry.Registry
  • func (s *Server) Run(ctx context.Context, cmd *cli.Command) error
  • func (s *Server) SetLayout(name string)
  • func (s *Server) TemplateExecutor() burrowapp.TemplateExecutor
• type Startable

Functions

func OpenDB

func OpenDB(ctx context.Context, dsn string, opts ...den.Option) (*den.DB, error)

OpenDB opens a database from a URL-style DSN. Struct-tag validation is always-on at the Den layer — documents with `validate:"..."` tags are checked before every Save; a violation returns an error wrapping den.ErrValidation.

Supported schemes:

• sqlite:///path/to/db — SQLite file database
• postgres://user:pass@host:5432/db — PostgreSQL

The matching Den backend package must be blank-imported by the consuming binary's main package — Burrow does not pull either backend in by default, so production binaries only link the engine they actually use:

import (
    _ "github.com/oliverandrich/den/backend/sqlite"   // for sqlite:// DSNs
    _ "github.com/oliverandrich/den/backend/postgres" // for postgres:// DSNs
)

Additional den.Options (for example den.WithStorage) are forwarded so callers can layer capabilities on top.

Types

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 New

func New(apps ...burrowapp.App) *Server

New 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. New panics if a dependency is missing from the input or if there is a dependency cycle.

The burrow root package re-exports this as burrow.NewServer.

func (*Server) CLICommands

func (s *Server) CLICommands() []*cli.Command

CLICommands returns CLI subcommands from all HasCLICommands apps, each wrapped to run inside the framework's boot lifecycle: the wrapped Action calls [Server.boot] (open DB, bootstrap, Configure all apps) before the original Action fires, and closes the database afterwards. Without this wrapping, contrib subcommands like `auth set-role` would run against uninitialised apps and fail with errors like "auth app not initialized".

Use this to wire framework-aware CLI subcommands into a cli.Command:

cmd := &cli.Command{
    Flags:    srv.Flags(nil),
    Action:   srv.Run,
    Commands: srv.CLICommands(),
}

Each returned command is a shallow copy of the registry's original; only Action is replaced. Mutating the returned commands' slice fields (Flags, Commands, Arguments) would also mutate the registry's originals — don't.

Limitations: sub-subcommands (a contrib subcommand's own nested Commands) are not recursively wrapped, and the top-level Action must be non-nil (a command that only forwards to sub-subcommands is not supported here).

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

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.

func (*Server) TemplateExecutor

func (s *Server) TemplateExecutor() burrowapp.TemplateExecutor

TemplateExecutor returns the server's template executor function. Use this after boot to obtain an executor for non-HTTP rendering via app.WithTemplateExecutor and web.RenderFragment. Returns nil if templates have not been built yet (i.e., before Server.Run).

type Startable

type Startable interface {
	Start(srv *Server) error
}

Startable is implemented by apps that need to start background processes after the full boot sequence completes (templates built, middleware and routes registered). It is the counterpart to app.HasShutdown.

Startable lives next to Server because it references the concrete *Server handle that background workers need.