@stacksjs/bun-router 0.0.14 → 0.0.15

package/src/errors/exceptions.ts

@@ -0,0 +1,536 @@
+/**
+ * Advanced Error Handling - Exception Hierarchy
+ *
+ * Comprehensive exception types with metadata, stack traces, and context information
+ */
+
+export interface ErrorContext {
+  requestId?: string
+  userId?: string | number
+  traceId?: string
+  spanId?: string
+  route?: string
+  method?: string
+  url?: string
+  userAgent?: string
+  ip?: string
+  timestamp?: Date
+  metadata?: Record<string, unknown>
+}
+
+export interface ErrorDetails {
+  code: string
+  message: string
+  context?: ErrorContext
+  cause?: Error
+  statusCode?: number
+  retryable?: boolean
+  severity?: 'low' | 'medium' | 'high' | 'critical'
+  category?: 'validation' | 'authentication' | 'authorization' | 'network' | 'database' | 'external' | 'system' | 'business'
+}
+
+/**
+ * Base exception class for all router errors
+ */
+export abstract class RouterException extends Error {
+  public readonly code: string
+  public readonly statusCode: number
+  public readonly context: ErrorContext
+  public readonly retryable: boolean
+  public readonly severity: 'low' | 'medium' | 'high' | 'critical'
+  public readonly category: string
+  public readonly timestamp: Date
+  public readonly cause?: Error
+
+  constructor(details: ErrorDetails) {
+    super(details.message)
+    this.name = this.constructor.name
+    this.code = details.code
+    this.statusCode = details.statusCode || 500
+    this.context = details.context || {}
+    this.retryable = details.retryable || false
+    this.severity = details.severity || 'medium'
+    this.category = details.category || 'system'
+    this.timestamp = new Date()
+    this.cause = details.cause
+
+    // Maintain proper stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor)
+    }
+  }
+
+  /**
+   * Convert error to JSON for logging/reporting
+   */
+  toJSON(): Record<string, any> {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      context: this.context,
+      retryable: this.retryable,
+      severity: this.severity,
+      category: this.category,
+      timestamp: this.timestamp.toISOString(),
+      stack: this.stack,
+      cause: this.cause
+        ? {
+            name: this.cause.name,
+            message: this.cause.message,
+            stack: this.cause.stack,
+          }
+        : undefined,
+    }
+  }
+
+  /**
+   * Create HTTP response for this error
+   */
+  toResponse(): Response {
+    const body = {
+      error: {
+        code: this.code,
+        message: this.message,
+        statusCode: this.statusCode,
+        timestamp: this.timestamp.toISOString(),
+        requestId: this.context.requestId,
+      },
+    }
+
+    return new Response(JSON.stringify(body), {
+      status: this.statusCode,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Error-Code': this.code,
+        'X-Request-ID': this.context.requestId || '',
+      },
+    })
+  }
+}
+
+/**
+ * Validation errors (400)
+ */
+export class ValidationException extends RouterException {
+  public readonly fields: Record<string, string[]>
+
+  constructor(message: string, fields: Record<string, string[]> = {}, context?: ErrorContext) {
+    super({
+      code: 'VALIDATION_ERROR',
+      message,
+      statusCode: 400,
+      context,
+      retryable: false,
+      severity: 'low',
+      category: 'validation',
+    })
+    this.fields = fields
+  }
+
+  toResponse(): Response {
+    const body = {
+      error: {
+        code: this.code,
+        message: this.message,
+        statusCode: this.statusCode,
+        timestamp: this.timestamp.toISOString(),
+        requestId: this.context.requestId,
+        fields: this.fields,
+      },
+    }
+
+    return new Response(JSON.stringify(body), {
+      status: this.statusCode,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Error-Code': this.code,
+        'X-Request-ID': this.context.requestId || '',
+      },
+    })
+  }
+}
+
+/**
+ * Authentication errors (401)
+ */
+export class AuthenticationException extends RouterException {
+  constructor(message: string = 'Authentication required', context?: ErrorContext) {
+    super({
+      code: 'AUTHENTICATION_ERROR',
+      message,
+      statusCode: 401,
+      context,
+      retryable: false,
+      severity: 'medium',
+      category: 'authentication',
+    })
+  }
+}
+
+/**
+ * Authorization errors (403)
+ */
+export class AuthorizationException extends RouterException {
+  public readonly requiredPermissions?: string[]
+
+  constructor(message: string = 'Access denied', requiredPermissions?: string[], context?: ErrorContext) {
+    super({
+      code: 'AUTHORIZATION_ERROR',
+      message,
+      statusCode: 403,
+      context,
+      retryable: false,
+      severity: 'medium',
+      category: 'authorization',
+    })
+    this.requiredPermissions = requiredPermissions
+  }
+}
+
+/**
+ * Resource not found errors (404)
+ */
+export class NotFoundException extends RouterException {
+  public readonly resource?: string
+  public readonly resourceId?: string
+
+  constructor(message: string = 'Resource not found', resource?: string, resourceId?: string, context?: ErrorContext) {
+    super({
+      code: 'NOT_FOUND',
+      message,
+      statusCode: 404,
+      context,
+      retryable: false,
+      severity: 'low',
+      category: 'business',
+    })
+    this.resource = resource
+    this.resourceId = resourceId
+  }
+}
+
+/**
+ * Method not allowed errors (405)
+ */
+export class MethodNotAllowedException extends RouterException {
+  public readonly allowedMethods: string[]
+
+  constructor(method: string, allowedMethods: string[], context?: ErrorContext) {
+    super({
+      code: 'METHOD_NOT_ALLOWED',
+      message: `Method ${method} not allowed. Allowed methods: ${allowedMethods.join(', ')}`,
+      statusCode: 405,
+      context,
+      retryable: false,
+      severity: 'low',
+      category: 'business',
+    })
+    this.allowedMethods = allowedMethods
+  }
+
+  toResponse(): Response {
+    const response = super.toResponse()
+    response.headers.set('Allow', this.allowedMethods.join(', '))
+    return response
+  }
+}
+
+/**
+ * Request timeout errors (408)
+ */
+export class TimeoutException extends RouterException {
+  public readonly timeoutMs: number
+
+  constructor(message: string = 'Request timeout', timeoutMs: number, context?: ErrorContext) {
+    super({
+      code: 'REQUEST_TIMEOUT',
+      message,
+      statusCode: 408,
+      context,
+      retryable: true,
+      severity: 'medium',
+      category: 'network',
+    })
+    this.timeoutMs = timeoutMs
+  }
+}
+
+/**
+ * Rate limit exceeded errors (429)
+ */
+export class RateLimitException extends RouterException {
+  public readonly retryAfter: number
+  public readonly limit: number
+  public readonly remaining: number
+
+  constructor(
+    message: string = 'Rate limit exceeded',
+    retryAfter: number,
+    limit: number,
+    remaining: number = 0,
+    context?: ErrorContext,
+  ) {
+    super({
+      code: 'RATE_LIMIT_EXCEEDED',
+      message,
+      statusCode: 429,
+      context,
+      retryable: true,
+      severity: 'medium',
+      category: 'network',
+    })
+    this.retryAfter = retryAfter
+    this.limit = limit
+    this.remaining = remaining
+  }
+
+  toResponse(): Response {
+    const response = super.toResponse()
+    response.headers.set('Retry-After', this.retryAfter.toString())
+    response.headers.set('X-RateLimit-Limit', this.limit.toString())
+    response.headers.set('X-RateLimit-Remaining', this.remaining.toString())
+    return response
+  }
+}
+
+/**
+ * Internal server errors (500)
+ */
+export class InternalServerException extends RouterException {
+  constructor(message: string = 'Internal server error', cause?: Error, context?: ErrorContext) {
+    super({
+      code: 'INTERNAL_SERVER_ERROR',
+      message,
+      statusCode: 500,
+      context,
+      cause,
+      retryable: true,
+      severity: 'high',
+      category: 'system',
+    })
+  }
+}
+
+/**
+ * Service unavailable errors (503)
+ */
+export class ServiceUnavailableException extends RouterException {
+  public readonly retryAfter?: number
+
+  constructor(message: string = 'Service unavailable', retryAfter?: number, context?: ErrorContext) {
+    super({
+      code: 'SERVICE_UNAVAILABLE',
+      message,
+      statusCode: 503,
+      context,
+      retryable: true,
+      severity: 'high',
+      category: 'system',
+    })
+    this.retryAfter = retryAfter
+  }
+
+  toResponse(): Response {
+    const response = super.toResponse()
+    if (this.retryAfter) {
+      response.headers.set('Retry-After', this.retryAfter.toString())
+    }
+    return response
+  }
+}
+
+/**
+ * Database errors
+ */
+export class DatabaseException extends RouterException {
+  public readonly query?: string
+  public readonly operation?: string
+
+  constructor(message: string, operation?: string, query?: string, cause?: Error, context?: ErrorContext) {
+    super({
+      code: 'DATABASE_ERROR',
+      message,
+      statusCode: 500,
+      context,
+      cause,
+      retryable: true,
+      severity: 'high',
+      category: 'database',
+    })
+    this.operation = operation
+    this.query = query
+  }
+}
+
+/**
+ * External service errors
+ */
+export class ExternalServiceException extends RouterException {
+  public readonly service: string
+  public readonly endpoint?: string
+
+  constructor(
+    message: string,
+    service: string,
+    endpoint?: string,
+    statusCode: number = 502,
+    cause?: Error,
+    context?: ErrorContext,
+  ) {
+    super({
+      code: 'EXTERNAL_SERVICE_ERROR',
+      message,
+      statusCode,
+      context,
+      cause,
+      retryable: true,
+      severity: 'medium',
+      category: 'external',
+    })
+    this.service = service
+    this.endpoint = endpoint
+  }
+}
+
+/**
+ * Circuit breaker open errors
+ */
+export class CircuitBreakerOpenException extends RouterException {
+  public readonly service: string
+  public readonly nextAttemptAt: Date
+
+  constructor(service: string, nextAttemptAt: Date, context?: ErrorContext) {
+    super({
+      code: 'CIRCUIT_BREAKER_OPEN',
+      message: `Circuit breaker is open for service: ${service}. Next attempt at: ${nextAttemptAt.toISOString()}`,
+      statusCode: 503,
+      context,
+      retryable: true,
+      severity: 'medium',
+      category: 'external',
+    })
+    this.service = service
+    this.nextAttemptAt = nextAttemptAt
+  }
+}
+
+/**
+ * Business logic errors
+ */
+export class BusinessLogicException extends RouterException {
+  public readonly businessRule: string
+
+  constructor(message: string, businessRule: string, context?: ErrorContext) {
+    super({
+      code: 'BUSINESS_LOGIC_ERROR',
+      message,
+      statusCode: 422,
+      context,
+      retryable: false,
+      severity: 'low',
+      category: 'business',
+    })
+    this.businessRule = businessRule
+  }
+}
+
+/**
+ * Configuration errors
+ */
+export class ConfigurationException extends RouterException {
+  public readonly configKey: string
+
+  constructor(message: string, configKey: string, context?: ErrorContext) {
+    super({
+      code: 'CONFIGURATION_ERROR',
+      message,
+      statusCode: 500,
+      context,
+      retryable: false,
+      severity: 'critical',
+      category: 'system',
+    })
+    this.configKey = configKey
+  }
+}
+
+/**
+ * File system errors
+ */
+export class FileSystemException extends RouterException {
+  public readonly path: string
+  public readonly operation: string
+
+  constructor(message: string, path: string, operation: string, cause?: Error, context?: ErrorContext) {
+    super({
+      code: 'FILESYSTEM_ERROR',
+      message,
+      statusCode: 500,
+      context,
+      cause,
+      retryable: false,
+      severity: 'medium',
+      category: 'system',
+    })
+    this.path = path
+    this.operation = operation
+  }
+}
+
+/**
+ * Factory functions for common errors
+ */
+export const ErrorFactory = {
+  validation: (message: string, fields?: Record<string, string[]>, context?: ErrorContext): ValidationException =>
+    new ValidationException(message, fields, context),
+
+  authentication: (message?: string, context?: ErrorContext): AuthenticationException =>
+    new AuthenticationException(message, context),
+
+  authorization: (message?: string, requiredPermissions?: string[], context?: ErrorContext): AuthorizationException =>
+    new AuthorizationException(message, requiredPermissions, context),
+
+  notFound: (resource?: string, resourceId?: string, context?: ErrorContext): NotFoundException =>
+    new NotFoundException(undefined, resource, resourceId, context),
+
+  methodNotAllowed: (method: string, allowedMethods: string[], context?: ErrorContext): MethodNotAllowedException =>
+    new MethodNotAllowedException(method, allowedMethods, context),
+
+  timeout: (timeoutMs: number, message?: string, context?: ErrorContext): TimeoutException =>
+    new TimeoutException(message, timeoutMs, context),
+
+  rateLimit: (retryAfter: number, limit: number, remaining?: number, context?: ErrorContext): RateLimitException =>
+    new RateLimitException(undefined, retryAfter, limit, remaining, context),
+
+  internalServer: (message?: string, cause?: Error, context?: ErrorContext): InternalServerException =>
+    new InternalServerException(message, cause, context),
+
+  serviceUnavailable: (message?: string, retryAfter?: number, context?: ErrorContext): ServiceUnavailableException =>
+    new ServiceUnavailableException(message, retryAfter, context),
+
+  database: (message: string, operation?: string, query?: string, cause?: Error, context?: ErrorContext): DatabaseException =>
+    new DatabaseException(message, operation, query, cause, context),
+
+  externalService: (
+    message: string,
+    service: string,
+    endpoint?: string,
+    statusCode?: number,
+    cause?: Error,
+    context?: ErrorContext,
+  ): ExternalServiceException => new ExternalServiceException(message, service, endpoint, statusCode, cause, context),
+
+  circuitBreakerOpen: (service: string, nextAttemptAt: Date, context?: ErrorContext): CircuitBreakerOpenException =>
+    new CircuitBreakerOpenException(service, nextAttemptAt, context),
+
+  businessLogic: (message: string, businessRule: string, context?: ErrorContext): BusinessLogicException =>
+    new BusinessLogicException(message, businessRule, context),
+
+  configuration: (message: string, configKey: string, context?: ErrorContext): ConfigurationException =>
+    new ConfigurationException(message, configKey, context),
+
+  fileSystem: (message: string, path: string, operation: string, cause?: Error, context?: ErrorContext): FileSystemException =>
+    new FileSystemException(message, path, operation, cause, context),
+}