framework

func (*App) AddCron ¶

func (a *App) AddCron(s *cron.Scheduler) *App

AddCron registers a Scheduler with the app's lifecycle: it starts when Start runs and stops when Stop runs. Returns the App for chaining so users can wire several schedulers in one expression.

func (*App) AddQueue ¶

func (a *App) AddQueue(q schedulerStartStop) *App

AddQueue registers any queue/worker that exposes Start(ctx) and Close(). The DBQueue from battery/queue satisfies this directly; in-memory and Redis variants can be wrapped.

func (*App) CrudHandler ¶

func (a *App) CrudHandler(name string) (*crud.CrudHandler, error)

CrudHandler returns a fully-wired in-process CRUD handler for a registered entity — the same handler shape the HTTP routes use (hooks, events, storage, JSON casing, registry). Use it to call CreateOne/UpdateOne/DeleteOne/ListAll directly, e.g. to compose several writes inside App.InTx (pass the InTx ctx so they join the same transaction). Returns an error if no entity is registered under name or the app has no DB.

func (*App) EntitiesFromDir ¶

func (a *App) EntitiesFromDir(dir string) error

EntitiesFromDir loads and registers every *.json declaration in dir.

func (*App) Entity ¶

func (a *App) Entity(name string, config entity.EntityConfig) *App

Entity registers an entity with the given name and configuration. Returns the App for fluent chaining. Panics on any misconfiguration — convenient for static, hand-written declarations where a bad config is a programming error you want to fail fast on. For generated or untrusted configs (e.g. an AI-authored field, a dynamic schema) where one bad entity should not crash the process, use TryEntity, which returns the error.

func (*App) EntityFromFile ¶

func (a *App) EntityFromFile(path string) (*entity.Entity, error)

EntityFromFile loads and registers one JSON entity declaration.

func (*App) Events ¶

func (a *App) Events() *event.EventBus

Events returns the application's event bus.

func (*App) Flags ¶

func (a *App) Flags() *featureflag.Evaluator

Flags returns the app's feature-flag evaluator, creating one on first call. The default backing store is in-memory; for clustered deployments call SetFlagStore with a Redis- or DB-backed implementation BEFORE any caller invokes Flags — once the lazy default fires, subsequent SetFlagStore calls panic to avoid the silent race where some goroutines still hold a reference to the previous evaluator.

The evaluator is also installed as featureflag.Default() so package- level featureflag.Bool(ctx, "...") calls work from anywhere in the app.

func (*App) Group ¶

func (a *App) Group(prefix string, opts ...routegroup.GroupOption) *routegroup.RouteGroup

Group creates a route group with the given prefix and optional configuration. The group supports its own middleware stack, access policy, OpenAPI tags, and MCP namespacing. Nested groups compose prefixes and middleware.

api := app.Group("/api")
api.Use(authMiddleware)
api.Get("/health", healthHandler)

admin := app.Group("/admin", routegroup.WithAccess(access.RequirePermission("admin:access")))
admin.Entity("settings", settingsConfig)

func (*App) GroupEntitiesFromDir ¶

func (a *App) GroupEntitiesFromDir(g *routegroup.RouteGroup, dir string) error

GroupEntitiesFromDir loads every *.json declaration in dir and registers each one inside the given RouteGroup — the group-scoped equivalent of EntitiesFromDir. CRUD routes mount at <group-prefix>/<entity-table>, MCP tools are namespaced under the group's MCPNamespace.

Use this with a /api group when every JSON entity should live behind a single prefix:

api := app.Group("/api")
app.GroupEntitiesFromDir(api, "entities")

func (*App) GroupEntity ¶

func (a *App) GroupEntity(g *routegroup.RouteGroup, name string, config entity.EntityConfig) *App

GroupEntity registers an entity with the given configuration inside a RouteGroup. CRUD routes mount at <group-prefix>/<entity-table>, MCP tools are namespaced under the group's MCPNamespace, and the OpenAPI tag reflects the group's OpenAPITag if set.

This is the group-scoped equivalent of App.Entity.

func (*App) HookRegistry ¶

func (a *App) HookRegistry(entityName string) *hook.HookRegistry

HookRegistry returns (or creates) the hook registry for a named entity.

func (*App) InTx ¶

func (a *App) InTx(ctx context.Context, fn func(ctx context.Context, tx *sql.Tx) error) error

InTx runs fn inside a database transaction opened on the App's DB. The inner context carries the *sql.Tx so any code path that calls TxFromContext (typed hooks, the various do* helpers, generated repo methods invoked via WithTx) participates atomically.

