Pushpin
-------
Date: April 8th, 2013
Author: Justin Karneges <justin@fanout.io>
Mailing List: http://lists.fanout.io/listinfo.cgi/fanout-users-fanout.io

Read: http://blog.fanout.io/2013/02/10/http-grip-proxy-hold-technique/

Pushpin is an HTTP reverse proxy server that makes it easy to implement
streaming and long-polling services. It communicates with backend web
applications using regular, short-lived HTTP requests (GRIP protocol). This
allows the backend applications to be written in any language and use any
webserver.

Additionally, Pushpin does all of this without exposing a proprietary protocol
to clients. The HTTP content between the client and your server is whatever
you want it to be. This makes it ideal for implementing APIs.

License:

  - Pushpin is offered under the GNU AGPL. See the COPYING file.

Features:

  - Implement any realtime HTTP API using any webserver for the logic
  - Proxied requests are streamed, so non-realtime requests remain unhindered
  - Fault tolerant dual-process design reduces risk if things go wrong
  - Handle thousands of simultaneous connections (thanks to Mongrel2)

Requirements:

  qt >= 4.7
  qca >= 2.0 (and an hmac(sha256)-supporting plugin, like qca-ossl)
  libzmq >= 2.0
  qjson
  mongrel2 (develop branch)
  zurl
  python
  python setproctitle
  python tnetstring
  python zmq
  python jinja2

Install guide:

  https://github.com/fanout/pushpin/wiki/Install

If accessing from Git, be sure to pull submodules:

  git submodule init
  git submodule update

Build and run:

  make
  cp config/pushpin.conf.example pushpin.conf
  cp config/routes.example routes
  ./pushpin

Test:

  By default, Pushpin listens on port 7999 and forwards to localhost port 80.
  If you've got a webserver running on port 80, you can confirm that proxying
  works by browsing to http://localhost:7999/

Multiprocess design:

  Pushpin consists of 4 processes: mongrel2, zurl, pushpin-proxy, and
  pushpin-handler. The main pushpin program (the "runner") launches them all
  in one shot.

  If you'd prefer to individually manage any of these processes yourself, then
  adjust the "services" field in pushpin.conf. You can even choose to not use
  the runner at all. In that case, Pushpin's own processes can be launched
  as follows:

  Proxy process:
    proxy/pushpin-proxy --config=/path/to/pushpin.conf

  Handler process:
    handler/pushpin-handler --config=/path/to/pushpin.conf

Architecture:

  +-----------------+
  | Web application |
  +-----------------+
    /|\          |
     |  HTTP     |
    \|/          |
  +------+       |
  | Zurl |       | HTTP
  +------+       |
    /|\          |
     |  ZeroMQ   |
    \|/         \|/
  +-----------------+
  |     Pushpin     |
  +-----------------+
    /|\
     |  ZeroMQ
    \|/
  +----------+
  | Mongrel2 |
  +----------+
    /|\
     |  HTTP
    \|/
  +--------+
  | Client |
  +--------+