errors

Overview ¶

Package errors provides standardized error handling for StreamSpace API.

This package implements a consistent error format across all API endpoints:

• Structured error responses with error codes
• Automatic HTTP status code mapping
• Optional error details for debugging
• Machine-readable error codes for client error handling

Error Structure:

• Code: Machine-readable error identifier (e.g., "QUOTA_EXCEEDED")
• Message: Human-readable error message
• Details: Optional additional context (wrapped errors, stack traces)
• StatusCode: HTTP status code (400, 401, 403, 404, 500, etc.)

Error Categories:

• Client Errors (4xx): Bad request, unauthorized, forbidden, not found
• Server Errors (5xx): Internal errors, database errors, service unavailable

Usage patterns:

// Simple error
return errors.NotFound("session")

// Error with custom message
return errors.QuotaExceeded("Maximum 5 sessions allowed")

// Wrap underlying error
return errors.DatabaseError(err)

// In HTTP handler
c.JSON(err.StatusCode, err.ToResponse())

JSON Response Format:

{
  "error": "QUOTA_EXCEEDED",
  "message": "Session quota exceeded",
  "code": "QUOTA_EXCEEDED",
  "details": "5/5 sessions active"
}

Package errors provides standardized error handling for StreamSpace API.

This file implements error handling middleware for Gin framework.

Purpose: - Centralize error handling across all API endpoints - Convert AppError to consistent JSON responses - Log errors with appropriate severity levels - Recover from panics gracefully - Provide helper functions for error responses

Features: - Automatic error logging (ERROR for 5xx, WARN for 4xx) - Panic recovery with error response - Consistent error response format - Error severity classification - Request abort on critical errors

Middleware Functions:

• ErrorHandler: Handles AppError and generic errors
• Recovery: Recovers from panics
• HandleError: Helper for error responses in handlers
• AbortWithError: Helper to abort request with error

Implementation Details: - Integrates with Gin's error handling mechanism (c.Errors) - Logs errors using standard library log (consider upgrading to structured logging) - Preserves error details for debugging - Automatically sets HTTP status codes

Thread Safety: - Middleware is thread-safe - Safe for concurrent requests

Dependencies: - github.com/gin-gonic/gin for HTTP framework

Example Usage:

// Apply error handling middleware
router.Use(errors.Recovery())
router.Use(errors.ErrorHandler())

// In handler: return error and let middleware handle it
func handler(c *gin.Context) {
    session, err := getSession(id)
    if err != nil {
        errors.HandleError(c, errors.SessionNotFound(id))
        return
    }
    c.JSON(200, session)
}

// Or abort immediately
if !authorized {
    errors.AbortWithError(c, errors.Forbidden("Access denied"))
    return
}