0
# Storage Nodes
1

2
Storage nodes provide file system interaction capabilities for reading, writing, and monitoring files and directories. These nodes enable Node-RED flows to persist data, process files, and react to file system changes.
3

4
## Capabilities
5

6
### File Output Node
7

8
Write data to files with various modes including append, overwrite, and delete operations.
9

10
```javascript { .api }
11
/**
12
 * File node for writing data to files
13
 * Registers as node type: "file"
14
 */
15
function FileNode(config) {
16
    RED.nodes.createNode(this, config);
17
    
18
    // Configuration properties:
19
    // config.filename - Target file path
20
    // config.appendNewline - Add newline after data
21
    // config.createDir - Create directory if it doesn't exist
22
    // config.overwriteFile - Overwrite mode: "false", "true", "delete"
23
    // config.encoding - File encoding: "none", "utf8", "ascii", "base64", "hex"
24
}
25
```
26

27
**Usage Examples:**
28

29
```javascript
30
// Append data to log file
31
{
32
    "filename": "/var/log/sensor-data.log",
33
    "appendNewline": true,
34
    "createDir": true,
35
    "overwriteFile": "false",
36
    "encoding": "utf8"
37
}
38

39
// Write JSON data to file (overwrite)
40
{
41
    "filename": "/tmp/config.json", 
42
    "appendNewline": false,
43
    "createDir": true,
44
    "overwriteFile": "true",
45
    "encoding": "utf8"
46
}
47

48
// Delete file
49
{
50
    "filename": "/tmp/temp-file.txt",
51
    "overwriteFile": "delete"
52
}
53

54
// Write binary data
55
{
56
    "filename": "/tmp/image.jpg",
57
    "encoding": "none",  // Binary mode
58
    "overwriteFile": "true"
59
}
60
```
61

62
### File Input Node
63

64
Read data from files with support for various formats and encoding options.
65

66
```javascript { .api }
67
/**
68
 * File In node for reading data from files
69
 * Registers as node type: "file in"
70
 */
71
function FileInNode(config) {
72
    RED.nodes.createNode(this, config);
73
    
74
    // Configuration properties:
75
    // config.filename - Source file path
76
    // config.format - Output format: "utf8", "lines", ""  (buffer)
77
    // config.chunk - Chunk size for large files
78
    // config.sendError - Send error if file doesn't exist
79
    // config.encoding - File encoding
80
    // config.allProps - Send all file properties
81
}
82
```
83

84
**Usage Examples:**
85

86
```javascript
87
// Read text file as string
88
{
89
    "filename": "/etc/config.txt",
90
    "format": "utf8",
91
    "sendError": false
92
}
93
// Output: { payload: "file contents as string" }
94

95
// Read file as lines array
96
{
97
    "filename": "/var/log/access.log", 
98
    "format": "lines",
99
    "sendError": true
100
}
101
// Output: { payload: ["line1", "line2", "line3", ...] }
102

103
// Read binary file as buffer
104
{
105
    "filename": "/tmp/image.png",
106
    "format": "",  // Buffer format
107
    "allProps": true
108
}
109
// Output: { 
110
//   payload: Buffer(...),
111
//   filename: "/tmp/image.png",
112
//   size: 12345,
113
//   lastModified: Date(...)
114
// }
115

116
// Dynamic filename from message
117
// Input:  { filename: "/tmp/data.json" }
118
// Config: { filename: "" }  // Empty = use msg.filename
119
// Output: Contents of /tmp/data.json
120
```
121

122
### Watch Node
123

124
Monitor file system changes including file modifications, creations, and deletions.
125

126
```javascript { .api }
127
/**
128
 * Watch node for monitoring file system changes
129
 * Registers as node type: "watch"
130
 */
131
function WatchNode(config) {
132
    RED.nodes.createNode(this, config);
133
    
134
    // Configuration properties:
135
    // config.files - Files/directories to watch (comma-separated)
136
    // config.recursive - Watch subdirectories recursively
137
    // config.watchType - Watch type: "file", "directory", "both"
138
}
139
```
140

141
**Usage Examples:**
142

143
```javascript
144
// Watch single file for changes
145
{
146
    "files": "/etc/config.conf",
147
    "recursive": false
148
}
149
// Output on change: { 
150
//   payload: "/etc/config.conf",
151
//   topic: "change", 
152
//   file: "/etc/config.conf",
153
//   type: "file"
154
// }
155

156
// Watch directory recursively
157
{
158
    "files": "/var/log/",
159
    "recursive": true,
160
    "watchType": "both"
161
}
162
// Monitors all files and subdirectories
163

164
// Watch multiple files/directories
165
{
166
    "files": "/tmp/file1.txt,/var/log/,/etc/config.d/",
167
    "recursive": false
168
}
169

170
// Watch events generated:
171
// - "change" - File content changed
172
// - "add" - File/directory created  
173
// - "unlink" - File deleted
174
// - "addDir" - Directory created
175
// - "unlinkDir" - Directory deleted
176
```
177

178
## Message Patterns
179

180
Storage nodes handle various message patterns for file operations:
181

