@nrutils/node-red-utils 0.0.0-stage → 0.2.0

package/node-red-resourceendpoint/README.md

@@ -0,0 +1,119 @@
+# node-red-resourceendpoint
+
+Serve files from your node package to the editor: scripts, stylesheets, images, JSON.
+
+## Usage
+
+```js
+const path = require('path');
+const { NodeRedNodeBase, nodeRedResourceEndpoint } = require('@nrutils/node-red-utils');
+
+module.exports = NodeRedNodeBase.createNode('chart-node', [nodeRedResourceEndpoint], (RED, thisNode, config) => {
+    // the runtime code of the node
+}, {
+    resources: [
+        path.join(__dirname, 'public'),            // every file under public/
+        path.join(__dirname, 'icons', 'chart.svg') // one file
+    ]
+});
+```
+
+Put the paths in `resources` in the fourth argument of `createNode`. They are registered when Node-RED loads the node, before any deploy, so the editor can load the files at once. `init()` exists for paths that depend on `config`; they are served only after the first deploy. `createNode` does not pass `resources` on to `RED.nodes.registerType`; the other keys (`credentials`, `settings`) still go there. The mixin must be in the `mixins` array.
+
+The files are now served under `node-red-resourceendpoint/chart-node/` relative to the editor URL. In the node's `.html`, use relative URLs so that `httpAdminRoot` and reverse proxies work:
+
+```html
+<script type="text/javascript" src="node-red-resourceendpoint/chart-node/chart-lib.js"></script>
+<link rel="stylesheet" href="node-red-resourceendpoint/chart-node/chart.css">
+<img src="node-red-resourceendpoint/chart-node/chart.svg">
+```
+
+## Example: a model list for the edit dialog
+
+The edit dialog of an I2C sensor node fills a dropdown from a JSON file of the package, and sets the address of the selected model. This works for a new node that is not deployed yet, because the files are served from when Node-RED loads the node. [`nodeRedEditorComms`](../node-red-editorcomms/README.md) cannot do this: it needs a deployed node.
+
+`i2c-sensor.js`:
+
+```js
+const path = require('path');
+const { NodeRedNodeBase, nodeRedResourceEndpoint } = require('@nrutils/node-red-utils');
+
+module.exports = NodeRedNodeBase.createNode('i2c-sensor', [nodeRedResourceEndpoint], (RED, thisNode, config) => {
+    thisNode.on('input', (msg, send, done) => {
+        msg.payload = { model: config.model, address: Number(config.address) };   // read the device here
+        send(msg);
+        done();
+    });
+}, {
+    resources: [path.join(__dirname, 'editor')]     // editor/models.json and anything else in editor/
+});
+```
+
+`editor/models.json`:
+
+```json
+[
+    { "id": "bme280", "label": "Bosch BME280", "address": 118 },
+    { "id": "sht31", "label": "Sensirion SHT31", "address": 68 }
+]
+```
+
+`i2c-sensor.html`:
+
+```html
+<script type="text/javascript">
+    RED.nodes.registerType('i2c-sensor', {
+        category: 'input',
+        color: '#e2d96e',
+        defaults: { model: { value: 'bme280' }, address: { value: 118 } },
+        inputs: 1,
+        outputs: 1,
+        label: function () { return this.model; },
+        oneditprepare: function () {
+            const node = this;
+            const select = $('#node-input-model');
+            // A file of this package: it loads also for a new node that is not deployed
+            $.getJSON('node-red-resourceendpoint/i2c-sensor/models.json', function (models) {
+                for (const m of models) select.append($('<option>').val(m.id).text(m.label));
+                select.val(node.model).on('change', function () {
+                    const model = models.find((m) => m.id === select.val());
+                    if (model) $('#node-input-address').val(model.address);
+                });
+            });
+        }
+    });
+</script>
+
+<script type="text/html" data-template-name="i2c-sensor">
+    <div class="form-row">
+        <label for="node-input-model">Model</label>
+        <select id="node-input-model"></select>
+    </div>
+    <div class="form-row">
+        <label for="node-input-address">Address</label>
+        <input type="text" id="node-input-address">
+    </div>
+</script>
+```
+
+## URL rules
+
+URLs have the form `node-red-resourceendpoint/<nodeType>/<path>`.
+
+- A registered file is served under its base name: `icons/chart.svg` above becomes `.../chart-node/chart.svg`.
+- A registered directory serves every file inside it, also in subdirectories: `public/js/app.js` becomes `.../chart-node/js/app.js`.
+- Anything else returns 404 and logs a warning.
+
+## Warnings
+
+Registration logs a warning with `RED.log.warn` when:
+
+- a registered path does not exist, so its URLs would return 404;
+- two different npm packages register files for the same `nodeType`. Both sets of files are served under the same URL prefix, and for the same file name the first registration wins. Use your node type, which is unique, as `nodeType`.
+
+## Security
+
+The route has no auth check, also when `adminAuth` is on.
+Serve only files that are safe to make public: editor scripts, styles, images.
+
+[Back to node-red-utils](../README.md)

