feat(helper/proxy): introduce proxy helper

jsr.json

@@ -79,6 +79,7 @@
     "./testing": "./src/helper/testing/index.ts",
     "./dev": "./src/helper/dev/index.ts",
     "./ws": "./src/helper/websocket/index.ts",
+    "./proxy": "./src/helper/proxy/index.ts",
     "./utils/body": "./src/utils/body.ts",
     "./utils/buffer": "./src/utils/buffer.ts",
     "./utils/color": "./src/utils/color.ts",

package.json

@@ -383,6 +383,11 @@
       "types": "./dist/types/helper/conninfo/index.d.ts",
       "import": "./dist/helper/conninfo/index.js",
       "require": "./dist/cjs/helper/conninfo/index.js"
+    },
+    "./proxy": {
+      "types": "./dist/types/helper/proxy/index.d.ts",
+      "import": "./dist/helper/proxy/index.js",
+      "require": "./dist/cjs/helper/proxy/index.js"
     }
   },
   "typesVersions": {
@@ -587,6 +592,9 @@
       ],
       "conninfo": [
         "./dist/types/helper/conninfo"
+      ],
+      "proxy": [
+        "./dist/types/helper/proxy"
       ]
     }
   },

src/helper/proxy/index.test.ts

@@ -0,0 +1,152 @@
+import { Hono } from '../../hono'
+import { proxyFetch } from '.'
+
+describe('Proxy Middleware', () => {
+  describe('proxyFetch', () => {
+    beforeEach(() => {
+      global.fetch = vi.fn().mockImplementation((req) => {
+        if (req.url === 'https://example.com/compressed') {
+          return Promise.resolve(
+            new Response('ok', {
+              headers: {
+                'Content-Encoding': 'gzip',
+                'Content-Length': '1',
+                'Content-Range': 'bytes 0-2/1024',
+                'X-Response-Id': '456',
+              },
+            })
+          )
+        } else if (req.url === 'https://example.com/uncompressed') {
+          return Promise.resolve(
+            new Response('ok', {
+              headers: {
+                'Content-Length': '2',
+                'Content-Range': 'bytes 0-2/1024',
+                'X-Response-Id': '456',
+              },
+            })
+          )
+        }
+        return Promise.resolve(new Response('not found', { status: 404 }))
+      })
+    })
+
+    it('compressed', async () => {
+      const app = new Hono()
+      app.get('/proxy/:path', (c) =>
+        proxyFetch(
+          new Request(`https://example.com/${c.req.param('path')}`, {
+            headers: {
+              'X-Request-Id': '123',
+              'Accept-Encoding': 'gzip',
+            },
+          })
+        )
+      )
+      const res = await app.request('/proxy/compressed')
+      const req = (global.fetch as ReturnType<typeof vi.fn>).mock.calls[0][0]
+
+      expect(req.url).toBe('https://example.com/compressed')
+      expect(req.headers.get('X-Request-Id')).toBe('123')
+      expect(req.headers.get('Accept-Encoding')).toBeNull()
+
+      expect(res.status).toBe(200)
+      expect(res.headers.get('X-Response-Id')).toBe('456')
+      expect(res.headers.get('Content-Encoding')).toBeNull()
+      expect(res.headers.get('Content-Length')).toBeNull()
+      expect(res.headers.get('Content-Range')).toBe('bytes 0-2/1024')
+    })
+
+    it('uncompressed', async () => {
+      const app = new Hono()
+      app.get('/proxy/:path', (c) =>
+        proxyFetch(
+          new Request(`https://example.com/${c.req.param('path')}`, {
+            headers: {
+              'X-Request-Id': '123',
+              'Accept-Encoding': 'gzip',
+            },
+          })
+        )
+      )
+      const res = await app.request('/proxy/uncompressed')
+      const req = (global.fetch as ReturnType<typeof vi.fn>).mock.calls[0][0]
+
+      expect(req.url).toBe('https://example.com/uncompressed')
+      expect(req.headers.get('X-Request-Id')).toBe('123')
+      expect(req.headers.get('Accept-Encoding')).toBeNull()
+
+      expect(res.status).toBe(200)
+      expect(res.headers.get('X-Response-Id')).toBe('456')
+      expect(res.headers.get('Content-Length')).toBe('2')
+      expect(res.headers.get('Content-Range')).toBe('bytes 0-2/1024')
+    })
+
+    it('proxySetRequestHeaders option', async () => {
+      const app = new Hono()
+      app.get('/proxy/:path', (c) =>
+        proxyFetch(
+          new Request(`https://example.com/${c.req.param('path')}`, {
+            headers: {
+              'X-Request-Id': '123',
+              'X-To-Be-Deleted': 'to-be-deleted',
+              'Accept-Encoding': 'gzip',
+            },
+          }),
+          {
+            proxySetRequestHeaders: {
+              'X-Request-Id': 'abc',
+              'X-Forwarded-For': '127.0.0.1',
+              'X-Forwarded-Host': 'example.com',
+              'X-To-Be-Deleted': undefined,
+            },
+          }
+        )
+      )
+      const res = await app.request('/proxy/compressed')
+      const req = (global.fetch as ReturnType<typeof vi.fn>).mock.calls[0][0]
+
+      expect(req.url).toBe('https://example.com/compressed')
+      expect(req.headers.get('X-Request-Id')).toBe('abc')
+      expect(req.headers.get('X-Forwarded-For')).toBe('127.0.0.1')
+      expect(req.headers.get('X-Forwarded-Host')).toBe('example.com')
+      expect(req.headers.get('X-To-Be-Deleted')).toBeNull()
+      expect(req.headers.get('Accept-Encoding')).toBeNull()
+
+      expect(res.status).toBe(200)
+      expect(res.headers.get('X-Response-Id')).toBe('456')
+      expect(res.headers.get('Content-Encoding')).toBeNull()
+      expect(res.headers.get('Content-Length')).toBeNull()
+      expect(res.headers.get('Content-Range')).toBe('bytes 0-2/1024')
+    })
+
+    it('proxySetRequestHeaderNames option', async () => {
+      const app = new Hono()
+      app.get('/proxy/:path', (c) =>
+        proxyFetch(
+          new Request(`https://example.com/${c.req.param('path')}`, {
+            headers: {
+              'X-Request-Id': '123',
+              'Accept-Encoding': 'gzip',
+            },
+          }),
+          {
+            proxyDeleteResponseHeaderNames: ['X-Response-Id'],
+          }
+        )
+      )
+      const res = await app.request('/proxy/compressed')
+      const req = (global.fetch as ReturnType<typeof vi.fn>).mock.calls[0][0]
+
+      expect(req.url).toBe('https://example.com/compressed')
+      expect(req.headers.get('X-Request-Id')).toBe('123')
+      expect(req.headers.get('Accept-Encoding')).toBeNull()
+
+      expect(res.status).toBe(200)
+      expect(res.headers.get('X-Response-Id')).toBeNull()
+      expect(res.headers.get('Content-Encoding')).toBeNull()
+      expect(res.headers.get('Content-Length')).toBeNull()
+      expect(res.headers.get('Content-Range')).toBe('bytes 0-2/1024')
+    })
+  })
+})

