app

type App ¶

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

App is the top-level application: it owns the DI container, the HTTP layer, the migration registry and the ordered set of providers/modules, and drives the two-phase boot lifecycle.

Typical use:

a := app.New(app.WithAddr(":8080"))
a.Register(UsersModule, BillingModule)
if err := a.Run(context.Background()); err != nil {
    log.Fatal(err)
}

App is not safe for concurrent Register/Boot; configure and boot it from a single goroutine, then serve. The container it owns is itself concurrency safe.

func New(opts ...Option) *App

func (a *App) Boot() error

func (a *App) Booted() bool

func (a *App) Commands() []Command

func (a *App) Container() *container.Container

func (a *App) Migrations() *migrations.Registry

func (a *App) Register(providers ...Provider) *App

a.Register(UsersModule, app.RegisterFunc(bindClock), &MetricsProvider{})

func (a *App) Run(ctx context.Context) error

func (a *App) Scope() *container.Container

rc := a.Scope()
defer ... // request lifetime
svc := container.MustMake[*RequestSvc](rc)

func (a *App) Test() error

func (a *App) Web() *web.App

type Booter ¶

type Booter interface {
	// Boot runs after every provider has registered. It may resolve
	// bindings owned by other providers.
	Boot(c *container.Container) error
}

Booter is the optional second phase of a Provider. A Provider that also implements Booter has its Boot method called once, after all providers have completed Register, in registration order.

type Command ¶

type Command interface {
	// Name is the command's invocation name, e.g. "users:prune".
	Name() string
}

Command is an opaque CLI command contributed by a module. The app layer only collects commands; the host program (or the cli package) dispatches them. Kept as an interface so app does not depend on a concrete CLI package.

type Module ¶

type Module struct {
	// Name identifies the module in diagnostics and ordering errors.
	Name string

	// Providers are registered (and booted) in slice order before the
	// module's own Register/Boot callbacks.
	Providers []Provider

	// Register, if non-nil, runs as a register-phase callback after the
	// module's providers have registered. Bind module-level services here.
	RegisterFn func(c *container.Container) error

	// Boot, if non-nil, runs in the boot phase after the module's providers
	// have booted. Resolve services and perform module-level wiring here.
	BootFn func(c *container.Container) error

	// Routes, if non-nil, runs in the boot phase against the application's
	// web router. Declare the feature's HTTP routes here.
	Routes func(r *web.Router)

	// Migrations, if non-nil, runs in the boot phase against the
	// application's migration registry. Register the feature's migrations
	// here.
	Migrations func(reg *migrations.Registry)

	// Commands, if non-nil, returns the feature's CLI commands. The slice is
	// collected by the app and exposed via App.Commands(); the app layer
	// does not run a CLI itself, leaving dispatch to the host program.
	Commands func() []Command
}

Module groups everything a feature needs — providers, routes, migrations and CLI commands — under a single name, so an entire feature is wired with one app.Register call.

A Module is a Provider itself: registering a module registers all of its providers (in slice order), then registers the module's own Register/Boot callbacks last so they observe the providers' bindings. During the application boot phase the module's route and migration callbacks run, giving the feature access to the web app and migration registry.

Construct a Module with NewModule and the With* options, or assemble the struct literal directly:

var UsersModule = app.NewModule("users",
    app.WithProviders(&UserServiceProvider{}),
    app.WithRoutes(func(r *web.Router) {
        r.Get("/users", listUsers)
    }),
    app.WithModuleMigrations(func(reg *migrations.Registry) {
        reg.Register(createUsersTable{})
    }),
)

func NewModule(name string, opts ...ModuleOption) *Module

func (m *Module) ProviderName() string

func (m *Module) Register(*container.Container) error

type ModuleOption ¶

type ModuleOption func(*Module)

ModuleOption configures a Module built with NewModule.

func WithCommands(fn func() []Command) ModuleOption

func WithModuleBoot(fn func(c *container.Container) error) ModuleOption

func WithModuleMigrations(fn func(reg *migrations.Registry)) ModuleOption

func WithModuleRegister(fn func(c *container.Container) error) ModuleOption

func WithProviders(p ...Provider) ModuleOption

func WithRoutes(fn func(r *web.Router)) ModuleOption

type Named ¶

type Named interface {
	// ProviderName returns a human-readable identifier.
	ProviderName() string
}

Named is an optional Provider/Module capability: a stable name used in boot-ordering errors and diagnostics. Providers that do not implement it are reported by their Go type.

type Option ¶

type Option func(*App)

Option configures an App at construction.

func WithAddr(addr string) Option

func WithContainer(c *container.Container) Option

func WithMigrations(reg *migrations.Registry) Option

func WithWebApp(w *web.App) Option

func WithWebOptions(opts ...web.Option) Option

type Provider ¶

type Provider interface {
	// Register binds this provider's services into the container.
	Register(c *container.Container) error
}

Provider contributes services to the application across two phases.

Register binds services into the container. It must NOT resolve other providers' bindings — they may not exist yet. Keep Register pure: declare factories, no side effects that depend on the rest of the app.

Boot runs after every provider has registered. Here a provider may resolve its dependencies, register routes on the web app, attach event hooks, schedule tasks, and so on. Implement Boot via the optional Booter interface; a provider that only binds services can skip it.

Providers boot in registration order, which is deterministic.

type RegisterFunc ¶

type RegisterFunc func(c *container.Container) error

RegisterFunc adapts a plain function into a register-only Provider. Use it for small providers that only bind a few services:

app.RegisterFunc(func(c *container.Container) error {
    container.Singleton(c, newClock)
    return nil
})

func (f RegisterFunc) Register(c *container.Container) error