feat(proxy): add fallback response handling in onError hook

Author: jkyberneees

README.md

@@ -179,7 +179,10 @@ interface ProxyRequestOptions {
     res: Response,
     body?: ReadableStream | null,
   ) => void | Promise<void>
-  onError?: (req: Request, error: Error) => void | Promise<void>
+  onError?: (
+    req: Request,
+    error: Error,
+  ) => void | Promise<void> | Promise<Response>
   beforeCircuitBreakerExecution?: (
     req: Request,
     opts: ProxyRequestOptions,
@@ -547,6 +550,23 @@ proxy(req, undefined, {
 })
 ```
 
+#### Returning Fallback Responses
+
+You can return a fallback response from the `onError` hook by resolving the hook with a `Response` object. This allows you to customize the error response sent to the client.
+
+```typescript
+proxy(req, undefined, {
+  onError: async (req, error) => {
+    // Log error
+    console.error("Proxy error:", error)
+
+    // Return a fallback response
+    console.log("Returning fallback response for:", req.url)
+    return new Response("Fallback response", { status: 200 })
+  },
+})
+```
+
 ## Performance Tips
 
 1. **URL Caching**: Keep `cacheURLs` enabled (default 100) for better performance

src/proxy.ts

@@ -166,8 +166,9 @@ export class FetchProxy {
       currentLogger.logRequestError(req, err, { requestId, executionTime })
 
       // Execute error hooks
+      let fallbackResponse: Response | void = undefined
       if (options.onError) {
-        await options.onError(req, err)
+        fallbackResponse = await options.onError(req, err)
       }
 
       // Execute circuit breaker completion hooks for failures
@@ -179,12 +180,17 @@ export class FetchProxy {
           state: this.circuitBreaker.getState(),
           failureCount: this.circuitBreaker.getFailures(),
           executionTimeMs: executionTime,
+          fallbackResponse,
         },
         options,
       )
 
+      if (fallbackResponse) {
+        // If onError provided a fallback response, return it
+        return fallbackResponse
+      }
       // Return appropriate error response
-      if (err.message.includes("Circuit breaker is OPEN")) {
+      else if (err.message.includes("Circuit breaker is OPEN")) {
         return new Response("Service Unavailable", { status: 503 })
       } else if (
         err.message.includes("timeout") ||

src/types.ts

@@ -83,7 +83,10 @@ export type AfterCircuitBreakerHook = (
   result: CircuitBreakerResult,
 ) => void | Promise<void>
 
-export type ErrorHook = (req: Request, error: Error) => void | Promise<void>
+export type ErrorHook = (
+  req: Request,
+  error: Error,
+) => void | Promise<void> | Promise<Response>
 
 // Circuit breaker result information
 export interface CircuitBreakerResult {
@@ -92,6 +95,7 @@ export interface CircuitBreakerResult {
   state: CircuitState
   failureCount: number
   executionTimeMs: number
+  fallbackResponse?: Response | void
 }
 
 export enum CircuitState {