Storage Nodes

/**
 * File node for writing data to files
 * Registers as node type: "file"
 */
function FileNode(config) {
    RED.nodes.createNode(this, config);
    
    // Configuration properties:
    // config.filename - Target file path
    // config.appendNewline - Add newline after data
    // config.createDir - Create directory if it doesn't exist
    // config.overwriteFile - Overwrite mode: "false", "true", "delete"
    // config.encoding - File encoding: "none", "utf8", "ascii", "base64", "hex"
}

// Append data to log file
{
    "filename": "/var/log/sensor-data.log",
    "appendNewline": true,
    "createDir": true,
    "overwriteFile": "false",
    "encoding": "utf8"
}

// Write JSON data to file (overwrite)
{
    "filename": "/tmp/config.json", 
    "appendNewline": false,
    "createDir": true,
    "overwriteFile": "true",
    "encoding": "utf8"
}

// Delete file
{
    "filename": "/tmp/temp-file.txt",
    "overwriteFile": "delete"
}

// Write binary data
{
    "filename": "/tmp/image.jpg",
    "encoding": "none",  // Binary mode
    "overwriteFile": "true"
}

/**
 * File In node for reading data from files
 * Registers as node type: "file in"
 */
function FileInNode(config) {
    RED.nodes.createNode(this, config);
    
    // Configuration properties:
    // config.filename - Source file path
    // config.format - Output format: "utf8", "lines", ""  (buffer)
    // config.chunk - Chunk size for large files
    // config.sendError - Send error if file doesn't exist
    // config.encoding - File encoding
    // config.allProps - Send all file properties
}

// Read text file as string
{
    "filename": "/etc/config.txt",
    "format": "utf8",
    "sendError": false
}
// Output: { payload: "file contents as string" }

// Read file as lines array
{
    "filename": "/var/log/access.log", 
    "format": "lines",
    "sendError": true
}
// Output: { payload: ["line1", "line2", "line3", ...] }

// Read binary file as buffer
{
    "filename": "/tmp/image.png",
    "format": "",  // Buffer format
    "allProps": true
}
// Output: { 
//   payload: Buffer(...),
//   filename: "/tmp/image.png",
//   size: 12345,
//   lastModified: Date(...)
// }

// Dynamic filename from message
// Input:  { filename: "/tmp/data.json" }
// Config: { filename: "" }  // Empty = use msg.filename
// Output: Contents of /tmp/data.json

/**
 * Watch node for monitoring file system changes
 * Registers as node type: "watch"
 */
function WatchNode(config) {
    RED.nodes.createNode(this, config);
    
    // Configuration properties:
    // config.files - Files/directories to watch (comma-separated)
    // config.recursive - Watch subdirectories recursively
    // config.watchType - Watch type: "file", "directory", "both"
}

// Watch single file for changes
{
    "files": "/etc/config.conf",
    "recursive": false
}
// Output on change: { 
//   payload: "/etc/config.conf",
//   topic: "change", 
//   file: "/etc/config.conf",
//   type: "file"
// }

// Watch directory recursively
{
    "files": "/var/log/",
    "recursive": true,
    "watchType": "both"
}
// Monitors all files and subdirectories

// Watch multiple files/directories
{
    "files": "/tmp/file1.txt,/var/log/,/etc/config.d/",
    "recursive": false
}

// Watch events generated:
// - "change" - File content changed
// - "add" - File/directory created  
// - "unlink" - File deleted
// - "addDir" - Directory created
// - "unlinkDir" - Directory deleted

// File write message structure
interface FileWriteMessage {
    payload: string | Buffer;    // Data to write
    filename?: string;           // Target file (overrides config)
    encoding?: string;           // File encoding override
    append?: boolean;            // Append mode override
}

// File read message structure  
interface FileReadMessage {
    filename?: string;           // File to read (overrides config)
    encoding?: string;           // Encoding override
}

