engine

package
v0.8.9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: Apache-2.0 Imports: 8 Imported by: 1

Documentation

Overview

Package engine owns the Engine — the central command router of the CQRS architecture. The Engine receives Commands from controllers, resolves the correct Domain from the Registry by GVK, and dispatches Handle. It is the only component that bridges the controller layer and the domain layer.

The Engine supports two execution modes:

  1. Synchronous (default) — Execute() dispatches directly to the Domain and returns the error to the caller (controller-runtime requeue path). This is the mode used in all current deployments.

  2. Async worker pool (optional) — Queue() enqueues Commands into a buffered channel; a configurable pool of goroutines drains it via workerLoop. This mode is opt-in via SetWorkers() and StartWorkers(), intended for high- throughput production deployments where controller goroutines should not block on Domain execution.

When no workers are configured (workers == 0), Queue() falls through to Execute() so callers need not distinguish between modes.

Index

Constants

This section is empty.

Variables

View Source
var ErrCircuitOpen = errors.New("circuit breaker is open for target GVK")

ErrCircuitOpen is returned when a pre-emptive circuit breaker trips for a given GVK or command.

Functions

This section is empty.

Types

type CircuitBreaker added in v0.8.8

type CircuitBreaker interface {
	// Allow returns true if the command execution is permitted, false if tripped.
	Allow(cmd command.Command) bool
}

CircuitBreaker defines the signature for pre-emptive circuit breaker checks.

type Engine

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

Engine routes Commands to the correct Domain and supports both synchronous and async execution modes. A single Engine instance is shared across all controllers registered with the manager.

func NewEngine

func NewEngine(registry *registry.Registry, logger logr.Logger) *Engine

NewEngine constructs an Engine bound to the given Registry and logger. The engine starts in synchronous mode (workers == 0). Call SetWorkers and StartWorkers to enable async execution.

func (*Engine) Execute

func (e *Engine) Execute(ctx context.Context, cmd command.Command) error

Execute dispatches a Command synchronously to the Domain registered for cmd.GVK. Returns an error if no Domain is registered, if the circuit breaker is open, or if Handle fails. The error propagates back to controller-runtime as a requeue signal.

func (*Engine) Queue

func (e *Engine) Queue(ctx context.Context, cmd command.Command) error

Queue enqueues a Command for async processing when workers > 0, or falls through to Execute when in synchronous mode. Blocks if the queue is full and returns ctx.Err() if the context is cancelled while waiting.

func (*Engine) SetCircuitBreaker added in v0.8.8

func (e *Engine) SetCircuitBreaker(cb CircuitBreaker)

SetCircuitBreaker registers a pre-emptive circuit breaker implementation to protect dispatch paths.

func (*Engine) SetWorkers

func (e *Engine) SetWorkers(n int)

SetWorkers configures the async worker pool size. Must be called before StartWorkers. Zero (default) keeps the Engine in synchronous mode.

func (*Engine) StartWorkers

func (e *Engine) StartWorkers()

StartWorkers spawns the configured number of async worker goroutines. No-op when workers == 0. Safe to call once at manager startup after SetWorkers.

func (*Engine) StopWorkers

func (e *Engine) StopWorkers(timeout time.Duration)

StopWorkers signals all worker goroutines to exit and waits for them to drain, up to the given timeout. Called during manager shutdown. No-op when workers == 0. Safe to call more than once.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL