feat: add proxy mode for forwarding requests to an upstream server

- add src/proxy.ts with hop-by-hop header filtering and x-forwarded-* headers
- add --proxy CLI flag and PROXY_TARGET env var (mutually exclusive with path)
- make serve/redirect/proxy/listen async, resolving once listening
- remove app.get() custom-route API
- add proxy, env validation, and CLI exclusivity tests

🤖 Generated with [OpenCode](https://opencode.ai) (Smart-router)

Author: daquinoaldo

README.md

@@ -1,6 +1,6 @@
 # HTTPS server running on localhost
 
-Run a server on localhost with a locally-trusted SSL certificate. Serve static files, define your own routes, or import it as a module in your project.
+Run a server on localhost with a locally-trusted SSL certificate. Serve static files, proxy an existing server, define your own routes, or import it as a module in your project.
 
 The certificate is provided by [mkcert](https://github.com/FiloSottile/mkcert). It automatically creates and installs a local CA in the system and browser root stores, and uses it to generate certificates that your machine trusts. **These are not valid certificates, they are for development only, and will only work in your machine.**
 
@@ -25,6 +25,7 @@ Usage notes:
   - `-H, --host <host>`: domain for the certificate (`HOST`)
   - `--cert-path <path>`: custom certificate directory (`CERT_PATH`)
   - `--reinstall`: force certificate re-generation (`REINSTALL=true`)
+  - `--proxy <url>`: proxy all requests to the given http(s) URL (`PROXY_TARGET`)
 - Specifying a port number prevents HTTP to HTTPS redirect.
 
 ### Standalone binaries
@@ -39,29 +40,26 @@ Install as a dependency:
 npm i -D https-localhost
 ```
 
-Then put in your `index.js` file:
+Then use it to serve static files or proxy an existing server.
 
 ```js
 import { createServer } from "https-localhost"
 // or, in CommonJS:
 // const { createServer } = require("https-localhost")
 
 const app = createServer()
-app.listen()     // optionally, specify a port
-app.redirect()   // enable http to https
-app.serve(path)  // serve static files
+await app.redirect() // enable http -> https
+await app.serve(path) // serve static files
 
-// optionally, define your own routes (GET only)
-app.get("/api/hello", (req, res) => res.end("Hello, world!"))
+// or, instead of serve, proxy an existing server:
+await app.proxy("http://localhost:3000")
 ```
 
 Alternatively, you can use the certificates in your own server:
 
 ```js
 import https from "node:https"
-import { getCerts } from "https-localhost/certs"
-// or, in CommonJS:
-// const { getCerts } = require("https-localhost/certs")
+import { getCerts } from "https-localhost/certs" // or: const { getCerts } = require("https-localhost/certs")
 
 const certs = await getCerts()
 

src/cli.ts

@@ -13,6 +13,7 @@ const parsedArgs = parseArgs({
     host: { type: "string", short: "H" },
     "cert-path": { type: "string" },
     reinstall: { type: "boolean" },
+    proxy: { type: "string" },
     help: { type: "boolean", short: "h" },
   },
 })
@@ -26,28 +27,36 @@ Options:
   -H, --host <host>        Host/domain for SSL cert (default: localhost or HOST env)
       --cert-path <path>   Directory to store/find certificates (default: CERT_PATH env)
       --reinstall          Force reinstall of certificates (default: REINSTALL env)
+      --proxy <url>        Proxy requests to the given http(s) URL (default: PROXY_TARGET env)
   -h, --help               Display help
 `)
   process.exit(0)
 }
 
 const staticFolder = parsedArgs.positionals[0] ?? process.cwd()
 
-const { port, host, "cert-path": certPath, reinstall } = parsedArgs.values
+const { port, host, "cert-path": certPath, reinstall, proxy } = parsedArgs.values
+
+if (proxy !== undefined && parsedArgs.positionals.length > 0) {
+  console.error("Error: --proxy and a static path are mutually exclusive.")
+  process.exit(1)
+}
 
 const env = getEnv({
   PORT: port,
   HOST: host,
   CERT_PATH: certPath,
   REINSTALL: reinstall,
+  PROXY_TARGET: proxy,
 })
 
 const app = createServer({
   domain: env.HOST,
   certPath: env.CERT_PATH,
   reinstall: env.REINSTALL,
 })
-app.serve(staticFolder, env.PORT)
+if (env.PROXY_TARGET !== undefined) app.proxy(env.PROXY_TARGET, env.PORT)
+else app.serve(staticFolder, env.PORT)
 if (env.PORT === 443) app.redirect()
 
 process.on("uncaughtException", err => {

src/env.ts

@@ -7,6 +7,12 @@ export const envSchema = z.object({
   REINSTALL: z
     .union([z.boolean(), z.string().transform(v => v === "true" || v === "1")])
     .default(false),
+  PROXY_TARGET: z
+    .url()
+    .refine(v => v.startsWith("http:") || v.startsWith("https:"), {
+      message: "PROXY_TARGET must be an http or https URL",
+    })
+    .optional(),
 })
 
 export type Env = z.infer<typeof envSchema>

src/index.ts

@@ -3,17 +3,17 @@ import type { Server } from "node:http"
 import https from "node:https"
 
 import { getCerts } from "./certs.ts"
+import { createProxyHandler } from "./proxy.ts"
 import { createRouter } from "./router.ts"
-import type { RouteHandler } from "./router.ts"
 import { createStaticHandler } from "./static.ts"
 
 export type HttpsLocalhostApp = {
   server?: Server
   http?: Server
-  get: (route: string, handler: RouteHandler) => void
   listen: (port?: number) => Promise<Server>
-  redirect: (httpPort?: number, httpsPort?: number) => void
-  serve: (staticPath?: string, port?: number) => void
+  proxy: (target: string, port?: number) => Promise<HttpsLocalhostApp>
+  redirect: (httpPort?: number, httpsPort?: number) => Promise<HttpsLocalhostApp>
+  serve: (staticPath?: string, port?: number) => Promise<HttpsLocalhostApp>
 }
 
 export function createServer({
@@ -28,34 +28,43 @@ export function createServer({
   const router = createRouter()
 
   const app: HttpsLocalhostApp = {
-    get(route, handler) {
-      router.get(route, handler)
-    },
     async listen(port = 443) {
-      app.server = https
-        .createServer(await getCerts({ domain, certPath, reinstall }), router.handleRequest)
-        .listen(port)
+      const certs = await getCerts({ domain, certPath, reinstall })
+      app.server = https.createServer(certs, router.handleRequest)
+      await new Promise<void>(resolve => {
+        app.server?.listen(port, resolve)
+      })
       console.info(`Server running on port ${port}.`)
       return app.server
     },
-    redirect(httpPort = 80, httpsPort = 443) {
-      app.http = http
-        .createServer((req, res) => {
-          const reqHost = req.headers.host ?? domain
-          res.writeHead(301, {
-            Location: `https://${reqHost.replace(`:${httpPort}`, "")}${
-              httpsPort !== 443 ? `:${httpsPort}` : ""
-            }${req.url ?? ""}`,
+    async proxy(target, port = 443) {
+      router.setProxyHandler(createProxyHandler(target))
+      console.info(`Proxying to ${target}`)
+      await app.listen(port)
+      return app
+    },
+    async redirect(httpPort = 80, httpsPort = 443) {
+      await new Promise<void>(resolve => {
+        app.http = http
+          .createServer((req, res) => {
+            const reqHost = req.headers.host ?? domain
+            res.writeHead(301, {
+              Location: `https://${reqHost.replace(`:${httpPort}`, "")}${
+                httpsPort !== 443 ? `:${httpsPort}` : ""
+              }${req.url ?? ""}`,
+            })
+            res.end()
           })
-          res.end()
-        })
-        .listen(httpPort)
+          .listen(httpPort, resolve)
+      })
       console.info("http to https redirection active.")
+      return app
     },
-    serve(staticPath = process.cwd(), port = 443) {
+    async serve(staticPath = process.cwd(), port = 443) {
       router.setStaticHandler(createStaticHandler(staticPath))
       console.info(`Serving static path: ${staticPath}`)
-      void app.listen(port)
+      await app.listen(port)
+      return app
     },
   }
 

src/proxy.ts

@@ -0,0 +1,74 @@
+import http from "node:http"
+import type {
+  IncomingMessage,
+  OutgoingHttpHeaders,
+  RequestListener,
+  ServerResponse,
+} from "node:http"
+import https from "node:https"
+
+const HOP_BY_HOP_HEADERS: ReadonlySet<string> = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+])
+
+function filterHeaders(headers: IncomingMessage["headers"]): OutgoingHttpHeaders {
+  const filtered: OutgoingHttpHeaders = {}
+  for (const [name, value] of Object.entries(headers)) {
+    if (value === undefined || HOP_BY_HOP_HEADERS.has(name.toLowerCase())) continue
+    filtered[name] = value
+  }
+  return filtered
+}
+
+export function createProxyHandler(target: string): RequestListener {
+  const url = new URL(target)
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`Unsupported proxy protocol: ${url.protocol}. Use http or https.`)
+  }
+  const transport = url.protocol === "https:" ? https : http
+  const port = url.port === "" ? (url.protocol === "https:" ? 443 : 80) : Number(url.port)
+
+  return function handleProxy(req: IncomingMessage, res: ServerResponse): void {
+    const headers = filterHeaders(req.headers)
+    headers.host = url.host
+    if (req.socket.remoteAddress !== undefined)
+      headers["x-forwarded-for"] = req.socket.remoteAddress
+    headers["x-forwarded-proto"] =
+      (req.socket as { encrypted?: boolean }).encrypted === true ? "https" : "http"
+    if (req.headers.host !== undefined) headers["x-forwarded-host"] = req.headers.host
+
+    const upstream = transport.request(
+      {
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port,
+        path: req.url,
+        method: req.method,
+        headers,
+      },
+      upstreamRes => {
+        res.writeHead(upstreamRes.statusCode ?? 502, filterHeaders(upstreamRes.headers))
+        upstreamRes.pipe(res)
+      },
+    )
+    upstream.on("error", () => {
+      if (res.headersSent) {
+        res.destroy()
+        return
+      }
+      res.writeHead(502, { "Content-Type": "text/plain; charset=utf-8" })
+      res.end("Bad gateway.")
+    })
+    req.on("aborted", () => {
+      upstream.destroy()
+    })
+    req.pipe(upstream)
+  }
+}

src/router.ts

@@ -2,22 +2,18 @@ import type { IncomingMessage, RequestListener, ServerResponse } from "node:http
 
 import { applyCors } from "./cors.ts"
 
-export type RouteHandler = (req: IncomingMessage, res: ServerResponse) => void
-
 export function createRouter(): {
   handleRequest: RequestListener
-  get: (route: string, handler: RouteHandler) => void
+  setProxyHandler: (handler: RequestListener | undefined) => void
   setStaticHandler: (handler: RequestListener | undefined) => void
 } {
-  const routes: Array<{ route: string; handler: RouteHandler }> = []
-
+  let proxyHandler: RequestListener | undefined
   let staticHandler: RequestListener | undefined
 
   function handleRequest(req: IncomingMessage, res: ServerResponse): void {
     if (applyCors(req, res)) return
-    const route = routes.find(candidate => candidate.route === req.url?.split("?")[0])
-    if (route !== undefined && req.method === "GET") {
-      route.handler(req, res)
+    if (proxyHandler !== undefined) {
+      proxyHandler(req, res)
       return
     }
     if (staticHandler !== undefined) {
@@ -28,13 +24,13 @@ export function createRouter(): {
     res.end("Not found.")
   }
 
-  function get(route: string, handler: RouteHandler): void {
-    routes.push({ route, handler })
+  function setProxyHandler(handler: RequestListener | undefined): void {
+    proxyHandler = handler
   }
 
   function setStaticHandler(handler: RequestListener | undefined): void {
     staticHandler = handler
   }
 
-  return { handleRequest, get, setStaticHandler }
+  return { handleRequest, setProxyHandler, setStaticHandler }
 }

test/cli.test.ts

@@ -33,6 +33,25 @@ void describe("cli", () => {
     }
   })
 
+  void it("exits with an error when --proxy and a path are both passed", async () => {
+    const proc = spawn("node", [cliPath, "--proxy", "http://localhost:3000", "some-path"], {
+      env: currentEnv(),
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+
+    let stderr = ""
+    const [code] = await new Promise<[number | null]>((resolve, reject) => {
+      proc.stderr.on("data", (data: Buffer) => {
+        stderr += data.toString()
+      })
+      proc.on("close", code => resolve([code]))
+      proc.on("error", reject)
+    })
+
+    assert.strictEqual(code, 1)
+    assert.ok(stderr.includes("mutually exclusive"))
+  })
+
   void it("prints help when --help is passed", async () => {
     const proc = spawn("node", [cliPath, "--help"], {
       env: currentEnv(),

test/env.test.ts

@@ -48,4 +48,20 @@ void describe("env", () => {
     assert.throws(() => envSchema.parse({ PORT: 0 }))
     assert.throws(() => envSchema.parse({ PORT: 70000 }))
   })
+
+  void it("rejects invalid proxy targets", () => {
+    assert.throws(() => envSchema.parse({ PROXY_TARGET: "not-a-url" }))
+    assert.throws(() => envSchema.parse({ PROXY_TARGET: "ftp://localhost:3000" }))
+  })
+
+  void it("accepts http and https proxy targets", () => {
+    assert.strictEqual(
+      envSchema.parse({ PROXY_TARGET: "http://localhost:3000" }).PROXY_TARGET,
+      "http://localhost:3000",
+    )
+    assert.strictEqual(
+      envSchema.parse({ PROXY_TARGET: "https://example.com" }).PROXY_TARGET,
+      "https://example.com",
+    )
+  })
 })

test/helpers.ts

@@ -18,7 +18,7 @@ export function currentEnv(): NodeJS.ProcessEnv {
   return env
 }
 
-function getRootCA(): Buffer | undefined {
+export function getRootCA(): Buffer | undefined {
   try {
     const certDir = getAppDataPath("https-localhost")
     const files = fs.readdirSync(certDir)