Adds ability to pin streams

Livesheet updating bots and scripts sometimes exhibit "false negatives", wherein some streams are marked offline when they are actually live

In these cases, livesheet operators struggle to keep a stream available due to the bot's activities

This branch introduces pins; when a stream's `isPinned` attribute is `true`, state-related attributes may not be changed (i.e., `status` and `isExpired`)

Clients that attempt to change the state of a pinned stream will receive a 409 response. They should handle this gracefully

Additionally, clients may now filter by pinned items. This is useful for only updating the state of non-pinned streams

Author: sayhiben

README.md

@@ -1,8 +1,42 @@
 # StreamSource
+Streamsource is a publicly readable API to store and retrieve information about livestreams across many streaming platforms.
+
+## Getting Started
+**If you just want to use the API to read stream data found at [streams.streamwall.io](http://streams.streamwall.io), see [API Reference](#api-reference)**
+
+### Current state
+Streamsource is in active development at a very early stage. Do not consider the API stable. We don't even have versioning yet! (we accept PRs!)
+
+Many assumptions are built in, and this application is tightly coupled to a few different services. This will improve over time.
+
+### Installation
+
+1. Clone this repository
+1. `npm install`
+1. Install Postgres and create a database, a user, etc.
+1. Copy example.env to just .env and update your configuration settings
+1. `npx sequelize-cli db:migrate`
+
+### Running
+
+1. Make sure Postgres is running
+1. Start server: `node bin/www`
+1. Preview streams json: http://localhost:3000/streams
+
+### Upgrading
+
+1. Get new code: `git pull`
+1. Apply migrations: `npx sequelize-cli db:migrate`
+1. Restart server: `node bin/www` 
+
+### Development and contributing
+
+This project is in its infancy. We're open to pull requests and will work with you to get improvements merged.
 
 ## API Reference
+
 ### Authentication
-Certain routes are protected with a JWT that you must include in your Authorization header when making authenticated requests.
+Most routes are protected with a JWT that you must include in your Authorization header when making authenticated requests.
 
 API tokens can be obtained by creating a user and POSTing to /users/login, which will generate and return a token.
 
@@ -11,6 +45,17 @@ Subsequent authenticated requests must include the following header:
 Authorization: Bearer MYTOKEN
 ```
 
+#### Getting Started with Authentication
+1. Create your user
+    ```
+    curl -d "[email protected]&password=abc123" -X POST http://localhost:3000/users/signup
+    ```
+2. Log in
+    ```
+    curl -d "[email protected]&password=abc123" -X POST http://localhost:3000/users/login
+    ```
+3. Save the token in your app/script/bot's configuration file (keep it secret!)
+
 ### POST /users/signup
 Creates a new user
 
@@ -67,6 +112,7 @@ Note: All string searches are case-insensitive and queried based on `ILIKE '%YOU
 |link|String|The URL of a stream|
 |status|String|One of: `['Live', 'Offline', 'Unknown']`|
 |notStatus|String|Exclude this status. One of: `['Live', 'Offline', 'Unknown']`|
+|isPinned|Boolean|Defaults to null. When true, prevents state changes, e.g. updates to `isExpired` or `status`|
 |isExpired|Boolean|Streams are considered expired when they are no longer active. Default: false|
 |title|String|Title of a stream|
 |notTitle|String|Title of a stream|
@@ -94,6 +140,7 @@ curl http://localhost:3000/streams?city=seattle
         "link": "https://www.instagram.com/future_crystals/live",
         "status": "Live",
         "title": "",
+        "isPinned": false,
         "isExpired": false,
         "checkedAt": "2020-09-25T04:58:52.840Z",
         "liveAt": "2020-09-25T04:58:52.840Z",
@@ -121,6 +168,7 @@ Create a new stream.
         "link": "https://www.instagram.com/future_crystals/live",
         "status": "Live",
         "title": "",
+        "isPinned": false,
         "isExpired": false,
         "checkedAt": "2020-09-25T04:58:52.840Z",
         "liveAt": "2020-09-25T04:58:52.840Z",
@@ -145,6 +193,7 @@ Get details for a single stream
         "link": "https://www.instagram.com/future_crystals/live",
         "status": "Live",
         "title": "",
+        "isPinned": false,
         "isExpired": false,
         "checkedAt": "2020-09-25T04:58:52.840Z",
         "liveAt": "2020-09-25T04:58:52.840Z",
@@ -184,3 +233,31 @@ Expire a stream
         ...
     }
 ```
+### PUT /streams/:id/pin
+Pin a stream; prevents state changes while pinned
+- **Requires authentication**
+- **Requires privileged role: Editor or Admin**
+```
+ curl -X PUT http://localhost:3000/streams/1/pin --header 'Authorization: Bearer MYTOKEN'
+```
+```json
+    {
+        ...
+        "isPinned": true,
+        ...
+    }
+```
+### DELETE /streams/:id/pin
+Unpin a stream
+- **Requires authentication**
+- **Requires privileged role: Editor or Admin**
+```
+ curl -X PUT http://localhost:3000/streams/1/pin --header 'Authorization: Bearer MYTOKEN'
+```
+```json
+    {
+        ...
+        "isPinned": false,
+        ...
+    }
+```

example.env

@@ -9,7 +9,7 @@ DB_SSL=false
 # Set to 0 for connecting to a production DB from local
 NODE_TLS_REJECT_UNAUTHORIZED=1
 
-# Generate your own sufficiently long, sufficiently random secret
+# Generate your own sufficiently long, sufficiently random secret (just a random string)
 JWT_SECRET=YOURSECRET
 
 # Sign up for an account at https://logdna.com/

migrations/20201010230535-add_ispinned_to_streams.js

@@ -0,0 +1,25 @@
+'use strict';
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    return queryInterface.sequelize.transaction(t => {
+      return Promise.all([
+        queryInterface.addColumn('Streams', 'isPinned', {
+          type: Sequelize.DataTypes.BOOLEAN,
+        }, { transaction: t }),
+        queryInterface.addIndex('Streams', ['isPinned'], {
+          fields: 'isPinned',
+          transaction: t,
+        }),
+      ]);
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    return queryInterface.sequelize.transaction(t => {
+      return Promise.all([
+        queryInterface.removeColumn('Streams', 'isPinned', { transaction: t }),
+      ]);
+    });
+  }
+};

models/stream.js

@@ -29,9 +29,9 @@ module.exports = (sequelize, DataTypes) => {
       // However, we know that multiple streamers sometimes
       // use the same name to stream, e.g., Bear Gang, Concrete Reporting, Unicorn Riot, Boop Troop, etc.
       const matchingFilter = [
-        {link: this.link},
+        { link: this.link },
       ]
-      if(this.source) {
+      if (this.source) {
         matchingFilter.push({ source: this.source })
       }
       const pastStream = await Stream.findOne({
@@ -99,6 +99,7 @@ module.exports = (sequelize, DataTypes) => {
       }
     },
     postedBy:  DataTypes.TEXT,
+    isPinned:  DataTypes.BOOLEAN,
     city:      DataTypes.TEXT,
     region:    DataTypes.TEXT,
     state:     {

routes/streams.js

@@ -68,6 +68,10 @@ async function getStreams(req, res) {
         field: 'isExpired',
         rule:  { [req.query.isExpired ? Op.is : Op.not]: true, }
       },
+      isPinned:    {
+        field: 'isPinned',
+        rule:  { [req.query.isPinned ? Op.is : Op.not]: true, }
+      },
       title:       {
         field: 'title',
         rule:  { [Op.iLike]: `%${req.query.title}%` }
@@ -173,7 +177,7 @@ async function getStreams(req, res) {
 
 async function normalizeLink(link) {
   let normalizedLink = link
-  normalizedLink = normalizedLink.replace(/\/$/,'')
+  normalizedLink = normalizedLink.replace(/\/$/, '')
   normalizedLink = normalizedLink.replace(/https?:\/\/(www\.)?/i, '')
   return normalizedLink
 }
@@ -188,11 +192,11 @@ async function createStream(req, res) {
   const normalizedLink = await normalizeLink(req.body.link)
   const existingStream = await Stream.findOne({
     where: {
-      link: { [Op.iLike]:  `%${normalizedLink}%` },
+      link:      { [Op.iLike]: `%${normalizedLink}%` },
       isExpired: false,
     }
   })
-  if(existingStream) {
+  if (existingStream) {
     res.status(303).json({ data: existingStream })
     return
   }
@@ -223,6 +227,20 @@ async function patchStream(req, res) {
   const id = req.params.id
   const stream = await Stream.findByPk(id)
 
+  const statusIsChanging = req.body.status && req.body.status !== stream.status
+  const isExpiredIsChanging = req.body.isExpired !== undefined && req.body.isExpired !== stream.isExpired
+  const willChangeState = statusIsChanging || isExpiredIsChanging
+  const pinInvalidatesStateChange = stream.isPinned && willChangeState
+  if (pinInvalidatesStateChange) {
+    const error = new Error("Stream is pinned and cannot alter 'isExpired' or 'status' states. Unpin this resource in order to make changes.")
+    res.status(409).json({
+      error: {
+        message: error.message
+      }
+    })
+    return
+  }
+
   const updatedStream = await stream.update({
     source:    req.body.source,
     platform:  req.body.platform,
@@ -235,7 +253,8 @@ async function patchStream(req, res) {
     city:      req.body.city,
     region:    req.body.region,
     checkedAt: req.body.checkedAt,
-    liveAt:    req.body.liveAt
+    liveAt:    req.body.liveAt,
+    isPinned:  req.body.isPinned,
   })
 
   if (updatedStream instanceof ValidationError) {
@@ -265,6 +284,40 @@ async function getStream(req, res) {
   res.status(200).json(response)
 }
 
+async function pinStream(req, res) {
+  if (!req.user || !accessControl.can(req.user.role).updateAny('stream').granted) {
+    res.status(401)
+    return
+  }
+
+  const id = req.params.id
+  const stream = await Stream.findByPk(id)
+  if (!stream) {
+    res.status(404).send()
+  }
+
+  await stream.update({ isPinned: true })
+
+  res.status(204).send()
+}
+
+async function unpinStream(req, res) {
+  if (!req.user || !accessControl.can(req.user.role).updateAny('stream').granted) {
+    res.status(401)
+    return
+  }
+
+  const id = req.params.id
+  const stream = await Stream.findByPk(id)
+  if (!stream) {
+    res.status(404).send()
+  }
+
+  await stream.update({ isPinned: false })
+
+  res.status(204).send()
+}
+
 async function expireStream(req, res) {
   if (!req.user || !accessControl.can(req.user.role).deleteAny('stream').granted) {
     res.status(401)
@@ -277,15 +330,34 @@ async function expireStream(req, res) {
     res.status(404).send()
     return
   }
+  if (stream.isPinned) {
+    const error = new Error("Stream is pinned and cannot alter 'isExpired' or 'status' states. Unpin this resource in order to make changes.")
+    res.status(409).json({
+      error: error,
+    })
+  }
+
   await stream.update({ isExpired: true })
   res.status(204).send()
 }
 
-/* GET streams listing. */
+// List streams
 router.get('/', getStreams)
+
+// Create
 router.post('/', passport.authenticate('jwt', { session: false }), createStream)
+
+// Pin / unpin streams. This is a field on the model; in RESTful terms, let's call this a "virtual resource". Think "pin" as in "thumbtack", not as a verb ;)
+router.put('/:id/pin', passport.authenticate('jwt', { session: false }), pinStream)
+router.delete('/:id/pin', passport.authenticate('jwt', { session: false }), unpinStream)
+
+// Read
 router.get('/:id', getStream)
+
+// Update
 router.patch('/:id', passport.authenticate('jwt', { session: false }), patchStream)
+
+// Soft delete
 router.delete('/:id', passport.authenticate('jwt', { session: false }), expireStream)
 
 module.exports = router;