frugal-iot-client 2.0.1 → 2.0.3

package/admin.js

@@ -7,7 +7,7 @@
 
 import {EL, GET, HTMLElementExtended} from '/node_modules/html-element-extended/htmlelementextended.js';
 import mqtt from '/node_modules/mqtt/dist/mqtt.esm.js'; // https://www.npmjs.com/package/mqtt
-import { CssUrl, DELETE, POST, XXX, brokerHost, configSet, el, getString, hasCapability, mqttTempConnect, retainedPattern, locationParameterChange, mqtt_client, preferedLanguageSet, preferedLanguages, redirectToLogin, server_config } from './core.js';
+import { CssUrl, DELETE, POST, XXX, brokerHost, configSet, el, getString, hasCapability, mqttTempConnect, mqtt_subscribe, retainedPattern, locationParameterChange, mqtt_client, preferedLanguageSet, preferedLanguages, redirectToLogin, server_config } from './core.js';
 
 
 // ---------- USB flashing over WebSerial ----------
@@ -291,6 +291,157 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
       this.replaceElement("enrolled_nodes", this.enrolledNodesList());
     });
   }
+  /*
+   * The Pis bridging to this server, and whether each is currently connected.
+   *
+   * Two independent answers, which is the point of showing both. "Last check-in" is the server's
+   * own record of that Pi collecting replicated logins, so it says the Pi is alive and talking
+   * HTTP. "Bridge" is the broker's retained state for that account, so it says the MQTT relay
+   * itself is up. A Pi with a broken bridge still checks in, and that difference is exactly what
+   * is hard to see from production any other way.
+   */
+  getBridges() {
+    if (!this.state.org) return;
+    GET(`/bridges_list/${this.state.org}`, {}, (err, json) => {
+      if (err) { this.message(err.message); return; }
+      this.state.bridges = json; // [{ site, account, created_at, last_pull }]
+      this.subscribeBridgeState();
+      this.replaceElement("bridges_list", this.bridgesList());
+    });
+  }
+  /*
+   * Watch each bridge's connection state.
+   *
+   * One subscription per bridge rather than the "+" wildcard, because mqtt_deliver matches an
+   * incoming topic with topicMatches, which understands a trailing "/#" and nothing else - a "+" in
+   * the middle is compared literally, so the broker would send the messages and none would ever be
+   * delivered to this callback. Exact topics are narrower anyway, and the retained value arrives
+   * immediately, so a state appears without waiting for anything to change.
+   *
+   * Tracked in a Set because mqtt_subscribe does not de-duplicate: without this, every refresh and
+   * every organization change would add another copy of the same subscription.
+   */
+  subscribeBridgeState() {
+    this.state.bridge_state = this.state.bridge_state || {};
+    this.state.bridge_subscribed = this.state.bridge_subscribed || new Set();
+    for (const b of (this.state.bridges || [])) {
+      const topic = `$SYS/broker/connection/${b.account}/state`;
+      if (this.state.bridge_subscribed.has(topic)) continue;
+      this.state.bridge_subscribed.add(topic);
+      // (topic, msg, retained) - the first argument is the topic, not the message
+      mqtt_subscribe(topic, (_topic, msg) => {
+        this.state.bridge_state[b.account] = String(msg);
+        this.replaceElement("bridges_list", this.bridgesList());
+      });
+    }
+  }
+  bridgesList() {
+    const bridges = this.state.bridges;
+    if (!bridges || !bridges.length) {
+      return el('p', {textContent:
+        "No Pi bridges to this server for this organization. A bridge relays a Pi's readings here " +
+        "while the Pi carries on working on its own - see INSTALLATION.md step 11."});
+    }
+    const state = this.state.bridge_state || {};
+    return el('table', {class: 'nodestates'}, [
+      el('tr', {}, [
+        el('th', {textContent: "Site"}), el('th', {textContent: "Bridge"}),
+        el('th', {textContent: "Last check-in"}), el('th', {textContent: "Added"}),
+      ]),
+      ...bridges.map((b) => {
+        // Three states, not two: nothing received yet is not the same as "down", and saying
+        // "Unknown" avoids reporting a healthy bridge as broken while the retained message is still
+        // in flight or when this login has not been granted the $SYS topic.
+        const raw = state[b.account];
+        const up = (raw === undefined) ? { label: "Unknown", hint: "No state received from the broker yet" }
+          : (raw === '1') ? { label: "Up", hint: "The broker reports this bridge connected" }
+          : { label: "DOWN", hint: "The broker reports this bridge not connected" };
+        return el('tr', {}, [
+          el('td', {i8n: false, textContent: b.site}),
+          el('td', {i8n: false, title: getString(up.hint), textContent: up.label}),
+          el('td', {i8n: false, textContent: b.last_pull ? this.formatLastSeen(new Date(b.last_pull).toISOString()) : getString("Never seen")}),
+          el('td', {i8n: false, textContent: b.created_at ? this.formatLastSeen(new Date(b.created_at).toISOString()) : ''}),
+        ]);
+      }),
+    ]);
+  }
+  /*
+   * Add a bridge, or re-issue an existing one's credentials.
+   *
+   * The result is shown once and is not stored anywhere it can be read back: the password is
+   * derived from a server secret and this row's timestamp, so the only copy is the one you put into
+   * the Pi's configuration. Re-running for the same site mints new ones and revokes the old, which
+   * is what makes it the way to recover from having lost them.
+   */
+  onBridgeAdd() {
+    const input = this.state.elements.bridge_site;
+    const site = (input && input.value || '').trim();
+    if (!site) { this.message(getString("Give the Pi a short name first")); return; }
+    if (this.state.bridges && this.state.bridges.some((b) => b.site === site)
+        && !window.confirm(
+          `"${site}" already exists.\n\n` +
+          `Adding it again issues a new broker password and a new replica token, and the ones that ` +
+          `Pi is using now stop working. It will stay disconnected until you put the new ones into ` +
+          `its configuration and restart its broker.`)) return;
+    POST(`/bridge_add/${this.state.org}`, { site }, (err, json) => {
+      if (err) { this.message(err.message); return; }
+      this.state.new_bridge = json;   // shown once, below
+      this.getBridges();              // refreshes the table and re-renders the card
+      this.replaceElement("bridge_new", this.newBridgeDetails());
+    });
+  }
+  /*
+   * What the Pi needs, once. Deliberately not fetchable again: there is no route that reads a
+   * bridge's password back, so losing it means issuing a new one.
+   */
+  newBridgeDetails() {
+    const b = this.state.new_bridge;
+    if (!b) return el('span', {});
+    return el('div', {class: 'bridge-new'}, [
+      el('h4', {textContent: "Copy these now - they are not shown again"}),
+      el('p', {textContent:
+        "Run this on the Pi, in the directory the server is installed in. Replace the placeholder " +
+        "with this server's fully-qualified name - the one on its certificate, which you can check " +
+        "by opening https:// that name in a browser. It will then ask for the broker password and " +
+        "for the replica token, in that order, so have both of the values below to hand."}),
+      el('pre', {i8n: false, textContent: b.command}),
+      el('table', {class: 'nodestates'}, [
+        el('tr', {}, [el('th', {textContent: "Broker account"}), el('td', {i8n: false, textContent: b.account})]),
+        el('tr', {}, [el('th', {textContent: "Broker password"}), el('td', {i8n: false, textContent: b.password})]),
+        el('tr', {}, [el('th', {textContent: "Replica token"}), el('td', {i8n: false, textContent: b.replica_token})]),
+      ]),
+      el('p', {textContent:
+        "Two credentials for two different connections: the password is what the MQTT bridge logs " +
+        "in with on port 8883, and the token is what lets that Pi pull this organization's logins " +
+        "over HTTPS, so the same people can log in there too. The token can be skipped - press " +
+        "Enter at its prompt - and added later by doing this again. Neither is asked for on the " +
+        "command line, so that neither ends up in the Pi's shell history."}),
+    ]);
+  }
+  bridgesRestContent() {
+    return el('div', {}, [
+      this.refreshableHeading("Bridged Pis", this.getBridges),
+      el('p', {textContent:
+        "A bridge relays a Pi's readings to this server, so its nodes appear here too, while the " +
+        "Pi carries on recording and serving on its own whenever the link is down. \"Bridge\" is " +
+        "the broker's live view of the relay; \"Last check-in\" is when that Pi last collected " +
+        "this organization's logins, which it does over HTTP - so a Pi can be checking in while " +
+        "its bridge is down, and the two together say which half is broken."}),
+      this.state.elements.bridges_list = this.bridgesList(),
+      el('section', {}, [
+        el('h3', {textContent: "Add a bridge"}),
+        el('p', {textContent:
+          "Give the Pi a short name - it becomes its broker account and cannot be changed later " +
+          "without reconfiguring that Pi. Lower-case letters, digits and hyphens."}),
+        el('div', {}, [
+          this.state.elements.bridge_site = el('input',
+            {type: 'text', name: 'site', placeholder: 'pi4', size: 16}),
+          el('button', {textContent: "Add", onclick: this.onBridgeAdd.bind(this)}),
+        ]),
+        this.state.elements.bridge_new = this.newBridgeDetails(),
+      ]),
+    ]);
+  }
   onNodeReset(project, nodeid) {
     // Destructive and not obvious: forgetting a node that is running is safe (it notices its
     // credential being refused and enrols again) but it does cost that node a few minutes offline.
@@ -315,10 +466,32 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
    */
   nodeStates() {
     return {
-      enrolled: { label: "Yes",      next: 'denied',   hint: "Has its own broker credential. Click to deny it." },
-      failed:   { label: "Failed",   next: 'approved', hint: "Asked and was refused. Click to let it enrol." },
-      approved: { label: "Approved", next: 'denied',   hint: "Its next request will be accepted. Click to deny it." },
-      denied:   { label: "Denied",   next: 'cleared',  hint: "Stopped, and its credential removed. Click to clear." },
+      enrolled: { label: "Yes",              next: 'denied',   hint: "Has its own broker credential. Click to deny it." },
+      // "Failed" alone read as a status rather than a control, so the one action this card exists to
+      // offer - approving a node that cannot prove anything - was not findable by someone looking
+      // for it. The label says what clicking does.
+      failed:   { label: "Failed - approve", next: 'approved', hint: "Asked and was refused. Click to let it enrol." },
+      approved: { label: "Approved",         next: 'denied',   hint: "Its next request will be accepted. Click to deny it." },
+      denied:   { label: "Denied",           next: 'cleared',  hint: "Stopped, and its credential removed. Click to clear." },
+    };
+  }
+  /*
+   * Why the server turned a node away, in words rather than the wire code.
+   *
+   * Worth the table: the codes are deliberately vague to the NODE (so that probing an organization
+   * name learns nothing), but an administrator looking at their own organization needs the
+   * difference - "wrong secret" and "project not registered" have completely different fixes, and
+   * neither is fixed by approving the node.
+   */
+  nodeAskReasons() {
+    return {
+      refused:            "enrolment secret wrong or missing",
+      no_such_project:    "project is not registered here",
+      bad_request:        "malformed org, project or node id",
+      needs_reset:        "already enrolled, cannot prove it",
+      denied:             "denied here",
+      rate_limited:       "asking too often",
+      broker_unavailable: "broker was unavailable",
     };
   }
   onNodeState(project, nodeid, state) {
@@ -335,7 +508,9 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
     const nodes = this.state.enrolled_nodes;
     if (!nodes || !nodes.length) {
       return el('p', {textContent:
-        "No nodes have enrolled yet. A node enrols itself the first time it connects."});
+        "No nodes have enrolled yet, and none is asking to. A node enrols itself the first time it " +
+        "connects; one that asks and is refused is listed here too, so an empty list means nothing " +
+        "is reaching this server at all - check that the node's org and enrol URL are this one."});
     }
     const states = this.nodeStates();
     return el('table', {class: 'nodestates'}, [
@@ -353,10 +528,14 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
             el('span', {class: 'pseudolink', title: getString(st.hint), textContent: st.label,
               onclick: this.onNodeState.bind(this, n.project, n.nodeid, st.next)}),
           ]),
