API Reference
actor
import "github.com/danmestas/dagnats/actor"actor/actor.go The actor package provides a lightweight actor runtime for DagNats. Actors are goroutines with channel mailboxes, supervised by parent actors. Pure Go — no NATS imports. NATS integration lives in engine/.
Index
- Variables
- type Actor
- type Address
- type AllForOne
- type Context
- type Directive
- type Lifecycle
- type Message
- type OneForOne
- type RestartScope
- type RestartTracker
- type Runtime
- type SpawnOption
- type SupervisionStrategy
Variables
ErrActorNotFound is returned when sending to an unknown address.
var ErrActorNotFound = fmt.Errorf("actor: not found")ErrAlreadyExists is returned when spawning at an occupied address.
var ErrAlreadyExists = fmt.Errorf("actor: already exists")ErrMailboxFull is returned when an actor’s mailbox is at capacity.
var ErrMailboxFull = fmt.Errorf("actor: mailbox full")type Actor
Actor is the interface all actors implement. Receive processes one message at a time — the runtime guarantees sequential delivery.
type Actor interface {
// Receive processes a single message. Returning an error
// triggers the supervision strategy.
Receive(ctx *Context, msg Message) error
}type Address
Address uniquely identifies an actor within the runtime.
type Address struct {
Type string // e.g. "workflow", "worker", "tool"
ID string // e.g. run ID, worker ID
}func (Address) String
func (a Address) String() stringString formats the address as “type.id” for logging and map keys.
type AllForOne
AllForOne restarts all siblings when any child fails. Useful when children have interdependent state.
type AllForOne struct {
// Decider maps errors to directives. If nil, defaults to Restart.
Decider func(error) Directive
}func (*AllForOne) Decide
func (s *AllForOne) Decide(err error) DirectiveDecide returns the directive for the given error.
func (*AllForOne) RestartScope
func (s *AllForOne) RestartScope() RestartScopeRestartScope returns RestartAll — all siblings restart.
type Context
Context provides services to a running actor.
type Context struct {
// contains filtered or unexported fields
}func (*Context) Self
func (c *Context) Self() AddressSelf returns this actor’s address.
func (*Context) Send
func (c *Context) Send(to Address, payload any) errorSend delivers a message to another actor’s mailbox. Returns an error if the target actor is not found or its mailbox is full.
func (*Context) Spawn
func (c *Context) Spawn(addr Address, actor Actor, opts ...SpawnOption) errorSpawn creates a child actor supervised by this actor.
type Directive
Directive tells a supervisor how to handle a failed child.
type Directive intconst (
Restart Directive = iota // Restart the failed actor
Stop // Stop the actor permanently
Escalate // Escalate failure to parent
Resume // Ignore the error, continue
)func (Directive) String
func (d Directive) String() stringString returns the lowercase name of the directive.
type Lifecycle
Lifecycle extends Actor with optional startup/shutdown hooks. Actors that don’t need hooks can implement Actor alone.
type Lifecycle interface {
// PreStart runs before the actor begins receiving messages.
// Errors here trigger supervision (the actor never starts).
PreStart(ctx *Context) error
// PostStop runs after the actor stops receiving messages.
// Used for cleanup. Errors are logged but not supervised.
PostStop(ctx *Context)
}type Message
Message is the envelope delivered to an actor’s mailbox.
type Message struct {
From Address
Payload any
}type OneForOne
OneForOne restarts only the failed child. The default strategy.
type OneForOne struct {
// Decider maps errors to directives. If nil, defaults to Restart.
Decider func(error) Directive
}func (*OneForOne) Decide
func (s *OneForOne) Decide(err error) DirectiveDecide returns the directive for the given error.
func (*OneForOne) RestartScope
func (s *OneForOne) RestartScope() RestartScopeRestartScope returns RestartOne — only the failed child restarts.
type RestartScope
RestartScope controls which actors restart on a failure.
type RestartScope intconst (
RestartOne RestartScope = iota // Only the failed actor
RestartAll // All children of the supervisor
)type RestartTracker
RestartTracker enforces a bounded number of restarts within a sliding time window. If the limit is exceeded, the tracker signals that the actor should be stopped or escalated.
type RestartTracker struct {
// contains filtered or unexported fields
}func NewRestartTracker
func NewRestartTracker(limit int, window time.Duration) *RestartTrackerNewRestartTracker creates a tracker allowing limit restarts within the given window. Panics if limit < 1.
func (*RestartTracker) Allow
func (tr *RestartTracker) Allow() boolAllow returns true if a restart is permitted. It prunes expired entries, then checks the count against the limit. If allowed, it records the restart time.
type Runtime
Runtime manages actor lifecycle, message delivery, and supervision. All methods are safe for concurrent use.
type Runtime struct {
// contains filtered or unexported fields
}func NewRuntime
func NewRuntime() *RuntimeNewRuntime creates an empty actor runtime.
func (*Runtime) Send
func (r *Runtime) Send(to Address, msg Message) errorSend delivers a message to an actor’s mailbox. Returns ErrActorNotFound if the address is unknown, ErrMailboxFull if the channel is at capacity.
func (*Runtime) Spawn
func (r *Runtime) Spawn(addr Address, actor Actor, opts ...SpawnOption) errorSpawn starts a new root-level actor. Use Context.Spawn for supervised child actors. Returns ErrAlreadyExists if the address is taken.
func (*Runtime) Stop
func (r *Runtime) Stop(addr Address) errorStop gracefully terminates an actor and its children.
func (*Runtime) StopAll
func (r *Runtime) StopAll()StopAll terminates all actors. Used in defer for cleanup.
type SpawnOption
SpawnOption configures actor spawning.
type SpawnOption func(*spawnOptions)func WithMailboxSize
func WithMailboxSize(size int) SpawnOptionWithMailboxSize sets the buffered channel capacity.
func WithSupervision
func WithSupervision(s SupervisionStrategy) SpawnOptionWithSupervision sets the strategy for this actor’s children.
type SupervisionStrategy
SupervisionStrategy decides how to handle a failed child actor. The runtime calls Decide when an actor’s Receive returns an error.
type SupervisionStrategy interface {
// Decide returns the directive for handling the failure.
Decide(err error) Directive
// RestartScope controls whether a failure restarts one child
// or all siblings under the same supervisor.
RestartScope() RestartScope
}Generated by gomarkdoc