Repository files navigation

Hermes is a dev tool designed to help teams to collaborate in the use of third party services that emit HTTP requests and need to be forwarded to your team's local machines. It provides a multi-users alternative tongrok or localtunnel.

You are working on your local machine on a piece of code that need to listen from an online service — providing HTTP requests (e.g. webhooks, chatBot service...). Basically, your computer is connected to your personal network (behind your NAT), so your localhost is invisible from the outside world...

The solution is well known: you need a HTTP/SSH tunneling system that forwards the requests to your computer. It's perfect when you're alone!But now, you are working as a team and each developer is running his own instance of the code locally and he would like to receive the payloads also. By design tunneling systems are limited to communicate with one user at a time.

Here comes Hermes and provides two modules:

• Thebridge is running on any of your servers online and listen to anyprovider requests
• Theadaptor is running on each local machine and replicate all the requests to thelocal server

When the response is emitted from thelocal server, it brings the response back to theprovider following the same logic.

This is the most basic case. It applies for a single developer working on his machine receiving a request from aprovider

Concurrency mode allowsconcurrent calls among clients (aka Adaptors). By default, the first response received from any client (adaptor) will be used as the final response for theprovider. This feature is particularly useful for teams of developers working in parallel when the provider do not require a client-specific response.

Exclusive mode permits to temporallychoose a single adaptor as responsible for building the response sent to theprovider.

• NodeJS >= 8.10.0

You need to procure any kind of server able to allow specific port access (different from 80 and 443) — you'll need 3 available ports.

All the code snippets provided below are gathered into thisexample directory

$ mkdir basic-bridge && cd basic-bridge$ npm init

$ npm install hermes-bridge dotenv

We encourage you to usedotenv package in order to protect your sensitive data from being published online. NB: .env should be listed into your.gitignore

// index.jsconstcreateBridgeServer=require('hermes-bridge')// Response used when no adaptors are connected (some providers like Facebook, accept 2xx status code only)constresponseFallback={statusCode:500,headers:{'content-type':'application/json; charset=utf-8'},body:JSON.stringify({error:'No local server provided'})}createBridgeServer({httpHost:'localhost',// default '127.0.0.1'httpPort:8000,// port on which the Bridge will listensocketHost:'localhost',// default httpHost || '127.0.0.1'socketPort:9000,// this port will be reused for the adaptor configurationdashboard:{// for you to control your adaptors in real timehost:'localhost',// default '127.0.0.1'port:8001,// port to access the dashboardadminAuth:{// credentials to connect onto the dashboardusername:'admin',password:dotEnv.parsed.ADMIN_AUTH_PASSWORD,// Change it into your .env file!jwtSecret:dotEnv.parsed.ADMIN_AUTH_JWT_SECRET// Change it also into your .env file!}},loggerLevel:'verbose',// 'info',defaultResponse:responseFallback// by default, hermes provide the fallback described above})

Notes: If you plan to not use any internal routing system (Apache, Nginx...), you should sethttpHost,socketHost,dashboard.host to'0.0.0.0' to expose your Bridge and Dashboard to the world.

$ node index.js

Notes

• For a basic DNS resolution you can use ourNGINX configuration file
• Some providers require to use HTTPS, we recommend to useLet's Encrypt withCerbot
• For SSL usage, you can use ourSSL NGINX configuration file — this example supposed you use letsencrypt & certbot
• DNS resolution for the socket endpoint is possible but not as easy as it seems. We recommend to use the IP for configuring the adaptor.BTW Contribution is more than welcome if you think it's an essential feature 🤗
• To run node as a daemon we recommend the use offorever orPM2
• Unfortunately forHeroku users, as far as the service doesn't allow multi-port exposure, hermes-bridge will not be compatible.

Navigate to the URL (or IP:port) you set up for your Hermesdashboard. You should have something like:

Then login with your admin credentials(the ones you choose into the bridge config file)

You can now add a newadaptor with the auth token of your choice — you will reuse it soon — the best is an alphanumeric string without spaces.

🎉 Server side setup is done: congrats! 🎉

The adaptor can be set in any dev environment that support NodeJS 8+.

All the information provided here are gathered into thisexample directory

Navigate to your project directory, then

$ npm install -D hermes-adaptor

Create ahermes.js file.

constadaptor=require('hermes-adaptor')adaptor.init({bridgeHost:'YOUR_SERVER_IP',bridgeSocketPort:9000,// the port you chose previouslylocalServerProtocol:'http',localServerHost:'localhost',localServerPort:8888,maxAttempts:10,// number of attempts to reconnect in case of network errorsattemptDelay:200,auth:{token:'gHmFyUkCSpGRXiWFxvLMpGYbMXvcsi',// Put here the token you choose in the dashboard},verbose:true// logger output level})

$ node hermes.js

You need to launch your local server too if you want the all system to do his job!

Notes

• We recommend to useconcurrently in order to start your dev-server in parallel with the adaptor
• For testing your setup, you can try acurl http://YOUR_SERVER_IP:YOUR_HTTP_PORT, then you should receive the request on your adaptor console (verbose = true).

Here you should have something like:

🎉 Nice! you can now start using Hermes for your development 🎉

Concurrency: All the online adaptors receive the requests — the first adaptor that respond back will be transmit to the provider

Deny: None of the online adaptors receive the requests —this feature particularly adapted to test a network failure case to observe the provider behavior

Exclusive: Only one adaptor is receiving the requests — this feature is particularly adapted for testing a specific response toward the provider

Ngrok is a great product to start developing alone or as a small team. It solves most of the problem you encounter by developing locally with remote providers. It also provides a reliable and secured SSH forwarding.

The philosophy behind Hermes is a bit different.

Here, we are interested to work as a team, each guy is developing locally chatbots and real time front-ends. But, one day the team get larger, and you miss some features,like being able to select on a UI the client that should receive the next request... — So we decide to give a try by developing Hermes.

Here a small features comparison to help you choose which tool suits you best.

• NodeJS 8+
• ReactJS w/ styled-components
• Jest
• Lerna

• We do not use Babel, why because we believe Node is now mature enough, and who REALLY needsimport/export in 2018.
• We try to use as less as possible package for thebridge andadaptor packages in order to keep focus on performance and limitate the dependency tree.
• We use the same eslint configuration for all the repository, it is opinionated, but we are good with that.

• Adaptor is able to restart on error
• Adaptor send fixed token tobridge
• Adaptor warn all users that a newadaptor connects

• Bridge validates theadaptor token
• Bridge prevents anyadaptor that do not provide an auth token to receive data
• Bridge is able to emit a fallback response if noadaptor is connected

• Dashboard provides auth
• Dashboard providesadaptor management in real time
• Dashboard provides console debug in real time
• Dashboard provides provider(s) requests management

• Provide an integration test suite

• Provide multiple types of requests (string, JSON, files, buffer, methods...)

This project is distributed under theMIT License.