package/node-red-singleton/NodeRedSingletonBackend.js

@@ -0,0 +1,30 @@
+/**
+ * Copyright 2024 Contributors
+ * Licensed under the Apache License, Version 2.0
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+'use strict';
+
+const path = require('path');
+const { NodeRedResourceEndpoint } = require('../node-red-resourceendpoint/NodeRedResourceEndpoint.js');
+
+/**
+ * NodeRedSingleton - Mixin that ensures only one instance of a node type can exist in a flow
+ * 
+ * This mixin simply provides a resource endpoint for the frontend script that will 
+ * actually enforces the singleton pattern in the editor.
+ * 
+ * @param {class} superclass - The class to extend with singleton capabilities
+ * @returns {class} A new class that extends the superclass with singleton functionality
+ */
+const nodeRedSingleton = (superclass) => class extends superclass {
+    // Serve the frontend script before the first deploy
+    static onRegisterType(RED) {
+        super.onRegisterType?.(RED);
+        new NodeRedResourceEndpoint(RED).registerResources('node-red-singleton',
+            path.join(__dirname, 'NodeRedSingletonFrontend.js'));
+    }
+};
+
+module.exports.nodeRedSingleton = nodeRedSingleton;

package/node-red-singleton/NodeRedSingletonFrontend.js