-          // Untrusted, and shown as such: an address and a time for the admin to recognise
+          // Untrusted, and shown as such: an address and a time for the admin to recognise. The
+          // reason is here too - without it every refusal looks the same, and the ones an admin can
+          // do something about (a project that is not registered, a node id that is not a node id)
+          // are indistinguishable from the one that approving fixes.
           el('td', {i8n: false, textContent: n.asked_at
             ? `${this.formatLastSeen(new Date(n.asked_at).toISOString())} from ${n.asked_from || '?'}` +
-              `${n.asked_count > 1 ? ` (${n.asked_count}x)` : ''}`
+              `${n.asked_count > 1 ? ` (${n.asked_count}x)` : ''}` +
+              `${n.asked_reason ? ` - ${this.nodeAskReasons()[n.asked_reason] || n.asked_reason}` : ''}`
             : (n.enrolled_at ? new Date(n.enrolled_at).toISOString().slice(0, 10) : '')}),
           el('td', {}, [
             n.enrolled_at
@@ -982,7 +1161,7 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
     // the enrolled-node list as well as reading server_config - leaving it out was why that section
     // always said "No nodes have enrolled yet": loadSectionIfNeeded returns early for a tab that is not
     // in this set, so the fetch never happened.
-    this.state.sectionsNeedingLoad = new Set(['OTA', 'Admin', 'Projects', 'Nodes', 'API']);
+    this.state.sectionsNeedingLoad = new Set(['OTA', 'Admin', 'Projects', 'Nodes', 'Bridges', 'API']);
     this.loadSectionIfNeeded(this.state.activeSectionTitle);
     // Only a card created without an organization has a dropdown of its own; replaceElement does
     // nothing for an element this rendering never made. Fine too if this.state.org is undefined.
@@ -1020,6 +1199,8 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
       this.getProjectsList();
     } else if (title === 'Nodes') {
       this.getEnrolledNodes();
+    } else if (title === 'Bridges') {
+      this.getBridges();
     } else if (title === 'API') {
       this.getPlatformsList();
       this.getFarmsList();
@@ -1404,7 +1585,9 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
          el('p', {textContent:
            "Each node has its own broker credential, which it collects from this server the first " +
            "time it connects. Forget one to have it issued a new credential - needed if its " +
-           "filesystem has been erased, because it can then no longer prove which node it is."}),
+           "filesystem has been erased, because it can then no longer prove which node it is. A " +
+           "node that asked and was refused is listed here as well, with why: click Approve on it " +
+           "to accept its next request whatever secret it presents. It retries every half hour."}),
          this.state.elements.enrolled_nodes = this.enrolledNodesList(),
        ]),
        el('section', {}, [
@@ -1456,6 +1639,7 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
        { key: 'message', title: "Message", orgs: 'adminOrgs', dropdown: 'messageorgsdropdown', rest: 'message_rest', content: this.messageRestContent },
        { key: 'retained', title: "Retained", orgs: 'adminOrgs', dropdown: 'retainedorgsdropdown', rest: 'retained_rest', content: this.retainedRestContent },
        { key: 'nodes', title: "Nodes", orgs: 'adminOrgs', dropdown: 'nodesorgsdropdown', rest: 'nodes_rest', content: this.nodesRestContent },
+       { key: 'bridges', title: "Bridges", orgs: 'adminOrgs', dropdown: 'bridgesorgsdropdown', rest: 'bridges_rest', content: this.bridgesRestContent },
        { key: 'api',   title: "API",   orgs: 'adminOrgs', dropdown: 'apiorgsdropdown',   rest: 'api_rest',   content: this.apiRestContent },
      ];
    }

