10 |
11 | A super fast, framework agnostic Node.js API Gateway for the masses ❤️
12 | *Docker images: https://hub.docker.com/repository/docker/kyberneees/rproxy*
13 | > Since v2.3.0, [AWS Lambda](https://www.youtube.com/watch?v=EBSdyoO3goc) proxying integration is supported via [`http-lambda-proxy`](https://www.npmjs.com/package/http-lambda-proxy) 🔥
14 | > Since v3.1.0, WebSockets proxying is supported via [`faye-websocket`](https://www.npmjs.com/package/faye-websocket) 🔥
15 |
16 | Read more online:
17 | - A “.js” API Gateway for the masses: https://itnext.io/a-js-api-gateway-for-the-masses-a12fdb9e961c
18 |
19 | ## Install
20 | ```js
21 | npm i fast-gateway
22 | ```
23 |
24 | ## Usage
25 | ### Gateway
26 | ```js
27 | const gateway = require('fast-gateway')
28 | const server = gateway({
29 | routes: [{
30 | prefix: '/service',
31 | target: 'http://127.0.0.1:3000'
32 | }]
33 | })
34 |
35 | server.start(8080)
36 | ```
37 | ### Remote Service
38 | ```js
39 | const service = require('restana')()
40 | service.get('/get', (req, res) => res.send('Hello World!'))
41 |
42 | service.start(3000)
43 | ```
44 | ### Testing
45 | ```bash
46 | curl -v http://127.0.0.1:8080/service/get
47 | ```
48 | ## More
49 | - Website and documentation: https://fgw.21no.de
--------------------------------------------------------------------------------
/benchmark/gateway-cluster.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const cluster = require('cluster')
4 | const os = require('os')
5 |
6 | if (cluster.isMaster) {
7 | const cpuCount = os.cpus().length
8 | for (let i = 0; i < cpuCount; i++) {
9 | cluster.fork()
10 | }
11 | } else {
12 | const gateway = require('../index')
13 |
14 | const server = gateway({
15 | routes: [{
16 | prefix: '/service',
17 | target: 'http://127.0.0.1:3000'
18 | }]
19 | })
20 |
21 | server.start(8080)
22 | }
23 |
24 | cluster.on('exit', (worker) => {
25 | cluster.fork()
26 | })
27 |
--------------------------------------------------------------------------------
/benchmark/gateway.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('../index')
4 |
5 | const server = gateway({
6 | routes: [{
7 | prefix: '/service',
8 | target: 'http://127.0.0.1:3000'
9 | }]
10 | })
11 |
12 | server.start(8080)
13 |
--------------------------------------------------------------------------------
/benchmark/service.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const service = require('restana')()
4 | service.get('/get', (req, res) => res.send('Hello World!'))
5 |
6 | service.start(3000)
7 |
--------------------------------------------------------------------------------
/benchmark/websocket/artillery-perf1.yml:
--------------------------------------------------------------------------------
1 | config:
2 | target: "ws://localhost:8080/echo"
3 | phases:
4 | - duration: 15
5 | arrivalRate: 20
6 | rampTo: 500
7 | name: "Ramping up the load"
8 | scenarios:
9 | - engine: "ws"
10 | flow:
11 | - send: 'echo me'
--------------------------------------------------------------------------------
/benchmark/websocket/echo.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('../../index')
4 | const WebSocket = require('faye-websocket')
5 | const http = require('http')
6 |
7 | gateway({
8 | routes: [{
9 | proxyType: 'websocket',
10 | prefix: '/echo',
11 | target: 'ws://127.0.0.1:3000'
12 | }]
13 | }).start(8080)
14 |
15 | const service = http.createServer()
16 | service.on('upgrade', (request, socket, body) => {
17 | if (WebSocket.isWebSocket(request)) {
18 | const ws = new WebSocket(request, socket, body)
19 |
20 | ws.on('message', (event) => {
21 | ws.send(event.data)
22 | })
23 | }
24 | })
25 | service.listen(3000)
26 |
--------------------------------------------------------------------------------
/demos/basic-express.js:
--------------------------------------------------------------------------------
1 | /* eslint-disable prefer-regex-literals */
2 |
3 | 'use strict'
4 |
5 | const gateway = require('../index')
6 | const express = require('express')
7 | const PORT = process.env.PORT || 8080
8 |
9 | gateway({
10 | server: express(),
11 |
12 | middlewares: [require('cors')(), require('helmet')()],
13 |
14 | routes: [
15 | {
16 | prefix: new RegExp('/public/.*'), // Express.js v5 requires a RegExp object
17 | // prefix: '/public', // Compatible with Express.js v4,
18 |
19 | urlRewrite: (req) => req.url.replace('/public', ''),
20 | target: 'http://localhost:3000',
21 | docs: {
22 | name: 'Public Service',
23 | endpoint: 'swagger.json',
24 | type: 'swagger'
25 | }
26 | },
27 | {
28 | prefix: new RegExp('/admin/.*'), // Express.js v5 requires a RegExp object
29 | // prefix: '/admin', // Compatible with Express.js v4,
30 | target: 'http://localhost:3001',
31 | middlewares: [
32 | /*
33 | require('express-jwt').expressjwt({
34 | secret: 'shhhhhhared-secret',
35 | algorithms: ['HS256'],
36 | }),
37 | */
38 | ]
39 | }
40 | ]
41 | }).listen(PORT, () => {
42 | console.log(`API Gateway listening on ${PORT} port!`)
43 | })
44 |
45 | const service1 = require('restana')({})
46 | service1
47 | .get('/hi', (req, res) => res.send('Hello World!'))
48 | .start(3000)
49 | .then(() => console.log('Public service listening on 3000 port!'))
50 |
51 | const service2 = require('restana')({})
52 | service2
53 | .get('/admin/users', (req, res) => res.send([]))
54 | .start(3001)
55 | .then(() => console.log('Admin service listening on 3001 port!'))
56 |
--------------------------------------------------------------------------------
/demos/basic-hostnames.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('../index')
4 | const PORT = process.env.PORT || 8080
5 | const http = require('http')
6 | const restana = require('restana')
7 |
8 | // binding hostnames to prefixes
9 | const hostnames2prefix = [{
10 | prefix: '/api',
11 | hostname: 'api.company.tld'
12 | }]
13 | // instantiate hostnames hook, this will prefix request urls according to data in hostnames2prefix
14 | const hostnamesHook = require('./../lib/hostnames-hook')(hostnames2prefix)
15 |
16 | // separately instantiate and configure restana application
17 | const app = restana()
18 | const server = http.createServer((req, res) => {
19 | hostnamesHook(req, res, () => {
20 | return app(req, res)
21 | })
22 | })
23 |
24 | // gateway configuration
25 | gateway({
26 | server: app, // injecting existing restana application
27 | middlewares: [
28 | ],
29 |
30 | routes: [{
31 | prefix: '/api',
32 | target: 'http://localhost:3000'
33 | }]
34 | })
35 |
36 | server.listen(PORT)
37 |
38 | const origin = require('restana')({})
39 | origin
40 | .get('/hi', (req, res) => res.send('Hello World!'))
41 | .start(3000)
42 |
--------------------------------------------------------------------------------
/demos/basic.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('./../index')
4 | const PORT = process.env.PORT || 8080
5 |
6 | const { expressjwt: jwt } = require('express-jwt')
7 |
8 | gateway({
9 | middlewares: [
10 | require('cors')(),
11 | require('helmet')()
12 | ],
13 |
14 | routes: [{
15 | prefix: '/public',
16 | target: 'http://localhost:3000'
17 | /*
18 | // applicable in case Swagger Definitions would be supported on downstream service
19 | docs: {
20 | name: 'Public Service',
21 | endpoint: 'swagger.json',
22 | type: 'swagger'
23 | }
24 | */
25 | }, {
26 | prefix: '/admin',
27 | target: 'http://localhost:3001',
28 | middlewares: [
29 | jwt({
30 | secret: 'shhhhhhared-secret',
31 | algorithms: ['HS256']
32 | })
33 | ]
34 | }, {
35 | // this route definition makes http://localhost:3000 (/public) a default service if other routes prefixes are omitted
36 | prefix: '/*',
37 | pathRegex: '',
38 | target: 'http://localhost:3000'
39 | }]
40 | }).start(PORT).then(server => {
41 | console.log(`API Gateway listening on ${PORT} port!`)
42 | })
43 |
44 | const service1 = require('restana')({})
45 | service1
46 | .get('/hi', (req, res) => res.send('Hello World!'))
47 | .get('/hi-chunked', (req, res) => {
48 | res.write('Hello ')
49 | res.write('World!')
50 | res.end()
51 | })
52 | .start(3000).then(() => console.log('Public service listening on 3000 port!'))
53 |
54 | const service2 = require('restana')({})
55 | service2
56 | .get('/users', (req, res) => res.send([]))
57 | .start(3001).then(() => console.log('Admin service listening on 3001 port!'))
58 |
--------------------------------------------------------------------------------
/demos/before-end-middleware.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('./../index')
4 | const PORT = process.env.PORT || 8080
5 |
6 | const middleware503to404 = (req, res, next) => {
7 | const end = res.end
8 | res.end = function (...args) {
9 | if (res.statusCode === 503) {
10 | res.statusCode = 404
11 | }
12 | return end.apply(res, args)
13 | }
14 |
15 | return next()
16 | }
17 |
18 | gateway({
19 | routes: [{
20 | prefix: '/service',
21 | target: 'http://127.0.0.1:3000',
22 | middlewares: [
23 | middleware503to404
24 | ]
25 | }]
26 | }).start(PORT).then(server => {
27 | console.log(`API Gateway listening on ${PORT} port!`)
28 | })
29 |
--------------------------------------------------------------------------------
/demos/circuitbreaker.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('../index')
4 | const onEnd = require('on-http-end')
5 | const CircuitBreaker = require('opossum')
6 |
7 | const options = {
8 | timeout: 1500, // If our function takes longer than "timeout", trigger a failure
9 | errorThresholdPercentage: 50, // When 50% of requests fail, trip the circuit
10 | resetTimeout: 30 * 1000 // After 30 seconds, try again.
11 | }
12 | const breaker = new CircuitBreaker(([req, res, url, proxy, proxyOpts]) => {
13 | return new Promise((resolve, reject) => {
14 | proxy(req, res, url, proxyOpts)
15 | onEnd(res, () => resolve()) // you can optionally evaluate response codes here...
16 | })
17 | }, options)
18 |
19 | breaker.fallback(([req, res], err) => {
20 | if (err.code === 'EOPENBREAKER') {
21 | res.send({
22 | message: 'Upps, looks like we are under heavy load. Please try again in 30 seconds!'
23 | }, 503)
24 | }
25 | })
26 |
27 | gateway({
28 | routes: [{
29 | proxyHandler: (...params) => breaker.fire(params),
30 | prefix: '/public',
31 | target: 'http://localhost:3000'
32 | }]
33 | }).start(8080).then(() => console.log('API Gateway listening on 8080 port!'))
34 |
35 | const service = require('restana')({})
36 | service
37 | .get('/longop', (req, res) => setTimeout(() => res.send('This operation will trigger the breaker failure counter...'), 2000))
38 | .get('/hi', (req, res) => res.send('Hello World!'))
39 | .start(3000).then(() => console.log('Public service listening on 3000 port!'))
40 |
--------------------------------------------------------------------------------
/demos/consistent-hashing.js:
--------------------------------------------------------------------------------
1 | // Gateway implementation
2 |
3 | 'use strict'
4 |
5 | const gateway = require('../index')
6 | const ConsistentHash = require('consistent-hash')
7 |
8 | const targets = [
9 | 'http://localhost:3000',
10 | 'http://localhost:3001',
11 | 'http://localhost:3002'
12 | ]
13 |
14 | const consistentHash = new ConsistentHash()
15 | targets.forEach((target) => consistentHash.add(target))
16 |
17 | gateway({
18 | routes: [
19 | {
20 | proxyHandler: (req, res, url, proxy, proxyOpts) => {
21 | const target = consistentHash.get(req.path)
22 | proxyOpts.base = target
23 |
24 | return proxy(req, res, url, proxyOpts)
25 | },
26 | prefix: '/api'
27 | }
28 | ]
29 | })
30 | .start(8080)
31 | .then(() => console.log('API Gateway listening on 8080 port!'))
32 |
33 | // Below is the services implementation, commonly located on separated projects
34 | const express = require('express')
35 |
36 | // service1.js
37 | const service1 = express()
38 | service1.get('/orders/:orderId', (req, res) => {
39 | res.header('Service-Id', 'service1')
40 | res.send('Order from service 1!')
41 | })
42 | service1.listen(3000, () => {
43 | console.log('Service 1 running!')
44 | })
45 |
46 | // service2.js
47 | const service2 = express()
48 |
49 | service2.get('/orders/:orderId', (req, res) => {
50 | res.header('Service-Id', 'service2')
51 | res.send('Order from service 2!')
52 | })
53 |
54 | service2.listen(3001, () => {
55 | console.log('Service 2 running!')
56 | })
57 |
58 | // service3.js
59 | const service3 = express()
60 |
61 | service3.get('/orders/:orderId', (req, res) => {
62 | res.header('Service-Id', 'service3')
63 | res.send('Order from service 3!')
64 | })
65 |
66 | service3.listen(3002, () => {
67 | console.log('Service 3 running!')
68 | })
69 |
--------------------------------------------------------------------------------
/demos/hooks-ts-example.ts:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | import { IncomingMessage } from 'http'
4 | import gateway from '../index'
5 | import { http } from '../lib/default-hooks'
6 | import { ServerResponse } from 'http'
7 |
8 | gateway({
9 | routes: [
10 | {
11 | prefix: '/httpbin',
12 | target: 'https://httpbin.org',
13 | hooks: {
14 | onRequest: (req: IncomingMessage, res: ServerResponse) => {
15 | console.log('Request to httpbin.org')
16 |
17 | return false
18 | },
19 | onResponse: (
20 | req: IncomingMessage,
21 | res: ServerResponse,
22 | proxyRequest: IncomingMessage,
23 | ) => {
24 | console.log('POST request to httpbin.org')
25 |
26 | // continue forwarding the response
27 | http.onResponse(req, res, proxyRequest)
28 | },
29 | },
30 | },
31 | ],
32 | }).start(8080)
33 |
--------------------------------------------------------------------------------
/demos/hooks.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('./../index')
4 | const PORT = process.env.PORT || 8080
5 |
6 | gateway({
7 | routes: [{
8 | prefix: '/service',
9 | target: 'http://127.0.0.1:3000',
10 | hooks: {
11 | async onRequest (req, res) {
12 | // you can alter the request object here
13 | // adding headers:
14 | req.headers['x-header'] = 'value'
15 | },
16 | rewriteHeaders (headers) {
17 | // you can alter response headers here
18 | return headers
19 | },
20 | onResponse (req, res, stream) {
21 | // you can alter the origin response and remote response here
22 | // default implementation explained here:
23 | // https://www.npmjs.com/package/fast-gateway#onresponse-hook-default-implementation
24 | }
25 | }
26 | }]
27 | }).start(PORT).then(server => {
28 | console.log(`API Gateway listening on ${PORT} port!`)
29 | })
30 |
--------------------------------------------------------------------------------
/demos/https-example.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('./../index')
4 |
5 | gateway({
6 | routes: [{
7 | prefix: '/httpbin',
8 | target: 'https://httpbin.org'
9 | }]
10 | }).start(8080)
11 |
--------------------------------------------------------------------------------
/demos/load-balancer-multiple-proxies.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('../index')
4 | const { P2cBalancer } = require('load-balancers')
5 | const lambdaProxy = require('http-lambda-proxy')
6 | const { onRequestNoOp, onResponse } = require('./../lib/default-hooks').lambda
7 |
8 | // @TODO: update the list of target origins or proxy instances
9 | const targets = [
10 | 'http://localhost:3000',
11 | lambdaProxy({
12 | target: process.env.FUNCTION_NAME,
13 | region: process.env.AWS_REGION
14 | })
15 | ]
16 | const balancer = new P2cBalancer(targets.length)
17 |
18 | gateway({
19 | routes: [{
20 | proxyHandler: (req, res, url, proxy, proxyOpts) => {
21 | const target = targets[balancer.pick()]
22 | if (typeof target === 'string') {
23 | proxyOpts.base = target
24 | } else {
25 | proxyOpts.onResponse = onResponse
26 | proxyOpts.onRequest = onRequestNoOp
27 | proxy = target
28 | }
29 |
30 | return proxy(req, res, url, proxyOpts)
31 | },
32 | prefix: '/balanced'
33 | }]
34 | }).start(8080).then(() => console.log('API Gateway listening on 8080 port!'))
35 |
36 | const service = require('restana')({})
37 | service
38 | .get('/get', (req, res) => res.send({ msg: 'Hello from service 1!' }))
39 | .start(3000).then(() => console.log('Public service listening on 3000 port!'))
40 |
41 | // Usage: curl 'http://localhost:8080/balanced/get'
42 |
--------------------------------------------------------------------------------
/demos/multiple-hooks.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('./../index')
4 | const PORT = process.env.PORT || 8080
5 |
6 | const { multipleHooks } = require('fg-multiple-hooks')
7 |
8 | const hook1 = async (req, res) => {
9 | console.log('hook1 with logic 1 called')
10 | // res.send('hook failed here');
11 | return false // do not abort the request
12 | }
13 |
14 | const hook2 = async (req, res) => {
15 | console.log('hook2 with logic 2 called')
16 | const shouldAbort = true
17 | if (shouldAbort) {
18 | res.send('handle a rejected request here')
19 | }
20 | return shouldAbort
21 | }
22 |
23 | gateway({
24 | routes: [{
25 | prefix: '/service',
26 | target: 'http://127.0.0.1:3000',
27 | hooks: {
28 | onRequest: (req, res) => multipleHooks(req, res, hook1, hook2), // you can add as many hooks as you please
29 | onResponse (req, res, stream) {
30 | // you can alter the origin response and remote response here
31 | // default implementation explained here:
32 | // https://www.npmjs.com/package/fast-gateway#onresponse-hook-default-implementation
33 | }
34 | }
35 | }]
36 | }).start(PORT).then(server => {
37 | console.log(`API Gateway listening on ${PORT} port!`)
38 | })
39 |
--------------------------------------------------------------------------------
/demos/post-processing.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const toArray = require('stream-to-array')
4 | const gateway = require('../index')
5 |
6 | gateway({
7 | routes: [{
8 | prefix: '/httpbin',
9 | target: 'https://httpbin.org',
10 | hooks: {
11 | async onResponse (req, res, stream) {
12 | // collect all streams parts
13 | const resBuffer = Buffer.concat(await toArray(stream))
14 |
15 | // parse response body, for example: JSON
16 | const payload = JSON.parse(resBuffer)
17 | // modify the response, for example adding new properties
18 | payload.newProperty = 'post-processing'
19 |
20 | // stringify response object again
21 | const newResponseBody = JSON.stringify(payload)
22 |
23 | // set new content-length header
24 | res.setHeader('content-length', '' + Buffer.byteLength(newResponseBody))
25 | // set response statusCode
26 | res.statusCode = stream.statusCode
27 |
28 | // send new response payload
29 | res.end(newResponseBody)
30 | }
31 | }
32 | }]
33 | }).start(8080)
34 |
--------------------------------------------------------------------------------
/demos/rate-limit.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('../index')
4 | const rateLimit = require('express-rate-limit')
5 | const requestIp = require('request-ip')
6 |
7 | gateway({
8 | middlewares: [
9 | // acquire request IP
10 | (req, res, next) => {
11 | req.ip = requestIp.getClientIp(req)
12 | return next()
13 | },
14 | // rate limiter
15 | rateLimit({
16 | windowMs: 1 * 60 * 1000, // 1 minutes
17 | max: 60, // limit each IP to 60 requests per windowMs
18 | handler: (req, res) => {
19 | res.send('Too many requests, please try again later.', 429)
20 | }
21 | })
22 | ],
23 | routes: [{
24 | prefix: '/public',
25 | target: 'http://localhost:3000'
26 | }]
27 | }).start(8080).then(() => console.log('API Gateway listening on 8080 port!'))
28 |
29 | const service = require('restana')({})
30 | service
31 | .get('/hi', (req, res) => res.send('Hello World!'))
32 | .start(3000).then(() => console.log('Public service listening on 3000 port!'))
33 |
--------------------------------------------------------------------------------
/demos/ssl-termination.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('./../index')
4 | const PORT = process.env.PORT || 4443
5 | const https = require('https')
6 | const pem = require('pem')
7 |
8 | pem.createCertificate({
9 | days: 1,
10 | selfSigned: true
11 | }, (err, keys) => {
12 | if (err) console.error(err)
13 |
14 | gateway({
15 | restana: {
16 | server: https.createServer({
17 | key: keys.serviceKey,
18 | cert: keys.certificate
19 | })
20 | },
21 | middlewares: [
22 | ],
23 |
24 | routes: [{
25 | prefix: '/api',
26 | target: 'http://localhost:3000'
27 | }]
28 | }).start(PORT).then(server => {
29 | console.log(`API Gateway listening on ${PORT} port!`)
30 | })
31 |
32 | const api = require('restana')({})
33 | api.get('/ssl-protected', (req, res) => {
34 | res.send('SSL Terminated!')
35 | })
36 |
37 | api.start(3000).then(() => console.log('API service listening on 3000 port!'))
38 | })
39 |
--------------------------------------------------------------------------------
/demos/target-load-balancer.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('../index')
4 | const { P2cBalancer } = require('load-balancers')
5 |
6 | // @TODO: update the list of target origins
7 | const targets = [
8 | 'http://localhost:3000',
9 | 'https://httpbin.org'
10 | ]
11 | const balancer = new P2cBalancer(targets.length)
12 |
13 | gateway({
14 | routes: [{
15 | proxyHandler: (req, res, url, proxy, proxyOpts) => {
16 | proxyOpts.base = targets[balancer.pick()]
17 |
18 | return proxy(req, res, url, proxyOpts)
19 | },
20 | prefix: '/balanced'
21 | }]
22 | }).start(8080).then(() => console.log('API Gateway listening on 8080 port!'))
23 |
24 | const service = require('restana')({})
25 | service
26 | .get('/get', (req, res) => res.send({ msg: 'Hello from service 1!' }))
27 | .start(3000).then(() => console.log('Public service listening on 3000 port!'))
28 |
29 | // Usage: curl 'http://localhost:8080/balanced/get'
30 |
--------------------------------------------------------------------------------
/demos/url-rewrite.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('../index')
4 | const PORT = process.env.PORT || 8080
5 |
6 | gateway({
7 | routes: [{
8 | pathRegex: '',
9 | prefix: '/customers/:customerId',
10 | target: 'http://localhost:3000',
11 | urlRewrite: ({ params: { customerId } }) => `/users/${customerId}`
12 | }]
13 | }).start(PORT).then(server => {
14 | console.log(`API Gateway listening on ${PORT} port!`)
15 | })
16 |
17 | const service = require('restana')({})
18 | service
19 | .get('/users/:id', (req, res) => res.send('Hello ' + req.params.id))
20 | .start(3000).then(() => console.log('Service listening on 3000 port!'))
21 |
--------------------------------------------------------------------------------
/demos/ws-proxy.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const gateway = require('./../index')
4 | const PORT = process.env.PORT || 8080
5 |
6 | gateway({
7 | routes: [{
8 | // ... other HTTP or WebSocket routes
9 | }, {
10 | proxyType: 'websocket',
11 | prefix: '/echo',
12 | target: 'ws://ws.ifelse.io',
13 | hooks: {
14 | onOpen: (ws, searchParams) => {
15 |
16 | }
17 | }
18 | }]
19 | }).start(PORT).then(server => {
20 | console.log(`API Gateway listening on ${PORT} port!`)
21 | })
22 |
--------------------------------------------------------------------------------
/docs/.nojekyll:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/BackendStack21/fast-gateway/944c17e5fba73a280674e0fcd03b030b9cd8f939/docs/.nojekyll
--------------------------------------------------------------------------------
/docs/CNAME:
--------------------------------------------------------------------------------
1 | fgw.21no.de
--------------------------------------------------------------------------------
/docs/README.md:
--------------------------------------------------------------------------------
1 | # Introduction
2 |
3 | [](https://github.com/BackendStack21/fast-gateway/actions/workflows/tests.yaml)
4 | [](https://www.npmjs.com/package/fast-gateway)
5 | [](https://www.npmjs.com/package/fast-gateway)
6 | [](https://www.npmjs.com/package/fast-gateway)
7 | [](https://www.npmjs.com/package/fast-gateway)
8 | [](https://github.com/jkyberneees/fast-gateway)
9 |
10 | 
11 |
12 | A super fast, framework agnostic Node.js API Gateway for the masses ❤️
13 | _Docker images: https://hub.docker.com/repository/docker/kyberneees/rproxy_
14 |
15 | > Since v2.3.0, [AWS Lambda](https://www.youtube.com/watch?v=EBSdyoO3goc) proxying integration is supported via [`http-lambda-proxy`](https://www.npmjs.com/package/http-lambda-proxy) 🔥
16 | > Since v3.1.0, WebSockets proxying is supported via [`faye-websocket`](https://www.npmjs.com/package/faye-websocket) 🔥
17 |
18 | Read more online:
19 |
20 | - A “.js” API Gateway for the masses: https://itnext.io/a-js-api-gateway-for-the-masses-a12fdb9e961c
21 |
22 | # Install
23 |
24 | ```js
25 | npm i fast-gateway
26 | ```
27 |
28 | # Usage
29 |
30 | Next we describe two examples proxying HTTP and Lambda downstream services.
31 |
32 | > For simplicity of reading, both examples are separated, however a single gateway configuration supports all routes configurations.
33 |
34 | ## HTTP proxying
35 |
36 | ### Gateway
37 |
38 | ```js
39 | const gateway = require('fast-gateway')
40 | const server = gateway({
41 | routes: [
42 | {
43 | prefix: '/service',
44 | target: 'http://127.0.0.1:3000',
45 | },
46 | ],
47 | })
48 |
49 | server.start(8080)
50 | ```
51 |
52 | ### Remote Service
53 |
54 | ```js
55 | const service = require('restana')()
56 | service.get('/get', (req, res) => res.send('Hello World!'))
57 |
58 | service.start(3000)
59 | ```
60 |
61 | ## AWS Lambda proxying
62 |
63 | ### Gateway
64 |
65 | ```bash
66 | npm i http-lambda-proxy
67 | ```
68 |
69 | ```js
70 | const gateway = require('fast-gateway')
71 | const server = gateway({
72 | routes: [
73 | {
74 | prefix: '/service',
75 | target: 'my-lambda-serverless-api',
76 | proxyType: 'lambda',
77 | proxyConfig: {
78 | region: 'eu-central-1',
79 | },
80 | },
81 | ],
82 | })
83 |
84 | server.start(8080)
85 | ```
86 |
87 | > You might also want to read: [Setting AWS Credentials in Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html)
88 |
89 | ### Function implementation
90 |
91 | ```js
92 | const serverless = require('serverless-http')
93 | const json = require('serverless-json-parser')
94 | const restana = require('restana')
95 |
96 | const service = restana()
97 | service.use(json())
98 |
99 | // routes
100 | service.get('/get', (req, res) => {
101 | res.send({msg: 'Go Serverless!'})
102 | })
103 | service.post('/post', (req, res) => {
104 | res.send(req.body)
105 | })
106 |
107 | // export handler
108 | module.exports.handler = serverless(service)
109 | ```
110 |
111 | # Configuration options explained
112 |
113 | ```js
114 | {
115 | // Optional server instance. Any HTTP framework that supports the following signature is compatible:
116 | // - server[HTTP_METHOD](pattern, [middleware1, middleware2,], handler)
117 | //
118 | // Known compatible frameworks: Restana, Express.js
119 | // If omitted, restana is used as default HTTP framework
120 | server,
121 | // Optional restana library configuration (https://www.npmjs.com/package/restana#configuration)
122 | // Please note that if "server" is provided, this settings are ignored.
123 | restana: {},
124 | // Optional global middlewares in the format: (req, res, next) => next()
125 | // Default value: []
126 | middlewares: [],
127 | // Optional global value for routes "pathRegex". Default value: '/*'
128 | pathRegex: '/*',
129 | // Optional global requests timeout value (given in milliseconds). Default value: '0' (DISABLED)
130 | // Ignored if proxyType = 'lambda'
131 | timeout: 0,
132 | // Optional "target" value that overrides the routes "target" config value. Feature intended for testing purposes.
133 | targetOverride: "https://yourdev.api-gateway.com",
134 | // Optional "Proxy Factory" implementation, allows integration of custom proxying strategies.
135 | // Behavior:
136 | // - If it returns any value (e.g. a custom proxy), that value will be used directly.
137 | // - If it returns `undefined` (or does not return anything), the default factory from `fast-gateway` will be used as a fallback.
138 | // - If it returns `null`, no proxy will be used and the default factory will be skipped entirely.
139 | // Default: the built-in proxy factory from `fast-gateway`
140 | proxyFactory: ({ proxyType, opts, route }) => {...}
141 | // Optional toggle for exposing minimal documentation of registered services at `GET /services.json`
142 | // Default value: true
143 | enableServicesEndpoint: true
144 |
145 | // HTTP proxy
146 | routes: [{
147 | // Optional proxy type definition. Supported values: http, http-legacy, lambda
148 | // Modules:
149 | // - http: fast-proxy-lite
150 | // - http-legacy: fast-proxy
151 | // - lambda: http-lambda-proxy
152 | // Default value: http
153 | proxyType: 'http'
154 | // Optional proxy library configuration:
155 | // - fast-proxy-lite: https://www.npmjs.com/package/fast-proxy-lite#options
156 | // - fast-proxy: https://www.npmjs.com/package/fast-proxy#options
157 | // - http-lambda-proxy: https://www.npmjs.com/package/http-lambda-proxy#options
158 | // Default value: {}
159 | proxyConfig: {},
160 | // Optional proxy handler function. Default value: (req, res, url, proxy, proxyOpts) => proxy(req, res, url, proxyOpts)
161 | proxyHandler: () => {},
162 | // Optional path matching regex. Default value: '/*'
163 | // In order to disable the 'pathRegex' at all, you can use an empty string: ''. Please note, when prefix is instance of RegExp, this setting is ignored.
164 | pathRegex: '/*',
165 | // Optional service requests timeout value (given in milliseconds). Default value: '0' (DISABLED)
166 | // This setting apply only when proxyType = 'http'
167 | timeout: 0,
168 | // Route prefix, defined as string or as a RegExp instance.
169 | prefix: '/public',
170 | // Uses the raw request query string value instead of req.query. Default value: false
171 | disableQsOverwrite: true,
172 | // Optional documentation configuration (unrestricted schema)
173 | docs: {
174 | name: 'Public Service',
175 | endpoint: '/api-docs',
176 | type: 'swagger'
177 | },
178 | // Optional "prefix rewrite" before request is forwarded. Default value: ''
179 | prefixRewrite: '',
180 | // Optional "url rewrite" hook. If defined, the prefixRewrite setting is ignored.
181 | urlRewrite: (req) => req.url,
182 | // Remote HTTP server URL to forward the request.
183 | // If proxyType = 'lambda', the value is the name of the Lambda function, version, or alias.
184 | target: 'http://localhost:3000',
185 | // Optional HTTP methods to limit the requests proxy to certain verbs only
186 | // Supported HTTP methods: ['GET', 'DELETE', 'PATCH', 'POST', 'PUT', 'HEAD', 'OPTIONS', 'TRACE']
187 | methods: ['GET', 'POST', ...],
188 | // Optional route level middlewares. Default value: []
189 | middlewares: [],
190 | // Optional proxy lifecycle hooks. Default value: {}
191 | hooks: {
192 | async onRequest (req, res) {
193 | // // we can optionally reply from here if required
194 | // res.end('Hello World!')
195 | //
196 | // // we can optionally update the request query params from here if required
197 | // req.query.category = 'js'
198 | //
199 | // return true // truthy value returned will abort the request forwarding
200 | },
201 | onResponse (req, res, stream) {
202 | // do some post-processing here
203 | // ...
204 | }
205 |
206 | // if proxyType= 'http', other options allowed https://www.npmjs.com/package/fast-proxy-lite#opts
207 | }
208 | }]
209 | }
210 | ```
211 |
212 | ## Default hooks
213 |
214 | For developers reference, default hooks implementation are located in `lib/default-hooks.js` file.
215 |
216 | # The "_GET /services.json_" endpoint
217 |
218 | Since version `1.3.5` the gateway exposes minimal documentation about registered services at: `GET /services.json`
219 |
220 | Since version `4.2.0`, the `/services.json` route can be disabled by setting `enableServicesEndpoint: false` in the gateway options.
221 |
222 | Example output:
223 |
224 | ```json
225 | [
226 | {
227 | "prefix": "/public",
228 | "docs": {
229 | "name": "Public Service",
230 | "endpoint": "/swagger.json",
231 | "type": "swagger"
232 | }
233 | },
234 | {
235 | "prefix": "/admin"
236 | }
237 | ]
238 | ```
239 |
240 | > NOTE: Please see `docs` configuration entry explained above.
241 |
242 | # WebSockets
243 |
244 | WebSockets proxying is supported since `v3.1.0`. Main considerations:
245 |
246 | - The `faye-websocket` module dependency require to be installed:
247 | ```bash
248 | npm i faye-websocket
249 | ```
250 | - WebSockets middlewares are not supported.
251 | - WebSocketRoute configuration definition:
252 |
253 | ```ts
254 | interface WebSocketRoute {
255 | proxyType: 'websocket'
256 | // https://github.com/faye/faye-websocket-node#initialization-options
257 | proxyConfig?: {}
258 | // used as micromatch matcher pattern: https://www.npmjs.com/package/micromatch
259 | // prefix examples: '/graphql', '/ws-all/*', ['/rtp', '/rtp/*.flv'], '!/media/*.avi'
260 | prefix: string
261 | target: string
262 | // https://github.com/faye/faye-websocket-node#subprotocol-negotiation
263 | subProtocols?: []
264 | hooks?: WebSocketHooks
265 | }
266 |
267 | interface WebSocketHooks {
268 | onOpen?: (ws: any, searchParams: URLSearchParams) => Promise{ 72 | server?: Object | restana.Service
| Express.Application 73 | proxyFactory?: (opts: ProxyFactoryOpts) => Function | null | undefined 74 | restana?: {} 75 | middlewares?: Function[] 76 | pathRegex?: string 77 | timeout?: number 78 | targetOverride?: string 79 | enableServicesEndpoint?: boolean 80 | routes: (Route | WebSocketRoute)[] 81 | } 82 | } 83 | 84 | declare function fastgateway< 85 | P extends restana.Protocol = restana.Protocol.HTTP, 86 | >(opts?: fastgateway.Options
): restana.Service
87 |
88 | export = fastgateway
89 |
--------------------------------------------------------------------------------
/index.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | /* eslint-disable no-useless-call */
4 |
5 | const defaultProxyFactory = require('./lib/proxy-factory')
6 | const restana = require('restana')
7 | const defaultProxyHandler = (req, res, url, proxy, proxyOpts) =>
8 | proxy(req, res, url, proxyOpts)
9 | const DEFAULT_METHODS = require('restana/libs/methods').filter(
10 | (method) => method !== 'all'
11 | )
12 | const NOOP = (req, res) => {}
13 | const PROXY_TYPES = ['http', 'lambda']
14 | const registerWebSocketRoutes = require('./lib/ws-proxy')
15 |
16 | const gateway = (opts) => {
17 | let proxyFactory
18 |
19 | if (opts.proxyFactory) {
20 | proxyFactory = (...args) => {
21 | const result = opts.proxyFactory(...args)
22 | return result === undefined ? defaultProxyFactory(...args) : result
23 | }
24 | } else {
25 | proxyFactory = defaultProxyFactory
26 | }
27 |
28 | opts = Object.assign(
29 | {
30 | middlewares: [],
31 | pathRegex: '/*',
32 | enableServicesEndpoint: true
33 | },
34 | opts
35 | )
36 |
37 | const router = opts.server || restana(opts.restana)
38 |
39 | // registering global middlewares
40 | opts.middlewares.forEach((middleware) => {
41 | router.use(middleware)
42 | })
43 |
44 | // registering services.json
45 | const services = opts.routes.map((route) => ({
46 | prefix: route.prefix,
47 | docs: route.docs
48 | }))
49 | if (opts.enableServicesEndpoint) {
50 | router.get('/services.json', (req, res) => {
51 | res.statusCode = 200
52 | res.setHeader('Content-Type', 'application/json')
53 | res.end(JSON.stringify(services))
54 | })
55 | }
56 |
57 | // processing websocket routes
58 | const wsRoutes = opts.routes.filter(
59 | (route) => route.proxyType === 'websocket'
60 | )
61 | if (wsRoutes.length) {
62 | if (typeof router.getServer !== 'function') {
63 | throw new Error(
64 | 'Unable to retrieve the HTTP server instance. ' +
65 | 'If you are not using restana, make sure to provide an "app.getServer()" alternative method!'
66 | )
67 | }
68 | registerWebSocketRoutes({
69 | routes: wsRoutes,
70 | server: router.getServer()
71 | })
72 | }
73 |
74 | // processing non-websocket routes
75 | opts.routes
76 | .filter((route) => route.proxyType !== 'websocket')
77 | .forEach((route) => {
78 | if (undefined === route.prefixRewrite) {
79 | route.prefixRewrite = ''
80 | }
81 |
82 | // retrieve proxy type
83 | const { proxyType = 'http' } = route
84 | const isDefaultProxyType = PROXY_TYPES.includes(proxyType)
85 | if (!opts.proxyFactory && !isDefaultProxyType) {
86 | throw new Error(
87 | 'Unsupported proxy type, expecting one of ' + PROXY_TYPES.toString()
88 | )
89 | }
90 |
91 | // retrieve default hooks for proxy
92 | const hooksForDefaultType = isDefaultProxyType
93 | ? require('./lib/default-hooks')[proxyType]
94 | : {}
95 | const { onRequestNoOp = NOOP, onResponse = NOOP } = hooksForDefaultType
96 |
97 | // populating required NOOPS
98 | route.hooks = route.hooks || {}
99 | route.hooks.onRequest = route.hooks.onRequest || onRequestNoOp
100 | route.hooks.onResponse = route.hooks.onResponse || onResponse
101 |
102 | // populating route middlewares
103 | route.middlewares = route.middlewares || []
104 |
105 | // populating pathRegex if missing
106 | route.pathRegex =
107 | route.pathRegex === undefined ? opts.pathRegex : route.pathRegex
108 |
109 | // instantiate route proxy
110 | const proxy = proxyFactory({ opts, route, proxyType })
111 |
112 | // route proxy handler function
113 | const proxyHandler = route.proxyHandler || defaultProxyHandler
114 |
115 | // populating timeout config
116 | route.timeout = route.timeout || opts.timeout
117 |
118 | // registering route handlers
119 | const methods = route.methods || DEFAULT_METHODS
120 |
121 | const args = [
122 | // path
123 | route.prefix instanceof RegExp
124 | ? route.prefix
125 | : route.prefix + route.pathRegex,
126 | // route middlewares
127 | ...route.middlewares,
128 | // route handler
129 | handler(route, proxy, proxyHandler)
130 | ]
131 |
132 | methods.forEach((method) => {
133 | method = method.toLowerCase()
134 | if (router[method]) {
135 | router[method].apply(router, args)
136 | }
137 | })
138 | })
139 |
140 | return router
141 | }
142 |
143 | const handler = (route, proxy, proxyHandler) => async (req, res, next) => {
144 | const {
145 | urlRewrite,
146 | prefix,
147 | prefixRewrite,
148 | hooks,
149 | timeout,
150 | disableQsOverwrite
151 | } = route
152 | const { onRequest } = hooks
153 |
154 | try {
155 | if (typeof urlRewrite === 'function') {
156 | req.url = urlRewrite(req)
157 | } else if (typeof prefix === 'string') {
158 | req.url = req.url.replace(prefix, prefixRewrite)
159 | }
160 |
161 | const shouldAbortProxy = await onRequest(req, res)
162 | if (!shouldAbortProxy) {
163 | const proxyOpts = Object.assign(
164 | {
165 | request: {
166 | timeout: req.timeout || timeout
167 | },
168 | queryString: disableQsOverwrite ? null : req.query
169 | },
170 | route.hooks
171 | )
172 |
173 | proxyHandler(req, res, req.url, proxy, proxyOpts)
174 | }
175 | } catch (err) {
176 | return next(err)
177 | }
178 | }
179 |
180 | module.exports = gateway
181 |
--------------------------------------------------------------------------------
/lib/default-hooks.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const pump = require('pump')
4 | const toArray = require('stream-to-array')
5 | const TRANSFER_ENCODING_HEADER_NAME = 'transfer-encoding'
6 |
7 | module.exports = {
8 | websocket: {
9 | onOpenNoOp (ws, searchParams) {}
10 | },
11 | lambda: {
12 | onRequestNoOp (req, res) {},
13 | onResponse (req, res, response) {
14 | const { statusCode, body } = JSON.parse(response.Payload)
15 |
16 | res.statusCode = statusCode
17 | res.end(body)
18 | }
19 | },
20 | http: {
21 | onRequestNoOp (req, res) {},
22 | async onResponse (req, res, stream) {
23 | const chunked = stream.headers[TRANSFER_ENCODING_HEADER_NAME]
24 | ? stream.headers[TRANSFER_ENCODING_HEADER_NAME].endsWith('chunked')
25 | : false
26 |
27 | if (req.headers.connection === 'close' && chunked) {
28 | try {
29 | // remove transfer-encoding header
30 | const transferEncoding = stream.headers[
31 | TRANSFER_ENCODING_HEADER_NAME
32 | ].replace(/(,( )?)?chunked/, '')
33 | if (transferEncoding) {
34 | // header format includes many encodings, example: gzip, chunked
35 | res.setHeader(TRANSFER_ENCODING_HEADER_NAME, transferEncoding)
36 | } else {
37 | res.removeHeader(TRANSFER_ENCODING_HEADER_NAME)
38 | }
39 |
40 | if (!stream.headers['content-length']) {
41 | // pack all pieces into 1 buffer to calculate content length
42 | const resBuffer = Buffer.concat(await toArray(stream))
43 |
44 | // add content-length header and send the merged response buffer
45 | res.setHeader('content-length', '' + Buffer.byteLength(resBuffer))
46 | res.end(resBuffer)
47 | }
48 | } catch (err) {
49 | res.statusCode = 500
50 | res.end(err.message)
51 | }
52 | } else {
53 | res.statusCode = stream.statusCode
54 | pump(stream, res)
55 | }
56 | }
57 | }
58 | }
59 |
--------------------------------------------------------------------------------
/lib/hostnames-hook.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | let micromatch
4 | try {
5 | micromatch = require('micromatch')
6 | } catch (e) {
7 | micromatch = {
8 | isMatch (value, pattern) {
9 | return value === pattern
10 | }
11 | }
12 | }
13 |
14 | module.exports = (hostname2prefix) => {
15 | const matches = {}
16 |
17 | return (req, res, cb) => {
18 | if (req.headers.host) {
19 | const hostHeader = req.headers.host.split(':')[0]
20 | let prefix = matches[hostHeader]
21 |
22 | if (!prefix) {
23 | for (const e of hostname2prefix) {
24 | if (micromatch.isMatch(hostHeader, e.hostname)) {
25 | prefix = e.prefix
26 | matches[hostHeader] = prefix
27 |
28 | break
29 | }
30 | }
31 | }
32 |
33 | if (prefix) {
34 | req.url = prefix + req.url
35 | }
36 | }
37 |
38 | return cb()
39 | }
40 | }
41 |
--------------------------------------------------------------------------------
/lib/proxy-factory.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | module.exports = (() => {
4 | let fastProxyLite, httpLambdaProxy, fastProxyLegacy
5 |
6 | return ({ proxyType, opts, route }) => {
7 | const base = opts.targetOverride || route.target
8 | const config = route.proxyConfig || {}
9 |
10 | switch (proxyType) {
11 | case 'http':
12 | fastProxyLite = fastProxyLite || require('fast-proxy-lite')
13 | return fastProxyLite({
14 | base,
15 | ...config
16 | }).proxy
17 |
18 | case 'lambda':
19 | httpLambdaProxy = httpLambdaProxy || require('http-lambda-proxy')
20 | return httpLambdaProxy({
21 | target: base,
22 | region: 'eu-central-1',
23 | ...config
24 | })
25 |
26 | case 'http-legacy':
27 | fastProxyLegacy = fastProxyLegacy || require('fast-proxy')
28 | return fastProxyLegacy({
29 | base,
30 | ...config
31 | }).proxy
32 |
33 | default:
34 | throw new Error(`Unsupported proxy type: ${proxyType}!`)
35 | }
36 | }
37 | })()
38 |
--------------------------------------------------------------------------------
/lib/ws-proxy.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const micromatch = require('micromatch')
4 | const { onOpenNoOp } = require('./default-hooks').websocket
5 |
6 | module.exports = (config) => {
7 | const WebSocket = require('faye-websocket')
8 |
9 | const { routes, server } = config
10 |
11 | routes.forEach((route) => {
12 | route._isMatch = micromatch.matcher(route.prefix)
13 | })
14 |
15 | server.on('upgrade', async (req, socket, body) => {
16 | if (WebSocket.isWebSocket(req)) {
17 | const url = new URL('http://fw' + req.url)
18 | const prefix = url.pathname || '/'
19 |
20 | const route = routes.find((route) => route._isMatch(prefix))
21 | if (route) {
22 | const subProtocols = route.subProtocols || []
23 | route.hooks = route.hooks || {}
24 | const onOpen = route.hooks.onOpen || onOpenNoOp
25 |
26 | const client = new WebSocket(req, socket, body, subProtocols)
27 |
28 | try {
29 | await onOpen(client, url.searchParams)
30 |
31 | const target =
32 | route.target + url.pathname + '?' + url.searchParams.toString()
33 | const remote = new WebSocket.Client(
34 | target,
35 | subProtocols,
36 | route.proxyConfig
37 | )
38 |
39 | client.pipe(remote)
40 | remote.pipe(client)
41 | } catch (err) {
42 | client.close(err.closeEventCode || 4500, err.message)
43 | }
44 | } else {
45 | socket.end()
46 | }
47 | }
48 | })
49 | }
50 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "fast-gateway",
3 | "version": "4.2.0",
4 | "description": "A Node.js API Gateway for the masses!",
5 | "main": "index.js",
6 | "types": "index.d.ts",
7 | "scripts": {
8 | "test": "nyc mocha test/*.test.js",
9 | "format": "npx standard --fix",
10 | "lint": "npx standard",
11 | "ws-bench": "npx artillery run benchmark/websocket/artillery-perf1.yml"
12 | },
13 | "repository": {
14 | "type": "git",
15 | "url": "git+https://github.com/jkyberneees/fast-gateway.git"
16 | },
17 | "keywords": [
18 | "fast",
19 | "http",
20 | "proxy",
21 | "api",
22 | "gateway"
23 | ],
24 | "author": "Rolando Santamaria Maso