ADR-009: Sentinel Errors with Typed Wrappers

Status	Date	Deciders
Accepted	2024-01-20	Core Team

Context

Error handling in Go requires deliberate design. go-mink needs to:

1. Identify Error Types: Let callers check for specific errors
2. Provide Context: Include relevant details (stream ID, version)
3. Support Wrapping: Work with errors.Is and errors.As
4. Be Idiomatic: Follow Go conventions

Common approaches:

• Sentinel errors (var ErrNotFound = errors.New("not found"))
• Typed errors (type NotFoundError struct{})
• Error codes
• Multiple return values

Decision

We will use Sentinel Errors for error type identification combined with Typed Error Wrappers for additional context.

Sentinel Errors

Define package-level sentinel errors for each error category:

// errors.go
package mink

import "errors"

// Sentinel errors for error type identification
var (
    // ErrConcurrencyConflict indicates version mismatch during append
    ErrConcurrencyConflict = errors.New("mink: concurrency conflict")

    // ErrStreamNotFound indicates the stream does not exist
    ErrStreamNotFound = errors.New("mink: stream not found")

    // ErrEventNotFound indicates the event does not exist
    ErrEventNotFound = errors.New("mink: event not found")

    // ErrAggregateNotFound indicates the aggregate does not exist
    ErrAggregateNotFound = errors.New("mink: aggregate not found")

    // ErrValidation indicates command validation failed
    ErrValidation = errors.New("mink: validation error")

    // ErrHandlerNotFound indicates no handler registered for command
    ErrHandlerNotFound = errors.New("mink: handler not found")

    // ErrProjectionFailed indicates projection processing failed
    ErrProjectionFailed = errors.New("mink: projection failed")

    // ErrSerializationFailed indicates event serialization failed
    ErrSerializationFailed = errors.New("mink: serialization failed")
)

Typed Error Wrappers

Provide typed errors with context that wrap sentinels:

// ConcurrencyError provides details about a concurrency conflict
type ConcurrencyError struct {
    StreamID        string
    ExpectedVersion int64
    ActualVersion   int64
}

func (e *ConcurrencyError) Error() string {
    return fmt.Sprintf("mink: concurrency conflict on stream %s: expected version %d, got %d",
        e.StreamID, e.ExpectedVersion, e.ActualVersion)
}

// Is implements errors.Is support
func (e *ConcurrencyError) Is(target error) bool {
    return target == ErrConcurrencyConflict
}

// ValidationError provides details about validation failures
type ValidationError struct {
    Field   string
    Message string
    Value   interface{}
}

func (e *ValidationError) Error() string {
    if e.Field != "" {
        return fmt.Sprintf("mink: validation error on field %s: %s", e.Field, e.Message)
    }
    return fmt.Sprintf("mink: validation error: %s", e.Message)
}

func (e *ValidationError) Is(target error) bool {
    return target == ErrValidation
}

// NotFoundError provides details about missing resources
type NotFoundError struct {
    ResourceType string
    ResourceID   string
}

func (e *NotFoundError) Error() string {
    return fmt.Sprintf("mink: %s not found: %s", e.ResourceType, e.ResourceID)
}

func (e *NotFoundError) Is(target error) bool {
    switch e.ResourceType {
    case "stream":
        return target == ErrStreamNotFound
    case "event":
        return target == ErrEventNotFound
    case "aggregate":
        return target == ErrAggregateNotFound
    default:
        return false
    }
}

Error Checking

// Using errors.Is for type checking
if errors.Is(err, mink.ErrConcurrencyConflict) {
    // Handle retry logic
}

// Using errors.As for accessing details
var concErr *mink.ConcurrencyError
if errors.As(err, &concErr) {
    log.Printf("Conflict on stream %s: expected %d, got %d",
        concErr.StreamID, concErr.ExpectedVersion, concErr.ActualVersion)
}

// Convenience functions
if mink.IsConcurrencyError(err) {
    // Same as errors.Is(err, ErrConcurrencyConflict)
}

