package lazyaddon ¶
import "golazy.dev/lazyaddon"Functions ¶
func MustOn[T any] ¶
MustOn is On with panic-on-error semantics for use from init functions.
func MustOn[T any](registration Registration, hook Hook[T], options CallbackOptions, callback func(*T) error)func On[T any] ¶
On registers callback for hook in the hook's catalog. Registration proves which add-on owns the callback; callbacks run only for application scopes that select that add-on.
func On[T any](registration Registration, hook Hook[T], options CallbackOptions, callback func(*T) error) errorfunc OnIn[T any] ¶
OnIn registers a callback in an explicit catalog.
func OnIn[T any](catalog *Catalog, registration Registration, hook Hook[T], options CallbackOptions, callback func(*T) error) errorfunc Provide[T any] ¶
Provide stores value in scope. A capability has exactly one provider per application scope, and only its defining add-on registration may provide it.
func Provide[T any](scope *Scope, registration Registration, capability Capability[T], value T) errorfunc Require[T any] ¶
Require returns a capability value from scope.
func Require[T any](scope *Scope, capability Capability[T]) (T, error)func Run[T any] ¶
Run executes active callbacks for hook in deterministic Before/After order.
func Run[T any](scope *Scope, hook Hook[T], event *T) errorTypes ¶
type CallbackOptions ¶
CallbackOptions identifies and orders one hook callback.
type CallbackOptions struct {
ID string
Before []string
After []string
}type Capability ¶
Capability is a typed, versioned value exchanged by add-ons in one application scope.
type Capability[T any] struct {
// contains filtered or unexported fields
}func DefineCapability[T any] ¶
DefineCapability defines a capability owned by registration in its catalog.
func DefineCapability[T any](registration Registration, id string, version uint) Capability[T]func DefineCapabilityIn[T any] ¶
DefineCapabilityIn defines a capability owned by registration in catalog.
func DefineCapabilityIn[T any](catalog *Catalog, registration Registration, id string, version uint) Capability[T]func (capability Capability[T]) ID ¶
ID returns the stable capability ID.
func (capability Capability[T]) ID() stringfunc (capability Capability[T]) Version ¶
Version returns the capability contract version.
func (capability Capability[T]) Version() uinttype Catalog ¶
Catalog stores add-on definitions, hook contracts, and callbacks. Registrations are process-wide by default, while resolved scopes are immutable and application-local.
type Catalog struct {
// contains filtered or unexported fields
}func NewCatalog ¶
NewCatalog creates an empty catalog. Most add-on packages use the default process catalog through MustRegister and On; explicit catalogs are useful in tests and applications that need complete registry isolation.
func NewCatalog() *Catalogfunc (catalog *Catalog) Register ¶
Register registers one add-on definition and returns its opaque registration.
func (catalog *Catalog) Register(definition Definition) (Registration, error)func (catalog *Catalog) RegisterPackage ¶
RegisterPackage registers all definitions in pkg and returns their opaque registrations in manifest order.
func (catalog *Catalog) RegisterPackage(pkg Package) ([]Registration, error)func (catalog *Catalog) Resolve ¶
Resolve validates and resolves selection, including required dependencies.
func (catalog *Catalog) Resolve(selection Selection) (*Scope, error)type Definition ¶
Definition describes one add-on exposed by an add-on package.
type Definition struct {
ID string
Version string
Description string
// Requires accepts id@version. A bare ID is normalized to this
// definition's Version, which is convenient for add-ons in one package.
Requires []string
Optional []string
Conflicts []string
}type Hook ¶
Hook is a typed lifecycle contract. Its ID and version form the stable cross-package identity; T is checked when callbacks are resolved.
type Hook[T any] struct {
// contains filtered or unexported fields
}func DefineHook[T any] ¶
DefineHook defines a hook contract in the default process catalog.
func DefineHook[T any](id string, version uint) Hook[T]func DefineHookIn[T any] ¶
DefineHookIn defines a hook contract in catalog.
func DefineHookIn[T any](catalog *Catalog, id string, version uint) Hook[T]func (hook Hook[T]) ID ¶
ID returns the stable hook ID.
func (hook Hook[T]) ID() stringfunc (hook Hook[T]) Version ¶
Version returns the hook contract version.
func (hook Hook[T]) Version() uinttype Manifest ¶
Manifest is the runtime-relevant subset of lazyaddon.toml. Distribution and installer-specific contribution metadata remains available in Raw.
type Manifest struct {
Schema int
Package PackageInfo
Addons []Definition
Raw []byte
Digest string
}func MustParseManifest ¶
MustParseManifest parses data and panics on failure.
func MustParseManifest(data []byte) Manifestfunc ParseManifest ¶
ParseManifest parses the core package and add-on dependency declarations from lazyaddon.toml without adding a TOML dependency to application binaries.
func ParseManifest(data []byte) (Manifest, error)func (manifest Manifest) Validate ¶
Validate validates core manifest identity and dependency declarations.
func (manifest Manifest) Validate() errortype Package ¶
Package registers all add-ons declared by one lazyaddon.toml manifest.
type Package struct {
Manifest Manifest
}type PackageInfo ¶
PackageInfo identifies one versioned add-on distribution.
type PackageInfo struct {
ID string
Version string
}type Registration ¶
Registration is an opaque proof that an add-on definition was registered by a catalog. Add-on packages should keep their Registration private and use it when defining capabilities and registering callbacks.
A Registration may be copied, but its zero value is invalid.
type Registration struct {
// contains filtered or unexported fields
}func MustRegister ¶
MustRegister registers every definition in pkg's manifest in the default process catalog, returns their opaque registrations, and panics on invalid or duplicate definitions.
func MustRegister(pkg Package) []Registrationfunc MustRegisterDefinition ¶
MustRegisterDefinition registers one definition in the default process catalog, returns its opaque registration, and panics on failure.
func MustRegisterDefinition(definition Definition) Registrationfunc (registration Registration) ID ¶
ID returns the registered add-on ID.
func (registration Registration) ID() stringtype Scope ¶
Scope is an immutable resolved add-on graph for one application.
type Scope struct {
// contains filtered or unexported fields
}func Resolve ¶
Resolve resolves selection against the default process catalog.
func Resolve(selection Selection) (*Scope, error)func (scope *Scope) Addons ¶
Addons returns selected and required add-on IDs in dependency-first order.
func (scope *Scope) Addons() []stringfunc (scope *Scope) Config ¶
Config returns a copy of the selected add-on's non-secret configuration.
func (scope *Scope) Config(id string) map[string]stringfunc (scope *Scope) Has ¶
Has reports whether id is active in this application scope.
func (scope *Scope) Has(id string) boolfunc (scope *Scope) HasCallbacks ¶
HasCallbacks reports whether at least one active add-on registered a callback for hook. It lets lifecycle owners avoid allocating optional subsystem state when no selected add-on contributes to that phase.
func (scope *Scope) HasCallbacks(hookID string) booltype Selection ¶
Selection is the set of add-ons explicitly selected by an application. Required add-ons are resolved automatically.
type Selection struct {
Addons []Use
}func Select ¶
Select constructs a Selection from add-on IDs.
func Select(ids ...string) Selectiontype Use ¶
Use selects one add-on for an application. Version is optional for manual selections; generated installer wiring always sets it from addons.toml.
type Use struct {
ID string
Version string
Config map[string]string
}
Package lazyaddon provides manifest-driven, per-application add-on selection, typed lifecycle hooks, and typed capabilities.
Add-on packages normally register their manifest during package initialization. A lifecycle owner defines a versioned hook, and callbacks run only for application scopes that select their owning add-on:
type Routes struct { Names []string } routes := lazyaddon.DefineHook[Routes]("example.com/app/routes", 1) seo := lazyaddon.MustRegisterDefinition(lazyaddon.Definition{ ID: "seo", Version: "v1.0.0", }) lazyaddon.MustOn(seo, routes, lazyaddon.CallbackOptions{ID: "routes"}, func(event *Routes) error { event.Names = append(event.Names, "sitemap") return nil }) scope, err := lazyaddon.Resolve(lazyaddon.Select("seo")) if err != nil { return err } event := Routes{} if err := lazyaddon.Run(scope, routes, &event); err != nil { return err }Resolved scopes are immutable and application-local. Capabilities exchange typed, versioned values between selected add-ons without process-global state. Use.Config is intended only for committed, non-secret configuration. Normal GoLazy applications let lazy add generate the imports and lazyapp.Config.Addons selection instead of assembling this wiring manually.