@rosepetal/node-red-contrib-async-function 1.0.0 → 1.0.2

package/README.md

@@ -20,7 +20,7 @@ Run heavy computations in Node-RED without slowing down your flows. This node wo
 
 ## How It Works
 
-Drop an **async function** node into your flow. Write your code just like you would in a regular function node. The difference? Your code runs in a separate worker thread, so heavy operations won't freeze Node-RED.
+Drop an **async function** node into your flow. Write your code just like you would in a regular function node. The difference? Your code runs in a separate worker thread by default (or a child process if configured), so heavy operations won't freeze Node-RED.
 
 ## When to Use This
 
@@ -40,9 +40,10 @@ Drop an **async function** node into your flow. Write your code just like you wo
 - **Function** – Your JavaScript code. Works with `async/await`, `return`, and `require()`.
 - **Outputs** – How many output wires (0-10). Return an array for multiple outputs.
 - **Timeout** – Maximum seconds to wait before killing the worker. Default: 30 seconds.
+- **Runtime** – Worker Threads (default, fastest) or Child Process (for native modules like `gl`).
 
 ### Worker Pool
-- **Workers** – Fixed number of worker threads (1-16). Each node maintains exactly this many workers. Default: 3.
+- **Workers** – Fixed number of workers (1-16). Each node maintains exactly this many workers. Default: 3.
 - **Queue Size** – Messages to queue when all workers are occupied. Default: 100.
 
 ### Modules
@@ -165,7 +166,7 @@ The node shows you what's happening in real time:
 
 ## Performance Notes
 
-- Worker threads add about 5-10ms overhead per message.
+- Worker threads add about 5-10ms overhead per message (child process mode is higher).
 - Best for operations taking more than 10ms to run.
 - Each node maintains a fixed pool of workers—no startup delay or dynamic scaling overhead.
 - Workers are dedicated per-node, ensuring predictable performance.

package/nodes/async-function.html