Convenience Functions

// Helper functions for common checks
func IsConcurrencyError(err error) bool {
    return errors.Is(err, ErrConcurrencyConflict)
}

func IsNotFoundError(err error) bool {
    return errors.Is(err, ErrStreamNotFound) ||
           errors.Is(err, ErrEventNotFound) ||
           errors.Is(err, ErrAggregateNotFound)
}

func IsValidationError(err error) bool {
    return errors.Is(err, ErrValidation)
}

func IsRetryable(err error) bool {
    return IsConcurrencyError(err)
}

Creating Errors

// Factory functions for creating errors
func NewConcurrencyError(streamID string, expected, actual int64) error {
    return &ConcurrencyError{
        StreamID:        streamID,
        ExpectedVersion: expected,
        ActualVersion:   actual,
    }
}

func NewValidationError(field, message string) error {
    return &ValidationError{
        Field:   field,
        Message: message,
    }
}

func NewStreamNotFoundError(streamID string) error {
    return &NotFoundError{
        ResourceType: "stream",
        ResourceID:   streamID,
    }
}

Consequences

Positive

1. Simple Checks: errors.Is(err, ErrConcurrencyConflict) is easy
2. Rich Details: Typed errors provide context
3. Idiomatic: Follows Go 1.13+ error handling
4. Wrapping Support: Works with error chains
5. Discoverability: Sentinels are easy to find in docs

Negative

1. Dual System: Both sentinels and types to maintain
2. Is() Implementation: Must remember to implement Is()
3. Documentation: Need to document both forms

Neutral

1. Migration: Old code checking error strings still works via Error()
2. Testing: Can test both sentinel and typed error

Error Handling Patterns

In Handlers

func (h *Handler) Handle(ctx context.Context, cmd Command) (CommandResult, error) {
    // Validation errors - return typed error
    if cmd.CustomerID == "" {
        return CommandResult{}, mink.NewValidationError("customerID", "required")
    }

    // Domain errors - wrap with context
    if err := aggregate.DoSomething(); err != nil {
        return CommandResult{}, fmt.Errorf("failed to process: %w", err)
    }

    // Infrastructure errors - wrap and return
    if err := store.SaveAggregate(ctx, aggregate); err != nil {
        return CommandResult{}, fmt.Errorf("failed to save: %w", err)
    }

    return mink.NewSuccessResult(aggregate.ID(), aggregate.Version()), nil
}

In API Layer

func handleError(w http.ResponseWriter, err error) {
    switch {
    case mink.IsConcurrencyError(err):
        http.Error(w, "Resource was modified, please retry", http.StatusConflict)

    case mink.IsNotFoundError(err):
        http.Error(w, "Resource not found", http.StatusNotFound)

    case mink.IsValidationError(err):
        http.Error(w, err.Error(), http.StatusBadRequest)

    default:
        log.Printf("Internal error: %v", err)
        http.Error(w, "Internal server error", http.StatusInternalServerError)
    }
}

Alternatives Considered

Alternative 1: Sentinel Errors Only

Description: Only use var ErrX = errors.New("x").

Rejected because:

• No way to include context (stream ID, version)
• Callers can't get details without parsing message

Alternative 2: Typed Errors Only

Description: Only use type XError struct{}.

Rejected because:

• Requires errors.As for checking (more verbose)
• Less discoverable in documentation
• Harder to remember struct names

Alternative 3: Error Codes

Description: Use numeric or string codes.

Rejected because:

• Not idiomatic Go
• Requires lookup tables
• Less type safety

Alternative 4: Multiple Return Values

Description: Return (result, errType, errDetails).

Rejected because:

• Not idiomatic Go
• Complicates function signatures
• Doesn't compose well

References

• Go 1.13 Error Handling
• Working with Errors in Go 1.13
• Error Handling in Go
• Don't Just Check Errors, Handle Them Gracefully