effect

Documentation

Overview

Package effect runs declarative actions described by world.Action.

Effects are the runtime side of Kiln's "no Go code from the agent" stance: every behavior the agent can author — validators, hooks, computed defaults, audit emits — is one of a closed set of action kinds whose parameters are themselves expressions. effect.Run is the single dispatcher.

Index

• func Run(ctx context.Context, a world.Action, scope Scope) error
• func RunHook(ctx context.Context, h *world.Hook, scope Scope) error
• type AuditRecord
• type EventRecord
• type Response
  • func Resolve(ctx context.Context, a world.Action, scope Scope) (Response, error)
  • func (r Response) WriteTo(w http.ResponseWriter) error
• type Scope

Functions

func Run

func Run(ctx context.Context, a world.Action, scope Scope) error

Run dispatches an action. Errors from the action propagate; for validate-style actions, the error is the validation message.

func RunHook

func RunHook(ctx context.Context, h *world.Hook, scope Scope) error

RunHook gates a hook on its Condition (if any) and then runs its Action. Returns nil if the condition is false (no error, no side effect).

Types

type AuditRecord

type AuditRecord struct {
	Channel string
	Message string
}

AuditRecord is what ActionAudit produces.

type EventRecord

type EventRecord struct {
	Topic string
	Data  any
}

EventRecord is what ActionEmitEvent produces.

type Response

type Response struct {
	Status int
	Body   any
}

Response describes the effect of a handler-style action (e.g. respond_json). It's separate from the side-effect Run path so routes have a clean "produce a response" surface independent of validate/set/audit.

func Resolve

func Resolve(ctx context.Context, a world.Action, scope Scope) (Response, error)

Resolve runs an action that's expected to produce a Response. Currently supported kinds: ActionRespondJSON. ActionNoop returns 204.

func (Response) WriteTo

func (r Response) WriteTo(w http.ResponseWriter) error

WriteTo writes r as JSON to w.

type Scope

type Scope struct {
	Entity any
	Ctx    map[string]any
	Result any
	Audit  func(AuditRecord)
	Emit   func(EventRecord)
}

Scope is the runtime context an action sees. Entity is the data being operated on (typically map[string]any for create/update, string id for delete). Ctx exposes request-derived values (user, tenant, request). Audit and Emit are hooks the host wires for ActionAudit / ActionEmitEvent.