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 DeclareSettings(host *MountContext, definitions ...settings.Definition) 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 Settings(host *MountContext) (*settings.Scope, 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
- func (host *MountContext) RegisterWebhook(definition webhooks.Definition) 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
- type WebhookProvider
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 DeclareSettings ¶
func DeclareSettings(host *MountContext, definitions ...settings.Definition) error
DeclareSettings records the settings this engine owns. Declaration is the contract: only the owning engine may declare or write its keys, so one engine's configuration never lands in another engine's migrations.
Settings must be declared during Mount. The registry freezes with the rest of the engine declarations, so nothing can introduce a key at runtime.
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 Settings ¶
func Settings(host *MountContext) (*settings.Scope, error)
Settings returns this engine's view of the settings store. The engine ID is bound, so an engine can only read and write keys it declared.
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.
func (*MountContext) RegisterWebhook ¶
func (host *MountContext) RegisterWebhook(definition webhooks.Definition) error
RegisterWebhook mounts an engine-owned public POST endpoint. Soro provides bounded exact request bytes and routing; the engine verifier and returned acceptor retain authentication, tenancy, durability, and domain ownership.
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
Webhooks WebhookProvider
Jobs *jobs.Client
Mail *mail.Client
Hooks *lifecycle.Registry
Health *health.Registry
Logger *slog.Logger
Observability *observability.Provider
Events *events.Bus
Settings *settings.Store
}
Services are the shared public Soro services made available to a mount. They are capabilities, not a replacement application container.
Source Files