Koa HTTP Proxy Middleware

0.1.0 verified Thu Apr 23 auth: no javascript abandoned

This package provides HTTP proxying capabilities for Koa 2 applications, serving as a middleware wrapper around the widely used `http-proxy-middleware` library. It enables developers to configure reverse proxies for routing requests to different target servers, perform path rewriting, and manage `changeOrigin` headers, which are common requirements for API gateways, development proxies, or microservice architectures. The library is currently at version 0.1.0 and has not seen any updates since its initial release in 2017, indicating it is no longer actively maintained. Its core proxying logic and options are derived directly from the underlying `http-proxy-middleware` dependency.

Common errors

error Error: Can't set headers after they are sent. ↓

cause This error typically occurs in Koa when middleware attempts to modify headers after a response has already been sent to the client. Proxy middleware can sometimes prematurely send a response or interfere with Koa's default response handling.

fix

Ensure that Koa's context (ctx.respond = false) is correctly managed if the proxy middleware is intended to fully handle the response, preventing Koa from attempting to send its own headers. Check for other middleware that might be sending responses prematurely. Sometimes, older proxy libraries have specific workarounds for Koa's res.end() behavior.

error CORS policy: No 'Access-Control-Allow-Origin' header is present ↓

cause Cross-Origin Resource Sharing (CORS) errors occur when a browser-based client tries to make a request to a different origin (domain, protocol, or port) than the one it originated from, and the server does not explicitly allow it. While a proxy often bypasses this for the *client*, the proxy *itself* must correctly forward or modify headers if the target API has CORS restrictions.

fix

Ensure changeOrigin: true is set in the proxy options to correctly set the Host header of the proxy request to the target's host. If the target API still requires specific CORS headers, you may need to add proxyRes event listeners to modify the response headers coming *from* the proxied server before they reach the client, or configure CORS on the target API itself if possible.

Warnings

breaking The package `koa-server-http-proxy` is considered abandoned. It has not been updated since its initial release (v0.1.0) in 2017. Using an unmaintained package can lead to security vulnerabilities, compatibility issues with newer Koa or Node.js versions, and a lack of support for modern web standards. ↓

fix Migrate to actively maintained Koa proxy middleware solutions like `koa-proxies` (uses `http-proxy-middleware` v2.x/v3.x) or `@whitetrefoil/koa-http-proxy` (uses `node-http-proxy` directly).

gotcha This package relies on an outdated version of `http-proxy-middleware` (specifically `0.17.4`). The `http-proxy-middleware` library has undergone significant API changes and improvements, with current stable versions being v3.x. The options and behavior described in modern `http-proxy-middleware` documentation may not apply to this `koa-server-http-proxy` wrapper. ↓

fix Consult the documentation for `http-proxy-middleware` version `0.17.4` specifically, or, preferably, migrate to a more current Koa proxy solution that uses a recent `http-proxy-middleware` version.

gotcha Using `body-parser` or similar middleware before the proxy middleware can cause requests with a body (e.g., POST requests) to hang or behave unexpectedly. The `http-proxy-middleware` (and its underlying `node-http-proxy`) expects to read the request stream directly. ↓

fix Ensure that `koa-server-http-proxy` (or any proxy middleware) is applied before any middleware that consumes the request body, such as `koa-bodyparser` or `koa-body`. Process the body *after* the proxy has decided not to handle the request, or use `responseInterceptor` in modern `http-proxy-middleware` to handle bodies after proxying.

Install

npm install koa-server-http-proxy

yarn add koa-server-http-proxy

pnpm add koa-server-http-proxy

Imports

proxy
```
const proxy = require('koa-server-http-proxy')
```
This package primarily supports CommonJS syntax as it was published in 2017 (v0.1.0) and has not been updated since. ESM is not officially supported.

Quickstart

Demonstrates setting up a basic HTTP proxy for a Koa application, showing single and multiple target configurations with path rewriting.

const Koa = require('koa')
const app = new Koa()
const proxy = require('koa-server-http-proxy')

// Proxy all /api requests to https://news-at.zhihu.com
app.use(proxy('/api', {
  target: 'https://news-at.zhihu.com',
  pathRewrite: { '^/api': 'api/4/' }, // Rewrites /api/themes to api/4/themes
  changeOrigin: true // Changes the origin header to the target URL
}))

// Example of multiple proxy targets
const proxyTable = {
  '/json': {
    target: 'http://jsonplaceholder.typicode.com',
    pathRewrite: { '^/json': '' }, // Rewrites /json/posts to /posts
    changeOrigin: true
  },
  '/another-api': {
    target: 'https://api.example.com',
    changeOrigin: true
  }
}

Object.keys(proxyTable).forEach((context) => {
  const options = proxyTable[context]
  app.use(proxy(context, options))
})

app.listen(3000, () => {
  console.log('Koa proxy server listening on port 3000')
  console.log('Try: http://127.0.0.1:3000/api/themes')
  console.log('Try: http://127.0.0.1:3000/json/posts/1')
})