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

package/lib/client.js

@@ -2,11 +2,15 @@
 /**
  * Minimal REST Server API client.
  *
+ * - Fixed endpoint paths under a base URL: <protocol>://<host>:<port><basePath><path>
+ *   e.g. https://192.168.0.20:8904/api/access_groups. The base can be fixed at
+ *   construction or chosen per request (withBase), e.g. from global context.
  * - Auth: "Authorization: Basic base64(':' + key)" by default (server v9.0+),
  *   "Authorization: <scheme> <key>" when a custom scheme token is configured,
  *   or the key in its own header ("X-API-Key: <key>" or a configured name)
  * - Credentials can be fixed at construction or supplied later (withCredentials)
- * - HATEOAS: everything is discovered from GET /api (features.*.href)
+ * - Failures are classified fatal (4xx, cert/TLS/auth/config) or transient
+ *   (5xx, 408, 429, timeouts, network); only transient ones are retried
  * - Optional server certificate pinning by SHA-1 or SHA-256 fingerprint
  *   (lets you talk to a self-signed REST Server without disabling verification)
  * - Optional client certificate (server "pinned client certificate" / thumbprint)
@@ -20,6 +24,7 @@ const fs = require('fs');
 const { URL } = require('url');
 
 const DEFAULT_PORT = 8904;
+const DEFAULT_BASE_PATH = '/api';
 const TOKEN_RE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/; // RFC 7230 token: a valid auth-scheme name
 
 function normFp(fp) {
@@ -68,15 +73,17 @@ function normaliseCredentials(cred, defaults) {
 function buildAuthHeaders(cred) {
     const c = normaliseCredentials(cred);
     if (!c.apiKey) throw new RestError('No API key: store one in the server config or pass a credentials object', { code: 'ENOCREDS' });
-    if (/[\r\n]/.test(c.apiKey)) throw new RestError('API key must not contain line breaks');
-    if (!AUTH_TYPES.includes(c.authType)) throw new RestError(`Auth type must be one of: ${AUTH_TYPES.join(', ')}`);
+    if (/[\r\n]/.test(c.apiKey)) throw new RestError('API key must not contain line breaks', { config: true });
+    if (!AUTH_TYPES.includes(c.authType)) throw new RestError(`Auth type must be one of: ${AUTH_TYPES.join(', ')}`, { config: true });
     if (c.authType === 'header') {
         if (!TOKEN_RE.test(c.headerName) || RESERVED_HEADERS.includes(c.headerName.toLowerCase())) {
-            throw new RestError(`Invalid API key header name "${c.headerName}"`);
+            throw new RestError(`Invalid API key header name "${c.headerName}"`, { config: true });
         }
         return { [c.headerName]: c.apiKey };
     }
-    if (c.authScheme && !TOKEN_RE.test(c.authScheme)) throw new RestError('Auth scheme must be a single token (letters, digits, - _ . etc., no spaces)');
+    if (c.authScheme && !TOKEN_RE.test(c.authScheme)) {
+        throw new RestError('Auth scheme must be a single token (letters, digits, - _ . etc., no spaces)', { config: true });
+    }
     return {
         Authorization: c.authScheme
             ? c.authScheme + ' ' + c.apiKey
@@ -84,6 +91,45 @@ function buildAuthHeaders(cred) {
     };
 }
 
+/**
+ * Build the server address from { url | host, port, basePath, protocol, plainHttp }.
+ * `host` may be a bare host/IP or a full URL; explicit fields override its parts.
+ * Without a scheme or port the port defaults to 8904; the base path defaults to /api.
+ * Returns { base: URL (origin only), apiRoot: origin + base path }.
+ */
+function parseTarget(o) {
+    o = o || {};
+    const given = String(o.host || o.url || '').trim();
+    const bad = (m) => new RestError(m, { code: 'ENOSERVER' });
+    if (!given) throw bad('No server address: set host in global context or the server config');
+    const hadScheme = /^https?:\/\//i.test(given);
+    let u;
+    try { u = new URL(hadScheme ? given : 'https://' + given); } catch (e) { throw bad(`Invalid server address "${given}"`); }
+
+    const proto = String(o.protocol || '').trim().toLowerCase().replace(/:?\/*$/, '');
+    if (proto) {
+        if (proto !== 'http' && proto !== 'https') throw bad(`Protocol must be "http" or "https", got "${o.protocol}"`);
+        u.protocol = proto + ':';
+    } else if (o.plainHttp) {
+        u.protocol = 'http:';
+    }
+
+    if (o.port !== undefined && o.port !== null && String(o.port).trim() !== '') {
+        const port = Number(o.port);
+        if (!(Number.isInteger(port) && port > 0 && port < 65536)) throw bad(`Invalid port "${o.port}"`);
+        u.port = String(port); // the default port for the scheme (80/443) is dropped from the URL, which is fine
+    } else if (!u.port && !hadScheme) {
+        u.port = String(DEFAULT_PORT);
+    }
+
+    let path = o.basePath !== undefined && o.basePath !== null && String(o.basePath).trim() !== ''
+        ? String(o.basePath).trim()
+        : (u.pathname && u.pathname !== '/' ? u.pathname : DEFAULT_BASE_PATH);
+    path = ('/' + path.replace(/^\/+/, '')).replace(/\/+$/, '');
+    const base = new URL(u.origin);
+    return { base, apiRoot: base.origin + path };
+}
+
 // OpenSSL errors seen when the other end isn't speaking TLS at all
 const NOT_TLS_CODES = ['ERR_SSL_WRONG_VERSION_NUMBER', 'ERR_SSL_UNEXPECTED_MESSAGE', 'ERR_SSL_PACKET_LENGTH_TOO_LONG', 'ERR_SSL_HTTP_REQUEST', 'ERR_SSL_RECORD_LAYER_FAILURE'];
 
@@ -91,7 +137,7 @@ const NOT_TLS_CODES = ['ERR_SSL_WRONG_VERSION_NUMBER', 'ERR_SSL_UNEXPECTED_MESSA
 function notTlsHint(e) {
     if (e && NOT_TLS_CODES.includes(e.code)) {
         e.message = `TLS handshake failed (${e.code}): the endpoint may not be using TLS. ` +
-            'For a plain-HTTP endpoint tick "Plain HTTP (insecure)" in the server config. ' + e.message;
+            'For a plain-HTTP endpoint set protocol "http" (global context) or tick "Plain HTTP (insecure)" in the server config. ' + e.message;
     }
     return e;
 }
@@ -100,36 +146,72 @@ function abortError() {
     return new RestError('Request aborted', { code: 'ABORTED', aborted: true });
 }
 
+// failures that retrying cannot fix: stop (and stop any polling)
+const FATAL_CODES = ['ECERTPIN', 'ENOCREDS', 'EDOWNGRADE', 'ENOSERVER', 'EPROTO',
+    'DEPTH_ZERO_SELF_SIGNED_CERT', 'SELF_SIGNED_CERT_IN_CHAIN', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+    'UNABLE_TO_GET_ISSUER_CERT_LOCALLY', 'CERT_HAS_EXPIRED', 'CERT_NOT_YET_VALID', 'CERT_REVOKED', 'ERR_TLS_CERT_ALTNAME_INVALID'];
+
+/**
+ * 'aborted' | 'fatal' | 'transient'.
+ * fatal: 4xx except 408/429 (401 key, 403 licence/privilege, 404 endpoint, 400 bad request...),
+ *        certificate / TLS / auth / configuration problems.
+ * transient: 408, 429, 5xx, timeouts and network errors.
+ */
+function classify(err) {
+    if (!err) return 'transient';
+    if (err.aborted) return 'aborted';
+    if (err.fatal || err.config) return 'fatal';
+    const s = err.statusCode;
+    if (s) return s === 408 || s === 429 || s >= 500 ? 'transient' : 'fatal';
+    const code = String(err.code || '');
+    if (FATAL_CODES.includes(code) || code.startsWith('ERR_SSL_') || code.startsWith('ERR_TLS_') || code.startsWith('CERT_')) return 'fatal';
+    return 'transient';
+}
+
+/** Retrying these can't create duplicates. POST/PATCH are never retried. */
+const IDEMPOTENT = ['GET', 'HEAD', 'DELETE', 'PUT'];
+
+/** setTimeout that resolves early when the signal aborts. */
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal && signal.aborted) return resolve();
+        const onAbort = () => { clearTimeout(t); resolve(); };
+        const t = setTimeout(() => { if (signal) signal.removeEventListener('abort', onAbort); resolve(); }, ms);
+        if (signal) signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+
+/** Back-off delay for retry n (1-based): base * 2^(n-1), capped. */
+function backoff(n, baseMs, maxMs) {
+    return Math.min(baseMs * Math.pow(2, Math.min(n - 1, 16)), maxMs);
+}
+
 class RestClient {
     /**
      * @param {object} o
-     * @param {string} o.url            host, IP or URL (https:// assumed)
-     * @param {number} [o.port]         default 8904
-     * @param {string} [o.apiKey]       optional; without it use withCredentials() per request source
+     * @param {string} [o.url]          host, IP or URL; optional when requests get a base via withBase()
+     * @param {number} [o.port]         default 8904 when the URL has no scheme
+     * @param {string} [o.basePath]     default '/api' (or the URL's own path)
+     * @param {boolean} [o.plainHttp]   use unencrypted http:// (bench/test only)
+     * @param {string} [o.apiKey]       optional; without it use withCredentials()
      * @param {string} [o.authType]     'authorization' (default) or 'header'
      * @param {string} [o.authScheme]   authorization: '' = Basic with ':<key>'; otherwise '<scheme> <key>'
      * @param {string} [o.headerName]   header: name of the key header (default X-API-Key)
      * @param {string} [o.fingerprint]  server cert SHA-1 (40 hex) or SHA-256 (64 hex), any separators
      * @param {boolean} [o.rejectUnauthorized] used only when no fingerprint is set
      * @param {string} [o.certPath] [o.keyPath] [o.pfxPath] [o.passphrase] client certificate
-     * @param {boolean} [o.rewriteHrefs] force followed hrefs back onto the configured host:port
-     * @param {boolean} [o.plainHttp]    use unencrypted http:// whatever the URL says (bench/test only)
+     * @param {boolean} [o.rewriteHrefs] force followed hrefs back onto the base host:port
      * @param {number} [o.timeoutMs]    default request timeout
      */
     constructor(o) {
         o = o || {};
-        let raw = String(o.url || '').trim();
-        if (!raw) throw new RestError('No server URL configured');
-        if (!/^https?:\/\//i.test(raw)) raw = 'https://' + raw;
-        const u = new URL(raw);
-        if (o.plainHttp) u.protocol = 'http:';
-        const port = parseInt(o.port, 10);
-        if (port > 0) u.port = String(port);
-        else if (!u.port) u.port = String(DEFAULT_PORT);
-
-        this.base = u;
-        const path = u.pathname && u.pathname !== '/' ? u.pathname.replace(/\/+$/, '') : '/api';
-        this.apiRoot = u.origin + path;
+        this.base = null;
+        this.apiRoot = null;
+        if (String(o.url || '').trim()) {
+            const t = parseTarget({ url: o.url, port: o.port, basePath: o.basePath, plainHttp: o.plainHttp });
+            this.base = t.base;
+            this.apiRoot = t.apiRoot;
+        }
         // no key here is fine: credentials can be supplied later with withCredentials().
         // The auth settings are still checked now, so a bad scheme/header fails at deploy.
         this.authDefaults = { authType: o.authType, authScheme: o.authScheme, headerName: o.headerName };
@@ -138,7 +220,7 @@ class RestClient {
         this.authHeaders = hasKey ? headers : null;
         this.fingerprint = normFp(o.fingerprint);
         if (this.fingerprint && this.fingerprint.length !== 40 && this.fingerprint.length !== 64) {
-            throw new RestError('Certificate fingerprint must be SHA-1 (40 hex) or SHA-256 (64 hex)');
+            throw new RestError('Certificate fingerprint must be SHA-1 (40 hex) or SHA-256 (64 hex)', { config: true });
         }
         this.rejectUnauthorized = o.rejectUnauthorized !== false;
         this.rewriteHrefs = o.rewriteHrefs !== false;
@@ -150,30 +232,42 @@ class RestClient {
             if (o.certPath) this.tlsExtra.cert = fs.readFileSync(o.certPath);
             if (o.keyPath) this.tlsExtra.key = fs.readFileSync(o.keyPath);
         } catch (e) {
-            throw new RestError('Cannot read client certificate: ' + e.message);
+            throw new RestError('Cannot read client certificate: ' + e.message, { config: true });
         }
         if (o.passphrase) this.tlsExtra.passphrase = o.passphrase;
-
-        this._discovery = null;
-        this._discoveryAt = 0;
     }
 
     /**
      * A client for the same server using other credentials (bare key string or
      * { apiKey, authType, authScheme, headerName }; missing fields fall back to this
-     * client's auth settings). Shares TLS settings; has its own discovery cache,
-     * because what /api lists depends on the operator behind the key.
+     * client's auth settings). Shares TLS settings.
      */
     withCredentials(cred) {
         const c = Object.create(this);
         c.authHeaders = buildAuthHeaders(normaliseCredentials(cred, this.authDefaults));
-        c._discovery = null;
-        c._discoveryAt = 0;
         return c;
     }
 
-    /** Resolve an href (absolute or relative) and optionally pin it to the configured host:port. */
+    /** A client for another address: { host, port, basePath, protocol } (see parseTarget). */
+    withBase(target) {
+        const t = parseTarget(target);
+        const c = Object.create(this);
+        c.base = t.base;
+        c.apiRoot = t.apiRoot;
+        return c;
+    }
+
+    /** Absolute URL of an endpoint under the base path: url('/cardholders', '325') -> .../api/cardholders/325 */
+    url(path, ...segments) {
+        if (!this.apiRoot) throw new RestError('No server address: set host in global context or the server config', { code: 'ENOSERVER' });
+        let p = String(path || '').replace(/^\/*/, '/').replace(/\/+$/, '');
+        for (const s of segments) p += '/' + encodeURIComponent(String(s));
+        return this.apiRoot + p;
+    }
+
+    /** Resolve an href (absolute or relative) and optionally pin it to the base host:port. */
     resolve(href) {
+        if (!this.base) throw new RestError('No server address: set host in global context or the server config', { code: 'ENOSERVER' });
         const t = new URL(href, this.base.origin);
         if (this.rewriteHrefs) {
             t.protocol = this.base.protocol;
@@ -262,7 +356,7 @@ class RestClient {
     }
 
     /**
-     * Make a request. Resolves { statusCode, headers, body, raw, url }.
+     * Make one request. Resolves { statusCode, headers, body, raw, url, method }.
      * Rejects RestError for transport errors and HTTP >= 400 (statusCode/body attached).
      */
     async request(method, href, body, opts) {
@@ -270,11 +364,11 @@ class RestClient {
         const target = this.resolve(href || this.apiRoot);
         const timeoutMs = opts.timeoutMs || this.timeoutMs;
         const signal = opts.signal;
-        // The socket is opened (and the server cert checked) before any header leaves,
-        // so the API key is never sent to a server that fails the fingerprint pin.
         if (!this.authHeaders) {
             throw new RestError('No API key: store one in the server config or pass a credentials object', { code: 'ENOCREDS' });
         }
+        // The socket is opened (and the server cert checked) before any header leaves,
+        // so the API key is never sent to a server that fails the fingerprint pin.
         const sock = await this._connect(target, signal, timeoutMs);
         const payload = body === undefined || body === null ? null : Buffer.from(JSON.stringify(body));
         const headers = Object.assign({
@@ -343,59 +437,66 @@ class RestClient {
         });
     }
 
-    /** GET /api, cached for cacheMs (default 10 min). */
-    async discover(opts) {
+    /**
+     * request() with back-off on transient failures, for idempotent methods only.
+     * opts.retry = { retries, delayMs, maxDelayMs, onRetry(err, attempt, delayMs) }.
+     * Fatal failures (and POST/PATCH failures) are thrown at once with err.category set.
+     */
+    async requestWithRetry(method, href, body, opts) {
         opts = opts || {};
-        const cacheMs = opts.cacheMs === undefined ? 600000 : opts.cacheMs;
-        if (!opts.force && this._discovery && Date.now() - this._discoveryAt < cacheMs) return this._discovery;
-        const res = await this.request('GET', this.apiRoot, null, opts);
-        if (!res.body || typeof res.body !== 'object' || !res.body.features) {
-            throw new RestError('GET /api did not return a features block (is this a REST Server API endpoint?)', res);
-        }
-        this._discovery = res.body;
-        this._discoveryAt = Date.now();
-        return this._discovery;
-    }
-
-    /** Look up features.<a>.<b>.href, e.g. feature('accessGroups.accessGroups'). */
-    async feature(path, opts) {
-        const d = await this.discover(opts);
-        let node = d.features;
-        for (const part of path.split('.')) node = node && node[part];
-        if (!node || !node.href) {
-            // licences may have changed; re-discover once before giving up
-            if (!(opts && opts.force)) return this.feature(path, Object.assign({}, opts, { force: true }));
-            throw new RestError(`Feature "features.${path}.href" not present in /api (not licensed, or operator lacks privilege)`, { code: 'ENOFEATURE' });
+        const r = opts.retry || {};
+        const retries = IDEMPOTENT.includes(method) ? Math.max(parseInt(r.retries, 10) || 0, 0) : 0;
+        for (let attempt = 1; ; attempt++) {
+            try {
+                return await this.request(method, href, body, opts);
+            } catch (err) {
+                err.category = classify(err);
+                err.attempt = attempt;
+                if (err.category !== 'transient' || attempt > retries) throw err;
+                const delay = backoff(attempt, r.delayMs || 5000, r.maxDelayMs || 60000);
+                err.retryInMs = delay;
+                if (r.onRetry) r.onRetry(err, attempt, delay);
+                await sleep(delay, opts.signal);
+                if (opts.signal && opts.signal.aborted) throw abortError();
+            }
         }
-        return node.href;
     }
 
     /**
-     * Follow next.href until exhausted. Resolves { results, pages, pageCount }.
-     * @param {string} href first page
-     * @param {object} [opts] { maxPages, signal, timeoutMs, onPage(body, index) }
+     * GET href; if the response is a page ({results, next}), follow next.href until exhausted.
+     * Resolves { body, paged, results, pages, pageCount, responses }.
+     * opts: { maxPages, signal, timeoutMs, retry, onResponse(res, index) }.
      */
-    async getAll(href, opts) {
+    async fetch(href, opts) {
         opts = opts || {};
         const maxPages = parseInt(opts.maxPages, 10) > 0 ? parseInt(opts.maxPages, 10) : Infinity;
-        const results = [];
-        const pages = [];
-        const seen = new Set();
-        let url = href;
-        while (url && pages.length < maxPages) {
-            if (seen.has(url)) break; // defensive: never loop on the same link
-            seen.add(url);
-            const res = await this.request('GET', url, null, opts);
+        const first = await this.requestWithRetry('GET', href, null, opts);
+        if (opts.onResponse) opts.onResponse(first, 0);
+        const b0 = first.body;
+        if (!b0 || typeof b0 !== 'object' || !Array.isArray(b0.results)) {
+            return { body: b0, paged: false, response: first };
+        }
+        const results = b0.results.slice();
+        const pages = [b0];
+        const seen = new Set([href]);
+        let next = b0.results.length && b0.next && b0.next.href;
+        while (next && pages.length < maxPages && !seen.has(next)) { // seen: never loop on the same link
+            seen.add(next);
+            const res = await this.requestWithRetry('GET', next, null, opts);
             const b = res.body || {};
             pages.push(b);
+            if (opts.onResponse) opts.onResponse(res, pages.length - 1);
             const batch = Array.isArray(b.results) ? b.results : [];
-            for (const r of batch) results.push(r);
-            if (opts.onPage) opts.onPage(b, pages.length - 1);
+            for (const x of batch) results.push(x);
             if (!batch.length) break;
-            url = b.next && b.next.href ? b.next.href : null;
+            next = b.next && b.next.href;
         }
-        return { results, pages, pageCount: pages.length };
+        return { body: b0, paged: true, results, pages, pageCount: pages.length, response: first };
     }
 }
 
-module.exports = { RestClient, RestError, normaliseCredentials, buildAuthHeaders, normFp, fmtFp, DEFAULT_PORT, DEFAULT_KEY_HEADER };
+module.exports = {
+    RestClient, RestError, classify, backoff, sleep, parseTarget,
+    normaliseCredentials, buildAuthHeaders, normFp, fmtFp,
+    DEFAULT_PORT, DEFAULT_BASE_PATH, DEFAULT_KEY_HEADER
+};

package/lib/outputs.js

@@ -15,6 +15,8 @@ const COLOURS = {
     requesting: { fill: 'blue', shape: 'dot' },
     paging: { fill: 'blue', shape: 'dot' },
     done: { fill: 'green', shape: 'dot' },
+    response: { fill: 'green', shape: 'ring' },
+    events: { fill: 'green', shape: 'dot' },
     subscribing: { fill: 'blue', shape: 'ring' },
     subscribed: { fill: 'green', shape: 'ring' },
     waiting: { fill: 'green', shape: 'ring' },

package/lib/subscription.js

@@ -0,0 +1,117 @@
+'use strict';
+/**
+ * Long-poll subscription loop shared by the item status and events nodes.
+ *
+ *   start (optional, e.g. POST /items/updates) -> first response + next link
+ *   loop: GET next link (long poll; server answers on change or after ~50 s)
+ *         data  -> onData + status output
+ *         empty -> node badge only (no status flood)
+ *         always follow the new next link
+ *
+ * Failures (all go to the error output, never the status output):
+ *   fatal      401 / 403 / 404 on the start endpoint / other 4xx / cert / TLS / config
+ *              -> error, polling STOPS until a new trigger or redeploy
+ *   expired    404 on a followed next link (subscription dropped: >30 s gap, server restart)
+ *              -> error, re-subscribe immediately (a second 404 in a row is fatal)
+ *   transient  5xx / 408 / 429 / timeout / network
+ *              -> error, back off retryDelay * 2^n up to maxRetryDelay, re-subscribe, forever
+ */
+const { RestError, classify, backoff, sleep } = require('./client');
+const { setStatus, reportError } = require('./outputs');
+
+const LONG_POLL_MS = 120000; // client-side timeout for a long poll (server returns at ~50 s)
+
+/**
+ * @param {object} o
+ * @param {object} o.node        Node-RED node (pollDelay, retryDelay, maxRetryDelay)
+ * @param {object} o.client      RestClient
+ * @param {AbortSignal} o.signal
+ * @param {string} o.label       e.g. '3 item(s)'
+ * @param {function} [o.start]   async () => res  (subscribe request; omit to poll startHref directly)
+ * @param {string} [o.startHref] first long-poll URL when there is no start request
+ * @param {function} o.nextHref  (res) => next long-poll URL or null
+ * @param {function} o.hasData   (res) => boolean
+ * @param {function} o.onStart   (res) => void   (emit the subscribe response)
+ * @param {function} o.onData    (res) => void   (emit updates)
+ * @param {function} [o.onEmpty] (res) => void   (optional emit of empty polls)
+ * @param {function} o.dataText  (res) => status text for a data response
+ * @param {object} [o.extra]     added to every status/error payload
+ * @returns {Promise<'stopped'|'fatal'>}
+ */
+async function runSubscription(o) {
+    const { node, client, signal, label } = o;
+    const extra = o.extra || {};
+    let next = null;
+    let fromStart = true;   // is `next` the start URL (404 there = endpoint missing = fatal)?
+    let failures = 0;
+    let expiredInARow = 0;
+
+    while (!signal.aborted) {
+        try {
+            if (!next) {
+                fromStart = true;
+                if (o.start) {
+                    node.status({ fill: 'blue', shape: 'ring', text: `subscribing ${label}` });
+                    const res = await o.start();
+                    if (signal.aborted) break;
+                    o.onStart(res);
+                    next = o.nextHref(res);
+                    if (!next) throw new RestError('Subscription response had no next link', { code: 'ENONEXT', fatal: true });
+                    setStatus(node, 'subscribed', `subscribed ${label}`, Object.assign({ statusCode: res.statusCode, url: res.url }, extra));
+                    fromStart = false;
+                } else {
+                    next = o.startHref;
+                    fromStart = true;
+                }
+            } else {
+                if (node.pollDelay) await sleep(node.pollDelay, signal);
+                if (signal.aborted) break;
+                node.status({ fill: 'green', shape: 'ring', text: `waiting (${label})` });
+                const res = await client.request('GET', next, null, { signal, timeoutMs: LONG_POLL_MS });
+                if (signal.aborted) break;
+                if (o.hasData(res)) {
+                    o.onData(res);
+                    setStatus(node, 'update', o.dataText(res), Object.assign({ statusCode: res.statusCode, url: res.url }, extra));
+                } else {
+                    // update-wait timed out with nothing new: badge only, then wait again
+                    if (o.onEmpty) o.onEmpty(res);
+                    node.status({ fill: 'green', shape: 'ring', text: `no change, re-waiting (${label})` });
+                }
+                const n = o.nextHref(res);
+                fromStart = false;
+                if (n) next = n;
+                // no new link: keep polling the same one (events) or re-subscribe (item status)
+                else if (o.start) next = null;
+            }
+            failures = 0;
+            expiredInARow = 0;
+        } catch (err) {
+            if (signal.aborted || err.aborted) break;
+            let category = classify(err);
+            if (err.statusCode === 404 && !fromStart && expiredInARow === 0) category = 'expired';
+            err.category = category;
+
+            if (category === 'fatal') {
+                reportError(node, err, Object.assign({ category, stopped: true }, extra));
+                node.status({ fill: 'red', shape: 'ring', text: `stopped: ${err.statusCode ? 'HTTP ' + err.statusCode : (err.code || 'error')}` });
+                return 'fatal';
+            }
+            next = null;
+            if (category === 'expired') {
+                expiredInARow++;
+                reportError(node, err, Object.assign({ category, resubscribing: true }, extra));
+                node.status({ fill: 'yellow', shape: 'ring', text: 'subscription expired, re-subscribing' });
+                continue;
+            }
+            expiredInARow = 0;
+            failures++;
+            const delay = backoff(failures, node.retryDelay, node.maxRetryDelay);
+            reportError(node, err, Object.assign({ category, attempt: failures, retryInMs: delay }, extra));
+            node.status({ fill: 'yellow', shape: 'dot', text: `retry ${failures} in ${Math.round(delay / 1000)} s` });
+            await sleep(delay, signal);
+        }
+    }
+    return 'stopped';
+}
+
+module.exports = { runSubscription, LONG_POLL_MS };

package/nodes/rest-events.html

@@ -0,0 +1,133 @@
+<script type="text/javascript">
+    RED.nodes.registerType('tdn-rest-events', {
+        category: 'TDN REST',
+        color: '#E2D96E',
+        defaults: {
+            name: { value: '' },
+            server: { value: '', type: 'tdn-rest-server', required: true },
+            creds: { value: 'credentials' },
+            credsType: { value: 'msg' },
+            query: { value: '' },
+            autoStart: { value: false },
+            pollDelay: { value: 0, validate: function (v) { var n = Number(v); return !isNaN(n) && n >= 0 && n <= 20000; } },
+            retryDelay: { value: 5000, validate: RED.validators.number() },
+            maxRetryDelay: { value: 60000, validate: RED.validators.number() },
+            emitTimeouts: { value: false },
+            contextKey: { value: '' },
+            contextStore: { value: '' },
+            keepEvents: { value: 100, validate: RED.validators.number() }
+        },
+        inputs: 1,
+        outputs: 3,
+        outputLabels: ['events', 'node status', 'error'],
+        icon: 'font-awesome/fa-bell',
+        label: function () { return this.name || 'event updates'; },
+        paletteLabel: 'event updates',
+        oneditprepare: function () {
+            $('#node-input-creds').typedInput({ default: 'msg', types: ['msg', 'flow', 'global', 'env'], typeField: '#node-input-credsType' });
+            var sel = $('#node-input-contextStore');
+            var stores = (RED.settings.context && RED.settings.context.stores) || ['default'];
+            sel.empty();
+            sel.append($('<option>').val('').text('default'));
+            stores.forEach(function (s) { if (s !== 'default') sel.append($('<option>').val(s).text(s)); });
+            sel.val(this.contextStore || '');
+        }
+    });
+</script>
+
+<script type="text/html" data-template-name="tdn-rest-events">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="event updates">
+    </div>
+    <div class="form-row">
+        <label for="node-input-server"><i class="fa fa-server"></i> Server</label>
+        <input type="text" id="node-input-server">
+    </div>
+    <div class="form-row">
+        <label for="node-input-creds"><i class="fa fa-key"></i> Credentials</label>
+        <input type="text" id="node-input-creds" style="width:70%">
+        <input type="hidden" id="node-input-credsType">
+    </div>
+    <div class="form-row">
+        <label for="node-input-query"><i class="fa fa-filter"></i> Filter</label>
+        <input type="text" id="node-input-query" placeholder="optional, e.g. group=23&amp;type=20001&amp;source=508">
+    </div>
+    <div class="form-row">
+        <label>&nbsp;</label>
+        <input type="checkbox" id="node-input-autoStart" style="display:inline-block;width:auto;vertical-align:top">
+        <label for="node-input-autoStart" style="width:auto">Start on deploy (credentials from flow / global / env)</label>
+    </div>
+    <div class="form-row">
+        <label for="node-input-pollDelay">Delay between waits (ms)</label>
+        <input type="text" id="node-input-pollDelay" style="width:100px"> <span>0&ndash;20000</span>
+    </div>
+    <div class="form-row">
+        <label for="node-input-retryDelay">Retry delay (ms)</label>
+        <input type="text" id="node-input-retryDelay" style="width:100px">
+    </div>
+    <div class="form-row">
+        <label for="node-input-maxRetryDelay">Max retry delay (ms)</label>
+        <input type="text" id="node-input-maxRetryDelay" style="width:100px">
+    </div>
+    <div class="form-row">
+        <label>&nbsp;</label>
+        <input type="checkbox" id="node-input-emitTimeouts" style="display:inline-block;width:auto;vertical-align:top">
+        <label for="node-input-emitTimeouts" style="width:auto">Also output empty (timed-out) wait responses</label>
+    </div>
+    <div class="form-row">
+        <label for="node-input-contextKey"><i class="fa fa-globe"></i> Global key</label>
+        <input type="text" id="node-input-contextKey" placeholder="optional, e.g. rest_events">
+    </div>
+    <div class="form-row">
+        <label for="node-input-keepEvents">Keep last</label>
+        <input type="text" id="node-input-keepEvents" style="width:100px"> <span>events</span>
+    </div>
+    <div class="form-row">
+        <label for="node-input-contextStore"><i class="fa fa-database"></i> Context store</label>
+        <select id="node-input-contextStore"></select>
+    </div>
+</script>
+
+<script type="text/html" data-help-name="tdn-rest-events">
+    <p>Subscribes to new events and keeps listening indefinitely.</p>
+    <p>Sequence: <code>GET &lt;server base&gt;/events/updates?&lt;filter&gt;</code> (e.g. <code>https://192.168.0.20:8904/api/events/updates</code>).
+       The server answers as soon as there are new events, or after ~50&nbsp;s with none. Each response carries the link for the
+       next wait (<code>updates.href</code>, or <code>next.href</code>), which is followed straight away, forever.</p>
+    <h3>Input</h3>
+    <dl class="message-properties">
+        <dt>any <span class="property-type">msg</span></dt>
+        <dd>Starts the subscription, or restarts it if it is running. <code>payload</code> = <code>"stop"</code>,
+            <code>msg.action = "stop"</code> or <code>msg.stop = true</code> stops it.</dd>
+        <dt class="optional">query <span class="property-type">object | string</span></dt>
+        <dd>Filter parameters merged over the node's <i>Filter</i>, e.g. <code>{"group":"23","source":"508"}</code>.
+            Use <i>get event groups</i> to find group and type ids.</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>.
+            Read once per start; removed from the trigger msg.</dd>
+    </dl>
+    <h3>Outputs</h3>
+    <ol class="node-ports">
+        <li>Events
+            <dl class="message-properties">
+                <dt>payload <span class="property-type">object</span></dt><dd>Full server response.</dd>
+                <dt>events <span class="property-type">array</span></dt><dd>Shortcut to <code>payload.events</code>.</dd>
+                <dt>phase <span class="property-type">string</span></dt><dd><code>events</code>, or <code>timeout</code> (only if enabled).</dd>
+                <dt>query / seq / statusCode / url</dt><dd></dd>
+            </dl>
+        </li>
+        <li>Status &ndash; successful server responses with events (<code>state: "update"</code>), plus <code>stopped</code> on a stop input.
+            Empty long polls show on the node badge only.</li>
+        <li>Error &ndash; every non-success, with <code>category</code>, <code>stopped</code>, <code>attempt</code>, <code>retryInMs</code>.</li>
+    </ol>
+    <h3>Failures</h3>
+    <ul>
+        <li><b>fatal</b> &ndash; 401 (API key), 403 (licence / privilege), 404 on the start endpoint, other 4xx, certificate or TLS failure:
+            polling <b>stops</b> until a new trigger or redeploy.</li>
+        <li><b>expired</b> &ndash; 404 on a followed link: starts again from the start endpoint.</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 continues.</li>
+    </ul>
+    <h3>Global context (optional)</h3>
+    <p>If a key is set, <code>global.&lt;key&gt;</code> keeps the last <i>Keep last</i> events (oldest first).</p>
+</script>