Convenience wrapper for callers that aren't already inside a CRUD hook — e.g. seeders, batch jobs, multi-entity write paths that need an explicit boundary. If fn returns an error, the tx rolls back and that error is returned unchanged.

func (*App) InitPlugins ¶

func (a *App) InitPlugins() error

InitPlugins initializes all registered plugins and batteries by calling their Init(app) method. Plugins go first (registration order), then batteries (dependency-resolved order). Each module does everything it needs from inside Init — register routes, add middleware, register MCP tools, attach hooks, swap the logger, etc.

Idempotent: the first successful call latches an internal flag so any later call returns nil without re-running plugin Inits. This lets tests call InitPlugins() manually pre-Start without colliding with the implicit call inside Start.

func (*App) IsEnabled ¶

func (a *App) IsEnabled(ctx context.Context, key string) bool

IsEnabled is a convenience wrapper that calls Flags().Bool with the supplied context. Use it from handler code that doesn't otherwise need a direct reference to the evaluator.

The context is expected to already carry an EvalContext (via featureflag.WithContext) when user/tenant gating matters; without one, the call still works but only the kill-switch (Flag.Enabled) and uniform rollout are consulted.

func (*App) JSONCasing ¶

func (a *App) JSONCasing() crud.JSONCase

JSONCasing returns the configured JSON casing strategy. Defaults to CaseCamel if not explicitly set.

func (*App) Lifecycle ¶

func (a *App) Lifecycle() *lifecycle.Lifecycle

Lifecycle returns the App's graceful-shutdown coordinator. Batteries and plugins use Lifecycle().RegisterDrainer / RegisterHealthChecker to participate in Shutdown beyond the simple OnStop hook.

func (*App) Logger ¶

func (a *App) Logger() *slog.Logger

Logger returns the App-local *slog.Logger. Middleware and plugins should call this — not slog.Default() — so that a logging plugin can replace the destination without rewiring globals.

Always non-nil. NewApp seeds the App with a JSON-to-stderr logger that is independent of slog.Default; an unrelated slog.SetDefault elsewhere in the process does not redirect this App's logs.

func (*App) Mount ¶

func (a *App) Mount(m Mountable) *App

Mount attaches a Mountable and registers its routes on the app's router immediately. The default middleware chain is already in place (committed during NewApp), so any handler the Mountable registers is wrapped with it. Returns the app for fluent chaining.

Mountables typically register a NotFound catch-all (e.g. a UI host that renders pages for any unrouted path), so call Mount AFTER any explicit routes you want to take precedence (entity CRUD, custom endpoints).

IMPORTANT — ordering with plugins/batteries: plugin.Init runs at App.Start (or InitPlugins), AFTER Mount has already registered the Mountable's routes. If a plugin's Init registers a more-specific route that overlaps with a Mountable's NotFound catch-all, the plugin's route still wins (ServeMux dispatches by specificity, not by registration order). But if a plugin registers a Mountable-style catch-all itself, it shadows any user routes added after Mount but before InitPlugins. Mount last unless you know what you're doing.

func (*App) Mountables ¶

func (a *App) Mountables() []Mountable

Mountables returns the Mountables registered via Mount, in registration order. Batteries use it to discover a mounted UI host (type-asserting to *uihost.Host) so they can register screens on the host's render pipeline rather than spinning up a second host. Returns a copy — callers must not mutate the App's internal slice.

func (*App) MustCrudHandler ¶

func (a *App) MustCrudHandler(name string) *crud.CrudHandler

MustCrudHandler is CrudHandler that panics on error — for app setup where a missing entity is a programming mistake.

func (*App) OnStart ¶

func (a *App) OnStart(fn func(ctx context.Context) error) *App

OnStart registers a function to run once during App.Start, before the HTTP server begins accepting connections. The context passed in is cancelled when Stop is called, so workers should respect it.

Hooks run in registration order; the first to return a non-nil error aborts Start.

func (*App) OnStop ¶

func (a *App) OnStop(fn func() error) *App

OnStop registers a function to run during App.Shutdown, after the HTTP server has shut down. Hooks run in reverse registration order — the last thing started is the first thing stopped. Internally the hook is wrapped as a lifecycle.Drainer so app-level cleanup and battery drains share one coordinator.

func (*App) OnStopFirst ¶

func (a *App) OnStopFirst(fn func() error) *App

OnStopFirst registers an OnStop hook that runs LAST under the reverse-order Stop iteration. Useful for plugins (battery/log especially) that must outlive every other shutdown step: their close hook needs to fire AFTER every other OnStop has had a chance to emit log entries.

Without this, a user that registers app.OnStop BEFORE RegisterPlugin(log) gets the order inverted on reverse iteration — log's close runs first, the user's OnStop logs into closed sinks.

