Koa Better HTTP Proxy

Common errors

• TypeError: proxy is not a function

  cause Incorrect import statement for the default export.
  fix For ES Modules, use `import proxy from 'koa-better-http-proxy';`. For CommonJS, use `const proxy = require('koa-better-http-proxy');`.

• TypeError: app.use is not a function

  cause Koa application instance is not correctly initialized or the middleware is being applied to a non-Koa object.
  fix Ensure you have `import Koa from 'koa';` and `const app = new Koa();` at the start of your Koa application setup, and that `koa` is installed (`npm install koa`).

• Property 'ctx' does not exist on type 'Context'.

  cause Using an outdated or incompatible TypeScript type definition for Koa's Context object, or a version mismatch between Koa and the proxy types.
  fix Ensure `koa-better-http-proxy` is at least v0.2.2 for TypeScript types, and that `koa` and `@types/koa` are correctly installed and aligned with your Koa version. Sometimes, reinstalling `@types/koa` can resolve such issues.

• Error: Cannot find module 'koa'

  cause The `koa` package is not installed as a dependency in the project.
  fix Install Koa: `npm install koa` or `yarn add koa`.

Warnings

• breaking The `memoizeHost` option was removed as it was never truly supported. Code relying on this option will break.
  Fix: Remove the `memoizeHost` option from your proxy configuration. There is no direct replacement as its functionality was not viable.
• breaking Headers could leak across requests in certain scenarios, leading to incorrect or unintended behavior for subsequent requests using the same proxy instance.
  Fix: Upgrade to version 0.2.9 or higher to receive the fix for header isolation.
• gotcha The `proxyReqOptDecorator` function does not allow modification of the request path. Attempts to change the path within this decorator will not take effect.
  Fix: Use the `proxyReqPathResolver` option to modify the request path before it is sent to the proxied host. `proxyReqOptDecorator` is intended for modifying other request options like headers or agent settings.
• gotcha By default, `Connection: close` is no longer set on proxy requests. If your backend relies on this header for specific connection management, its absence might alter behavior.
  Fix: If `Connection: close` is required, manually add it using the `headers` option or `proxyReqOptDecorator`: `headers: { 'Connection': 'close' }`.
• gotcha The `userResDecorator` and `userResHeadersDecorator` functions pass `proxyRes` and `ctx` by reference. While this *can* be exploited to modify response headers directly, it is not a stable API and future releases may remove this 'exploit'.
  Fix: Avoid mutating `proxyRes` or `ctx` directly within decorators. Rely on dedicated options or hooks for header modification when they become available to ensure future compatibility. Focus `userResDecorator` on modifying response data and `userResHeadersDecorator` on modifying headers.

Install

• npm install koa-better-http-proxy npm
• yarn add koa-better-http-proxy yarn
• pnpm add koa-better-http-proxy pnpm

Imports

• proxy
  wrong:

  import { proxy } from 'koa-better-http-proxy';

  correct:

  import proxy from 'koa-better-http-proxy';

  The main proxy function is a default export.
• proxy
  wrong:

  const { proxy } = require('koa-better-http-proxy');

  correct:

  const proxy = require('koa-better-http-proxy');

  CommonJS `require` for the default export.
• ProxyOptions

  import type { ProxyOptions, Context } from 'koa-better-http-proxy';

  Import types for options and Koa Context when using TypeScript. Types were added in v0.2.2.

Quickstart

This example sets up a Koa server with `koa-better-http-proxy` to proxy requests starting with `/api` to `httpbin.org/anything`. It demonstrates path rewriting using `proxyReqPathResolver` and modifying the response body with `userResDecorator`.

import Koa from 'koa';
import proxy from 'koa-better-http-proxy';
import Router from '@koa/router';
import { URL } from 'url';

const app = new Koa();
const router = new Router();

router.all('/api/(.*)', proxy('httpbin.org', {
  port: 80,
  https: false,
  proxyReqPathResolver: (ctx) => {
    const url = new URL(ctx.url, `http://${ctx.host}`);
    console.log(`Proxying request path: ${url.pathname}${url.search}`);
    return `/anything${url.pathname.substring('/api'.length)}${url.search}`;
  },
  userResDecorator: (proxyRes, proxyResData, ctx) => {
    const data = JSON.parse(proxyResData.toString('utf8'));
    data.proxiedBy = 'koa-better-http-proxy';
    data.originalUrl = ctx.url;
    return JSON.stringify(data);
  }
}));

app.use(router.routes());
app.use(router.allowedMethods());

app.listen(3000, () => {
  console.log('Koa proxy server listening on port 3000');
  console.log('Try: curl http://localhost:3000/api/my-test?q=hello');
});