node-red-contrib-tdn-eventsub 0.2.2 → 0.2.3

package/nodes/rest-events.js

@@ -0,0 +1,172 @@
+'use strict';
+const { RestClient, RestError } = require('../lib/client');
+const { OUT_RESPONSE, send, setStatus, reportError, storeName } = require('../lib/outputs');
+const { configureCreds, resolveCreds, stripCreds } = require('../lib/credentials');
+const { runSubscription } = require('../lib/subscription');
+
+/**
+ * Event updates subscription.
+ *
+ *   GET <base>/events/updates?<filters>  (long poll: returns new events, or empty after ~50 s)
+ *   loop: follow the returned updates/next link, forever
+ *
+ * Filters (node "Filter" setting, msg.query at start): e.g. group=23&type=20001&source=508
+ * Failure handling (back-off, hard stop on key/cert/licence errors): lib/subscription.js.
+ * Any message starts (or restarts) it; msg.payload "stop", msg.action "stop" or msg.stop = true ends it.
+ */
+
+const PATH = '/events/updates';
+const MAX_DELAY_MS = 20000;
+
+function isStop(msg) {
+    const word = (v) => typeof v === 'string' && v.trim().toLowerCase() === 'stop';
+    return msg.stop === true || word(msg.payload) || word(msg.action);
+}
+
+/** The long-poll link to follow: updates.href (preferred) or next.href. */
+function nextHref(res) {
+    const b = res.body || {};
+    return (b.updates && b.updates.href) || (b.next && b.next.href) || null;
+}
+
+function eventsOf(res) {
+    return res.body && Array.isArray(res.body.events) ? res.body.events : [];
+}
+
+module.exports = function (RED) {
+    function RestEventsNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+        node.name = config.name;
+        node.server = RED.nodes.getNode(config.server);
+        node.query = (config.query || '').trim();
+        node.pollDelay = Math.min(Math.max(parseInt(config.pollDelay, 10) || 0, 0), MAX_DELAY_MS);
+        node.retryDelay = Math.max(parseInt(config.retryDelay, 10) || 5000, 100);
+        node.maxRetryDelay = Math.max(parseInt(config.maxRetryDelay, 10) || 60000, node.retryDelay);
+        node.emitTimeouts = config.emitTimeouts === true;
+        node.contextKey = (config.contextKey || '').trim();
+        node.contextStore = config.contextStore || '';
+        node.keepEvents = Math.max(parseInt(config.keepEvents, 10) || 100, 1);
+        node.autoStart = config.autoStart === true;
+        configureCreds(node, config);
+
+        let run = null; // { ctrl }
+
+        function storeEvents(events) {
+            if (!node.contextKey || !events.length) return;
+            const g = node.context().global;
+            const store = storeName(node.contextStore);
+            const list = (g.get(node.contextKey, store) || []).concat(events);
+            g.set(node.contextKey, list.slice(-node.keepEvents), store); // newest last, capped
+        }
+
+        async function loop(ctrl, cred, query) {
+            let client;
+            try {
+                client = node.server.getClient(cred, node);
+            } catch (e) {
+                reportError(node, e, { stopped: true, category: 'fatal' });
+                node.status({ fill: 'red', shape: 'ring', text: 'stopped: ' + (e.code || 'error') });
+                return;
+            }
+            const startHref = RestClient.addQuery(client.url(PATH), query);
+            let seq = 0;
+            const emit = (res, phase) => {
+                const events = eventsOf(res);
+                storeEvents(events);
+                send(node, OUT_RESPONSE, {
+                    topic: 'rest/events/updates',
+                    payload: res.body,      // full server response
+                    events,
+                    phase,                  // 'events' | 'timeout'
+                    seq: ++seq,
+                    query,
+                    statusCode: res.statusCode,
+                    url: res.url
+                });
+            };
+            await runSubscription({
+                node,
+                client,
+                signal: ctrl.signal,
+                label: 'events',
+                extra: { query },
+                startHref,
+                nextHref,
+                hasData: (res) => eventsOf(res).length > 0,
+                onStart: () => {},
+                onData: (res) => emit(res, 'events'),
+                onEmpty: (res) => { if (node.emitTimeouts) emit(res, 'timeout'); },
+                dataText: (res) => `${eventsOf(res).length} event(s) @ ${new Date().toLocaleTimeString()}`
+            });
+        }
+
+        function stop(reason) {
+            if (run) {
+                run.ctrl.abort();
+                run = null;
+                setStatus(node, 'stopped', reason || 'stopped');
+            }
+        }
+
+        function start(cred, msgQuery) {
+            const query = Object.assign(RestClient.parseQueryString(node.query),
+                msgQuery ? (typeof msgQuery === 'string' ? RestClient.parseQueryString(msgQuery) : msgQuery) : {});
+            if (run) stop('replaced by new subscription');
+            const ctrl = new AbortController();
+            run = { ctrl };
+            loop(ctrl, cred, query).catch((e) => reportError(node, e)).finally(() => {
+                if (run && run.ctrl === ctrl) run = null;
+            });
+        }
+
+        if (!node.server) node.status({ fill: 'red', shape: 'dot', text: 'no server config' });
+        else node.status({ fill: 'grey', shape: 'ring', text: 'idle' });
+
+        node.on('input', async function (msg, sendFn, done) {
+            done = done || function () {};
+            if (isStop(msg)) {
+                stripCreds(RED, node, msg);
+                if (run) stop('stopped by input');
+                else setStatus(node, 'stopped', 'not running');
+                return done();
+            }
+            let cred;
+            try {
+                cred = await resolveCreds(RED, node, msg);
+            } catch (e) {
+                reportError(node, e);
+                return done();
+            } finally {
+                stripCreds(RED, node, msg);
+            }
+            if (!node.server) {
+                reportError(node, new RestError('No REST server configured', { code: 'ENOSERVER' }));
+                return done();
+            }
+            start(cred, msg.query);
+            done(); // the trigger message is handled; the subscription carries on by itself
+        });
+
+        let autoTimer = null;
+        if (node.autoStart && node.server) {
+            // credentials from flow/global/env only (there is no msg yet)
+            autoTimer = setTimeout(() => {
+                autoTimer = null;
+                resolveCreds(RED, node, {}).then((cred) => start(cred)).catch((e) => reportError(node, e));
+            }, 500);
+        }
+
+        node.on('close', function (removed, done) {
+            if (typeof removed === 'function') { done = removed; }
+            if (autoTimer) clearTimeout(autoTimer);
+            if (run) { run.ctrl.abort(); run = null; }
+            node.status({});
+            done();
+        });
+    }
+
+    RED.nodes.registerType('tdn-rest-events', RestEventsNode);
+};
+
+module.exports.nextHref = nextHref;

