Document streaming WebSocket subscriptions

README.md

@@ -40,11 +40,13 @@ checkout.
    any kind of XML or HTML document, nor does it implement
    `.host-meta` discovery
 
- - [WebSocket](https://tools.ietf.org/html/rfc6455)-based
-   subscriptions to WebSub topics, in addition to the usual
+ - [WebSocket][]-based subscriptions to WebSub topics, in
+   addition to the usual
    [WebHook](https://en.wikipedia.org/wiki/Webhook)-based
    subscriptions.
 
+  [WebSocket]: https://tools.ietf.org/html/rfc6455
+
 ## Configuration
 
 The most important RacketMQ configuration variable is its canonical
@@ -171,6 +173,9 @@ continue to exist, and is terminated.
       `hub.callback` and other relevant parameters to manage
       subscriptions.
 
+    - method `GET`, when an `upgrade` header with value `websocket` is
+      present: create a streaming subscription to a topic. See below.
+
  - `/topic/`*topic* — Local topic endpoint.
 
    A *local topic* is a topic managed by this hub. Publishers `POST`
@@ -203,6 +208,37 @@ continue to exist, and is terminated.
 
     - method `GET`: retrieve a static resource.
 
+## Streaming WebSocket-based Subscriptions
+
+In addition to the [standard][w3cspec] WebHook-based subscriptions,
+RacketMQ offers [WebSocket][]-based subscriptions.
+
+If your server's base URL is `https://example.com/`, then connecting a
+WebSocket to URL `wss://example.com/hub&hub.topic=MYTOPIC` will create
+a streaming subscription to the topic `MYTOPIC`. (For plain `http:`,
+use `ws:`.)
+
+Content will be delivered from the server as JSON messages of the form
+
+```json
+{
+  "topic": "MYTOPIC",
+  "link": {
+    "hub": "https://example.com/hub",
+    "self": "https://example.com/topic/MYTOPIC"
+  },
+  "content-type": "text/plain",
+  "content-base64": "..."
+}
+```
+
+The `link` object corresponds to the `Link` headers that would usually
+be sent in a WebSub WebHook-based content distribution request, the
+`content-type` string to the `Content-Type` header, and the
+`content-base64` string to the base64-encoded bytes of the body. The
+`topic` string is always based on the `hub.topic` parameter supplied
+in the URL that the WebSocket was initially connected to.
+
 ## Conformance
 
 At the time of writing, no official list of conformance criteria