docs: add Proxy Helper (honojs#582)

.vitepress/config.ts

@@ -134,6 +134,7 @@ const sidebars = (): DefaultTheme.SidebarItem[] => [
       { text: 'Factory', link: '/docs/helpers/factory' },
       { text: 'html', link: '/docs/helpers/html' },
       { text: 'JWT', link: '/docs/helpers/jwt' },
+      { text: 'Proxy', link: '/docs/helpers/proxy' },
       { text: 'SSG', link: '/docs/helpers/ssg' },
       { text: 'Streaming', link: '/docs/helpers/streaming' },
       { text: 'Testing', link: '/docs/helpers/testing' },

docs/helpers/proxy.md

@@ -0,0 +1,84 @@
+# Proxy Helper
+
+Proxy Helper provides useful functions when using Hono application as a (reverse) proxy.
+
+## Import
+
+```ts
+import { Hono } from 'hono'
+import { proxy } from 'hono/proxy'
+```
+
+## `proxy()`
+
+`proxy()` is a `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 you can return as a response from the handler.
+
+### Examples
+
+Simple usage:
+
+```ts
+app.get('/proxy/:path', (c) => {
+  return proxy(`http://${originServer}/${c.req.param('path')}`)
+})
+```
+
+Complicated usage:
+
+```ts
+app.get('/proxy/:path', async (c) => {
+  const res = await proxy(
+    `http://${originServer}/${c.req.param('path')}`,
+    {
+      headers: {
+        ...c.req.header(), // optional, specify only when forwarding all the request data (including credentials) is necessary.
+        '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.header('Authorization')
+      },
+    }
+  )
+  res.headers.delete('Set-Cookie')
+  return res
+})
+```
+
+Or you can pass the `c.req` as a parameter.
+
+```ts
+app.all('/proxy/:path', (c) => {
+  return proxy(`http://${originServer}/${c.req.param('path')}`, {
+    ...c.req, // optional, specify only when forwarding all the request data (including credentials) is necessary.
+    headers: {
+      ...c.req.header(),
+      '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.header('Authorization')
+    },
+  })
+})
+```
+
+### `ProxyFetch`
+
+The type of `proxy()` is defined as `ProxyFetch` and is as follows
+
+```ts
+interface ProxyRequestInit extends Omit<RequestInit, 'headers'> {
+  raw?: Request
+  headers?:
+    | HeadersInit
+    | [string, string][]
+    | Record<RequestHeader, string | undefined>
+    | Record<string, string | undefined>
+}
+
+interface ProxyFetch {
+  (
+    input: string | URL | Request,
+    init?: ProxyRequestInit
+  ): Promise<Response>
+}
+```