goplt/docs/adr/0015-error-bus-implementation.md

ADR-0015: Error Bus Implementation

Status

Accepted

Context

The platform needs a centralized error handling mechanism for:

• Capturing panics and errors
• Logging errors consistently
• Sending errors to external services (Sentry, etc.)
• Avoiding error handling duplication

Options considered:

1. Channel-based in-process bus - Simple, Go-idiomatic
2. Event bus integration - Use existing event bus
3. Direct logging - No bus, direct integration
4. External service integration - Direct to Sentry

Decision

Implement a channel-based error bus with pluggable sinks:

1. Error bus interface: type ErrorPublisher interface { Publish(err error) }
2. Channel-based implementation: Background goroutine consumes errors from channel
3. Pluggable sinks: Logger (always), Sentry (optional, Phase 6)
4. Panic recovery middleware: Automatically publishes panics to error bus

Rationale:

• Simple, idiomatic Go pattern
• Non-blocking error publishing (buffered channel)
• Decouples error capture from error handling
• Easy to add new sinks (Sentry, logging, metrics)
• Can be extended to use event bus later if needed

Consequences

Positive

• Centralized error handling
• Non-blocking (doesn't slow down request path)
• Easy to extend with new sinks
• Consistent error handling across the platform

Negative

• Additional goroutine overhead (minimal)
• Must ensure error bus doesn't become bottleneck

Implementation Notes

• Create pkg/errorbus/errorbus.go interface
• Implement internal/errorbus/channel_bus.go:
  • Buffered channel (e.g., size 100)
  • Background goroutine consumes errors
  • Multiple sinks (logger, optional Sentry)
• Add panic recovery middleware that publishes to bus
• Register in DI container as singleton
• Monitor channel size to detect error storms