CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Testing: npm test - Runs mocha tests (currently no tests implemented)

Installation for development:

# In this project directory
npm link

# In your Node-RED user directory (typically ~/.node-red)
npm link node-red-contrib-rosepetal-python-executor

# Restart Node-RED to load the new node

Linting & Type Checking: Currently no linting configured - consider adding ESLint and Python linting

Architecture Overview

This is a high-performance Node-RED custom node that executes Python code within flows. The architecture consists of four layers:

1. Node-RED Integration (python-executor.js)

• Implements standard Node-RED node API with two execution modes:
  • Single execution: New Python process per message (secure, ~50-100ms overhead)
  • Persistent process: Long-running Python process (fast, ~3-10ms overhead)
• Message queuing system for persistent mode with performance monitoring
• Process lifecycle management with automatic restart on crash
• Communication via JSON over stdin/stdout pipes
• Performance tracking: Execution time, throughput, queue monitoring
• Debug logging: Detailed performance metrics and statistics
• Enhanced status display: Real-time performance indicators

2. UI Layer (python-executor.html)

• Node registration with ACE/Monaco editor for syntax-highlighted Python code
• Configuration: Python path, timeout, execution mode, debug logging
• Lives in the "function" category with blue color (#3776AB)
• Performance monitoring UI: Debug checkbox for detailed logging
• Enhanced help documentation: Performance tips and usage examples

3. Python Execution (lib/python-runner.py)

• Two modes: --persistent flag for long-running process
• Enhanced return handling: Supports return statements via function wrapping
• Automatic image detection and base64 encoding/decoding
• Pre-imports safe modules: json, base64, math, datetime, random, re, collections, itertools
• Optional data science libraries: numpy (as np), pandas (as pd), PIL
• Captures stdout/stderr and includes in response
• Performance optimization: Minimal overhead for real-time applications

4. Security (lib/sandbox.py)

• AST-based code validation (currently disabled for performance)
• Forbidden imports: os, sys, subprocess, socket, urllib, etc.
• Restricted builtins environment
• Validates against dangerous attribute patterns (____, func_, im_*)

Communication Protocol

JSON messages over stdin/stdout:

Request:

{
  "code": "# Python code\nreturn msg",
  "msg": { "payload": "data", "topic": "test" }
}

Response:

// Success
{ 
  "result": { 
    "payload": "modified", 
    "_stdout": "print output",
    "_performance": {
      "executionTime": 5,
      "totalExecutions": 1234,
      "avgTime": 7,
      "queueLength": 0,
      "mode": "persistent"
    }
  } 
}

// Error
{ "error": { "message": "error", "type": "Exception", "traceback": "..." } }

Key Implementation Details

• Image handling: Automatically converts image bytes to/from base64 using detection of PNG/JPEG/GIF headers
• Return handling: Supports return statements via function wrapping (fixed issue with return outside function)
• Message queuing: Persistent mode queues messages and processes sequentially with performance tracking
• Process management: Monitors process health and restarts if needed
• Timeout enforcement: Uses setTimeout to kill hung processes
• Performance monitoring: Real-time execution time, throughput, and queue length tracking
• Debug logging: Optional detailed performance metrics and statistics
• Status indicators: Enhanced node status display with performance metrics

Performance Characteristics

• Persistent mode: 3-10ms average execution time for real-time applications
• Throughput: 100-300 messages/second depending on Python code complexity
• Queue management: Automatic queue length monitoring and status updates
• Memory efficiency: Optimized for long-running processes with automatic cleanup
• Error recovery: Automatic process restart on crashes with performance impact tracking

Files Structure

node-red-contrib-rosepetal-python-executor/
├── package.json                    # NPM package configuration
├── python-executor.html            # UI with syntax highlighting & performance config
├── python-executor.js              # Enhanced core logic with performance monitoring
├── lib/
│   ├── python-runner.py           # Enhanced Python execution with return support
│   └── sandbox.py                 # Security validation (disabled for performance)
├── examples/
│   ├── example-flow.json          # Basic usage examples
│   ├── opencv-example.json        # OpenCV/computer vision examples
│   └── high-performance-demo.json # Real-time performance testing
├── DEPENDENCIES.md                # Python dependencies and virtual env guide
├── PERFORMANCE.md                 # Performance optimization and real-time usage
├── README.md                      # Complete usage documentation
└── CLAUDE.md                      # This file

Development Notes

• No linting configured - consider adding ESLint and Python linting
• Test infrastructure exists but no tests written
• Could benefit from TypeScript for type safety
• The node follows standard Node-RED patterns for error handling with done() callbacks
• Performance optimized: Persistent mode recommended for real-time applications
• Security: Sandbox validation disabled by default for performance (can be re-enabled)
• Debugging: Use debug mode for detailed performance analysis