// File read output message
interface FileReadOutput {
    payload: string | Buffer | string[];  // File contents
    filename: string;                     // Source file path
    size?: number;                        // File size in bytes
    lastModified?: Date;                  // Last modification time
    encoding?: string;                    // File encoding used
}

// Watch event message
interface WatchEventMessage {
    payload: string;             // File/directory path
    topic: string;               // Event type: "change", "add", "unlink", etc.
    file: string;                // File path
    type: string;                // "file" or "directory"
    size?: number;               // File size (for file events)
}

// Absolute paths
{
    "filename": "/home/user/data.txt"          // Unix/Linux
    "filename": "C:\\Users\\User\\data.txt"   // Windows
}

// Relative paths (relative to Node-RED working directory)
{
    "filename": "data/sensors.log"
    "filename": "../config/settings.json"
}

// Dynamic paths from message properties
{
    "filename": ""  // Uses msg.filename
}
// Input message: { filename: "/tmp/dynamic.txt", payload: "data" }

// Path with variables (using mustache templates)
{
    "filename": "/logs/{{topic}}/{{timestamp}}.log"
}
// Input: { topic: "sensors", timestamp: "2023-01-01", payload: "data" }
// Writes to: /logs/sensors/2023-01-01.log

// Text encodings
{
    "encoding": "utf8"     // Default for text files
    "encoding": "ascii"    // ASCII encoding  
    "encoding": "latin1"   // Latin-1/ISO-8859-1
    "encoding": "utf16le"  // UTF-16 Little Endian
}

// Binary encodings
{
    "encoding": "base64"   // Base64 encoding
    "encoding": "hex"      // Hexadecimal encoding
    "encoding": "none"     // Binary/buffer mode
}

// Encoding examples:
// UTF-8 text: "Hello World" → "Hello World"
// Base64: "Hello World" → "SGVsbG8gV29ybGQ="  
// Hex: "Hello World" → "48656c6c6f20576f726c64"
// Buffer: "Hello World" → Buffer<48 65 6c 6c 6f 20 57 6f 72 6c 64>

// Automatic directory creation
{
    "filename": "/deep/nested/path/file.txt",
    "createDir": true  // Creates /deep/nested/path/ if needed
}

// Directory watching
{
    "files": "/var/log/",
    "recursive": true,
    "watchType": "directory"  // Only directory events
}

// Directory deletion (via file delete)
{
    "filename": "/tmp/empty-directory/",
    "overwriteFile": "delete"  // Removes empty directory
}

// Common error scenarios and handling:

// File not found (read operations)
{
    "sendError": true   // Send error message to flow
    "sendError": false  // Silent failure, no output
}

// Permission denied
// Result: Error message with details sent to catch nodes

// Disk space full (write operations)  
// Result: Error message indicating insufficient space

// Invalid file path
// Result: Error message with path validation details

// Watch target doesn't exist
// Result: Warning logged, watch continues for when target appears

// File locked by another process
// Result: Error message indicating file is in use

// Chunked reading for large files
{
    "format": "stream",     // Stream mode
    "chunk": "1024"         // 1KB chunks
}

// Streaming write operations
// Input: Stream of messages with incremental data
// Output: Continuous file writing without memory buildup

// Extended file information
{
    "allProps": true
}
// Output includes:
// - filename: File path
// - size: File size in bytes
// - lastModified: Last modification timestamp
// - created: Creation timestamp (if available)
// - mode: File permissions
// - isDirectory: Boolean directory flag

// Safe file writing (atomic operations)
{
    "filename": "/critical/config.json",
    "overwriteFile": "true",
    "createDir": true
}

// Process:
// 1. Write to temporary file
// 2. Verify write completion  
// 3. Atomic rename to target file
// 4. Ensures file is never partially written

// Path traversal protection
// Blocked: "../../../etc/passwd"
// Blocked: "/etc/shadow"
// Allowed: "./data/file.txt" (within working directory)

// File permission checking
// Verifies read/write permissions before operations
// Respects system file access controls

// Sandbox restrictions (when enabled)
// Limits file access to designated directories only
// Prevents access to system files and sensitive locations