Pushpin Documentation

Pushpin supports WebSockets by converting connection activity and messages into HTTP requests sent to your backend. This allows for stateless backend handling.

Key concepts for WebSocket integration:

• Connection Lifecycle: When a new connection arrives, the backend receives a request where wsContext.isOpening() is true. You must call wsContext.accept() and optionally wsContext.subscribe(channel) to establish the connection.
• Message Handling: Messages are received via wsContext.recv(). If recv() returns null, the connection is closed.
• Publishing: Use a publisher to broadcast messages to channels using publisher.publishFormats(channel, format).
• Statelessness: The wsContext only exists for the duration of the handler invocation. The backend does not need to maintain long-lived socket connections.

const { WebSocketMessageFormat } = require( '@fanoutio/grip' );

app.post('/websocket', async (req, res) => {
    const { wsContext } = req.grip;

    // If this is a new connection, accept it and subscribe it to a channel
    if (wsContext.isOpening()) {
        wsContext.accept();
        wsContext.subscribe('all');
    }

    while (wsContext.canRecv()) {
        var message = wsContext.recv();

        // If return value is null then connection is closed
        if (message == null) {
            wsContext.close();
            break;
        }

        // broadcast the message to everyone connected
        await publisher.publishFormats('all', WebSocketMessageFormat(message));
    }

    res.end();
});

To create an HTTP streaming connection, your backend must respond to a proxied request with two specific headers: Grip-Hold: stream and Grip-Channel: <channel_name>.

When Pushpin receives these headers, it converts the response to Transfer-Encoding: chunked for the client and holds the connection open, subscribing the client to the specified channel. The backend request is then considered complete.

To push data to the stream, make an HTTP POST request to Pushpin's private control API (default: http://localhost:5561/publish/) with a JSON payload specifying the channel and the content format.

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 22
Grip-Hold: stream
Grip-Channel: test

welcome to the stream

curl -d '{ "items": [ { "channel": "test", "formats": { "http-stream": { "content": "hello there\n" } } } ] }' \
    http://localhost:5561/publish

For low-level services without a webserver, Pushpin can communicate with backends via ZeroMQ using TNetStrings.

1. Configure a route in Pushpin's routes file using the zhttpreq prefix: * zhttpreq/tcp://<address>:<port>
2. The backend should implement a REP (Reply) socket.
3. To activate an HTTP stream, the backend must respond with a TNetString containing a dictionary that includes Grip-Hold: stream and Grip-Channel: <channel> in the headers list.

* zhttpreq/tcp://127.0.0.1:10000

import zmq
import tnetstring

zmq_context = zmq.Context()
sock = zmq_context.socket(zmq.REP)
sock.connect('tcp://127.0.0.1:10000')

while True:
    req = tnetstring.loads(sock.recv()[1:])

    resp = {
        'id': req['id'],
        'code': 200,
        'reason': 'OK',
        'headers': [
            ['Grip-Hold', 'stream'],
            ['Grip-Channel', 'test'],
            ['Content-Type', 'text/plain']
        ],
        'body': 'welcome to the stream\n'
    }

    sock.send('T' + tnetstring.dumps(resp))