node-red-contrib-tdn-eventsub 0.1.0

package/lib/client.js

@@ -0,0 +1,322 @@
+'use strict';
+/**
+ * Minimal REST Server API client.
+ *
+ * - Auth: "Authorization: Basic base64(':' + key)" by default (server v9.0+),
+ *   or "Authorization: <scheme> <key>" when a custom scheme token is configured
+ * - HATEOAS: everything is discovered from GET /api (features.*.href)
+ * - 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)
+ * - No external dependencies
+ */
+const tls = require('tls');
+const net = require('net');
+const http = require('http');
+const https = require('https');
+const fs = require('fs');
+const { URL } = require('url');
+
+const DEFAULT_PORT = 8904;
+const TOKEN_RE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/; // RFC 7230 token: a valid auth-scheme name
+
+function normFp(fp) {
+    return String(fp || '').replace(/[^0-9a-f]/gi, '').toUpperCase();
+}
+
+function fmtFp(hex) {
+    return (hex.match(/.{1,2}/g) || []).join(':');
+}
+
+class RestError extends Error {
+    constructor(message, extra) {
+        super(message);
+        this.name = 'RestError';
+        Object.assign(this, extra || {});
+    }
+}
+
+function abortError() {
+    return new RestError('Request aborted', { code: 'ABORTED', aborted: true });
+}
+
+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
+     * @param {string} [o.authScheme]   '' = Basic with ':<key>'; otherwise sent as '<scheme> <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 {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);
+        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.apiKey = String(o.apiKey || '').trim();
+        const scheme = String(o.authScheme || '').trim();
+        if (scheme && !TOKEN_RE.test(scheme)) throw new RestError('Auth scheme must be a single token (letters, digits, - _ . etc., no spaces)');
+        if (/[\r\n]/.test(this.apiKey)) throw new RestError('API key must not contain line breaks');
+        this.authHeader = scheme
+            ? scheme + ' ' + this.apiKey
+            : 'Basic ' + Buffer.from(':' + this.apiKey, 'utf8').toString('base64');
+        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)');
+        }
+        this.rejectUnauthorized = o.rejectUnauthorized !== false;
+        this.rewriteHrefs = o.rewriteHrefs !== false;
+        this.timeoutMs = parseInt(o.timeoutMs, 10) > 0 ? parseInt(o.timeoutMs, 10) : 30000;
+
+        this.tlsExtra = {};
+        try {
+            if (o.pfxPath) this.tlsExtra.pfx = fs.readFileSync(o.pfxPath);
+            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);
+        }
+        if (o.passphrase) this.tlsExtra.passphrase = o.passphrase;
+
+        this._discovery = null;
+        this._discoveryAt = 0;
+    }
+
+    /** Resolve an href (absolute or relative) and optionally pin it to the configured host:port. */
+    resolve(href) {
+        const t = new URL(href, this.base.origin);
+        if (this.rewriteHrefs) {
+            t.protocol = this.base.protocol;
+            t.hostname = this.base.hostname;
+            t.port = this.base.port;
+        } else if (this.base.protocol === 'https:' && t.protocol !== 'https:') {
+            // never let a server-supplied link downgrade us to cleartext (the API key would follow)
+            throw new RestError(`Refusing to follow non-HTTPS link ${t.protocol}//${t.host}${t.pathname}`, { code: 'EDOWNGRADE' });
+        }
+        return t;
+    }
+
+    /** Append query params to an href that may already carry its own. Skips empty values. */
+    static addQuery(href, params) {
+        const t = new URL(href);
+        for (const [k, v] of Object.entries(params || {})) {
+            if (v === undefined || v === null || v === '') continue;
+            t.searchParams.set(k, String(v));
+        }
+        return t.toString();
+    }
+
+    /** Parse "a=1&b=two" into an object. */
+    static parseQueryString(qs) {
+        const out = {};
+        if (!qs) return out;
+        const sp = new URLSearchParams(String(qs).replace(/^[?&]/, ''));
+        for (const [k, v] of sp) out[k] = v;
+        return out;
+    }
+
+    _connect(target, signal, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const host = target.hostname.replace(/^\[|\]$/g, '');
+            const port = parseInt(target.port, 10) || (target.protocol === 'http:' ? 80 : 443);
+            let sock;
+            let done = false;
+            const finish = (err, s) => {
+                if (done) return;
+                done = true;
+                clearTimeout(timer);
+                if (signal) signal.removeEventListener('abort', onAbort);
+                if (err) {
+                    if (sock) sock.destroy();
+                    reject(err);
+                } else resolve(s);
+            };
+            const onAbort = () => finish(abortError());
+            const timer = setTimeout(() => finish(new RestError(`Connect timeout to ${host}:${port}`, { code: 'ETIMEDOUT' })), Math.min(timeoutMs, 15000));
+            if (signal) {
+                if (signal.aborted) return finish(abortError());
+                signal.addEventListener('abort', onAbort);
+            }
+
+            if (target.protocol === 'http:') {
+                sock = net.connect({ host, port }, () => finish(null, sock));
+                sock.once('error', (e) => finish(e));
+                return;
+            }
+
+            const pinning = !!this.fingerprint;
+            const opts = Object.assign({
+                host,
+                port,
+                rejectUnauthorized: pinning ? false : this.rejectUnauthorized,
+                ALPNProtocols: ['http/1.1']
+            }, this.tlsExtra);
+            if (!net.isIP(host)) opts.servername = host;
+
+            sock = tls.connect(opts);
+            sock.once('error', (e) => finish(e));
+            sock.once('secureConnect', () => {
+                if (pinning) {
+                    const c = sock.getPeerCertificate();
+                    const actual = this.fingerprint.length === 40 ? normFp(c.fingerprint) : normFp(c.fingerprint256);
+                    if (!actual || actual !== this.fingerprint) {
+                        return finish(new RestError(
+                            `Server certificate fingerprint mismatch. Expected ${fmtFp(this.fingerprint)}, got ${c.fingerprint256 || '(none)'} (SHA-256) / ${c.fingerprint || '(none)'} (SHA-1)`,
+                            { code: 'ECERTPIN', actualFingerprint256: c.fingerprint256, actualFingerprint: c.fingerprint }
+                        ));
+                    }
+                }
+                finish(null, sock);
+            });
+        });
+    }
+
+    /**
+     * Make a request. Resolves { statusCode, headers, body, raw, url }.
+     * Rejects RestError for transport errors and HTTP >= 400 (statusCode/body attached).
+     */
+    async request(method, href, body, opts) {
+        opts = opts || {};
+        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.
+        const sock = await this._connect(target, signal, timeoutMs);
+        const payload = body === undefined || body === null ? null : Buffer.from(JSON.stringify(body));
+        const headers = {
+            Authorization: this.authHeader,
+            Accept: 'application/json',
+            Connection: 'close'
+        };
+        if (payload) {
+            headers['Content-Type'] = 'application/json';
+            headers['Content-Length'] = payload.length;
+        }
+        const lib = target.protocol === 'http:' ? http : https;
+
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (err, res) => {
+                if (settled) return;
+                settled = true;
+                if (signal) signal.removeEventListener('abort', onAbort);
+                if (err) reject(err); else resolve(res);
+            };
+            let req;
+            const onAbort = () => { if (req) req.destroy(); finish(abortError()); };
+            try {
+                req = lib.request({
+                    method,
+                    host: target.hostname,
+                    port: target.port,
+                    path: target.pathname + target.search,
+                    headers,
+                    createConnection: () => sock
+                }, onResponse);
+            } catch (e) {
+                // e.g. invalid header characters: don't leak the already-open socket
+                sock.destroy();
+                return finish(e);
+            }
+            function onResponse(res) {
+                const chunks = [];
+                res.on('data', (c) => chunks.push(c));
+                res.on('error', (e) => finish(e));
+                res.on('end', () => {
+                    const raw = Buffer.concat(chunks).toString('utf8');
+                    let parsed = raw;
+                    if (raw.length) {
+                        try { parsed = JSON.parse(raw); } catch (e) { /* leave as text */ }
+                    } else parsed = null;
+                    const out = { statusCode: res.statusCode, headers: res.headers, body: parsed, raw, url: target.toString(), method };
+                    if (res.statusCode >= 400) {
+                        const detail = parsed && typeof parsed === 'object' && parsed.message ? `: ${parsed.message}` : (typeof parsed === 'string' && parsed ? `: ${parsed.slice(0, 200)}` : '');
+                        return finish(new RestError(`HTTP ${res.statusCode} ${method} ${target.pathname}${detail}`, out));
+                    }
+                    finish(null, out);
+                });
+            }
+            if (signal) {
+                if (signal.aborted) return onAbort();
+                signal.addEventListener('abort', onAbort);
+            }
+            req.setTimeout(timeoutMs, () => {
+                req.destroy();
+                finish(new RestError(`Request timeout after ${timeoutMs} ms: ${method} ${target.pathname}`, { code: 'ETIMEDOUT', timeout: true }));
+            });
+            req.on('error', (e) => finish(e));
+            if (payload) req.write(payload);
+            req.end();
+        });
+    }
+
+    /** GET /api, cached for cacheMs (default 10 min). */
+    async discover(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' });
+        }
+        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) }
+     */
+    async getAll(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 b = res.body || {};
+            pages.push(b);
+            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);
+            if (!batch.length) break;
+            url = b.next && b.next.href ? b.next.href : null;
+        }
+        return { results, pages, pageCount: pages.length };
+    }
+}
+
+module.exports = { RestClient, RestError, normFp, fmtFp, DEFAULT_PORT };