func (*App) RegisterBattery ¶

func (a *App) RegisterBattery(b Battery, deps ...string) *App

RegisterBattery registers a heavyweight, lifecycle-aware battery module (auth, search, cache, etc.) with the application. deps lists battery names that must be initialized before this one. Returns the App for chaining.

Batteries are initialized in dependency-resolved order during App.Start, before the HTTP server binds. Each battery's Init does whatever it needs by calling into the App (routes, middleware, hooks, MCP tools). Batteries that also implement BatteryLifecycle get their OnStart/OnStop fired by the App at the appropriate moment.

Example:

app.RegisterBattery(auth.New(auth.Config{...}), "search") // depends on search battery

func (*App) RegisterEntities ¶

func (a *App) RegisterEntities(entities map[string]entity.EntityConfig) *App

RegisterEntities registers each (name, config) pair via App.Entity in alphabetical-by-name order. Sorting matters: Entity has order-sensitive side effects — router registration, MCP tool list order, OpenAPI tag emission — and Go's map iteration is randomised, so unsorted iteration would mean non-deterministic /openapi.json bytes across restarts (breaking ETag caching) and non-deterministic MCP tools/list responses. FK relations stay safe because AutoMigrate also topologically sorts.

Returns the App for fluent chaining.

app.RegisterEntities(map[string]entity.EntityConfig{
    "foods":  foodsConfig,
    "meals":  mealsConfig,
    "users":  usersConfig,
})

func (*App) RegisterPlugin ¶

func (a *App) RegisterPlugin(plugin Plugin) *App

RegisterPlugin registers a plugin with the application's plugin manager. Returns the App for fluent chaining.

Panics if InitPlugins has already run — plugins must be registered before App.Start (or the explicit InitPlugins call) so their Init fires. The panic is a clear contract violation rather than a silent no-op that would have the new plugin's routes / middleware vanish.

func (*App) RegisterReadiness ¶

func (a *App) RegisterReadiness(name string, check func(ctx context.Context) error) *App

RegisterReadiness adds a readiness check. Names are not required to be unique — duplicates surface in the /readyz response as repeated rows, which is occasionally useful (the same backend probed at two layers).

Pass a timeout on the context if your check could hang; /readyz also applies an overall deadline, but per-check timeouts give better signal in the response.

func (*App) Router ¶

func (a *App) Router() *router.Router

Router returns the App's *router.Router for advanced use (plugin authors, batteries that need to register routes with custom matching, sub-router construction). Application code should prefer the App-level helpers:

• App.Use(mw) — register middleware (instead of Router().Use)
• App.Get/Post/... — register routes (instead of Router().Handle)
• App.Group(prefix) — sub-routes (instead of Router().Group)

Both forms are functionally equivalent — App.Use forwards to Router().Use — but the App-level surface is the canonical one in docs and examples.

Exposed as a method (rather than a field) so plugins and batteries can swap or wrap the router during Init without callers depending on direct field assignment.

func (*App) Routine ¶

func (a *App) Routine(r migrate.Routine) *App

Routine registers a stored routine (function, procedure, trigger, or view) as a first-class migration object. Its Up runs on every boot (idempotent CREATE OR REPLACE) after tables are migrated, and `migrate generate` tracks it for reversible versioned migrations. Returns App for chaining.

func (*App) RunWithSignals ¶

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

RunWithSignals blocks until SIGINT or SIGTERM is received, then runs Shutdown. Returns Shutdown's error, or nil if ctx is cancelled before a signal arrives.

func (*App) SetFlagStore ¶

func (a *App) SetFlagStore(s featureflag.Store) *App

SetFlagStore swaps the underlying store. Must be called before any caller has triggered the lazy default; a second SetFlagStore call (or any call after Flags() / IsEnabled has already been used) panics to avoid the silent race where stale references to the previous evaluator persist in handler closures.

Useful for tests that want a preconfigured store, or for production wiring that uses a persistent backend — wire it during NewApp setup, before any request runs.

func (*App) SetLogger ¶

func (a *App) SetLogger(l *slog.Logger)

SetLogger replaces the App's logger. Atomic; safe to call concurrently with in-flight requests — atomic.Pointer.Store is race-free, and middleware reading via App.Logger() sees the new value on the next request.

Panics if l is nil — the App's logger is always non-nil; pass a discard logger (slog.New(slog.DiscardHandler)) to silence output.

func (*App) Shutdown ¶

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

Shutdown gracefully stops the HTTP server, stops every registered battery in reverse dependency order, then runs each OnStop hook in reverse registration order. Matches net/http.Server.Shutdown's signature (takes a deadline ctx) but does the FULL lifecycle teardown. Safe to call multiple times — subsequent calls are no-ops.

