Koa HTTP Proxy (Abandoned)

0.0.1 verified Thu Apr 23 auth: no javascript abandoned

This package, `koa-http-proxy`, is an extremely early-stage Koa middleware designed to proxy HTTP requests, wrapping the `nodejitsu/node-http-proxy` library. It is currently at version 0.0.1 and was last published approximately 9 years ago, indicating it is effectively abandoned and unmaintained. Due to its age, it is highly unlikely to be compatible with modern Koa (v2.x or v3.x) and recent Node.js versions (v12+ or v18+ required by Koa 2.x/3.x respectively). Its key differentiator was its direct integration with Koa, but it lacks the features, stability, and security updates found in more actively maintained Koa proxy solutions like `koa-proxies` or `koa-better-http-proxy`. This package should not be used in new projects.

Common errors

error TypeError: app.use is not a function ↓

cause Using `koa-http-proxy` (an older Koa 1.x style middleware) with a modern Koa application (Koa 2.x or 3.x) that expects `async function (ctx, next)` middleware signature. Koa 1.x used generator functions.

fix

This package is incompatible with modern Koa. Replace koa-http-proxy with a contemporary Koa proxy solution like koa-proxies or koa-better-http-proxy.

error ERR_REQUIRE_ESM ↓

cause Attempting to import `koa-http-proxy` using `import` syntax in an ES module environment. The package is CommonJS-only.

fix

This package is not designed for modern ESM projects. Use an ESM-compatible proxy middleware for Koa, such as @whitetrefoil/koa-http-proxy (v2.0.0+) or koa-proxies.

error Proxying requests hangs or times out without response. ↓

cause Likely due to incompatibility with newer Node.js versions, incorrect `node-http-proxy` options, or issues with body parsing middleware conflicting with the proxy. Older proxy libraries can struggle with modern HTTP features or stream handling. Also, using a body parser middleware before the proxy can cause requests with bodies to hang.

fix

Do not use koa-http-proxy. If using an alternative Koa proxy, ensure no koa-bodyparser or similar middleware processes the request body *before* the proxy middleware for routes being proxied. Consult the documentation of your chosen proxy middleware for correct configuration.

Warnings

breaking This package is unmaintained (last published 9 years ago at 0.0.1) and is likely incompatible with modern Koa (v2.x or v3.x) and Node.js versions (v12+ required for Koa 2.x, v18+ for Koa 3.x). Attempting to use it will likely result in runtime errors or unexpected behavior. ↓

fix Do not use this package. Migrate to a actively maintained Koa proxy middleware like `koa-proxies` or `koa-better-http-proxy`.

gotcha Security vulnerabilities may be present due to lack of maintenance. Unmaintained HTTP proxy libraries can expose applications to various risks, including request manipulation, header injection, or denial-of-service attacks. The underlying `node-http-proxy` also has an older codebase. ↓

fix Migrate to a well-maintained and regularly updated proxy solution to ensure security patches and best practices are applied. Carefully review the configuration and ensure proper input validation.

breaking This package was developed for an older generation of Koa (likely Koa 1.x which used generator functions). Koa 2.x and 3.x transitioned to async/await middleware, which this package's 0.0.1 version will not support, causing `app.use` to fail or the middleware chain to break. ↓

fix Upgrade to a Koa proxy middleware designed for Koa 2.x/3.x `async/await` patterns. For example, `koa-proxies` or `koa-better-http-proxy`.

gotcha Configuration options are directly passed to `node-http-proxy`. This requires developers to be familiar with the older API of `node-http-proxy`, which might itself have quirks or unpatched issues. ↓

fix Consult the documentation for the specific version of `node-http-proxy` it wraps (likely very old). However, the best fix is to use a modern Koa proxy that has a more up-to-date and documented API.

gotcha A general Koa security concern: if `app.proxy = true` is set in your Koa application, an attacker might be able to influence `ctx.hostname` via crafted `Host` or `X-Forwarded-Host` headers, leading to 'userinfo host header injection' (CVE-2026-27959). This applies to Koa versions below 2.16.4 and 3.1.2. ↓

fix Ensure your Koa application is updated to versions 2.16.4 or 3.1.2 and higher to mitigate CVE-2026-27959. Always validate `ctx.hostname` if used for security-sensitive URL construction.

Install

npm install koa-http-proxy

yarn add koa-http-proxy

pnpm add koa-http-proxy

Imports

$proxy
wrong
```
import $proxy from 'koa-http-proxy';
```
correct
```
const $proxy = require('koa-http-proxy');
```
This package is CommonJS-only based on the provided example and its age. It does not support ES modules directly.
koa
wrong
```
import Koa from 'koa';
```
correct
```
const Koa = require('koa');
```
While Koa itself supports ESM in newer versions, the quickstart example for this package uses CommonJS. For modern Koa, `import Koa from 'koa';` is standard.

Quickstart

Demonstrates setting up a basic Koa application using koa-http-proxy to proxy all incoming requests to 'https://www.google.com'.

const Koa = require('koa');
const $proxy = require('koa-http-proxy');

const app = new Koa();

app.use($proxy('https://www.google.com', {
  // Example of passing options to node-http-proxy
  // For full options, refer to the node-http-proxy documentation (which is also older)
  // e.g., to change origin:
  // changeOrigin: true
}));

app.listen(3000, () => {
  console.log('Koa proxy server listening on port 3000');
  console.log('Proxying requests to https://www.google.com');
  console.log('Try visiting http://localhost:3000 in your browser.');
});