goplt/docs/content/stories/epic1/1.4-error-handling.md

Story 1.4: Error Handling and Error Bus

Metadata

• Story ID: 1.4
• Title: Error Handling and Error Bus
• Epic: 1 - Core Kernel & Infrastructure
• Status: Completed
• Priority: High
• Estimated Time: 4-5 hours
• Dependencies: 1.1, 1.3

Goal

Implement centralized error handling with an error bus that captures, logs, and optionally reports all application errors.

Description

This story creates a complete error handling system with an error bus that captures all errors, logs them with context, and provides a foundation for future error reporting integrations (like Sentry).

Deliverables

1. Error Bus Interface (pkg/errorbus/errorbus.go)

• ErrorPublisher interface with Publish(err error) method
• Error context support
• Error categorization

2. Channel-Based Error Bus (internal/errorbus/channel_bus.go)

• Buffered channel for error publishing
• Background goroutine consumes errors
• Logs all errors with context (request ID, user ID, etc.)
• Error aggregation
• Optional: Sentry integration placeholder (Epic 6)

3. Panic Recovery Middleware

• Recovers from panics in HTTP handlers
• Publishes panics to error bus
• Returns appropriate HTTP error responses (500)
• Preserves error context

4. Integration

• Integration with DI container
• Integration with HTTP middleware stack
• Integration with logger

Implementation Steps

1. Create Error Bus Interface

   • Create pkg/errorbus/errorbus.go
   • Define ErrorPublisher interface

2. Implement Channel-Based Error Bus

   • Create internal/errorbus/channel_bus.go
   • Implement buffered channel
   • Implement background consumer
   • Add error logging

3. Create Panic Recovery Middleware

   • Create middleware for Gin
   • Recover from panics
   • Publish to error bus
   • Return error responses

4. Integrate with DI

   • Create provider function
   • Register in container

5. Integrate with HTTP Server

   • Add panic recovery middleware
   • Test error handling

Acceptance Criteria

• Errors are captured and logged via error bus
• Panics are recovered and logged
• HTTP handlers return proper error responses
• Error bus is injectable via DI
• Error context (request ID, user ID) is preserved
• Background error consumer works correctly
• Error bus doesn't block request handling

Related ADRs

• ADR-0015: Error Bus Implementation
• ADR-0026: Error Reporting Service

Implementation Notes

• Use buffered channels to prevent blocking
• Background goroutine should handle errors asynchronously
• Preserve error context (stack traces, request IDs)
• Consider error rate limiting in future
• Placeholder for Sentry integration in Epic 6

Testing

# Test error bus
go test ./internal/errorbus/...

# Test panic recovery
# Trigger panic in handler and verify recovery

Files to Create/Modify

• pkg/errorbus/errorbus.go - Error bus interface
• internal/errorbus/channel_bus.go - Error bus implementation
• internal/server/middleware.go - Panic recovery middleware
• internal/di/providers.go - Add error bus provider