Documentation
¶
Overview ¶
Package hooks provides WordPress-style actions, filters and events.
Contracts:
- Priority: lower prio runs first; equal prio runs in registration order.
- Do passes the payload to actions as-is (typed) and joins their errors.
- Apply threads v through filters; on the first error it stops and returns the last good value with the error.
- Emit marshals the payload to JSON and delivers it to the actions registered under the event name as a json.RawMessage, both when it runs async (via the "hooks.event" job when a queue is attached) and when it falls back to sync delivery. Emit never returns an error.
Index ¶
- Constants
- type ActionFunc
- type FilterFunc
- type Registry
- func (r *Registry) Action(name string, prio int, fn ActionFunc) Token
- func (r *Registry) Apply(ctx context.Context, name string, v any) (any, error)
- func (r *Registry) AttachQueue(q *jobs.Queue)
- func (r *Registry) Do(ctx context.Context, name string, payload any) error
- func (r *Registry) Emit(ctx context.Context, name string, payload any)
- func (r *Registry) Filter(name string, prio int, fn FilterFunc) Token
- func (r *Registry) Names() []string
- func (r *Registry) Remove(t Token) bool
- func (r *Registry) Subscriptions() map[string]int
- type Token
Constants ¶
const EventJobKind = "hooks.event"
EventJobKind is the job kind used to deliver Emit events asynchronously.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ActionFunc ¶
ActionFunc handles an action or event.
type FilterFunc ¶
FilterFunc transforms a value in a filter chain.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds actions and filters by name. It is safe for concurrent use.
func (*Registry) Action ¶
func (r *Registry) Action(name string, prio int, fn ActionFunc) Token
Action registers fn under name with priority prio and returns a token for Remove.
func (*Registry) AttachQueue ¶
AttachQueue makes Emit asynchronous and registers the "hooks.event" job handler on q.
func (*Registry) Do ¶
Do runs every action registered under name synchronously and returns their errors joined with errors.Join (nil when all succeed).
func (*Registry) Emit ¶
Emit publishes an event. With a queue attached it is persisted as a "hooks.event" job and delivered by a worker (retried on error); otherwise, or if enqueueing fails, it is delivered synchronously. Errors are logged.
Emit enqueues on its own pool connection: call it after a db.InTx transaction commits, never inside one (it would stall on the lock).
func (*Registry) Filter ¶
func (r *Registry) Filter(name string, prio int, fn FilterFunc) Token
Filter registers fn under name with priority prio and returns a token for Remove.
func (*Registry) Remove ¶
Remove unregisters the action or filter identified by t and reports whether it was registered. In-flight Do/Apply calls that already copied the chain still run it; later calls do not.
func (*Registry) Subscriptions ¶ added in v0.16.0
Subscriptions returns the number of action and filter subscribers per hook name (names with no subscriber are absent).
type Token ¶
type Token struct {
// contains filtered or unexported fields
}
Token identifies one Action or Filter registration; pass it to Remove on the registry that issued it (ids are per registry, so another registry may hold an unrelated registration with the same token). The zero Token identifies nothing.
Source Files