Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/2o3t/koa2-proxy-middleware

http proxy middleware for koa2
https://github.com/2o3t/koa2-proxy-middleware

2o3t cors http http-proxy-middleware https koa koa-proxy-middleware koa2 koa2-proxy-middleware middleware proxy

Last synced: about 1 month ago
JSON representation

http proxy middleware for koa2

Awesome Lists containing this project

README

        

# @2o3t/koa2-proxy-middleware

Node.js proxying made simple. Configure proxy middleware with ease for [koa2](https://github.com/koajs/koa).

Powered by [`http-proxy-middleware`](https://github.com/chimurai/http-proxy-middleware). [![GitHub stars](https://img.shields.io/github/stars/chimurai/http-proxy-middleware.svg?style=social&label=Star)](https://github.com/chimurai/http-proxy-middleware)

## TL;DR

Proxy `/api` requests to `http://www.2o3t.cn`

```javascript
const Koa = require('koa');
const app = new Koa();
const proxy = require('@2o3t/koa2-proxy-middleware');

// app.use(proxy({ target: 'http://www.2o3t.cn', changeOrigin: true }));

const Router = require('koa-router');
const router = new Router();
router.use(
'/api',
proxy({ target: 'http://www.2o3t.cn', changeOrigin: true })
);
app.use(router.routes())
.use(router.allowedMethods());
app.listen(3000);
// http://localhost:3000/api/foo/bar -> http://www.2o3t.cn/api/foo/bar
```

_All_ `http-proxy` [options](https://github.com/nodejitsu/node-http-proxy#options) can be used, along with some extra `http-proxy-middleware` [options](#options).

:bulb: **Tip:** Set the option `changeOrigin` to `true` for [name-based virtual hosted sites](http://en.wikipedia.org/wiki/Virtual_hosting#Name-based).

## Install

```javascript
$ npm install --save-dev @2o3t/koa2-proxy-middleware
// or
yarn add @2o3t/koa2-proxy-middleware
```

## Core concept

Proxy middleware configuration.

#### proxy([context,] config)

```javascript
const proxy = require('@2o3t/koa2-proxy-middleware');

const apiProxy = proxy('/api', { target: 'http://www.2o3t.cn' });
// \____/ \_____________________________/
// | |
// context options

// 'apiProxy' is now ready to be used as middleware in a server.
```

- **context**: Determine which requests should be proxied to the target host.
(more on [context matching](#context-matching))
- **options.target**: target host to proxy to. _(protocol + host)_

(full list of [`http-proxy-middleware` configuration options](#options))

#### proxy(uri [, config])

```javascript
// shorthand syntax for the example above:
const apiProxy = proxy('http://www.2o3t.cn/api');
```

More about the [shorthand configuration](#shorthand).

## Example

An example with `koa2` server.

```javascript
const Koa = require('koa');
const app = new Koa();
const proxy = require('@2o3t/koa2-proxy-middleware');

// proxy middleware options
const options = {
target: 'http://www.2o3t.cn', // target host
changeOrigin: true, // needed for virtual hosted sites
ws: true, // proxy websockets
pathRewrite: {
'^/api/old-path': '/api/new-path', // rewrite path
'^/api/remove/path': '/path' // remove base path
},
router: {
// when request.headers.host == 'dev.localhost:3000',
// override target 'http://www.2o3t.cn' to 'http://localhost:8000'
'dev.localhost:3000': 'http://localhost:8000'
}
};

// create the proxy (without context)
const exampleProxy = proxy(options);

app.use(exampleProxy)

app.use(ctx => {
console.log(ctx.status);
});

app.listen(3003);
```

## Context matching

Providing an alternative way to decide which requests should be proxied; In case you are not able to use the server's [`path` parameter](http://expressjs.com/en/4x/api.html#app.use) to mount the proxy or when you need more flexibility.

[RFC 3986 `path`](https://tools.ietf.org/html/rfc3986#section-3.3) is used for context matching.

```
foo://example.com:8042/over/there?name=ferret#nose
\_/ \______________/\_________/ \_________/ \__/
| | | | |
scheme authority path query fragment
```

- **path matching**

- `proxy({...})` - matches any path, all requests will be proxied.
- `proxy('/', {...})` - matches any path, all requests will be proxied.
- `proxy('/api', {...})` - matches paths starting with `/api`

- **multiple path matching**

- `proxy(['/api', '/ajax', '/someotherpath'], {...})`

- **wildcard path matching**

For fine-grained control you can use wildcard matching. Glob pattern matching is done by _micromatch_. Visit [micromatch](https://www.npmjs.com/package/micromatch) or [glob](https://www.npmjs.com/package/glob) for more globbing examples.

- `proxy('**', {...})` matches any path, all requests will be proxied.
- `proxy('**/*.html', {...})` matches any path which ends with `.html`
- `proxy('/*.html', {...})` matches paths directly under path-absolute
- `proxy('/api/**/*.html', {...})` matches requests ending with `.html` in the path of `/api`
- `proxy(['/api/**', '/ajax/**'], {...})` combine multiple patterns
- `proxy(['/api/**', '!**/bad.json'], {...})` exclusion

**Note**: In multiple path matching, you cannot use string paths and wildcard paths together.

- **custom matching**

For full control you can provide a custom function to determine which requests should be proxied or not.

```javascript
/**
* @return {Boolean}
*/
const filter = function(pathname, req) {
return pathname.match('^/api') && req.method === 'GET';
};

const apiProxy = proxy(filter, { target: 'http://www.2o3t.cn' });
```

## Options

### [`http-proxy-middleware` configuration options](https://github.com/chimurai/http-proxy-middleware#options)

### new options

- `option.proxyBody`: [Boolean|Function] Collect the results returned by the agent and assign them to `ctx.body`. Default: false.

```js
option.proxyBody: true,
// or
option.proxyBody: function(json, proxyRes, req, res, ctx) {
ctx.body = json;
}
```

## License

The MIT License (MIT)

Copyright (c) 2018-2019 Zyao89