package/cards.js

@@ -733,6 +733,7 @@ const ADMIN_CARDS = [
   { section: 'message',  title: 'Publish Message',  capability: 'ADMIN' },
   { section: 'retained', title: 'Retained messages', capability: 'ADMIN' },
   { section: 'nodes',   title: 'Nodes',            capability: 'ADMIN' },
+  { section: 'bridges', title: 'Bridges',          capability: 'ADMIN' },
   { section: 'api',   title: 'API',             capability: 'ADMIN' },
 ];
 

package/core.js

@@ -118,15 +118,38 @@ function unshiftUnique(arr, v) {
 }
  */
 
-// Subscribe to a topic (no wild cards as topic not passed to cb)
-function mqtt_subscribe(topic, cb) { // cb(message)
+/*
+ * Say what the broker made of a subscription.
+ *
+ * A broker that REFUSES one does not report an error: MQTT 3.1.1 answers with SUBACK return code
+ * 0x80, which mqtt.js hands back as granted qos 128 in the second argument. Checking only `err`
+ * therefore made a refusal completely silent - "Subscribing to X" and then nothing, for ever,
+ * looking exactly like a topic nobody publishes to. That is the difference between "no permission"
+ * and "no data", and it is the first thing you want to know.
+ */
+function subscribeResult(topic, err, granted) {
+  if (err) { console.error("Subscribe failed", topic, err); return; }
+  const refused = (granted || []).filter((g) => g.qos === 128);
+  if (refused.length) {
+    console.error(`Subscribe REFUSED by the broker: ${topic} - this login's broker account has no `
+      + `permission for it. Its rights are set when it logs in; a permission added since then `
+      + `needs a fresh login, or "frugal-iot-rebuild-dynsec" on the server.`);
+  }
+}
+
+/*
+ * Subscribe to a topic.  cb(topic, message, retained) - see mqtt_deliver, which passes all three.
+ *
+ * A trailing "/#" works. A "+" anywhere does NOT: topicMatches understands only the trailing form,
+ * so the broker would deliver the messages and none of them would reach cb. Subscribe to each
+ * concrete topic instead, or teach topicMatches about "+".
+ */
+function mqtt_subscribe(topic, cb) { // cb(topic, message, retained)
   console.log("Subscribing to ", topic);
   mqtt_subscriptions.push({topic, cb});
   // There may be no client yet - it only connects once it knows which organization's credentials to use
   if (mqtt_client && mqtt_client.connected) {
-    mqtt_client.subscribe(topic, (err) => {
-      if (err) console.error(err);
-    })
+    mqtt_client.subscribe(topic, (err, granted) => subscribeResult(topic, err, granted))
   } else {
     console.log("Delaying till connected"); // It will resubscribe from "subscriptions"
   }
@@ -2055,10 +2078,13 @@ class MqttTopic {
       type: this.type === 'exponential' ? 'logarithmic' : 'linear',
       display: this.type !== 'bool',
       title: {
+        display: true, // Chart.js hides a scale title unless asked - without this the axis has no label at all
         // noinspection JSUnresolvedReference
         color: this.color,  // The family colour; the per-line variation happens in MqttGraph.addDataset
+        font: { size: 20 },
+        // The unit is what tells two axes apart when both read as a number - "Temperature (°C)"
         // noinspection JSUnresolvedReference
-        text: getString(this.name.replace(/[0-9]+$/,'')),
+        text: getString(this.name.replace(/[0-9]+$/,'')) + (unitSymbol(this.units) ? ` (${unitSymbol(this.units)})` : ''),
       },
       // 0 is not valid on a logarithmic axis, so fall back to auto-scaling (undefined) rather than 0
       // noinspection JSUnresolvedReference
@@ -2823,9 +2849,7 @@ class MqttClient extends HTMLElementExtended {
           mqtt_subscriptions.forEach((s) => {
             if (!mqtt_client._resubscribeTopics[s.topic]) { // Not really public interface but cleaner console as not needed
               console.log("Now connected, subscribing to", s.topic);
-              mqtt_client.subscribe(s.topic, (err) => {
-                if (err) console.error(err);
-              });
+              mqtt_client.subscribe(s.topic, (err, granted) => subscribeResult(s.topic, err, granted));
             }
           })
         } else {

package/package.json

@@ -29,7 +29,10 @@
   "license": "MIT",
   "main": "webcomponents.js",
   "name": "frugal-iot-client",
-  "repository": "https://github.com/mitra42/frugal-iot-client",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mitra42/frugal-iot-client.git"
+  },
   "scripts": {
     "fixtures": "node test/fixtures/regenerate.js",
     "link:hee": "ln -sfn ../../html-element-extended node_modules/html-element-extended && ls -ld node_modules/html-element-extended",
@@ -38,5 +41,5 @@
     "unlink:hee": "rm -f node_modules/html-element-extended && npm install html-element-extended"
   },
   "type": "module",
-  "version": "2.0.1"
+  "version": "2.0.3"
 }

package/test/graph.test.js

@@ -67,3 +67,24 @@ describe('lines sharing a schema colour are told apart', () => {
     assert.equal(new Set(colors).size, 3);
   });
 });