src/helper/proxy/index.ts

@@ -0,0 +1,82 @@
+/**
+ * @module
+ * Proxy Helper for Hono.
+ */
+
+// Typical header names for requests for proxy use
+type ProxyRequestHeaderName = 'X-Forwarded-For' | 'X-Forwarded-Proto' | 'X-Forwarded-Host'
+
+interface ProxyRequestInit extends RequestInit {
+  /**
+   * Headers that are overwritten in requests to the origin server.
+   * Specify undefined to delete the header.
+   */
+  proxySetRequestHeaders?: Partial<Record<ProxyRequestHeaderName, string>> &
+    Record<string, string | undefined>
+  /**
+   * Headers included in the response from the origin server that should be removed in the response to the client.
+   */
+  proxyDeleteResponseHeaderNames?: string[]
+}
+
+interface ProxyFetch {
+  (input: RequestInfo | URL, init?: ProxyRequestInit): Promise<Response>
+  (input: string | URL | globalThis.Request, init?: ProxyRequestInit): Promise<Response>
+}
+
+/**
+ * Fetch API wrapper for proxy.
+ * The parameters and return value are the same as for `fetch` (except for the proxy-specific options).
+ *
+ * The “Accept-Encoding” header is replaced with an encoding that the current runtime can handle.
+ * Unnecessary response headers are deleted and a Response object is returned that can be returned
+ * as is as a response from the handler.
+ *
+ * @example
+ * ```ts
+ * app.get('/proxy/:path', (c) => {
+ *   return proxyFetch(new Request(`http://${originServer}/${c.req.param('path')}`, c.req.raw), {
+ *     proxySetRequestHeaders: {
+ *       'X-Forwarded-For': '127.0.0.1',
+ *       'X-Forwarded-Host': c.req.header('host'),
+ *       Authorization: undefined, // do not propagate request headers contained in c.req.raw
+ *     },
+ *     proxyDeleteResponseHeaderNames: ['Cookie'],
+ *   })
+ * })
+ * ```
+ */
+export const proxyFetch: ProxyFetch = async (input, proxyInit) => {
+  const {
+    proxySetRequestHeaders = {},
+    proxyDeleteResponseHeaderNames = [],
+    ...requestInit
+  } = proxyInit ?? {}
+
+  const req = new Request(input, requestInit)
+  req.headers.delete('accept-encoding')
+
+  for (const [key, value] of Object.entries(proxySetRequestHeaders)) {
+    if (value !== undefined) {
+      req.headers.set(key, value)
+    } else {
+      req.headers.delete(key)
+    }
+  }
+
+  const res = await fetch(req)
+  const resHeaders = new Headers(res.headers)
+  if (resHeaders.has('content-encoding')) {
+    resHeaders.delete('content-encoding')
+    // Content-Length is the size of the compressed content, not the size of the original content
+    resHeaders.delete('content-length')
+  }
+  for (const key of proxyDeleteResponseHeaderNames) {
+    resHeaders.delete(key)
+  }
+
+  return new Response(res.body, {
+    ...res,
+    headers: resHeaders,
+  })
+}