Merge pull request #3 from streamwall/isPinned

Adds ability to pin 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;