package/lib/outputs.js

@@ -0,0 +1,76 @@
+'use strict';
+/**
+ * Shared helpers: every functional node has 3 outputs
+ *   [0] response  - full server response
+ *   [1] status    - state changes, for listing elsewhere (dashboards, logs)
+ *   [2] error     - errors, for listing elsewhere
+ */
+
+const OUT_RESPONSE = 0;
+const OUT_STATUS = 1;
+const OUT_ERROR = 2;
+
+const COLOURS = {
+    idle: { fill: 'grey', shape: 'ring' },
+    requesting: { fill: 'blue', shape: 'dot' },
+    paging: { fill: 'blue', shape: 'dot' },
+    done: { fill: 'green', shape: 'dot' },
+    subscribing: { fill: 'blue', shape: 'ring' },
+    subscribed: { fill: 'green', shape: 'ring' },
+    waiting: { fill: 'green', shape: 'ring' },
+    update: { fill: 'green', shape: 'dot' },
+    timeout: { fill: 'green', shape: 'ring' },
+    resubscribing: { fill: 'yellow', shape: 'ring' },
+    retrying: { fill: 'yellow', shape: 'dot' },
+    busy: { fill: 'yellow', shape: 'ring' },
+    stopped: { fill: 'grey', shape: 'ring' },
+    error: { fill: 'red', shape: 'dot' }
+};
+
+function nowIso() { return new Date().toISOString(); }
+
+function send(node, index, msg) {
+    const arr = [null, null, null];
+    arr[index] = msg;
+    node.send(arr);
+}
+
+function setStatus(node, state, text, extra) {
+    const c = COLOURS[state] || COLOURS.idle;
+    const shortText = text.length > 60 ? text.slice(0, 57) + '...' : text;
+    node.status({ fill: c.fill, shape: c.shape, text: shortText });
+    send(node, OUT_STATUS, {
+        topic: 'status',
+        payload: Object.assign({
+            state,
+            text,
+            node: node.id,
+            name: node.name || '',
+            type: node.type,
+            time: nowIso()
+        }, extra || {})
+    });
+}
+
+function reportError(node, err, extra) {
+    const payload = Object.assign({
+        message: err && err.message ? err.message : String(err),
+        code: err && err.code,
+        statusCode: err && err.statusCode,
+        url: err && err.url,
+        body: err && err.body,
+        node: node.id,
+        name: node.name || '',
+        type: node.type,
+        time: nowIso()
+    }, extra || {});
+    node.status({ fill: 'red', shape: 'dot', text: payload.message.length > 60 ? payload.message.slice(0, 57) + '...' : payload.message });
+    // log only (no msg arg), so Catch nodes don't double-report what output 3 already carries
+    node.error(payload.message);
+    send(node, OUT_ERROR, { topic: 'error', payload, error: { message: payload.message, source: { id: node.id, type: node.type, name: node.name } } });
+}
+
+/** Resolve the global-context store name ('' -> default store). */
+function storeName(s) { return s && s !== 'default' ? s : undefined; }
+
+module.exports = { OUT_RESPONSE, OUT_STATUS, OUT_ERROR, send, setStatus, reportError, storeName, nowIso };