182
```javascript { .api }
183
// File write message structure
184
interface FileWriteMessage {
185
    payload: string | Buffer;    // Data to write
186
    filename?: string;           // Target file (overrides config)
187
    encoding?: string;           // File encoding override
188
    append?: boolean;            // Append mode override
189
}
190

191
// File read message structure  
192
interface FileReadMessage {
193
    filename?: string;           // File to read (overrides config)
194
    encoding?: string;           // Encoding override
195
}
196

197
// File read output message
198
interface FileReadOutput {
199
    payload: string | Buffer | string[];  // File contents
200
    filename: string;                     // Source file path
201
    size?: number;                        // File size in bytes
202
    lastModified?: Date;                  // Last modification time
203
    encoding?: string;                    // File encoding used
204
}
205

206
// Watch event message
207
interface WatchEventMessage {
208
    payload: string;             // File/directory path
209
    topic: string;               // Event type: "change", "add", "unlink", etc.
210
    file: string;                // File path
211
    type: string;                // "file" or "directory"
212
    size?: number;               // File size (for file events)
213
}
214
```
215

216
## File Path Handling
217

218
Storage nodes support various file path patterns:
219

220
```javascript { .api }
221
// Absolute paths
222
{
223
    "filename": "/home/user/data.txt"          // Unix/Linux
224
    "filename": "C:\\Users\\User\\data.txt"   // Windows
225
}
226

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

233
// Dynamic paths from message properties
234
{
235
    "filename": ""  // Uses msg.filename
236
}
237
// Input message: { filename: "/tmp/dynamic.txt", payload: "data" }
238

239
// Path with variables (using mustache templates)
240
{
241
    "filename": "/logs/{{topic}}/{{timestamp}}.log"
242
}
243
// Input: { topic: "sensors", timestamp: "2023-01-01", payload: "data" }
244
// Writes to: /logs/sensors/2023-01-01.log
245
```
246

247
## Encoding Support
248

249
File nodes support various character encodings:
250

251
```javascript { .api }
252
// Text encodings
253
{
254
    "encoding": "utf8"     // Default for text files
255
    "encoding": "ascii"    // ASCII encoding  
256
    "encoding": "latin1"   // Latin-1/ISO-8859-1
257
    "encoding": "utf16le"  // UTF-16 Little Endian
258
}
259

260
// Binary encodings
261
{
262
    "encoding": "base64"   // Base64 encoding
263
    "encoding": "hex"      // Hexadecimal encoding
264
    "encoding": "none"     // Binary/buffer mode
265
}
266

267
// Encoding examples:
268
// UTF-8 text: "Hello World" → "Hello World"
269
// Base64: "Hello World" → "SGVsbG8gV29ybGQ="  
270
// Hex: "Hello World" → "48656c6c6f20576f726c64"
271
// Buffer: "Hello World" → Buffer<48 65 6c 6c 6f 20 57 6f 72 6c 64>
272
```
273

274
## Directory Operations
275

276
File nodes can create directories and handle directory-related operations:
277

278
```javascript { .api }
279
// Automatic directory creation
280
{
281
    "filename": "/deep/nested/path/file.txt",
282
    "createDir": true  // Creates /deep/nested/path/ if needed
283
}
284

285
// Directory watching
286
{
287
    "files": "/var/log/",
288
    "recursive": true,
289
    "watchType": "directory"  // Only directory events
290
}
291

292
// Directory deletion (via file delete)
293
{
294
    "filename": "/tmp/empty-directory/",
295
    "overwriteFile": "delete"  // Removes empty directory
296
}
297
```
298

299
## Error Handling
300

301
Storage nodes handle various file system error conditions:
302

303
```javascript { .api }
304
// Common error scenarios and handling:
305

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

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

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

318
// Invalid file path
319
// Result: Error message with path validation details
320

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

324
// File locked by another process
325
// Result: Error message indicating file is in use
326
```
327

328
## Advanced Features
329

330
### Large File Handling
331

332
```javascript { .api }
333
// Chunked reading for large files
334
{
335
    "format": "stream",     // Stream mode
336
    "chunk": "1024"         // 1KB chunks
337
}
338

339
// Streaming write operations
340
// Input: Stream of messages with incremental data
341
// Output: Continuous file writing without memory buildup
342
```
343

344
### File Metadata
345

346
```javascript { .api }
347
// Extended file information
348
{
349
    "allProps": true
350
}
351
// Output includes:
352
// - filename: File path
353
// - size: File size in bytes
354
// - lastModified: Last modification timestamp
355
// - created: Creation timestamp (if available)
356
// - mode: File permissions
357
// - isDirectory: Boolean directory flag
358
```
359

360
### Atomic Operations
361

362
```javascript { .api }
363
// Safe file writing (atomic operations)
364
{
365
    "filename": "/critical/config.json",
366
    "overwriteFile": "true",
367
    "createDir": true
368
}
369

370
// Process:
371
// 1. Write to temporary file
372
// 2. Verify write completion  
373
// 3. Atomic rename to target file
374
// 4. Ensures file is never partially written
375
```
376

377
## Security Considerations
378

379
Storage nodes implement security measures for file access:
380

381
```javascript { .api }
382
// Path traversal protection
383
// Blocked: "../../../etc/passwd"
384
// Blocked: "/etc/shadow"
385
// Allowed: "./data/file.txt" (within working directory)
386

387
// File permission checking
388
// Verifies read/write permissions before operations
389
// Respects system file access controls
390

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