mastercontroller 1.2.9 → 1.2.11

package/MasterAction.js

@@ -1,5 +1,5 @@
 
-// version 0.0.21
+// version 0.0.22
 
 var master = require('./MasterControl');
 var fileserver = require('fs');
@@ -133,18 +133,6 @@ class MasterAction{
 		}
 	}
 
-	returnReact(data, location){
-		
-			var masterView = null;
-			data = data === undefined ? {} : data;
-			this.params = this.params === undefined ? {} : this.params;
-			this.params = tools.combineObjects(data, this.params);
-			var func = master.viewList;
-			this.params = tools.combineObjects(this.params, func);
-			var html = master.reactView.compile(this.__currentRoute.toController, this.__currentRoute.toAction, this.__currentRoute.root);
-		
-	}
-
 	returnView(data, location){
 		
 		var masterView = null;
@@ -202,6 +190,74 @@ class MasterAction{
 		return false;
 	}
 
+	// Serves binary files with proper headers and MIME types
+	// options: {
+	//   contentType: string (auto-detected if not provided),
+	//   disposition: 'inline' | 'attachment' (default: 'attachment'),
+	//   filename: string (defaults to original filename)
+	// }
+	returnFile(filePath, options){
+		options = options || {};
+
+		// Default options
+		var disposition = options.disposition || 'attachment';
+		var filename = options.filename || filePath.split('/').pop();
+		var contentType = options.contentType;
+
+		// Auto-detect content type if not provided
+		if (!contentType) {
+			var ext = filePath.split('.').pop().toLowerCase();
+			var mimeTypes = {
+				'pdf': 'application/pdf',
+				'jpg': 'image/jpeg',
+				'jpeg': 'image/jpeg',
+				'png': 'image/png',
+				'gif': 'image/gif',
+				'svg': 'image/svg+xml',
+				'zip': 'application/zip',
+				'csv': 'text/csv',
+				'txt': 'text/plain',
+				'xml': 'application/xml',
+				'json': 'application/json',
+				'mp4': 'video/mp4',
+				'mp3': 'audio/mpeg',
+				'wav': 'audio/wav',
+				'doc': 'application/msword',
+				'docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+				'xls': 'application/vnd.ms-excel',
+				'xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+				'ppt': 'application/vnd.ms-powerpoint',
+				'pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation'
+			};
+			contentType = mimeTypes[ext] || 'application/octet-stream';
+		}
+
+		try {
+			// Read file as binary
+			var fileBuffer = fileserver.readFileSync(filePath);
+
+			// Build headers
+			var headers = {
+				'Content-Type': contentType,
+				'Content-Length': fileBuffer.length,
+				'Content-Disposition': disposition + '; filename="' + filename + '"'
+			};
+
+			// Send response
+			if (!this.__response._headerSent) {
+				this.__response.writeHead(200, headers);
+				this.__response.end(fileBuffer);
+			}
+		} catch(error) {
+			// Handle file not found or read errors
+			if (!this.__response._headerSent) {
+				this.__response.writeHead(404, {'Content-Type': 'text/plain'});
+				this.__response.end('File not found: ' + filePath);
+			}
+			console.error('Error serving file:', error);
+		}
+	}
+
 
 }
 

package/README.md

@@ -49,6 +49,50 @@ Use `setupServer('https', credentials)` or configure via environment TLS; see do
 - `docs/server-setup-nginx-reverse-proxy.md`
 - `docs/environment-tls-reference.md`
 
