txhttprelay is a raw socket to HTTP relay. It enables daemons or services that require interaction with RESTful APIs to gain access to them without worrying about the messyness of implementing HTTP APIs in your core service, HTTPS verification, authetncation or API specifications.
As an example, you can use txhttprelay to open a UNIX or TCP socket, pipe simple JSON-encoded requests at it and the relay will handle the entire interface with any number of RESTful APIs for you.
For HTTPS/SSL validation you'll need to install the (optional) txverifyssl from:
https://github.com/meeb/txverifyssl
txhttprelay is compatible with Python >=2.6 and Twisted >=9 for wide compatibility on older systems.
See the example txhttprelay.tac, txhttprelay.sh and local_config.py files for full examples on deployment.
Each request is a single line of JSON terminated by \n or \r\n, the request contains the name of the request (see local_config.py), an arbitrary ID for the request, and two optional paramters. "params" is used to replace values in the request URL, "data" is used to send POST data. Both are JSON-encoded dicts.
The ID is generated by your client and used to track the request, such as by using an uuid.uuid4() value. Once accepted the relay will provide a confirmation by sending back immediately a "status":"dispatched" message. At some point in the future you'll get a second message back containing "status":"ok" or "status":"error", "time" which is how long the request took in seconds and a "response" containing the serialised response from the server.
Responses are only "OK" when the response code matches that of the expected response code.
Here's an example TCP session using the provided local_config.py.example file:
$ telnet 127.0.0.1 9876
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
{"request":"hl2", "id":"123", "params":{"count":1}}
{"status": "dispatched", "id": "123"}
{"status": "ok", "time": 0.39596, "id": "123", "response": {.. lots of data here ...}}
Here's an example of an error using a server that doesn't resolve:
$ telnet localhost 9876
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
{"request":"hl2", "id":"456", "params":{"count":1}}
{"status": "dispatched", "id": "456"}
{"status": "error", "time": 0.00455, "id": 123, "response": {"error": "DNS lookup failed: address 'api.steampowered.dead' not found: [Errno -5] No address associated with hostname."}}
You can install (and use --upgrade to upgrade) the latest version via "pip" directly from github:
$ pip install git+git://github.com/meeb/txhttprelay.git@masterPlease do report, fork or otherwise notify me of any bugs or issues.