Protocols

patchbay currently implements 4 different protocols: PubSub, Multi-Producer/Multi-Consumer Queues, Requester, and Responder.

PubSub

To subscribe to a pubsub channel, make a request like this:

curl https://patchbay.pub/pubsub/acgt1234
      

Then, to publish a message to all subscribers on that channel:

curl https://patchbay.pub/pubsub/acgt1234 -d "Hi there"
      

It can be useful to keep the connection open, rather than curl exiting after each received message. That can be accomplished using persist=true (be sure to disable curl buffering for small messages):

curl 'https://patchbay.pub/pubsub/acgt1234?persist=true' --no-buffer
      

MPMC Queues

An MPMC producer is creating by POSTing to the /queue/ protocol:

curl https://patchbay.pub/queue/acgt1234 -d "Hi there"
      

Unlike pubsub publishers, producers will block until a consumer patches in to the other side.

A consumer is created by GETing:

curl https://patchbay.pub/queue/acgt1234
      

Requester/Responder

Requester/Responder (req/res) is where the full power of patchbay is unlocked. In its simple form, it can be used almost exactly like MPMC:

curl https://patchbay.pub/req/acgt1234
      

curl https://patchbay.pub/res/acgt1234 -d "Hi there"
      

There are 2 key features of req/res that give it far more power than MPMC:

1. Clients have access to the full range of HTTP methods (POST, PUT, DELETE, etc), instead of just GET.
2. The request path is passed through to responders, so they can change behavior based on it.

Examples below.

Requester POST

What if you wanted to upload some data to your server? With req/res you can send data in both directions:

curl https://patchbay.pub/req/acgt1234 -d "Data"
      

curl https://patchbay.pub/res/acgt1234 -d "Thanks for the data" > file.txt
      

Request Headers and Path

Here's where things get really cool. To have a fully-functional web server, we need access to more information about the client request, for example the request path, headers, query parameters, etc. Run the simple req/res examples again, but this time add -v to the responder:

curl https://patchbay.pub/req/acgt1234 -d "Data"
      

curl https://patchbay.pub/res/acgt1234 -v -d "Thanks for the data" > file.txt
      

curl will print out information about the headers received from the patchbay server:

< HTTP/2 200
< access-control-allow-origin: *
< pb-h-accept: */*
< pb-h-content-length: 4
< pb-h-content-type: application/x-www-form-urlencoded
< pb-h-user-agent: curl/7.67.0
< pb-uri: /req/i3ia-je5s
< content-type: text/plain; charset=utf-8
< content-length: 4
< date: Thu, 12 Dec 2019 19:23:16 GMT
      

Notice that some of these headers are prepended with "pb-". These headers are actually originally passed from the requester to patchbay. They can be easily parsed to determine all the information we need about the client request. See the headers section for more information.

You may already see the problem. By the time curl prints out those headers, the responder has already exited and the connection with the requester is gone forever, so there's no way to use the information. In order to get around this, we use a technique we call "double clutch" requests. It works because patchbay implements a responder query param switch=true. If set, rather than connecting the responder directly to the requester, patchbay switches the requester to whatever channel (usually random) the responder specifies in its body, and returns the requester path/headers/etc to the responder. The requester remains blocked on the new channel, until the responder makes a second request, after having processed the request info, and they are patched together as usual. Ok that's kind of a lot. It's not as bad as it sounds. Here's an example:

Typically you start with a responder waiting with something it wants to serve:

curl 'https://patchbay.pub/res/acgt1234?switch=true' -d "myrandomchannel" -v
      

Then a requester comes along:

curl https://patchbay.pub/req/acgt1234
      

The responder exits immediately, but the requester is now waiting on myrandomchannel. The responder can process the request, then complete the transaction by POSTing to the random channel it specified in the first request:

curl https://patchbay.pub/myrandomchannel -d "Final response"
      

Obviously this isn't very useful with curl. But it's straight-forward to build full web servers around it in less than 150 lines of code. See for example patchbay-http-js and patchbay-browser-responder (which lets you host files from your browser!).

The combination of the /req/ and /res/ protocols essentially gives patchbay the power to be a completely transparent conduit for HTTP interactions. You can implement any sort of HTTP server, and tunnel it through patchbay.

Headers

Certain patchbay functionality relies on passing special headers. These are only available for responders and producers.

Pb-H-*

Any header that starts with Pb-H- is considered a passthrough header. For headers received by the responder, these represent the original headers sent by the requester to patchbay. For headers sent from the responder to patchbay, these headers will be stripped of the Pb-H- prefix and passed through to the requester.

Pb-Uri

The Pb-Uri header is only valid in the requester->responder direction. It represents the request URI, including the path and query parameters, which the requester originally made to patchbay.

Pb-Status

The Pb-Status header is only valid in the responder->requester direction. The value provided will be passed to the requester as the HTTP status code for the original request the requester made to patchbay.