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
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.
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.
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!
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.
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
- missingsecret
when publishing backend, or invalid JSON payload in HTTP API requests401
- invalidtoken
when publishing backend, or invalidsecret
otherwise403
- forbidden, TLS is required404
- endpoint not found405
- HTTP method is not allowed501
- Method/service is not implemented (HTTP API)503
- Backend service became unavailable (HTTP API)
- more tests
- can't upstream without token+secret
- can't client without secret
- multiple endpoints
- ERRORS client doesn't exist any more, etc
MIT