Documentation
¶
Overview ¶
Package hooks is the host-side engine behind the SDK's typed actions and filters (see pkg/sdk/hooks.go).
Actions are fire-and-forget: every callback runs in its own goroutine with panic recovery and a timeout derived from the server lifecycle context (the analytics dispatchListeners model). Filters run synchronously in ascending priority order; a failing filter leaves the value unchanged.
Index ¶
- Constants
- func OnAction[T any](h Registrar, a sdk.Action[T], priority int, fn func(context.Context, T))
- func OnFilter[T any](h Registrar, f sdk.Filter[T], priority int, ...)
- type Engine
- func (e *Engine) AddAction(name string, priority int, fn func(ctx context.Context, payload any))
- func (e *Engine) AddFilter(name string, priority int, fn func(ctx context.Context, v any) (any, error))
- func (e *Engine) Apply(ctx context.Context, name string, v any) any
- func (e *Engine) ApplyStrict(ctx context.Context, name string, v any) (any, error)
- func (e *Engine) Fire(caller context.Context, name string, payload any)
- func (e *Engine) For(plugin string) Registrar
- func (e *Engine) HasAction(name string) bool
- func (e *Engine) HasFilter(name string) bool
- func (e *Engine) RemovePlugin(plugin string)
- func (e *Engine) SetActionTimeout(d time.Duration)
- func (e *Engine) SetLifecycleContext(ctx context.Context)
- func (e *Engine) Wait()
- type Registrar
Constants ¶
const DefaultActionTimeout = 10 * time.Second
DefaultActionTimeout bounds each action callback.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine stores hook registrations and dispatches them.
func (*Engine) AddFilter ¶
func (e *Engine) AddFilter(name string, priority int, fn func(ctx context.Context, v any) (any, error))
AddFilter implements Registrar for host-owned (untagged) registrations.
func (*Engine) Apply ¶
Apply runs the filter chain for name over v and returns the result. A filter that errors, panics or changes the value's type is logged and skipped; the value stays as it was before that filter.
func (*Engine) ApplyStrict ¶
ApplyStrict is Apply, except a *sdk.Reject RETURNED by a filter (matched with errors.As) stops the chain and is returned to the caller (used by entity.before_save to reject a save). Any other error, and panics, are logged and skipped like in Apply: the filter's change is dropped.
func (*Engine) Fire ¶
Fire starts every callback registered for name, in ascending priority, each in its own goroutine, and returns immediately. Callbacks do not inherit the caller's cancellation: they run under the lifecycle context with a timeout, but see the caller's context values.
func (*Engine) For ¶
For returns a registrar that tags registrations with the plugin name so log lines identify the offender.
func (*Engine) RemovePlugin ¶
RemovePlugin drops every action and filter registered under the plugin name. The host calls it when a plugin's Wire fails so the half-wired plugin does not keep running callbacks.
func (*Engine) SetActionTimeout ¶
SetActionTimeout overrides the per-callback action timeout.
func (*Engine) SetLifecycleContext ¶
SetLifecycleContext sets the parent context of action callbacks; cancelling it (server shutdown) cancels in-flight callbacks.
type Registrar ¶
type Registrar interface {
AddAction(name string, priority int, fn func(ctx context.Context, payload any))
AddFilter(name string, priority int, fn func(ctx context.Context, v any) (any, error))
}
Registrar is the untyped hook registration surface. Lower priority runs first; ties run in registration order.
Source Files