@@ -0,0 +1,54 @@
+/**
+ * Copyright 2024 Contributors
+ * Licensed under the Apache License, Version 2.0
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+//
+//  NodeRedSingletonFrontend.js
+//
+//  Frontend handler for Node-RED singleton nodes.
+//  A node type with "singleton: true" in its definition can have one node in the editor.
+//  - A new node that one user action added alone (palette drop, quick add, paste of one node):
+//    the script undoes that action, so links, groups and the changed state come back too.
+//  - Other duplicates (an import of several nodes, a saved flow with two nodes):
+//    the script does not delete them. It shows a warning.
+//
+
+if (!window.NodeRedSingletonInitialized) {
+    window.NodeRedSingletonInitialized = true;
+
+    const instances = {};       // node type -> Set of node ids in the editor
+    const warned = new Set();   // node types with a warning in the current operation
+
+    // The node ids that a history event adds, also inside a "multi" event
+    const addedIds = (ev) => !ev ? [] : [...(ev.t === 'add' && ev.nodes) || [], ...(ev.events || []).flatMap(addedIds)];
+
+    function check(node) {
+        const ids = instances[node.type];
+        if (!ids || ids.size < 2 || !ids.has(node.id)) return;
+
+        const added = addedIds(RED.history.peek());
+        if (added.length === 1 && added[0] === node.id) {
+            RED.history.pop();
+            RED.view.redraw(true);
+            RED.notify(`Only one "${node.type}" node is allowed. The new node was removed.`, 'warning');
+        } else if (!warned.has(node.type)) {
+            warned.add(node.type);
+            setTimeout(() => warned.delete(node.type), 0);
+            RED.notify(`Only one "${node.type}" node is allowed, but the flows have ${ids.size}. Delete the extra nodes.`, 'warning');
+        }
+    }
+
+    RED.events.on('nodes:add', (node) => {
+        if (!node || !node.type || RED.nodes.getType(node.type)?.singleton !== true) return;
+        const ids = instances[node.type] ??= new Set();
+        ids.add(node.id);
+        // Wait until the editor has recorded the action in its history
+        if (ids.size > 1) setTimeout(() => check(node), 0);
+    });
+
+    RED.events.on('nodes:remove', (node) => {
+        if (node && node.type) instances[node.type]?.delete(node.id);
+    });
+}

package/node-red-singleton/README.md

@@ -0,0 +1,72 @@
+# node-red-singleton
+
+EXPERIMENTAL. The API and the behavior can change in a minor release.
+
+Allow only one node of a type in the editor. Useful for a node that owns a device, a port or another resource that two nodes cannot share.
+
+The check runs only in the editor. The runtime does not check, so a flow deployed through the admin API, or a flow file edited by hand, can still hold two nodes. If two nodes would break your node, also check in the runtime, as the example below does.
+
+## Usage
+
+A node that receives sensor data on a fixed UDP port. Two nodes cannot bind the same port, so the editor allows one node, and the runtime checks again:
+
+```js
+const dgram = require('dgram');
+const { NodeRedNodeBase, nodeRedSingleton } = require('@nrutils/node-red-utils');
+
+const PORT = 41234;     // the sensors send here; only one socket can bind this port
+let owner = null;       // id of the node that has the socket
+
+module.exports = NodeRedNodeBase.createNode('udp-sensors', [nodeRedSingleton], (RED, thisNode, config) => {
+    // A flow deployed through the admin API skips the editor check, so check here too
+    if (owner) {
+        thisNode.status({ fill: 'red', shape: 'ring', text: 'not started: one node only' });
+        thisNode.error(`Node ${owner} has UDP port ${PORT}. Only one udp-sensors node can run.`);
+        return;
+    }
+    owner = thisNode.id;
+    const socket = dgram.createSocket('udp4');
+    socket.on('message', (data, rinfo) => thisNode.send({ payload: data.toString(), sender: rinfo.address }));
+    socket.on('error', (err) => thisNode.error(err));
+    socket.bind(PORT);
+
+    thisNode.on('close', (done) => {
+        owner = null;
+        socket.close(() => done());
+    });
+});
+```
+
+```html
+<script type="text/javascript" src="node-red-resourceendpoint/node-red-singleton/NodeRedSingletonFrontend.js"></script>
+
+<script type="text/javascript">
+    RED.nodes.registerType('udp-sensors', {
+        category: 'function',
+        color: '#ffcccc',
+        singleton: true,
+        defaults: { name: { value: '' } },
+        inputs: 0,
+        outputs: 1,
+        label: function () { return this.name || 'udp-sensors'; }
+    });
+</script>
+
+<script type="text/html" data-template-name="udp-sensors">
+    <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="Name">
+    </div>
+</script>
+```
+
+`singleton: true` goes at the top level of the definition, not in `defaults`.
+
+## Behavior
+
+- When one user action adds only a second node of the type (drag from the palette, quick add, paste or import of that one node), the editor shows a warning and undoes that action. Thus the new node goes away with its links, and the changed state of the workspace is as before. Redo adds it again, and the check undoes it again.
+- When an import or paste adds a second node together with other nodes, the editor does not delete anything. It shows a warning that asks you to delete the extra nodes. The same warning shows when the editor loads saved flows that have two or more nodes of the type.
+- The limit covers the whole editor: all flow tabs, not one tab.
+- When you delete the existing node, you can add a new one.
+
+[Back to node-red-utils](../README.md)