ADR-004: Command Bus with Middleware Pipeline

Status	Date	Deciders
Accepted	2024-02-15	Core Team

Context

Command handling in CQRS applications involves cross-cutting concerns:

1. Validation: Ensure commands are valid before processing
2. Authorization: Check if user can execute command
3. Logging: Record command execution for debugging
4. Metrics: Track command performance
5. Idempotency: Prevent duplicate processing
6. Error Handling: Recover from panics gracefully
7. Correlation: Track requests across services

We need a flexible way to compose these concerns without polluting handler logic.

Decision

We will implement a Command Bus with a Middleware Pipeline pattern, inspired by HTTP middleware in Go.

Architecture

Command ──▶ Middleware 1 ──▶ Middleware 2 ──▶ ... ──▶ Handler
                │                 │                      │
                ▼                 ▼                      ▼
            (before)          (before)              (execute)
                │                 │                      │
                ◀─────────────────◀──────────────────────┘
            (after)           (after)

Middleware Interface

// MiddlewareFunc is a function that handles a command
type MiddlewareFunc func(ctx context.Context, cmd Command) (CommandResult, error)

// Middleware wraps a handler with additional behavior
type Middleware func(next MiddlewareFunc) MiddlewareFunc

Command Bus Implementation

type CommandBus struct {
    handlers   map[string]MiddlewareFunc
    middleware []Middleware
}

func (b *CommandBus) Use(m Middleware) {
    b.middleware = append(b.middleware, m)
}

func (b *CommandBus) Register(cmdType string, handler MiddlewareFunc) {
    b.handlers[cmdType] = handler
}

func (b *CommandBus) Dispatch(ctx context.Context, cmd Command) (CommandResult, error) {
    handler, ok := b.handlers[cmd.CommandType()]
    if !ok {
        return CommandResult{}, ErrHandlerNotFound
    }

    // Build middleware chain
    final := handler
    for i := len(b.middleware) - 1; i >= 0; i-- {
        final = b.middleware[i](final)
    }

    return final(ctx, cmd)
}

Built-in Middleware

// Validation
func ValidationMiddleware() Middleware {
    return func(next MiddlewareFunc) MiddlewareFunc {
        return func(ctx context.Context, cmd Command) (CommandResult, error) {
            if v, ok := cmd.(Validator); ok {
                if err := v.Validate(); err != nil {
                    return CommandResult{}, NewValidationError(err)
                }
            }
            return next(ctx, cmd)
        }
    }
}

// Recovery
func RecoveryMiddleware() Middleware {
    return func(next MiddlewareFunc) MiddlewareFunc {
        return func(ctx context.Context, cmd Command) (result CommandResult, err error) {
            defer func() {
                if r := recover(); r != nil {
                    err = fmt.Errorf("panic in command handler: %v", r)
                }
            }()
            return next(ctx, cmd)
        }
    }
}

// Logging
func LoggingMiddleware(logger Logger) Middleware {
    return func(next MiddlewareFunc) MiddlewareFunc {
        return func(ctx context.Context, cmd Command) (CommandResult, error) {
            start := time.Now()
            logger.Info("Dispatching command", "type", cmd.CommandType())

            result, err := next(ctx, cmd)

            logger.Info("Command completed",
                "type", cmd.CommandType(),
                "duration", time.Since(start),
                "error", err)

            return result, err
        }
    }
}

// Idempotency
func IdempotencyMiddleware(store IdempotencyStore) Middleware {
    return func(next MiddlewareFunc) MiddlewareFunc {
        return func(ctx context.Context, cmd Command) (CommandResult, error) {
            if idem, ok := cmd.(IdempotentCommand); ok {
                key := idem.IdempotencyKey()

                // Check for existing result
                if result, found := store.Get(ctx, key); found {
                    return result, nil
                }

                // Execute and store
                result, err := next(ctx, cmd)
                if err == nil {
                    store.Set(ctx, key, result, 24*time.Hour)
                }
                return result, err
            }
            return next(ctx, cmd)
        }
    }
}

Consequences

Positive

1. Separation of Concerns: Cross-cutting logic isolated from handlers
2. Composability: Mix and match middleware as needed
3. Testability: Test middleware independently
4. Reusability: Share middleware across commands
5. Familiar Pattern: Similar to HTTP middleware in Go
6. Ordering Control: Explicit middleware execution order

Negative

1. Debugging Complexity: Stack traces span multiple functions
2. Performance Overhead: Each middleware adds function calls
3. Order Sensitivity: Middleware order matters (can be confusing)

Neutral

1. Configuration: Need to configure middleware order explicitly
2. Context Usage: Heavy reliance on context for passing data

Middleware Order

Recommended middleware order:

bus := mink.NewCommandBus()

// 1. Recovery (outermost - catches panics)
bus.Use(mink.RecoveryMiddleware())

// 2. Metrics (track all attempts)
bus.Use(mink.MetricsMiddleware(metrics))

// 3. Tracing (create spans)
bus.Use(mink.TracingMiddleware(tracer))

// 4. Logging (log all attempts)
bus.Use(mink.LoggingMiddleware(logger))

// 5. Correlation ID (set correlation)
bus.Use(mink.CorrelationIDMiddleware(nil))

// 6. Timeout (prevent long-running commands)
bus.Use(mink.TimeoutMiddleware(30 * time.Second))

// 7. Validation (reject invalid commands early)
bus.Use(mink.ValidationMiddleware())

// 8. Authorization (check permissions)
bus.Use(AuthorizationMiddleware(authService))

// 9. Idempotency (deduplicate)
bus.Use(mink.IdempotencyMiddleware(store))

// 10. Retry (handle transient failures)
bus.Use(mink.RetryMiddleware(3, 100*time.Millisecond))

Alternatives Considered

Alternative 1: Decorator Pattern

Description: Wrap handlers with decorator classes.

Pros:

• Type-safe
• Clear interfaces

Rejected because:

• More verbose in Go
• Less flexible composition
• Doesn't match Go idioms

Alternative 2: Event-Based Hooks

Description: Emit events before/after command execution.

Pros:

• Decoupled
• Can add listeners dynamically

Rejected because:

• Less control over execution order
• Harder to short-circuit (validation)
• Complex error handling

Alternative 3: Aspect-Oriented Programming

Description: Use code generation for cross-cutting concerns.

Rejected because:

• Not idiomatic in Go
• Requires build-time tooling
• Magic behavior

Alternative 4: Direct Handler Composition

Description: Each handler manually calls validation, logging, etc.

Rejected because:

• Code duplication
• Easy to forget steps
• Hard to enforce consistency

References

• Go HTTP Middleware Pattern
• MediatR Pipeline Behaviors
• Axon Framework Interceptors