@@ -7,10 +7,11 @@
         defaults: {
             name: { value: '' },
             func: {
-                value: '// Write your async code here\n// The code runs in a worker thread\n// Available: msg, return, async/await, require()\n// Not available: context, flow, global, node\n\nreturn msg;'
+                value: '// Write your async code here\n// The code runs in a worker thread or child process\n// Available: msg, return, async/await, require()\n// Not available: context, flow, global, node\n\nreturn msg;'
             },
             outputs: { value: 1, validate: RED.validators.number() },
             timeout: { value: 30000, validate: RED.validators.number() },
+            executionMode: { value: 'worker_threads' },
             numWorkers: { value: 3, validate: RED.validators.number() },
             maxQueueSize: { value: 100, validate: RED.validators.number() },
             libs: { value: [] },
@@ -239,6 +240,32 @@
             // Ensure configured module vars are registered in the editor on load
             updateEditorModules();
 
+            // Restart Workers button click handler
+            $('#node-restart-workers').on('click', function() {
+                var btn = $(this);
+                var status = $('#node-restart-status');
+                var nodeId = node.id;
+
+                btn.prop('disabled', true);
+                status.text('Restarting...').css('color', '#666');
+
+                $.ajax({
+                    url: 'async-function/' + nodeId + '/restart',
+                    type: 'POST',
+                    success: function(data) {
+                        status.text('✓ Workers restarted').css('color', 'green');
+                        setTimeout(function() { status.text(''); }, 3000);
+                    },
+                    error: function(xhr) {
+                        var msg = xhr.responseJSON ? xhr.responseJSON.error : 'Restart failed';
+                        status.text('✗ ' + msg).css('color', 'red');
+                    },
+                    complete: function() {
+                        btn.prop('disabled', false);
+                    }
+                });
+            });
+
             // Resize editor on dialog resize
             $('#dialog-form').on('dialogresize', function() {
                 const rows = $('#dialog-form>div:not(#async-func-tabs-content)');
@@ -412,6 +439,13 @@
                     <input id="node-input-timeout" style="width:120px;" value="30000">
                     <span style="margin-left:5px;">ms</span>
                 </div>
+                <div class="form-row">
+                    <label for="node-input-executionMode"><i class="fa fa-bolt"></i> Runtime</label>
+                    <select id="node-input-executionMode" style="width: 260px;">
+                        <option value="worker_threads">Worker Threads (fastest)</option>
+                        <option value="child_process">Child Process (native modules)</option>
+                    </select>
+                </div>
             </div>
 
             <!-- Worker Pool Section -->
@@ -440,6 +474,22 @@
                     <ol id="node-input-libs-container"></ol>
                 </div>
             </div>
+
+            <!-- Actions Section -->
+            <div class="async-func-section">
+                <div class="async-func-section-header">
+                    <i class="fa fa-refresh"></i> Actions
+                </div>
+                <div class="form-row" style="margin-bottom: 0;">
+                    <button type="button" class="red-ui-button" id="node-restart-workers">
+                        <i class="fa fa-refresh"></i> Restart Workers
+                    </button>
+                    <span id="node-restart-status" style="margin-left: 10px;"></span>
+                    <div style="margin-top: 8px; color: #999; font-size: 12px;">
+                        Restarts all worker processes/threads to reload modules and reset state.
+                    </div>
+                </div>
+            </div>
         </div>
 
         <!-- Function Tab -->
@@ -456,12 +506,13 @@
             <div class="form-tips">
                 <b>Tips:</b>
                 <ul style="margin-top:5px; margin-bottom:0;">
-                    <li>Code runs in a worker thread to prevent blocking</li>
-                    <li>Available: <code>msg</code>, <code>return</code>, <code>async/await</code>, <code>require()</code></li>
-                    <li>Not available: <code>context</code>, <code>flow</code>, <code>global</code>, <code>node</code></li>
-                    <li>Return <code>msg</code> for single output, or <code>[msg1, msg2]</code> for multiple outputs</li>
-                    <li>Return <code>null</code> to stop the flow</li>
-                </ul>
+                <li>Code runs in a worker thread or child process to prevent blocking</li>
+                <li>Available: <code>msg</code>, <code>return</code>, <code>async/await</code>, <code>require()</code></li>
+                <li>Not available: <code>context</code>, <code>flow</code>, <code>global</code>, <code>node</code></li>
+                <li>Use "Child Process" runtime for native modules that require main thread (e.g., <code>gl</code>)</li>
+                <li>Return <code>msg</code> for single output, or <code>[msg1, msg2]</code> for multiple outputs</li>
+                <li>Return <code>null</code> to stop the flow</li>
+            </ul>
             </div>
         </div>
 
@@ -469,7 +520,7 @@
 </script>
 
 <script type="text/html" data-help-name="async-function">
-    <p>Execute custom JavaScript code in a worker thread to prevent event loop blocking.</p>
+    <p>Execute custom JavaScript code in a worker thread or child process to prevent event loop blocking.</p>
 
     <h3>Inputs</h3>
     <dl class="message-properties">
@@ -486,8 +537,8 @@
     </dl>
 
     <h3>Details</h3>
-    <p>This node executes JavaScript code in a worker thread, preventing CPU-intensive operations
-    from blocking the Node-RED event loop.</p>
+    <p>This node executes JavaScript code in a worker thread or child process, preventing CPU-intensive
+    operations from blocking the Node-RED event loop.</p>
 
     <h4>Available in Code</h4>
     <ul>
@@ -554,8 +605,10 @@ return msg;</pre>
         <dd>Number of output ports (0-10). Use array return for multiple outputs.</dd>
         <dt>Timeout</dt>
         <dd>Maximum execution time in milliseconds (1000-300000). Worker is terminated if exceeded. Default: 30000 (30s).</dd>
+        <dt>Runtime</dt>
+        <dd>Worker Threads (default, fastest) or Child Process (useful for native modules like <code>gl</code>).</dd>
         <dt>Workers</dt>
-        <dd>Fixed number of worker threads (1-16). Each node maintains exactly this many workers. Default: 3.</dd>
+        <dd>Fixed number of workers (1-16). Each node maintains exactly this many workers. Default: 3.</dd>
         <dt>Queue Size</dt>
         <dd>Maximum number of messages queued when all workers are busy (10-1000). Default: 100.</dd>
         <dt>Buffers</dt>
@@ -582,7 +635,7 @@ return msg;</pre>
 
     <h3>Performance Notes</h3>
     <ul>
-        <li>Worker threads add ~5-10ms overhead per message</li>
+        <li>Worker threads add ~5-10ms overhead per message (child process mode is higher)</li>
         <li>Best for CPU-intensive operations (>10ms execution time)</li>
         <li>For simple operations, use the standard function node</li>
         <li>Workers are pooled and reused for efficiency</li>

package/nodes/async-function.js

@@ -5,8 +5,19 @@
  * to prevent event loop blocking.
  */
 
+const path = require('path');
 const { WorkerPool } = require('./lib/worker-pool');
-const { installModule, getNodeRedUserDir } = require('./lib/module-installer');
+const { ChildProcessPool } = require('./lib/child-process-pool');
+
+function resolveNodeRedUserDir(RED) {
+    if (RED && RED.settings && RED.settings.userDir) {
+        return path.resolve(RED.settings.userDir);
+    }
+    if (process.env.NODE_RED_HOME) {
+        return path.resolve(process.env.NODE_RED_HOME);
+    }
+    return process.cwd();
+}
 
 function extractMsgKeysFromCode(code) {
     const keys = new Set();
@@ -97,11 +108,30 @@ function applyPerformanceMetrics(node, originalMsg, targetMsg, performance) {
     }
     copyPerformance(targetMsg.performance, collected);
 
+    const transferToWorkerMs = normalizePerformanceValue(
+        performance.transferToWorkerMs ??
+        performance.transfer_to_worker_ms ??
+        performance.transferToPythonMs ??
+        performance.transfer_to_python_ms
+    );
+    const executionMs = normalizePerformanceValue(
+        performance.executionMs ?? performance.execution_ms
+    );
+    const transferToMainMs = normalizePerformanceValue(
+        performance.transferToMainMs ??
+        performance.transfer_to_main_ms ??
+        performance.transferToJsMs ??
+        performance.transfer_to_js_ms
+    );
+    const totalMs = normalizePerformanceValue(
+        performance.totalMs ?? performance.total_ms ?? performance.total
+    );
+
     collected[label] = {
-        transferToPythonMs: normalizePerformanceValue(performance.transfer_to_python_ms ?? performance.transferToPythonMs),
-        executionMs: normalizePerformanceValue(performance.execution_ms ?? performance.executionMs),
-        transferToJsMs: normalizePerformanceValue(performance.transfer_to_js_ms ?? performance.transferToJsMs),
-        totalMs: normalizePerformanceValue(performance.totalMs ?? performance.total_ms ?? performance.total)
+        transferToWorkerMs,
+        executionMs,
+        transferToMainMs,
+        totalMs
     };
 
     targetMsg.performance = collected;
@@ -188,6 +218,8 @@ module.exports = function(RED) {
         node.timeout = config.timeout || 30000;
         node.name = config.name || '';
         node.errorRecoveryTimer = null;  // Track error recovery timer
+        const modeValue = typeof config.executionMode === 'string' ? config.executionMode.trim() : '';
+        node.executionMode = modeValue.toLowerCase() === 'child_process' ? 'child_process' : 'worker_threads';
 
         // Migrate old config to new format (backwards compatibility)
         if (config.minWorkers !== undefined || config.maxWorkers !== undefined) {
@@ -196,59 +228,85 @@ module.exports = function(RED) {
         }
 
         // Store libs configuration
-        node.libs = config.libs || [];
+        node.libs = Array.isArray(config.libs) ? config.libs : [];
+
+        if (RED.settings.functionExternalModules === false && node.libs.length > 0) {
+            node.error('External modules are disabled by Node-RED settings.');
+            node.status({
+                fill: 'red',
+                shape: 'dot',
+                text: 'Modules disabled'
+            });
+            return;
+        }
+
+        const nodeRedUserDir = resolveNodeRedUserDir(RED);
+
+        // Verify modules are resolvable WITHOUT loading them in the main thread.
+        // Loading native modules (like 'gl') in main thread prevents them from
+        // working in worker threads due to native module registration conflicts.
+        if (node.libs.length > 0) {
+            const { createRequire } = require('module');
+            const nodeRedRequire = createRequire(path.join(nodeRedUserDir, 'package.json'));
 
-        // Pre-check and install missing modules
-        if (node.libs && node.libs.length > 0) {
             for (const lib of node.libs) {
+                if (!lib || !lib.module || !lib.var) {
+                    continue;
+                }
                 try {
-                    require.resolve(lib.module);
+                    // Only resolve the path - don't actually load the module
+                    nodeRedRequire.resolve(lib.module);
                 } catch (err) {
-                    if (err.code === 'MODULE_NOT_FOUND') {
-                        node.warn(`Installing missing module: ${lib.module}`);
-                        if (!installModule(lib.module)) {
-                            node.error(`Failed to install module: ${lib.module}. Please install it manually in ~/.node-red`);
-                        }
-                    }
+                    node.error(`Module "${lib.module}" not found. Install it with: cd ${nodeRedUserDir} && npm install ${lib.module}`);
+                    node.status({
+                        fill: 'red',
+                        shape: 'dot',
+                        text: `Module not found: ${lib.module}`
+                    });
+                    return;
                 }
             }
         }
 
-        // Create per-node worker pool
-        try {
-            node.pool = new WorkerPool({
-                numWorkers: config.numWorkers || 3,
-                maxQueueSize: config.maxQueueSize || 100,
-                taskTimeout: node.timeout,
-                shmThreshold: 0,
-                libs: node.libs,
-                nodeRedUserDir: getNodeRedUserDir()
-            });
-        } catch (err) {
-            node.error('Failed to create worker pool: ' + err.message);
-            node.status({
-                fill: 'red',
-                shape: 'dot',
-                text: 'Pool creation failed'
-            });
-            return;
-        }
+        const startPool = () => {
+            try {
+                const PoolImpl = node.executionMode === 'child_process' ? ChildProcessPool : WorkerPool;
+                node.pool = new PoolImpl({
+                    numWorkers: config.numWorkers || 3,
+                    maxQueueSize: config.maxQueueSize || 100,
+                    taskTimeout: node.timeout,
+                    shmThreshold: 0,
+                    libs: node.libs,
+                    nodeRedUserDir
+                });
+            } catch (err) {
+                node.error('Failed to create worker pool: ' + err.message);
+                node.status({
+                    fill: 'red',
+                    shape: 'dot',
+                    text: 'Pool creation failed'
+                });
+                return;
+            }
 
-        // Initialize pool
-        node.pool.initialize().then(() => {
-            updateStatus(node);
-            // Start periodic status updates
-            node.statusInterval = setInterval(() => {
+            node.pool.initialize().then(() => {
                 updateStatus(node);
-            }, 2000);  // Update every 2 seconds
-        }).catch(err => {
-            node.error('Failed to initialize worker pool: ' + err.message);
-            node.status({
-                fill: 'red',
-                shape: 'dot',
-                text: 'Init failed'
+                // Start periodic status updates
+                node.statusInterval = setInterval(() => {
+                    updateStatus(node);
+                }, 2000);  // Update every 2 seconds
+            }).catch(err => {
+                node.error('Failed to initialize worker pool: ' + err.message);
+                node.status({
+                    fill: 'red',
+                    shape: 'dot',
+                    text: 'Init failed'
+                });
             });
-        });
+        };
+
+        // Start the pool directly - module validation already done synchronously above
+        startPool();
 
         // Handle incoming messages
         node.on('input', async function(msg, send, done) {
@@ -260,6 +318,11 @@ module.exports = function(RED) {
                 }
             };
 
+            if (!node.pool) {
+                done(new Error('Worker pool is not initialized'));
+                return;
+            }
+
             const timing = { start: process.hrtime.bigint() };
             const workerMsg = buildWorkerInputMsg(msg, node.func);
 
@@ -347,5 +410,26 @@ module.exports = function(RED) {
     }
 
     // Register the node type
-    RED.nodes.registerType('async-function', AsyncFunctionNode);
+    RED.nodes.registerType('async-function', AsyncFunctionNode, {
+        dynamicModuleList: 'libs'
+    });
+
+    // HTTP endpoint to restart workers for a specific node
+    RED.httpAdmin.post('/async-function/:id/restart', async function(req, res) {
+        const node = RED.nodes.getNode(req.params.id);
+        if (!node || !node.pool) {
+            return res.status(404).json({ error: 'Node not found or pool not initialized' });
+        }
+
+        try {
+            await node.pool.shutdown();
+            node.pool.initialized = false;
+            node.pool.shuttingDown = false;
+            await node.pool.initialize();
+            updateStatus(node);
+            res.json({ success: true, message: 'Workers restarted' });
+        } catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
 };