publication-server - npm Package Compare versions

Comparing version 1.0.0 to 1.1.0

client/package.json

 {
   "name": "publication-client",
-  "version": "0.0.0",
+  "version": "1.0.0",
   "description": "A client for a publication-server",
@@ -5,0 +5,0 @@ "main": "dist/browser/index.js",

package.json

 {
   "name": "publication-server",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "",
@@ -5,0 +5,0 @@ "main": "src/index.js",

README.md

@@ -35,13 +35,36 @@ publication-server
 One plus of this server is that it can authenticate WebSocket requests via the
-headers on the request. This is done in the authentication function that is
-passed to the `publication-server` constructor. The function should be as
-follows:
+headers on the initial `UPGRADE` request. This is done in the *REQUIRED*
+authentication function that is passed to the `publication-server` constructor.
+This authentication function takes two parameters which are the originating HTTP
+`UPGRADE` request and a callback. The callback has the following signature:
 
 ```js
-function authenticationFunction(ws, done) {
+/**
+ * This callback is called to signal that we've either authenticated the
+ * incoming HTTP UPGRADE request or we've rejected it.
+ *
+ * @param {Error} err The error that we've returned to signify why the user
+ *    failed authentication. If `err` is null we've successfully authenticated
+ *    the incoming connection to upgrade into a WebSocket.
+ * @param {String} userId An optional unique tag to identify a user by. It is
+ *    exposed inside of publications at `this.userId`. Some publications may
+ *    not require this value, which is why it is optional to return, although
+ *    it is highly encouraged to return a `userId` to be set.
+ */
+function done (err, userId) {}
+```
+
+The authorization function would have the following flow then:
+
+```js
+function authenticationFunction(req, done) {
   // Logic checking the websocket headers, etc.
   // ...
-  // We get the ID of the user that this connection is for as a String.
 
-  done(null, userId);
+  // If the request failed authentication, return an error.
+  if (failedAuth) process.nextTick(done, new Error('failed to authenticate user'));
+
+  // If the request passed authentication, call the callback with the the ID
+  // of the user that we've authenticated.
+  process.nextTick(done, null, `SUPERUSER$12345`);
 }
@@ -96,4 +119,16 @@ ```
 
+### Gracefully shutting down
+The publication server also exposes a `shutdown` function which accepts an
+optional timeout, within which it is expected to close all current websocket
+connections. The timeout within which to gracefully shutdown defaults to zero
+if none is provided. Also note that the unit is in milliseconds. As an example:
+
+```js
+// This gives the server 10 seconds to gracefully shutdown.
+pubSub.shutdown(10000);
+```
+
+
 ### Client
 
 See [publication-client](https://github.com/mixmaxhq/publication-server/blob/master/client/README.md) for the client for this server.

src/index.js

 'use strict';
 
 const _ = require('underscore');
+const assert = require('assert');
 const Primus = require('primus');
@@ -24,4 +25,12 @@
   constructor({authFn, mountPath, errHandler, server} = {}) {
+    assert(authFn, 'Must provide an authorization function');
+
     this._subscriptions = {};
-    this._authFn = authFn;
+    this._authFn = (req, done) => {
+      authFn(req, (err, userId) => {
+        // Make the userId available to the session and any publications.
+        req.userId = userId;
+        done(err);
+      });
+    };
     this._mountPath = mountPath;
@@ -55,4 +64,18 @@ this._errHandler = errHandler;
   }
+
+  /**
+   * Gracefully shutdowns the publication server.
+   *
+   * @param {Number} timeout The amount of time we'll give the WebSocket server
+   * to gracefully shutdown.
+   */
+  shutdown(timeout) {
+    this._primus.destroy({
+      // Don't force the HTTP server to close by default, that's not our job.
+      close: false,
+      timeout
+    });
+  }
 }
 
 module.exports = PublicationServer;

No alert changes

Improved metrics

Total package byte prevSize

430561

0.56%

Lines of code

11664

0.23%

Number of lines in readme file

133

35.71%

No dependency changes