mastercontroller 1.2.14 → 1.3.0

package/MasterControl.js

@@ -1,5 +1,5 @@
 // MasterControl - by Alexander rich
-// version 1.0.251
+// version 1.0.252
 
 var url = require('url');
 var fileserver = require('fs');
@@ -192,7 +192,16 @@ class MasterControl {
 
     component(folderLocation, innerFolder){
 
-        var rootFolderLocation = path.join(this.root, folderLocation, innerFolder);
+        // Enhanced: Support both relative (to master.root) and absolute paths
+        // If folderLocation is absolute, use it directly; otherwise join with master.root
+        var rootFolderLocation;
+        if (path.isAbsolute(folderLocation)) {
+            // Absolute path provided - use it directly
+            rootFolderLocation = path.join(folderLocation, innerFolder);
+        } else {
+            // Relative path - join with master.root (original behavior)
+            rootFolderLocation = path.join(this.root, folderLocation, innerFolder);
+        }
 
         // Structure is always: {rootFolderLocation}/config/initializers/config.js
         var configPath = path.join(rootFolderLocation, 'config', 'initializers', 'config.js');
@@ -251,6 +260,9 @@ class MasterControl {
             // before user config initializes them.
             try {
                 $that.addInternalTools([
+                    'MasterPipeline',
+                    'MasterTimeout',
+                    'MasterErrorRenderer',
                     'MasterAction',
                     'MasterActionFilters',
                     'MasterRouter',
@@ -267,6 +279,10 @@ class MasterControl {
             } catch (e) {
                 console.error('[MasterControl] Failed to load internal tools:', e && e.message);
             }
+
+            // Register core middleware that must run for framework to function
+            $that._registerCoreMiddleware();
+
             if(type === "http"){
                 $that.serverProtocol = "http";
                 return http.createServer(async function(req, res) {
@@ -423,120 +439,148 @@ class MasterControl {
         });
     }
 
-    async serverRun(req, res){
+    /**
+     * Register core middleware that must run for the framework to function
+     * This includes: static files, body parsing, scoped services, routing, error handling
+     */
+    _registerCoreMiddleware(){
         var $that = this;
-        console.log("path", `${req.method} ${req.url}`);
 
-          // Handle CORS preflight (OPTIONS) requests early and positively
-        if (req.method === 'OPTIONS') {
-            try {
-                if (this.cors && typeof this.cors.load === 'function') {
-                    if (!this.cors.options) {
-                        this.cors.init({
-                            origin: true,
-                            methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
-                            allowedHeaders: true,
-                            credentials: false,
-                            maxAge: 86400
-                        });
+        // 1. Static File Serving
+        $that.pipeline.use(async (ctx, next) => {
+            if (ctx.isStatic) {
+                // Serve static files
+                let pathname = `.${ctx.request.url}`;
+
+                fs.exists(pathname, function (exist) {
+                    if (!exist) {
+                        ctx.response.statusCode = 404;
+                        ctx.response.end(`File ${pathname} not found!`);
+                        return;
                     }
-                    this.cors.load({ request: req, response: res });
-                } else {
-                    res.setHeader('access-control-allow-origin', '*');
-                    res.setHeader('access-control-allow-methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
-                    if (req.headers['access-control-request-headers']) {
-                        res.setHeader('access-control-allow-headers', req.headers['access-control-request-headers']);
+
+                    if (fs.statSync(pathname).isDirectory()) {
+                        pathname += '/index' + path.parse(pathname).ext;
                     }
-                    res.setHeader('access-control-max-age', '86400');
-                }
-            } catch (e) {
-                res.setHeader('access-control-allow-origin', '*');
-                res.setHeader('access-control-allow-methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
-                if (req.headers['access-control-request-headers']) {
-                    res.setHeader('access-control-allow-headers', req.headers['access-control-request-headers']);
-                }
-                res.setHeader('access-control-max-age', '86400');
-            }
-            res.statusCode = 204;
-            res.setHeader('content-length', '0');
-            res.end();
-            return;
-        }
 
-        // Apply CORS headers to ALL non-OPTIONS requests
-        try {
-            if (this.cors && typeof this.cors.load === 'function') {
-                this.cors.load({ request: req, response: res });
-            }
-        } catch (e) {
-            console.warn('CORS load failed for non-OPTIONS request:', e.message);
-        }
+                    fs.readFile(pathname, function(err, data) {
+                        if (err) {
+                            ctx.response.statusCode = 500;
+                            ctx.response.end(`Error getting the file: ${err}.`);
+                        } else {
+                            const mimeType = $that.router.findMimeType(path.parse(pathname).ext);
+                            ctx.response.setHeader('Content-type', mimeType || 'text/plain');
+                            ctx.response.end(data);
+                        }
+                    });
+                });
 
-        // parse URL
-        const parsedUrl = url.parse(req.url);
-        // extract URL path
-        let pathname = `.${parsedUrl.pathname}`;
+                return; // Terminal - don't call next()
+            }
 
-        // based on the URL path, extract the file extension. e.g. .js, .doc, ...
-        const ext = path.parse(pathname).ext;
+            await next(); // Not static, continue pipeline
+        });
 
-        // handle simple preflight configuration - might need a complex approch for all scenarios
+        // 2. Timeout Tracking (optional - disabled by default until init)
+        // Will be configured by user in config.js with master.timeout.init()
+        // This is just a placeholder registration - actual timeout is set in user config
 
+        // 3. Request Body Parsing (always needed)
+        $that.pipeline.use(async (ctx, next) => {
+            // Parse body using MasterRequest
+            const params = await $that.request.getRequestParam(ctx.request, ctx.response);
 
-        // if extension exist then its a file.
-        if(ext === ""){
-          var requestObject = await this.middleware(req, res);
-          if(requestObject !== -1){
-            // HSTS header if enabled
-            if(this.serverProtocol === 'https' && this._hstsEnabled){
-                res.setHeader('strict-transport-security', `max-age=${this._hstsMaxAge}; includeSubDomains`);
+            // Merge parsed params into context
+            if (params && params.query) {
+                ctx.params.query = params.query;
             }
-            var loadedDone = false;
-            if (typeof $that._loadedFunc === 'function') {
-               loadedDone = $that._loadedFunc(requestObject);
-                if (loadedDone){
-                    require(`${this.root}/config/load`)(requestObject);
-                } 
+            if (params && params.formData) {
+                ctx.params.formData = params.formData;
             }
-            else{
-                require(`${this.root}/config/load`)(requestObject);
+
+            await next();
+        });
+
+        // 4. Load Scoped Services (per request - always needed)
+        $that.pipeline.use(async (ctx, next) => {
+            for (var key in $that._scopedList) {
+                var className = $that._scopedList[key];
+                $that.requestList[key] = new className();
             }
-           
-          
-          }
-        }
-        else{
-      
-            fs.exists(pathname, function (exist) {
-      
-                if(!exist) {
-                  // if the file is not found, return 404
-                  res.statusCode = 404;
-                  res.end(`File ${pathname} not found!`);
-                  return;
-                }
-      
-                // if is a directory search for index file matching the extension
-                if (fs.statSync(pathname).isDirectory()) pathname += '/index' + ext;
-      
-                // read file from file system
-                fs.readFile(pathname, function(err, data){
-                  if(err){
-                    res.statusCode = 500;
-                    res.end(`Error getting the file: ${err}.`);
-                  } else {
-                    const mimeType = $that.router.findMimeType(ext);
-                    
-                    // if the file is found, set Content-type and send data
-                    res.setHeader('Content-type', mimeType || 'text/plain' );
-                    res.end(data);
-                  }
-                });
-      
+            await next();
+        });
+
+        // 4. HSTS Header (if enabled for HTTPS)
+        $that.pipeline.use(async (ctx, next) => {
+            if ($that.serverProtocol === 'https' && $that._hstsEnabled) {
+                ctx.response.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+            }
+            await next();
+        });
+
+        // 5. Routing (TERMINAL - always needed)
+        $that.pipeline.run(async (ctx) => {
+            // Load config/load which triggers routing
+            require(`${$that.root}/config/load`)(ctx);
+        });
+
+        // 6. Global Error Handler
+        $that.pipeline.useError(async (error, ctx, next) => {
+            logger.error({
+                code: 'MC_ERR_PIPELINE',
+                message: 'Error in middleware pipeline',
+                error: error.message,
+                stack: error.stack,
+                path: ctx.request.url,
+                method: ctx.type
             });
+
+            if (!ctx.response.headersSent) {
+                ctx.response.statusCode = 500;
+                ctx.response.setHeader('Content-Type', 'application/json');
+                ctx.response.end(JSON.stringify({
+                    error: 'Internal Server Error',
+                    message: process.env.NODE_ENV === 'production'
+                        ? 'An error occurred'
+                        : error.message
+                }));
+            }
+        });
+    }
+
+    async serverRun(req, res){
+        var $that = this;
+        console.log("path", `${req.method} ${req.url}`);
+
+        // Create request context for middleware pipeline
+        const parsedUrl = url.parse(req.url);
+        const pathname = parsedUrl.pathname;
+        const ext = path.parse(pathname).ext;
+
+        const context = {
+            request: req,
+            response: res,
+            requrl: url.parse(req.url, true),
+            pathName: pathname.replace(/^\/|\/$/g, '').toLowerCase(),
+            type: req.method.toLowerCase(),
+            params: {},
+            state: {},       // User-defined state shared across middleware
+            master: $that,   // Access to framework instance
+            isStatic: ext !== '' // Is this a static file request?
+        };
+
+        // Execute middleware pipeline
+        try {
+            await $that.pipeline.execute(context);
+        } catch (error) {
+            console.error('Pipeline execution failed:', error);
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.end('Internal Server Error');
+            }
         }
-     
-    } // end server()
+
+    } // end serverRun()
 
     start(server){
         this.server = server;
@@ -565,6 +609,9 @@ class MasterControl {
         if(requiredList.constructor === Array){
             // Map module names to their new organized paths
             const modulePathMap = {
+                'MasterPipeline': './MasterPipeline',
+                'MasterTimeout': './MasterTimeout',
+                'MasterErrorRenderer': './error/MasterErrorRenderer',
                 'MasterError': './error/MasterError',
                 'MasterAction': './MasterAction',
                 'MasterActionFilters': './MasterActionFilters',

package/MasterCors.js

@@ -11,6 +11,13 @@ class MasterCors{
 		else{
 			master.error.log("cors options missing", "warn");
 		}
+
+		// Auto-register with pipeline if available
+		if (master.pipeline) {
+			master.pipeline.use(this.middleware());
+		}
+
+		return this; // Chainable
 	}
 
 	load(params){
@@ -167,6 +174,28 @@ class MasterCors{
 			}
 		}
 	}
+
+	/**
+	 * Get CORS middleware for the pipeline
+	 * Handles both preflight OPTIONS requests and regular requests
+	 */
+	middleware() {
+		var $that = this;
+
+		return async (ctx, next) => {
+			// Handle preflight OPTIONS request
+			if (ctx.type === 'options') {
+				$that.load({ request: ctx.request, response: ctx.response });
+				ctx.response.statusCode = 204;
+				ctx.response.end();
+				return; // Terminal - don't call next()
+			}
+
+			// Regular request - apply CORS headers
+			$that.load({ request: ctx.request, response: ctx.response });
+			await next();
+		};
+	}
 }
 
 master.extend("cors", MasterCors);

package/MasterPipeline.js

@@ -0,0 +1,344 @@
+// MasterPipeline - Middleware Pipeline System
+// version 1.0
+
+var master = require('./MasterControl');
+const { logger } = require('./error/MasterErrorLogger');
+
+class MasterPipeline {
+    constructor() {
+        this.middleware = [];
+        this.errorHandlers = [];
+    }
+
+    /**
+     * Use: Add middleware that processes request/response
+     *
+     * Middleware signature: async (ctx, next) => { await next(); }
+     * - ctx: Request context { request, response, params, state, ... }
+     * - next: Function to call next middleware in chain
+     *
+     * Example:
+     *   master.use(async (ctx, next) => {
+     *       console.log('Before');
+     *       await next();
+     *       console.log('After');
+     *   });
+     *
+     * @param {Function} middleware - Middleware function
+     * @returns {MasterPipeline} - For chaining
+     */
+    use(middleware) {
+        if (typeof middleware !== 'function') {
+            throw new Error('Middleware must be a function');
+        }
+
+        this.middleware.push({
+            type: 'use',
+            handler: middleware,
+            path: null
+        });
+
+        return this; // Chainable
+    }
+
+    /**
+     * Run: Add terminal middleware that ends the pipeline
+     *
+     * Terminal middleware signature: async (ctx) => { /* send response */ }
+     * - Does NOT call next()
+     * - Must send response
+     *
+     * Example:
+     *   master.run(async (ctx) => {
+     *       ctx.response.end('Hello World');
+     *   });
+     *
+     * @param {Function} middleware - Terminal middleware function
+     * @returns {MasterPipeline} - For chaining
+     */
+    run(middleware) {
+        if (typeof middleware !== 'function') {
+            throw new Error('Terminal middleware must be a function');
+        }
+
+        this.middleware.push({
+            type: 'run',
+            handler: middleware,
+            path: null
+        });
+
+        return this; // Chainable
+    }
+
+    /**
+     * Map: Conditionally execute middleware based on path
+     *
+     * Map signature: (path, configure)
+     * - path: String or RegExp to match request path
+     * - configure: Function that receives a branch pipeline
+     *
+     * Example:
+     *   master.map('/api/*', (api) => {
+     *       api.use(authMiddleware);
+     *       api.use(jsonMiddleware);
+     *   });
+     *
+     * @param {String|RegExp} path - Path pattern to match
+     * @param {Function} configure - Function to configure branch pipeline
+     * @returns {MasterPipeline} - For chaining
+     */
+    map(path, configure) {
+        if (typeof configure !== 'function') {
+            throw new Error('Map configuration must be a function');
+        }
+
+        // Create sub-pipeline for this branch
+        const branch = new MasterPipeline();
+        configure(branch);
+
+        // Wrap branch in conditional middleware
+        const conditionalMiddleware = async (ctx, next) => {
+            const requestPath = ctx.pathName || ctx.request.url;
+
+            if (this._pathMatches(requestPath, path)) {
+                // Execute branch pipeline
+                await branch.execute(ctx);
+                // After branch completes, continue main pipeline
+                await next();
+            } else {
+                // Skip branch, continue main pipeline
+                await next();
+            }
+        };
+
+        this.middleware.push({
+            type: 'map',
+            handler: conditionalMiddleware,
+            path: path
+        });
+
+        return this; // Chainable
+    }
+
+    /**
+     * UseError: Add error handling middleware
+     *
+     * Error middleware signature: async (error, ctx, next) => { }
+     * - error: The caught error
+     * - ctx: Request context
+     * - next: Pass to next error handler or rethrow
+     *
+     * Example:
+     *   master.useError(async (err, ctx, next) => {
+     *       if (err.statusCode === 404) {
+     *           ctx.response.statusCode = 404;
+     *           ctx.response.end('Not Found');
+     *       } else {
+     *           await next(); // Pass to next error handler
+     *       }
+     *   });
+     *
+     * @param {Function} handler - Error handler function
+     * @returns {MasterPipeline} - For chaining
+     */
+    useError(handler) {
+        if (typeof handler !== 'function') {
+            throw new Error('Error handler must be a function');
+        }
+
+        this.errorHandlers.push(handler);
+        return this; // Chainable
+    }
+
+    /**
+     * Execute: Run the middleware pipeline for a request
+     *
+     * Called internally by the framework for each request
+     *
+     * @param {Object} context - Request context
+     */
+    async execute(context) {
+        let index = 0;
+
+        // Create the next function for middleware chain
+        const next = async () => {
+            // If we've run all middleware, we're done
+            if (index >= this.middleware.length) {
+                return;
+            }
+
+            const current = this.middleware[index++];
+
+            try {
+                if (current.type === 'run') {
+                    // Terminal middleware - don't pass next
+                    await current.handler(context);
+                } else {
+                    // Regular middleware - pass next
+                    await current.handler(context, next);
+                }
+            } catch (error) {
+                // Error occurred, run error handlers
+                await this._handleError(error, context);
+            }
+        };
+
+        // Start the pipeline
+        await next();
+    }
+
+    /**
+     * Handle errors through error handler chain
+     *
+     * @param {Error} error - The error that occurred
+     * @param {Object} context - Request context
+     */
+    async _handleError(error, context) {
+        let errorIndex = 0;
+
+        const nextError = async () => {
+            if (errorIndex >= this.errorHandlers.length) {
+                // No more error handlers, log and send generic error
+                logger.error({
+                    code: 'MC_ERR_UNHANDLED',
+                    message: 'Unhandled error in middleware pipeline',
+                    error: error.message,
+                    stack: error.stack
+                });
+
+                if (!context.response.headersSent) {
+                    context.response.statusCode = 500;
+                    context.response.end('Internal Server Error');
+                }
+                return;
+            }
+
+            const handler = this.errorHandlers[errorIndex++];
+
+            try {
+                await handler(error, context, nextError);
+            } catch (handlerError) {
+                // Error in error handler
+                logger.error({
+                    code: 'MC_ERR_ERROR_HANDLER_FAILED',
+                    message: 'Error handler threw an error',
+                    error: handlerError.message
+                });
+                await nextError();
+            }
+        };
+
+        await nextError();
+    }
+
+    /**
+     * Check if request path matches the map path pattern
+     *
+     * @param {String} requestPath - The request path
+     * @param {String|RegExp} pattern - The pattern to match
+     * @returns {Boolean} - True if matches
+     */
+    _pathMatches(requestPath, pattern) {
+        // Normalize paths (ensure leading slash)
+        requestPath = '/' + requestPath.replace(/^\/|\/$/g, '');
+
+        if (typeof pattern === 'string') {
+            pattern = '/' + pattern.replace(/^\/|\/$/g, '');
+
+            // Wildcard support: /api/* matches /api/users, /api/posts, etc.
+            if (pattern.endsWith('/*')) {
+                const prefix = pattern.slice(0, -2);
+                return requestPath === prefix || requestPath.startsWith(prefix + '/');
+            }
+
+            // Exact or prefix match
+            return requestPath === pattern || requestPath.startsWith(pattern + '/');
+        }
+
+        if (pattern instanceof RegExp) {
+            return pattern.test(requestPath);
+        }
+
+        return false;
+    }
+
+    /**
+     * Discover and load middleware from folders
+     *
+     * @param {String|Object} options - Folder path or options object
+     */
+    discoverMiddleware(options) {
+        const fs = require('fs');
+        const path = require('path');
+
+        const folders = typeof options === 'string'
+            ? [options]
+            : (options.folders || ['middleware']);
+
+        folders.forEach(folder => {
+            const dir = path.join(master.root, folder);
+            if (!fs.existsSync(dir)) {
+                console.warn(`[Middleware] Folder not found: ${folder}`);
+                return;
+            }
+
+            const files = fs.readdirSync(dir)
+                .filter(file => file.endsWith('.js'))
+                .sort(); // Alphabetical order
+
+            files.forEach(file => {
+                try {
+                    const middlewarePath = path.join(dir, file);
+                    const middleware = require(middlewarePath);
+
+                    // Support two patterns:
+                    // Pattern 1: module.exports = async (ctx, next) => {}
+                    if (typeof middleware === 'function') {
+                        this.use(middleware);
+                    }
+                    // Pattern 2: module.exports = { register: (master) => {} }
+                    else if (middleware.register && typeof middleware.register === 'function') {
+                        middleware.register(master);
+                    }
+                    else {
+                        console.warn(`[Middleware] Invalid export in ${folder}/${file}`);
+                        return;
+                    }
+
+                    console.log(`[Middleware] Loaded: ${folder}/${file}`);
+                } catch (err) {
+                    console.error(`[Middleware] Failed to load ${folder}/${file}:`, err.message);
+                }
+            });
+        });
+    }
+
+    /**
+     * Clear all middleware (useful for testing)
+     */
+    clear() {
+        this.middleware = [];
+        this.errorHandlers = [];
+    }
+
+    /**
+     * Inspect pipeline (for debugging)
+     *
+     * @returns {Object} - Pipeline information
+     */
+    inspect() {
+        return {
+            middlewareCount: this.middleware.length,
+            errorHandlerCount: this.errorHandlers.length,
+            middleware: this.middleware.map((m, i) => ({
+                index: i,
+                type: m.type,
+                path: m.path,
+                name: m.handler.name || 'anonymous'
+            }))
+        };
+    }
+}
+
+// Register with master
+master.extend("pipeline", MasterPipeline);