+
+describe('an axis says what it measures', () => {
+  // graphdataset.graph is the route to a graph that does not need a connected element or a canvas
+  const axisOf = (mt, g) => { mt.graphdataset = { graph: g }; const id = mt.yaxisid; return g.state.scales[id]; };
+
+  test('the title is drawn, and carries the unit symbol', () => {
+    const { projectMt } = mock.runScenario('one-device');
+    const g = new (customElements.get('mqtt-graph'))();
+    const axis = axisOf(projectMt.nodes['esp8266-fb94bb'].groups.sht.topics.temperature, g);
+    assert.equal(axis.title.display, true);
+    assert.equal(axis.title.text, 'Temperature (°C)');
+  });
+
+  test('a reading with no unit in the schema gets a bare name', () => {
+    const { projectMt } = mock.runScenario('one-device');
+    const g = new (customElements.get('mqtt-graph'))();
+    const mt = projectMt.nodes['esp8266-fb94bb'].groups.sht.topics.temperature;
+    mt.units = undefined;
+    assert.equal(axisOf(mt, g).title.text, 'Temperature');
+  });
+});

package/test/page.test.js

@@ -84,7 +84,7 @@ describe('which admin cards a user gets', () => {
     assert.deepEqual(cards.adminCardsFor('dev').map((c) => c.section), ['info', 'flash']);
     withCapabilities('READ', 'ADMIN');
     assert.deepEqual(cards.adminCardsFor('dev').map((c) => c.section),
-      ['info', 'admin', 'projects', 'message', 'retained', 'nodes', 'api']);
+      ['info', 'admin', 'projects', 'message', 'retained', 'nodes', 'bridges', 'api']);
   });
 
   test('flashing and pushing an OTA binary are separate capabilities', () => {
@@ -108,7 +108,7 @@ describe('the project back', () => {
     const back = document.createElement('mqtt-projectback');
     back.setAttribute('organization', 'dev');
     document.body.append(back);
-    assert.equal(back.querySelectorAll('.fi-admincard').length, 7);
+    assert.equal(back.querySelectorAll('.fi-admincard').length, 8);
     back.remove();
   });
 
@@ -228,7 +228,7 @@ describe('the project back', () => {
     document.body.append(back);
     back.querySelectorAll('.fi-admincard__head').forEach((h) => h.click());
     const sections = [...back.querySelectorAll('mqtt-admin')].map((a) => a.getAttribute('section'));
-    assert.deepEqual(sections, ['admin', 'projects', 'message', 'retained', 'nodes', 'api']);
+    assert.deepEqual(sections, ['admin', 'projects', 'message', 'retained', 'nodes', 'bridges', 'api']);
     back.remove();
   });
 });