add notes regarding handling unauthorized ACK request

When someone is looking at Nightscout and needs the alarm silenced, it is very
desirable to always silence the local UI. This patch documents some of the
working code around handling the alarm notification process, as well as
provides commentary on handling unauthorized scenarios.  There are some open
questions such as how to update the permission set after authorization.

lib/api3/alarmSocket.js

@@ -49,6 +49,8 @@ function AlarmSocket (app, env, ctx) {
 
     });
 
+    // Turns all notifications on the event bus back into events to be
+    // broadcast to clients.
     ctx.bus.on('notification', self.emitNotification);
   };
 
@@ -77,6 +79,7 @@ function AlarmSocket (app, env, ctx) {
           return err;
         } else {
       // Subscribe for acking alarms
+      // Client sends ack, which sends a notificaiton through our internal bus
       socket.on('ack', function onAck (level, group, silenceTime) {
       ctx.notifications.ack(level, group, silenceTime, true);
           console.info(LOG + 'ack received ' + level + ' ' + group + ' ' + silenceTime);
@@ -127,18 +130,29 @@ function AlarmSocket (app, env, ctx) {
           var perms = {
             read: ctx.authorization.checkMultiple('api:*:read', auth.shiros)
           , ack: ctx.authorization.checkMultiple('notifications:*:ack', auth.shiros)
-
           };
           // Subscribe for acking alarms
+          // TODO: does this produce double ACK after the authorizing? Only if reconnecting?
+          // TODO: how will perms get updated after authorizing?
           socket.on('ack', function onAck (level, group, silenceTime) {
             if (perms.ack) {
+              // This goes through the server-wide event bus.
               ctx.notifications.ack(level, group, silenceTime, true);
               console.info(LOG + 'ack received ' + level + ' ' + group + ' ' + silenceTime);
             } else {
               // TODO: send a message to client to silence locally, but not
               // globally, and request authorization.
+              // This won't go through th event bus.
+              // var acked = { silenceTime, group, level };
+              // socket.emit('authorization_needed', acked);
             }
           });
+          /* TODO: need to know when to update the permissions.
+          // Can we use
+          socket.on('resubscribe', function update_permissions ( ) {
+            // perms = { ... };
+          });
+          */
 
           var okResponse = { success: true, message: 'Subscribed for alarms', ...perms };
           if (shouldCallBack) {

lib/client/index.js

@@ -1233,6 +1233,28 @@ client.load = function load (serverSettings, callback) {
       stopAlarm(false, null, notify);
     }
   });
+  /*
+  *
+  // TODO: When an unauthorized client attempts to silence an alarm, we should
+  // allow silencing locally, request for authorization, and if the
+  // authorization succeeds even republish the ACK notification. something like...
+  alarmSocket.on('authorization_needed', function(details) {
+    if (alarmInProgress) {
+      console.log('clearing alarm');
+      stopAlarm(true, details.silenceTime, currentNotify);
+    }
+    client.hashauth.requestAuthentication(function afterRequest () {
+      console.log("SUCCESSFULLY AUTHORIZED, REPUBLISHED ACK?");
+      // easiest way to update permission set on server side is to send another message.
+      alarmSocket.emit('resubscribe', currentNotify, details);
+
+      if (isClient && currentNotify) {
+        alarmSocket.emit('ack', currentNotify.level, currentNotify.group, details.silenceTime);
+      }
+    });
+  });
+
+  */
 
   $('#testAlarms').click(function(event) {
 

lib/notifications.js

@@ -185,6 +185,10 @@ function init (env, ctx) {
       notifications.ack(1, group, time);
     }
 
+    /*
+    * TODO: modify with a local clear, this will clear all connected clients,
+    * globally
+    */
     if (sendClear) {
       var notify = {
         clear: true
@@ -192,6 +196,8 @@ function init (env, ctx) {
         , message: group + ' - ' + ctx.levels.toDisplay(level) + ' was ack\'d'
         , group: group
       };
+      // When web client sends ack, this translates the websocket message into
+      // an event on our internal bus.
       ctx.bus.emit('notification', notify);
       logEmitEvent(notify);
     }