Merge pull request #2 from BackendStack21/add-fallback-support-via-onError-hook

Add fallback support via on error hook

Author: jkyberneees

README.md

@@ -135,6 +135,7 @@ interface CircuitBreakerResult {
   state: CircuitState // Current circuit breaker state
   failureCount: number // Current failure count
   executionTimeMs: number // Execution time in milliseconds
+  fallbackResponseProvided?: boolean // Whether a fallback response was provided
 }
 ```
 
@@ -179,7 +180,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 +551,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

package.json

@@ -26,7 +26,8 @@
     "clean": "rm -rf lib/",
     "prepublishOnly": "bun run clean && bun run build",
     "example:benchmark": "bun run examples/local-gateway-server.ts",
-    "deploy": "bun run prepublishOnly && bun publish"
+    "deploy": "bun run prepublishOnly && bun publish",
+    "actions": "DOCKER_HOST=$(docker context inspect --format '{{.Endpoints.docker.Host}}') act"
   },
   "repository": {
     "type": "git",

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,
+          fallbackResponseProvided: fallbackResponse instanceof Response,
         },
         options,
       )
 
+      if (fallbackResponse instanceof Response) {
+        // 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
+  fallbackResponseProvided?: boolean
 }
 
 export enum CircuitState {

tests/dos-prevention.test.ts

@@ -1,8 +1,4 @@
-import { afterAll, describe, expect, test, mock } from "bun:test"
-
-afterAll(() => {
-  mock.restore()
-})
+import { describe, expect, test } from "bun:test"
 
 describe("DoS and Resource Exhaustion Security Tests", () => {
   describe("Request Parameter Validation", () => {

tests/enhanced-hooks.test.ts

@@ -9,18 +9,17 @@ import {
   beforeEach,
   jest,
   afterAll,
-  mock,
+  spyOn,
 } from "bun:test"
 import { FetchProxy } from "../src/proxy"
 import { CircuitState } from "../src/types"
 import type { ProxyRequestOptions, CircuitBreakerResult } from "../src/types"
 
-// Mock fetch for testing
-const mockFetch = jest.fn()
-;(global as any).fetch = mockFetch
+// Spy on fetch for testing
+let fetchSpy: ReturnType<typeof spyOn>
 
 afterAll(() => {
-  mock.restore()
+  fetchSpy?.mockRestore()
 })
 
 describe("Enhanced Hook Naming Conventions", () => {
@@ -39,8 +38,9 @@ describe("Enhanced Hook Naming Conventions", () => {
       headers: new Headers({ "content-type": "application/json" }),
     })
 
-    mockFetch.mockClear()
-    mockFetch.mockResolvedValue(mockResponse)
+    fetchSpy = spyOn(global, "fetch")
+    fetchSpy.mockClear()
+    fetchSpy.mockResolvedValue(mockResponse)
   })
 
   describe("beforeRequest Hook", () => {
@@ -56,7 +56,7 @@ describe("Enhanced Hook Naming Conventions", () => {
 
       expect(beforeRequestHook).toHaveBeenCalledTimes(1)
       expect(beforeRequestHook).toHaveBeenCalledWith(request, options)
-      expect(mockFetch).toHaveBeenCalledTimes(1)
+      expect(fetchSpy).toHaveBeenCalledTimes(1)
     })
 
     it("should handle async beforeRequest hooks", async () => {
@@ -139,7 +139,7 @@ describe("Enhanced Hook Naming Conventions", () => {
       const request = new Request("https://example.com/test")
       const error = new Error("Network error")
 
-      mockFetch.mockRejectedValueOnce(error)
+      fetchSpy.mockRejectedValueOnce(error)
 
       const options: ProxyRequestOptions = {
         afterCircuitBreakerExecution: afterCircuitBreakerHook,
@@ -166,7 +166,7 @@ describe("Enhanced Hook Naming Conventions", () => {
       const request = new Request("https://example.com/test")
 
       // Add some delay to the fetch
-      mockFetch.mockImplementationOnce(
+      fetchSpy.mockImplementationOnce(
         () =>
           new Promise((resolve) => setTimeout(() => resolve(mockResponse), 50)),
       )
@@ -296,8 +296,8 @@ describe("Enhanced Hook Naming Conventions", () => {
       await proxy.proxy(request, undefined, options)
 
       // Verify the mock was called (we can't easily verify exact headers due to internal processing)
-      expect(mockFetch).toHaveBeenCalledTimes(1)
-      expect(mockFetch).toHaveBeenCalledWith(
+      expect(fetchSpy).toHaveBeenCalledTimes(1)
+      expect(fetchSpy).toHaveBeenCalledWith(
         expect.any(String),
         expect.objectContaining({
           headers: expect.any(Headers),
@@ -315,7 +315,7 @@ describe("Enhanced Hook Naming Conventions", () => {
         },
       })
 
-      mockFetch.mockResolvedValueOnce(originalResponse)
+      fetchSpy.mockResolvedValueOnce(originalResponse)
 
       const request = new Request("https://example.com/test")
 

tests/header-injection.test.ts

@@ -1,14 +1,10 @@
 /**
  * Security tests for header injection vulnerabilities
  */
-import { describe, expect, it, afterAll, mock } from "bun:test"
+import { describe, expect, it } from "bun:test"
 
 import { recordToHeaders } from "../src/utils"
 
-afterAll(() => {
-  mock.restore()
-})
-
 describe("Header Injection Security Tests", () => {
   describe("CRLF Header Injection", () => {
     it("should reject header names with CRLF characters", () => {

tests/http-method-validation.test.ts

@@ -1,12 +1,13 @@
-import { describe, it, expect, beforeEach, afterAll, mock } from "bun:test"
+import { describe, it, expect, beforeEach, spyOn, afterEach } from "bun:test"
 import { validateHttpMethod } from "../src/utils"
 import { FetchProxy } from "../src/proxy"
 
-afterAll(() => {
-  mock.restore()
-})
-
 describe("HTTP Method Validation Security Tests", () => {
+  let fetchSpy: ReturnType<typeof spyOn>
+
+  afterEach(() => {
+    fetchSpy?.mockRestore()
+  })
   describe("Direct Method Validation", () => {
     it("should reject CONNECT method", () => {
       expect(() => {
@@ -75,6 +76,15 @@ describe("HTTP Method Validation Security Tests", () => {
         base: "http://httpbin.org", // Use a real service for testing
         circuitBreaker: { enabled: false },
       })
+
+      // Mock fetch to return a successful response
+      fetchSpy = spyOn(global, "fetch").mockResolvedValue(
+        new Response("", {
+          status: 200,
+          statusText: "OK",
+          headers: new Headers({ "content-type": "text/plain" }),
+        }),
+      )
     })
 
     it("should reject CONNECT method in proxy (if runtime allows it)", async () => {
@@ -107,6 +117,9 @@ describe("HTTP Method Validation Security Tests", () => {
       // The normalized request should work fine
       const response = await proxy.proxy(request)
       expect(response.status).toBe(200)
+
+      // Verify fetch was called
+      expect(fetchSpy).toHaveBeenCalledTimes(1)
     })
 
     it("should allow safe methods in proxy", async () => {
@@ -116,6 +129,9 @@ describe("HTTP Method Validation Security Tests", () => {
 
       const response = await proxy.proxy(request)
       expect(response.status).toBe(200)
+
+      // Verify fetch was called
+      expect(fetchSpy).toHaveBeenCalledTimes(1)
     })
 
     it("should validate methods when passed through request options", async () => {

tests/index.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeAll, afterAll, mock } from "bun:test"
+import { describe, it, expect, beforeAll, afterAll, spyOn } from "bun:test"
 import createFetchGate, { FetchProxy } from "../src/index"
 import {
   buildURL,
@@ -55,7 +55,7 @@ describe("fetch-gate", () => {
 
   afterAll(() => {
     server?.stop()
-    mock.restore()
+    // No need for explicit restore with spyOn as it's automatically cleaned up
   })
 
   describe("createFetchGate", () => {
@@ -308,10 +308,9 @@ describe("fetch-gate", () => {
 
   describe("Circuit Breaker Edge Cases", () => {
     it("should transition to HALF_OPEN state after reset timeout", async () => {
-      // Custom mock for Date.now()
-      const originalDateNow = Date.now
-      let now = originalDateNow()
-      global.Date.now = () => now
+      // Spy on Date.now()
+      let now = Date.now()
+      const dateNowSpy = spyOn(Date, "now").mockImplementation(() => now)
 
       const circuitBreaker = new CircuitBreaker({
         failureThreshold: 1,
@@ -330,8 +329,8 @@ describe("fetch-gate", () => {
 
       expect(circuitBreaker.getState()).toBe(CircuitState.HALF_OPEN)
 
-      // Restore original Date.now()
-      global.Date.now = originalDateNow
+      // Restore Date.now() spy
+      dateNowSpy.mockRestore()
     })
 
     it("should reset failures after successful execution in HALF_OPEN state", async () => {

tests/logging.test.ts

@@ -1,12 +1,4 @@
-import {
-  describe,
-  expect,
-  it,
-  beforeEach,
-  spyOn,
-  afterAll,
-  mock,
-} from "bun:test"
+import { describe, expect, it, beforeEach, spyOn, afterAll } from "bun:test"
 import { FetchProxy } from "../src/proxy"
 import {
   ProxyLogger,
@@ -15,11 +7,11 @@ import {
 } from "../src/logger"
 import { CircuitState } from "../src/types"
 
-// Mock fetch for testing
-const originalFetch = global.fetch
+// Spy on fetch for testing
+let fetchSpy: ReturnType<typeof spyOn>
 
 afterAll(() => {
-  mock.restore()
+  fetchSpy?.mockRestore()
 })
 
 describe("Logging Integration", () => {