+### How File Uploads Work
+
+MasterController handles file uploads through the `formidable` library (v3.5.4+) integrated into the request parsing pipeline in `MasterRequest.js`.
+
+**Processing Flow:**
+
+1. **Content-Type Detection** - When a request arrives, the framework parses the `Content-Type` header to determine how to handle the request body (`MasterRequest.js:34-36`)
+
+2. **Multipart Form Data** - For `multipart/form-data` requests (file uploads), the framework uses formidable's `IncomingForm` to parse the request (`MasterRequest.js:43-78`)
+
+3. **Event-Based Parsing** - Formidable emits events during parsing:
+   - `field` event: Captures regular form fields and adds them to `parsedURL.formData.fields`
+   - `file` event: Captures uploaded files and stores them in `parsedURL.formData.files` as arrays (supporting multiple file uploads per field)
+   - `end` event: Signals completion and resolves the promise with parsed data
+
+4. **File Metadata** - Each uploaded file object includes:
+   - `name` or `originalFilename`: The original filename
+   - `extension`: Extracted file extension (e.g., `.jpg`, `.pdf`)
+   - `filepath`: Temporary location where formidable stored the file
+   - Other formidable metadata (size, mimetype, etc.)
+
+5. **Accessing Uploads in Controllers** - In your controller actions, access uploaded files via:
+   ```js
+   this.params.formData.files['fieldName'][0]  // First file for 'fieldName'
+   this.params.formData.fields['textField']     // Regular form fields
+   ```
+
+6. **Multiple Files** - Files are always stored as arrays in `parsedURL.formData.files[field]`, allowing multiple files to be uploaded with the same field name (`MasterRequest.js:59-65`)
+
+7. **Cleanup** - Use `this.request.deleteFileBuffer(filePath)` to remove temporary files after processing (`MasterRequest.js:162-169`)
+
+**Configuration Options:**
+
+You can configure file upload behavior via `master.request.init()`:
+- `disableFormidableMultipartFormData`: Set to `true` to skip file upload parsing
+- `formidable`: Pass options directly to formidable (upload directory, max file size, etc.)
+
+**Supported Content Types:**
+- `multipart/form-data` - File uploads
+- `application/x-www-form-urlencoded` - Standard forms
+- `application/json` - JSON payloads
+- `text/plain` - Plain text (1MB limit)
+- `text/html` - HTML content
+
 ### Production tips
 - Prefer a reverse proxy for TLS and serve Node on a high port.
 - If keeping TLS in Node, harden TLS and manage cert rotation.

package/examples/FileServingExample.js

@@ -0,0 +1,88 @@
+// Example: Binary File Serving with MasterController
+//
+// This example demonstrates how to use the returnFile() method
+// to serve binary files in your MasterController application.
+
+class ExampleController extends MasterAction {
+
+	// Example 1: Serve a PDF file for download
+	downloadPdf(){
+		var filePath = master.root + '/storage/documents/report.pdf';
+		this.returnFile(filePath);
+		// Downloads as 'report.pdf' with auto-detected content-type
+	}
+
+	// Example 2: Display an image inline
+	showImage(){
+		var filePath = master.root + '/storage/images/photo.jpg';
+		this.returnFile(filePath, {
+			disposition: 'inline'  // Display in browser instead of download
+		});
+	}
+
+	// Example 3: Serve file with custom filename
+	downloadReport(){
+		var filePath = master.root + '/storage/reports/monthly-2024-01.pdf';
+		this.returnFile(filePath, {
+			filename: 'January_Report.pdf'  // Custom filename for download
+		});
+	}
+
+	// Example 4: Serve file with explicit content type
+	downloadCsv(){
+		var filePath = master.root + '/storage/exports/data.csv';
+		this.returnFile(filePath, {
+			contentType: 'text/csv',
+			filename: 'export.csv'
+		});
+	}
+
+	// Example 5: Serve dynamic file based on user request
+	downloadUserFile(){
+		var fileId = this.params.id;
+		var filePath = master.root + '/storage/user-files/' + fileId;
+
+		// You might want to add authentication/authorization checks here
+		// if (this.session.userId !== file.ownerId) { ... }
+
+		this.returnFile(filePath, {
+			filename: 'user-document.pdf'
+		});
+	}
+
+	// Example 6: Serve images inline (for img src tags)
+	serveUserAvatar(){
+		var userId = this.params.id;
+		var avatarPath = master.root + '/storage/avatars/' + userId + '.png';
+		this.returnFile(avatarPath, {
+			disposition: 'inline',
+			contentType: 'image/png'
+		});
+	}
+
+}
+
+module.exports = ExampleController;
+
+
+// Supported MIME types (auto-detected by file extension):
+//
+// Images: jpg, jpeg, png, gif, svg
+// Documents: pdf, doc, docx, xls, xlsx, ppt, pptx
+// Data: csv, json, xml, txt
+// Archives: zip
+// Media: mp3, mp4, wav
+//
+// For other file types, use contentType option or files will be served as 'application/octet-stream'
+
+
+// Route configuration example:
+// In your routes.js:
+//
+// {
+//   "url" : "/download/pdf",
+//   "namespace" : "example",
+//   "controller" : "ExampleController",
+//   "action" : "downloadPdf",
+//   "type" : "GET"
+// }

package/package.json

@@ -18,5 +18,5 @@
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "version": "1.2.9"
+  "version": "1.2.11"
 }