From aa2fa227e9cdd5aa4f8facd93775f6180e44a17b Mon Sep 17 00:00:00 2001
From: Eugen Rochko <eugen@zeonfederated.com>
Date: Thu, 2 Feb 2017 16:35:06 +0100
Subject: [PATCH] Adding documentation for streaming API. Fixing filtering bug

---
 docs/README.md                      |  1 +
 docs/Using-the-API/Streaming-API.md | 40 +++++++++++++++++++++++++++++
 streaming/index.js                  |  4 ++-
 3 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 docs/Using-the-API/Streaming-API.md

diff --git a/docs/README.md b/docs/README.md
index 17487c296..5036ea22c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -10,6 +10,7 @@ Index
 
 ### Using the API
 - [API documentation](Using-the-API/API.md)
+- [Streaming API documentation](Using-the-API/Streaming-API.md)
 - [Testing the API with cURL](Using-the-API/Testing-with-cURL.md)
 - [OAuth details](Using-the-API/OAuth-details.md)
 - [Tips for app developers](Using-the-API/Tips-for-app-developers.md)
diff --git a/docs/Using-the-API/Streaming-API.md b/docs/Using-the-API/Streaming-API.md
new file mode 100644
index 000000000..b6d41ab0e
--- /dev/null
+++ b/docs/Using-the-API/Streaming-API.md
@@ -0,0 +1,40 @@
+Streaming API
+=============
+
+Your application can use a server-sent events endpoint to receive updates in real-time. Server-sent events is an incredibly simple transport method that relies entirely on chunked-encoding transfer, i.e. the HTTP connection is kept open and receives new data periodically.
+
+### Endpoints:
+
+**GET /api/v1/streaming/user**
+
+Returns events that are relevant to the authorized user, i.e. home timeline and notifications
+
+**GET /api/v1/streaming/public**
+
+Returns all public statuses
+
+**GET /api/v1/streaming/hashtag**
+
+Returns all public statuses for a particular hashtag (query param `tag`)
+
+### Stream contents
+
+The stream will contain events as well as heartbeat comments. Lines that begin with a colon (`:`) can be ignored by parsers, they are simply there to keep the connection open. Events have this structure:
+
+```
+event: name
+data: payload
+
+```
+
+[See MDN](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format)
+
+### Event types
+
+|Event|Description|What's in the payload|
+|-----|-----------|---------------------|
+|`update`|A new status has appeared!|Status|
+|`notification`|A new notification|Notification|
+|`delete`|A status has been deleted|ID of the deleted status|
+
+The payload is JSON-encoded.
diff --git a/streaming/index.js b/streaming/index.js
index fd57c4e56..af1da8ae7 100644
--- a/streaming/index.js
+++ b/streaming/index.js
@@ -90,7 +90,9 @@ const streamFrom = (id, req, res, needsFiltering = false) => {
   redisClient.on('message', (channel, message) => {
     const { event, payload } = JSON.parse(message)
 
-    if (needsFiltering) {
+    // Only messages that may require filtering are statuses, since notifications
+    // are already personalized and deletes do not matter
+    if (needsFiltering && event === 'update') {
       pgPool.connect((err, client, done) => {
         if (err) {
           log.error(err)