@2o3t/koa2-proxy-middleware
Version:
http proxy middleware for koa2
183 lines (128 loc) • 5.72 kB
Markdown
# @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). [](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