Call this from your signal handler.

func (*App) Start ¶

func (a *App) Start(addr string) error

Start starts the HTTP server on the given address. Auto-migrates tables, registers OpenAPI/Swagger, debug stats, applies the default middleware chain (unless disabled), and calls Mount on every attached Mountable.

Sets the process title to the app name for visibility in ps/Activity Monitor.

func (*App) T ¶

func (a *App) T(ctx context.Context, key string, params ...map[string]any) string

T is a convenience wrapper around the app's Translator. Returns the bare key when no Translator has been wired via WithI18n.

The ctx is expected to already carry a Locale (the i18n middleware attaches one per request from Accept-Language); when it doesn't, the Translator's fallback locale is used.

func (*App) Table ¶

func (a *App) Table(t migrate.Table) *App

Table registers a raw, non-entity table for migration only — no CRUD, no HTTP routes, no validation, no auto-injected columns. The table participates in auto-migrate, diffing, and generation alongside entities (including foreign keys that cross between the two). For users who want migration coverage of a table without the entity machinery. Returns App for chaining.

func (*App) Translator ¶

func (a *App) Translator() *i18n.Translator

Translator returns the wired Translator, or nil if WithI18n was never called. Useful for handlers that need to drive locale-aware formatting beyond simple lookups.

func (*App) TryEntity ¶

func (a *App) TryEntity(name string, config entity.EntityConfig) (err error)

TryEntity is the error-returning variant of Entity: it registers an entity and returns an error on any misconfiguration instead of panicking. It also recovers panics from deeper validation (e.g. an invalid TenantField) and converts them to errors, so a single bad config can never take down the process — the property an agent-driven authoring loop needs.

func (*App) Use ¶

func (a *App) Use(mw ...router.Middleware) *App

Use appends middleware to the app's router chain. The default chain (installed by NewApp unless WithoutDefaultMiddleware is set) stays in place — Use adds to it, never silently replaces it. Plugins call Use from their Init to contribute middleware; router late-binding means these additions also wrap routes registered before the plugin loaded.

func (*App) View ¶

func (a *App) View(v migrate.View) *App

View registers a database view — a virtual table built from other entities. The view is created on boot after its source tables (and tracked reversibly by `migrate generate`), and, when it declares Columns, it is also exposed through the ORM as a READ-ONLY entity: List/Get and the query layer work, but no write routes are registered. Returns App for chaining.

func (*App) WithAuditLog ¶

func (a *App) WithAuditLog(cfg AuditConfig) *App

WithAuditLog enables audit logging on every entity registered on the app (or the subset named in cfg.Entities). Call AFTER Entity registrations.

Returns the app for fluent chaining. Panics if the audit table cannot be created — this is initialization-time work so loud failure is preferable to silent log loss.

func (*BatteryManager) All ¶

func (bm *BatteryManager) All() []Battery

All returns all registered batteries in dependency-resolved order.

func (*BatteryManager) Get ¶

func (bm *BatteryManager) Get(name string) (Battery, error)

Get retrieves a battery by name. Returns the Battery interface so callers can type-assert to the concrete type or any optional interface.

func (*BatteryManager) InitAll ¶

func (bm *BatteryManager) InitAll(app *App) error

InitAll initializes all batteries in dependency order. Called during App.Start before the HTTP server binds.

func (*BatteryManager) Names ¶

func (bm *BatteryManager) Names() []string

Names returns battery names in dependency-resolved order.

func (*BatteryManager) Register ¶

func (bm *BatteryManager) Register(b Battery, deps ...string) error

Register adds a battery with optional dependency declarations. Deps lists battery names that must be initialized before this one. Returns an error on duplicate name or unknown dependency.

func (*BatteryManager) StartAll ¶

func (bm *BatteryManager) StartAll(ctx context.Context) error

StartAll calls OnStart on batteries that implement BatteryLifecycle, in dependency order (dependencies first).

func (*BatteryManager) StopAll ¶

func (bm *BatteryManager) StopAll(ctx context.Context) error

StopAll calls OnStop on batteries that implement BatteryLifecycle, in reverse dependency order (dependents first, then dependencies).

func (*PluginManager) All ¶

func (pm *PluginManager) All() []Plugin

All returns all registered plugins in order.

func (*PluginManager) Get ¶

func (pm *PluginManager) Get(name string) (Plugin, error)

Get retrieves a plugin by name.

func (*PluginManager) InitAll ¶

func (pm *PluginManager) InitAll(app *App) error

InitAll initializes all plugins in registration order.

