duplex-hub

README

Duplex Gateway

Duplex Gateway allows Duplex services to be securely published on the web. It currently only works for Duplex services using WebSocket as the transport and JSON as the codec. Run on Heroku, then connect with WebSocket passing auth tokens. Hand that socket connection to your local Duplex RPC. Now anybody with proper credentials can connect via WebSocket to the gateway and interact with your private Duplex services.

TODO: improve this description

Running the Gateway

You can run the Gateway anywhere, but it's easiest to deploy on Heroku. With a Heroku account, you can deploy your own Gateway right now with this button:

The TOKEN is autogenerated to ensure a good secret. After deploying go to the Heroku Dashboard and Settings for your app and click Reveal Config Vars to see your publish token.

Publishing Duplex Services

First connect to the Gateway over HTTPS. Use a path that you'd like to use as a public endpoint. You need to authenticate by passing a token secret as a query parameter that the gateway was configured with. Also pass a secret query parameter that will be used to authenticate clients connecting to your endpoint.

Now upgrade to WebSocket. Over WebSocket, perform the Duplex handshake. This connection is now like any other Duplex connection and can send and receive requests and replies. Clients connecting to the Gateway will have their own connection, but their messages will be multiplexed over this single connection.

Using Duplex Services

Given a known endpoint that services are exposed on, you can connect to that endpoint like a regular Duplex peer over WebSocket transport. You just have to connect with HTTPS passing a secret query parameter. That's it!

Using Services via HTTP

You can also perform HTTP POST requests against subpaths of the endpoint. The subpath will be used as the method to make a request against. Your body will be used as the request payload. The response will be the reply payload as JSON. These requests also require the secret query parameter.

If a method does not return, the request will block indefinitely. Use query param async=true when using methods intended for async calls.

Status Codes

Since using WebSocket in the browser gives much less insight into what went wrong with HTTP connections, here are how various HTTP error codes are used in Duplex Gateway:

• 400 - missing secret when publishing backend, or invalid JSON payload in HTTP API requests
• 401 - invalid token when publishing backend, or invalid secret otherwise
• 403 - forbidden, TLS is required
• 404 - endpoint not found
• 405 - HTTP method is not allowed
• 501 - Method/service is not implemented (HTTP API)
• 503 - Backend service became unavailable (HTTP API)

TODO

• more tests
  • can't upstream without token+secret
  • can't client without secret
  • multiple endpoints
  • ERRORS client doesn't exist any more, etc

License

MIT