Documentation
¶
Overview ¶
Package engine provides trusted, statically linked Soro engine composition.
Index ¶
- Constants
- Variables
- func DeclareEvent[T any](host *MountContext, definition events.Definition[T]) error
- func Enqueue[T river.JobArgs](ctx context.Context, host *MountContext, args T, options ...jobs.Option) (*jobs.Result, error)
- func Provide[T any](host *MountContext, name string, capability T) error
- func ProvideAPI[T any](host *MountContext, api T) error
- func Publish[T any](ctx context.Context, host *MountContext, definition events.Definition[T], ...) error
- func RegisterJob[T river.JobArgs](host *MountContext, handler jobs.Handler[T]) (err error)
- func Require[T any](host *MountContext, dependencyID, name string) (T, error)
- func RequireAPI[T any](host *MountContext, dependencyID string) (T, error)
- func Subscribe[T any](host *MountContext, definition events.Definition[T], subscriber string, ...) error
- func UseAPI[T any](host *MountContext, engineID string) (T, bool, error)
- type APIProvider
- type Engine
- type Manifest
- type MigrationProvider
- type MountContext
- func (host *MountContext) API() *api.ScopedRouter
- func (host *MountContext) Config() *config.Config
- func (host *MountContext) Database() *database.DB
- func (host *MountContext) EngineID() string
- func (host *MountContext) Logger() *slog.Logger
- func (host *MountContext) Mail() *mail.Client
- func (host *MountContext) Observability() *observability.Provider
- func (host *MountContext) RegisterHealth(name string, check health.Check) error
- func (host *MountContext) RegisterHook(model any, stage lifecycle.Stage, priority int, handler lifecycle.Handler) error
- type Registry
- func (registry *Registry) Freeze() error
- func (registry *Registry) Frozen() bool
- func (registry *Registry) MigrationGroups() ([]migrate.Group, error)
- func (registry *Registry) MigrationPlan() (*migrate.Plan, error)
- func (registry *Registry) Migrations() ([]migrate.Migration, error)
- func (registry *Registry) Mount(ctx context.Context, host *MountContext) error
- func (registry *Registry) MountedManifests() []Manifest
- func (registry *Registry) MountedOrder() []string
- func (registry *Registry) Register(engines ...Engine) error
- type Services
Constants ¶
const DefaultAPIVersion = "v1"
Variables ¶
var ErrFrozen = errors.New("engine declarations are frozen")
Functions ¶
func DeclareEvent ¶
func DeclareEvent[T any](host *MountContext, definition events.Definition[T]) error
DeclareEvent establishes an engine-owned event topic before subscribers or publishers can use it.
func Enqueue ¶
func Enqueue[T river.JobArgs](ctx context.Context, host *MountContext, args T, options ...jobs.Option) (*jobs.Result, error)
Enqueue inserts an engine-owned typed River job. The job kind must use the engine's <engine-id>. namespace before it is forwarded to the shared client.
func Provide ¶
func Provide[T any](host *MountContext, name string, capability T) error
Provide exposes an engine-owned service to engines that declare the owner as a direct dependency. Capabilities are startup composition contracts: they must be provided during Mount and consumers retain the returned interface.
func ProvideAPI ¶
func ProvideAPI[T any](host *MountContext, api T) error
ProvideAPI publishes the engine's canonical typed capability surface. An engine should normally provide one API value whose methods expose narrow capability interfaces to dependents.
func Publish ¶
func Publish[T any](ctx context.Context, host *MountContext, definition events.Definition[T], payload T) error
Publish publishes an engine-owned typed event. Dependent engines can subscribe to this event through Subscribe without bypassing ownership checks.
func RegisterJob ¶
RegisterJob registers a typed River worker through an engine host.
func Require ¶
func Require[T any](host *MountContext, dependencyID, name string) (T, error)
Require resolves a typed capability from a direct engine dependency. The consumer owns T, so providers can expose concrete services without importing consumer packages.
func RequireAPI ¶
func RequireAPI[T any](host *MountContext, dependencyID string) (T, error)
RequireAPI resolves the canonical typed API of a direct engine dependency.
func Subscribe ¶
func Subscribe[T any](host *MountContext, definition events.Definition[T], subscriber string, handler events.Handler[T]) error
Subscribe registers a named typed event. The event definition may belong to this engine or to another engine's valid namespace; the subscriber is stored as <engine-id>/<subscriber>. The owning engine must declare the topic first.
Types ¶
type APIProvider ¶
APIProvider is the small API capability needed to create an engine scope. api.API implements it without exposing its mux or Huma API to engines.
type Engine ¶
type Engine interface {
Manifest() Manifest
Mount(context.Context, *MountContext) error
}
Engine is a statically linked application component. Mount is startup composition only; lifecycle start and stop are deliberately separate work.
type Manifest ¶
type Manifest struct {
ID string
Name string
Description string
Version string
APIVersion string
Dependencies []string
Integrations []string
DefaultPath string
}
Manifest is the stable identity and composition metadata for one engine. Dependencies are required; integrations only affect ordering when present. Dependency versions are intentionally not interpreted by this package.
type MigrationProvider ¶
MigrationProvider declares engine-owned migrations. Soro only collects these declarations; applying SQL remains an explicit migrate.Migrator operation.
type MountContext ¶
type MountContext struct {
// contains filtered or unexported fields
}
MountContext is the engine-facing service boundary. It intentionally does not contain or expose *soro.App.
func NewMountContext ¶
func NewMountContext(services Services) *MountContext
func (*MountContext) API ¶
func (host *MountContext) API() *api.ScopedRouter
func (*MountContext) Config ¶
func (host *MountContext) Config() *config.Config
func (*MountContext) Database ¶
func (host *MountContext) Database() *database.DB
func (*MountContext) EngineID ¶
func (host *MountContext) EngineID() string
func (*MountContext) Logger ¶
func (host *MountContext) Logger() *slog.Logger
func (*MountContext) Mail ¶
func (host *MountContext) Mail() *mail.Client
func (*MountContext) Observability ¶
func (host *MountContext) Observability() *observability.Provider
func (*MountContext) RegisterHealth ¶
func (host *MountContext) RegisterHealth(name string, check health.Check) error
RegisterHealth registers an engine-owned readiness check under <engine-id>/<name>.
func (*MountContext) RegisterHook ¶
func (host *MountContext) RegisterHook(model any, stage lifecycle.Stage, priority int, handler lifecycle.Handler) error
RegisterHook registers a model-specific lifecycle handler. Engine code is trusted and model ownership is not inferred from Go types; global hook registration is intentionally not part of the engine boundary.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry owns explicit engine declarations and one startup composition.
func NewRegistry ¶
NewRegistry creates an empty registry or records errors from the optional initial explicit engine list. Register can be used when callers need the registration error directly.
func (*Registry) MigrationGroups ¶
MigrationGroups returns validated, engine-prefixed declarations in dependency order. It only declares migrations and never executes SQL.
func (*Registry) MigrationPlan ¶
MigrationPlan returns the immutable migration plan for the registered engines. It only declares migrations and never executes SQL.
func (*Registry) Migrations ¶
Migrations returns a cloned flattened declaration in dependency order. It intentionally does not create a ledger or execute SQL.
func (*Registry) Mount ¶
func (registry *Registry) Mount(ctx context.Context, host *MountContext) error
Mount validates all declarations, prepares all engine scopes, and then runs each engine once in dependency order. No migration SQL is executed here.
func (*Registry) MountedManifests ¶
MountedManifests returns immutable composition metadata in dependency order.
func (*Registry) MountedOrder ¶
type Services ¶
type Services struct {
Config *config.Config
Database *database.DB
API APIProvider
Jobs *jobs.Client
Mail *mail.Client
Hooks *lifecycle.Registry
Health *health.Registry
Logger *slog.Logger
Observability *observability.Provider
Events *events.Bus
}
Services are the shared public Soro services made available to a mount. They are capabilities, not a replacement application container.
Source Files