package/nodes/rest-item-status.html

@@ -76,22 +76,21 @@
 <script type="text/html" data-help-name="tdn-rest-item-status">
     <p>Subscribes to status changes for a set of REST Server items and keeps listening indefinitely.
        Needs REST Server v8.30+ and the RESTStatus licence.</p>
-    <p>Sequence: <code>POST features.items.updates.href</code> with <code>{"itemIds":[...]}</code> (returns current state),
+    <p>Sequence: <code>POST &lt;server base&gt;/items/updates</code> (e.g. <code>https://192.168.0.20:8904/api/items/updates</code>) with <code>{"itemIds":[...]}</code> (returns current state),
        then an update-wait <code>GET next.href</code>. When an update arrives it is output and a new update-wait is sent.
        When an update-wait times out (~50&nbsp;s, empty <code>updates</code>) another one is sent.
-       A <code>404</code> means the server dropped the subscription (more than 30&nbsp;s between calls, or server restart), so it re-subscribes.
-       Any other error is reported, then retried with exponential back-off.</p>
+       A <code>404</code> on a followed link means the server dropped the subscription (more than 30&nbsp;s between calls, or server restart), so it re-subscribes.</p>
     <h3>Input</h3>
     <dl class="message-properties">
         <dt>payload <span class="property-type">string | number | array | object</span></dt>
         <dd>The source id(s): <code>"508"</code>, <code>"508,526"</code>, <code>["508","526"]</code>,
             <code>{"itemIds":["508","526"]}</code>, or an array of item objects with an <code>id</code> (e.g. straight from <i>get items</i> results).
-            <code>msg.itemIds</code> takes precedence if present.</dd>
+            <code>msg.itemIds</code>, then <code>msg.id</code>, take precedence if present.</dd>
         <dt class="optional">credentials <span class="property-type">string | object</span></dt><dd>Used only when the server config has no API key stored.
             Read from the <i>Credentials</i> property (default <code>msg.credentials</code>; msg, flow, global or env): a bare key string, or
             <code>{"apiKey":"...", "authType":"authorization"|"header", "authScheme":"...", "headerName":"X-API-Key"}</code>.
             Missing fields fall back to the server config. A msg-borne credentials property is removed from the trigger msg.</dd>
-        <dd>Credentials are read once per trigger and kept for that subscription. A new trigger replaces the running subscription. <code>payload</code> = <code>"stop"</code> or <code>msg.stop = true</code> stops it.</dd>
+        <dd>Credentials are read once per trigger and kept for that subscription. A new trigger replaces the running subscription. <code>payload</code> = <code>"stop"</code>, <code>msg.action = "stop"</code> or <code>msg.stop = true</code> stops it.</dd>
     </dl>
     <h3>Outputs</h3>
     <ol class="node-ports">
@@ -103,9 +102,18 @@
                 <dt>itemIds / seq / statusCode / url</dt><dd></dd>
             </dl>
         </li>
-        <li>Node status &ndash; <code>payload.state</code>: <code>subscribing</code>, <code>subscribed</code>, <code>update</code>, <code>resubscribing</code>, <code>retrying</code>, <code>stopped</code>. Each long-poll wait and timeout shows on the node badge only, so this output isn't flooded every ~50&nbsp;s.</li>
-        <li>Error &ndash; <code>payload.message</code>, <code>statusCode</code>, <code>body</code> (on 9.60+ a 403 lists the ids you may monitor), <code>attempt</code>, <code>retryInMs</code>.</li>
+        <li>Status &ndash; successful server responses only: <code>subscribed</code> (POST ok), <code>update</code> (poll with updates); plus <code>stopped</code> on a stop input.
+            Empty long polls (~every 50&nbsp;s) show on the node badge only.</li>
+        <li>Error &ndash; <code>payload.message</code>, <code>statusCode</code>, <code>body</code> (on 9.60+ a 403 lists the ids you may monitor), <code>category</code>, <code>stopped</code>, <code>attempt</code>, <code>retryInMs</code>.</li>
     </ol>
+    <h3>Failures</h3>
+    <p>Every non-success goes to the error output (never the status output), with <code>category</code>:</p>
+    <ul>
+        <li><b>fatal</b> &ndash; 401 (API key), 403 (licence / privilege), 404 on the subscribe endpoint, other 4xx, certificate or TLS failure:
+            polling <b>stops</b> (<code>stopped: true</code>) until a new trigger or redeploy.</li>
+        <li><b>expired</b> &ndash; 404 on a followed link (subscription dropped by the server): re-subscribes immediately.</li>
+        <li><b>transient</b> &ndash; 5xx, 408, 429, timeout, network: back-off <i>retry delay</i> &times; 2<sup>n</sup> up to <i>max</i>, then re-subscribes. Runs until stopped.</li>
+    </ul>
     <h3>Global context (optional)</h3>
     <p>If a key is set, <code>global.&lt;key&gt;</code> is kept as a map of item id &rarr; latest status (with an <code>updated</code> time).</p>
     <h3>Notes</h3>

package/nodes/rest-item-status.js

@@ -1,26 +1,25 @@
 'use strict';
 const { OUT_RESPONSE, send, setStatus, reportError, storeName, nowIso } = require('../lib/outputs');
 const { configureCreds, resolveCreds, stripCreds } = require('../lib/credentials');
+const { runSubscription } = require('../lib/subscription');
+const { RestError } = require('../lib/client');
 
 /**
  * Item status subscription (REST Server v8.30+, RESTStatus licence).
  *
- *   POST features.items.updates.href  {itemIds:[...]}  -> current status + next.href
- *   loop: GET next.href (long poll, ~50 s server timeout)
- *         -> updates (emit) or empty (timeout: just wait again)
- *         -> always follow the new next.href
- *   404  -> subscription dropped (>30 s gap or server restart): POST again
- *   other errors -> back off and re-subscribe, forever, until stopped
+ *   POST <base>/items/updates  {itemIds:[...]}  -> current status + next.href
+ *   loop: GET next.href (long poll, ~50 s server timeout) -> updates or empty, follow next.href
  *
+ * Failure handling (back-off, hard stop on key/cert/licence errors): lib/subscription.js.
  * One trigger starts it; it then runs indefinitely. A new trigger with ids replaces
- * the subscription; msg.payload "stop" (or msg.stop = true) ends it.
+ * the subscription; msg.payload "stop", msg.action "stop" or msg.stop = true ends it.
  */
 
-const MAX_GAP_MS = 20000;      // the server drops a subscription if next.href isn't fetched within 30 s
-const LONG_POLL_MS = 120000;   // client-side timeout for the GET (server returns at ~50 s)
+const PATH = '/items/updates';
+const MAX_GAP_MS = 20000; // the server drops a subscription if next.href isn't fetched within 30 s
 
 function parseIds(msg) {
-    let v = msg.itemIds !== undefined ? msg.itemIds : msg.payload;
+    let v = msg.itemIds !== undefined ? msg.itemIds : (msg.id !== undefined ? msg.id : msg.payload);
     if (v && typeof v === 'object' && !Array.isArray(v) && v.itemIds !== undefined) v = v.itemIds;
     if (typeof v === 'number') v = [v];
     if (typeof v === 'string') v = v.split(/[\s,;]+/);
@@ -36,7 +35,8 @@ function parseIds(msg) {
 }
 
 function isStop(msg) {
-    return msg.stop === true || (typeof msg.payload === 'string' && msg.payload.trim().toLowerCase() === 'stop');
+    const word = (v) => typeof v === 'string' && v.trim().toLowerCase() === 'stop';
+    return msg.stop === true || word(msg.payload) || word(msg.action);
 }
 
 module.exports = function (RED) {
@@ -46,7 +46,7 @@ module.exports = function (RED) {
         node.name = config.name;
         node.server = RED.nodes.getNode(config.server);
         node.pollDelay = Math.min(Math.max(parseInt(config.pollDelay, 10) || 0, 0), MAX_GAP_MS);
-        node.retryDelay = Math.max(parseInt(config.retryDelay, 10) || 5000, 500);
+        node.retryDelay = Math.max(parseInt(config.retryDelay, 10) || 5000, 100);
         node.maxRetryDelay = Math.max(parseInt(config.maxRetryDelay, 10) || 60000, node.retryDelay);
         node.emitTimeouts = config.emitTimeouts === true;
         node.contextKey = (config.contextKey || '').trim();
@@ -55,15 +55,6 @@ module.exports = function (RED) {
 
         let run = null; // { ctrl, ids }
 
-        function sleep(ms, signal) {
-            return new Promise((resolve) => {
-                if (signal.aborted) return resolve();
-                const t = setTimeout(() => { signal.removeEventListener('abort', onAbort); resolve(); }, ms);
-                const onAbort = () => { clearTimeout(t); resolve(); };
-                signal.addEventListener('abort', onAbort, { once: true });
-            });
-        }
-
         function storeUpdates(updates) {
             if (!node.contextKey || !Array.isArray(updates) || !updates.length) return;
             const g = node.context().global;
@@ -74,83 +65,49 @@ module.exports = function (RED) {
             g.set(node.contextKey, map, store);
         }
 
-        function emit(res, phase, ids, seq) {
-            const body = res.body || {};
-            storeUpdates(body.updates);
-            send(node, OUT_RESPONSE, {
-                topic: 'rest/items/updates',
-                payload: body,                              // full server response
-                updates: Array.isArray(body.updates) ? body.updates : [],
-                phase,                                      // 'subscribe' | 'update' | 'timeout'
-                seq,
-                itemIds: ids,
-                statusCode: res.statusCode,
-                url: res.url
-            });
+        function emitter(ids) {
+            let seq = 0;
+            return (res, phase) => {
+                const body = res.body || {};
+                storeUpdates(body.updates);
+                send(node, OUT_RESPONSE, {
+                    topic: 'rest/items/updates',
+                    payload: body,                              // full server response
+                    updates: Array.isArray(body.updates) ? body.updates : [],
+                    phase,                                      // 'subscribe' | 'update' | 'timeout'
+                    seq: ++seq,
+                    itemIds: ids,
+                    statusCode: res.statusCode,
+                    url: res.url
+                });
+            };
         }
 
         async function loop(ids, ctrl, cred) {
-            const signal = ctrl.signal;
             let client;
-            // credentials are taken once, from the trigger; the subscription keeps using them
-            try { client = node.server.getClient(cred); } catch (e) { reportError(node, e); return; }
-
-            let next = null;
-            let failures = 0;
-            let seq = 0;
-            while (!signal.aborted) {
-                try {
-                    if (!next) {
-                        setStatus(node, 'subscribing', `subscribing ${ids.length} item(s)`, { itemIds: ids });
-                        const href = await client.feature('items.updates', { signal });
-                        const res = await client.request('POST', href, { itemIds: ids }, { signal });
-                        if (signal.aborted) break;
-                        emit(res, 'subscribe', ids, ++seq);
-                        next = res.body && res.body.next && res.body.next.href;
-                        if (!next) throw new Error('Subscription response had no next.href');
-                        setStatus(node, 'subscribed', `subscribed ${ids.length} item(s)`, { itemIds: ids });
-                    } else {
-                        if (node.pollDelay) await sleep(node.pollDelay, signal);
-                        if (signal.aborted) break;
-                        // badge only - every long poll would otherwise flood the status output
-                        node.status({ fill: 'green', shape: 'ring', text: `waiting (${ids.length} item(s))` });
-                        const res = await client.request('GET', next, null, { signal, timeoutMs: LONG_POLL_MS });
-                        if (signal.aborted) break;
-                        const updates = res.body && Array.isArray(res.body.updates) ? res.body.updates : [];
-                        if (updates.length) {
-                            emit(res, 'update', ids, ++seq);
-                            setStatus(node, 'update', `${updates.length} update(s) @ ${new Date().toLocaleTimeString()}`, {
-                                count: updates.length,
-                                ids: updates.map((u) => u.id)
-                            });
-                        } else {
-                            // update-wait timed out with nothing new: send another update-wait.
-                            // Badge only - this happens every ~50 s and would flood the status output.
-                            if (node.emitTimeouts) emit(res, 'timeout', ids, ++seq);
-                            node.status({ fill: 'green', shape: 'ring', text: `wait timed out, re-waiting (${ids.length} item(s))` });
-                        }
-                        next = res.body && res.body.next && res.body.next.href;
-                        if (!next) {
-                            setStatus(node, 'resubscribing', 'no next link, re-subscribing');
-                        }
-                    }
-                    failures = 0;
-                } catch (err) {
-                    if (signal.aborted || err.aborted) break;
-                    next = null;
-                    if (err.statusCode === 404 && failures === 0) {
-                        // subscription expired (gap > 30 s or server restart) - re-POST straight away once
-                        setStatus(node, 'resubscribing', 'subscription expired (404), re-subscribing');
-                        failures++;
-                        continue;
-                    }
-                    failures++;
-                    const delay = Math.min(node.retryDelay * Math.pow(2, Math.min(failures - 1, 10)), node.maxRetryDelay);
-                    reportError(node, err, { itemIds: ids, attempt: failures, retryInMs: delay });
-                    setStatus(node, 'retrying', `retry ${failures} in ${Math.round(delay / 1000)} s`, { attempt: failures, retryInMs: delay, error: err.message });
-                    await sleep(delay, signal);
-                }
+            try {
+                client = node.server.getClient(cred, node);
+            } catch (e) {
+                reportError(node, e, { itemIds: ids, stopped: true, category: 'fatal' });
+                node.status({ fill: 'red', shape: 'ring', text: 'stopped: ' + (e.code || 'error') });
+                return;
             }
+            const emit = emitter(ids);
+            const updatesOf = (res) => (res.body && Array.isArray(res.body.updates) ? res.body.updates : []);
+            await runSubscription({
+                node,
+                client,
+                signal: ctrl.signal,
+                label: `${ids.length} item(s)`,
+                extra: { itemIds: ids },
+                start: () => client.request('POST', client.url(PATH), { itemIds: ids }, { signal: ctrl.signal }),
+                nextHref: (res) => (res.body && res.body.next && res.body.next.href) || null,
+                hasData: (res) => updatesOf(res).length > 0,
+                onStart: (res) => emit(res, 'subscribe'),
+                onData: (res) => emit(res, 'update'),
+                onEmpty: (res) => { if (node.emitTimeouts) emit(res, 'timeout'); },
+                dataText: (res) => `${updatesOf(res).length} update(s) @ ${new Date().toLocaleTimeString()}`
+            });
         }
 
         function stop(reason) {
@@ -161,7 +118,7 @@ module.exports = function (RED) {
             }
         }
 
-        if (!node.server) setStatus(node, 'error', 'no server config');
+        if (!node.server) node.status({ fill: 'red', shape: 'dot', text: 'no server config' });
         else node.status({ fill: 'grey', shape: 'ring', text: 'idle' });
 
         node.on('input', async function (msg, sendFn, done) {
@@ -182,12 +139,12 @@ module.exports = function (RED) {
                 stripCreds(RED, node, msg);
             }
             if (!node.server) {
-                reportError(node, new Error('No REST server configured'));
+                reportError(node, new RestError('No REST server configured', { code: 'ENOSERVER' }));
                 return done();
             }
             const ids = parseIds(msg);
             if (!ids.length) {
-                reportError(node, new Error('No item ids in msg.payload / msg.itemIds (string "508,526", array, or {itemIds:[...]})'));
+                reportError(node, new RestError('No item ids in msg.payload / msg.itemIds / msg.id (string "508,526", array, or {itemIds:[...]})', { code: 'EBADINPUT' }));
                 return done();
             }
             if (run) stop('replaced by new subscription');