actor

type Actor interface {
	// Send enqueues a message for processing. Blocks until the message
	// is enqueued, the context is canceled, or the actor is stopped.
	Send(ctx context.Context, msg Envelope) error
	// Pause stops message processing until Resume or Step is called.
	Pause() error
	// Resume continues normal message processing after a Pause.
	Resume() error
	// Step processes exactly one message when paused.
	Step() error
	// Done returns a channel that is closed when the actor stops.
	Done() <-chan struct{}
}

type ActorMetrics interface {
	// Message handling
	MessageDuration(msgType string) metrics.Timer
	MessageProcessed(msgType string, success bool)
	MessagePanic(msgType string)

	// Mailbox
	MailboxDepth(actorID string, depth int)

	// Scheduler
	SchedulerInflight(actorID string, count int)
	SchedulerTaskDuration() metrics.Timer
	SchedulerTaskCompleted(success bool)
}

type BaseActor struct {
	// contains filtered or unexported fields
}

type Envelope struct {
	Type  string     // Message type name for handler dispatch
	Data  []byte     // JSON-encoded message payload
	Reply chan Reply // Channel for sending the response
}

type HandleOption func(*HandleOpts)

type HandleOpts struct {
	// MessageType overrides the default type name derived from the Go type.
	MessageType string
	// InitFunc is called during actor initialization.
	InitFunc HandlerInitFunc
}

type HandlerCtx interface {
	context.Context
	// Log returns the actor's logger.
	Log() *slog.Logger
	// Schedule runs f asynchronously outside the actor's mailbox processing.
	// Use for I/O-bound or long-running operations that shouldn't block message handling.
	Schedule(f scheduleFunc)
	// Request sends a request to another actor and waits for the response.
	// Returns [ErrSelfRequest] if the request would be sent to the same actor.
	Request(ctx context.Context, req any) (res any, err error)
	// contains filtered or unexported methods
}

type HandlerInitFunc func(hc HandlerCtx) error

type HandlerRegistrar interface {
	// Register adds a handler for a message type.
	Register(msgType string, f func() any, handle MsgHandlerFunc, init HandlerInitFunc)
}

type HandlerRegistration func(registrar HandlerRegistrar)

type MsgHandlerFunc func(hc HandlerCtx, msg any) (any, error)

type OnPanic func(recovered any, stack []byte, msg any)

type Options struct {
	// MailboxSize is the capacity of the message queue. Defaults to 1024.
	MailboxSize int
	// ControlSize is the capacity of the control channel. Defaults to 16.
	ControlSize int
	// Context is the parent context for the actor's lifecycle.
	Context context.Context
	// Logger for actor operations. Defaults to slog.Default().
	Logger *slog.Logger
	// OnPanic is called when a handler panics. Defaults to logging the panic.
	OnPanic OnPanic
	// MaxConcurrentTasks caps the number of tasks run via HandlerCtx.Schedule.
	// If 0 or negative, defaults to 32.
	MaxConcurrentTasks int
	// Metrics for actor instrumentation. If nil, a no-op implementation is used.
	Metrics ActorMetrics
}

type RawHandler interface {
	// InitHandler is called once when the actor starts, before processing messages.
	InitHandler(hc HandlerCtx) error
	// HandleMessage processes a message and returns a response.
	HandleMessage(hc HandlerCtx, mt string, data []byte) (any, error)
}

type Reply struct {
	Result any   // Handler return value (nil for fire-and-forget)
	Error  error // Handler error, if any
}

type Scheduler interface {
	// Schedule queues a function for asynchronous execution.
	Schedule(f scheduleFunc)
	// Wait blocks until all in-flight tasks complete.
	Wait()
}

type State[T any] struct {
	// contains filtered or unexported fields
}

type StateOp[T any] func(*T)

type StateReadOp[T any, R any] func(*T) R

type StateTask[T any] interface {
	// contains filtered or unexported methods
}

type TypedHandlerRegistry struct {
	// contains filtered or unexported fields
}