Wraps each Init in a deferred recover so a panic — most commonly `http: multiple registrations for ...` from a duplicate route pattern — gets tagged with the offending plugin's name. Without this the panic surfaces deep in ServeMux with no context about which plugin registered the conflicting route.

Tracks per-plugin init state so that a retry after partial failure (App.InitPlugins rolls back its global latch on error) only re-runs plugins that haven't already applied side effects. Without this a retry would re-Register the routes the successful plugins already added and panic on the ServeMux duplicate-pattern check.

func (*PluginManager) Names ¶

func (pm *PluginManager) Names() []string

Names returns the names of all registered plugins in registration order.

func (*PluginManager) Register ¶

func (pm *PluginManager) Register(plugin Plugin) error

Register adds a plugin to the manager. Returns an error if a plugin with the same name is already registered, or if the name is invalid (empty, whitespace-only, contains a control character, or longer than maxModuleNameLen).

func (*Registry) All ¶

func (r *Registry) All() map[string]*entity.Entity

All returns a copy of the map of all registered entities. Map iteration order is randomised by Go; use AllSorted() for stable iteration in code paths that emit order-sensitive output.

func (*Registry) AllSorted ¶

func (r *Registry) AllSorted() []*entity.Entity

AllSorted returns every registered entity in alphabetical order by name. Use this whenever the iteration order affects bytes-on-the-wire (OpenAPI tag emission, LLM-markdown, codegen output) so the same registry produces the same artefact across restarts.

func (*Registry) Get ¶

func (r *Registry) Get(name string) (*entity.Entity, error)

Get retrieves an Entity by name. Returns an error if no entity with that name is registered.

func (*Registry) Register ¶

func (r *Registry) Register(ent *entity.Entity) error

Register adds an Entity to the registry. Returns an error if an entity with the same name already exists.

func (*Registry) SetDB ¶

func (r *Registry) SetDB(db *sql.DB)

SetDB sets the database connection on the registry and propagates it to all registered entities.

func (*TestApp) Close ¶

func (ta *TestApp) Close()

Close is a no-op for in-memory testing (provided for API consistency).

func (*TestApp) Delete ¶

func (ta *TestApp) Delete(path string) *TestResponse

Delete performs a DELETE request.

func (*TestApp) Get ¶

func (ta *TestApp) Get(path string) *TestResponse

Get performs a GET request and returns a TestResponse for assertions.

func (*TestApp) Post ¶

func (ta *TestApp) Post(path string, body any) *TestResponse

Post performs a POST request with a JSON body.

func (*TestApp) Put ¶

func (ta *TestApp) Put(path string, body any) *TestResponse

Put performs a PUT request with a JSON body.

func (*TestApp) Request ¶

func (ta *TestApp) Request(method, path string, body io.Reader) *TestRequest

Request creates a raw TestRequest for further customisation before Execute.

func (*TestRequest) Execute ¶

func (tr *TestRequest) Execute() *TestResponse

Execute sends the request and returns a TestResponse.

func (*TestRequest) WithBody ¶

func (tr *TestRequest) WithBody(body any) *TestRequest

WithBody sets the request body. Non-reader values are marshalled as JSON.

func (*TestRequest) WithHeader ¶

func (tr *TestRequest) WithHeader(key, value string) *TestRequest

WithHeader adds a header to the request.

func (*TestResponse) AssertBodyContains ¶

func (tr *TestResponse) AssertBodyContains(t testing.TB, substr string) *TestResponse

AssertBodyContains asserts the body contains the given substring.

func (*TestResponse) AssertHeader ¶

func (tr *TestResponse) AssertHeader(t testing.TB, key, expected string) *TestResponse

AssertHeader asserts a response header value. Chainable.

func (*TestResponse) AssertJSON ¶

func (tr *TestResponse) AssertJSON(t testing.TB, expected any) *TestResponse

AssertJSON asserts the response body equals expected after JSON normalisation. Compares decoded values (not raw strings) so key order and number types don't matter.

func (*TestResponse) AssertStatus ¶

func (tr *TestResponse) AssertStatus(t testing.TB, expected int) *TestResponse

AssertStatus asserts the HTTP status code. Chainable.

func (*TestResponse) Body ¶

func (tr *TestResponse) Body() string

Body returns the response body as a string.

func (*TestResponse) Close ¶

func (tr *TestResponse) Close()

Close is a no-op (API consistency).

func (*TestResponse) JSON ¶

func (tr *TestResponse) JSON(v any) error

JSON decodes the response body into v.

func (*TestResponse) Status ¶

func (tr *TestResponse) Status() int

Status returns the HTTP status code.