package/nodes/rest-item-status.html

@@ -0,0 +1,101 @@
+<script type="text/javascript">
+    RED.nodes.registerType('tdn-rest-item-status', {
+        category: 'TDN REST',
+        color: '#E2D96E',
+        defaults: {
+            name: { value: '' },
+            server: { value: '', type: 'tdn-rest-server', required: true },
+            pollDelay: { value: 1000, 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: '' }
+        },
+        inputs: 1,
+        outputs: 3,
+        outputLabels: ['status updates', 'node status', 'error'],
+        icon: 'font-awesome/fa-heartbeat',
+        label: function () { return this.name || 'item status updates'; },
+        paletteLabel: 'item status',
+        oneditprepare: function () {
+            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-item-status">
+    <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="item status 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-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_itemStatus">
+    </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-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),
+       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>
+    <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>
+        <dd>A new trigger replaces the running subscription. <code>payload</code> = <code>"stop"</code> or <code>msg.stop = true</code> stops it.</dd>
+    </dl>
+    <h3>Outputs</h3>
+    <ol class="node-ports">
+        <li>Status updates
+            <dl class="message-properties">
+                <dt>payload <span class="property-type">object</span></dt><dd>Full server response: <code>{updates:[{id,status,statusText,statusFlags}], next:{href}}</code>.</dd>
+                <dt>updates <span class="property-type">array</span></dt><dd>Shortcut to <code>payload.updates</code>.</dd>
+                <dt>phase <span class="property-type">string</span></dt><dd><code>subscribe</code> (initial state from the POST), <code>update</code>, or <code>timeout</code> (only if enabled).</dd>
+                <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>
+    </ol>
+    <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>
+    <p>Before 9.50 the first update-wait repeats the POST's results; that is the server's behaviour and is passed through as-is.</p>
+</script>