@triophore/falconjs 1.0.0

package/falconBaseWorker.js

@@ -0,0 +1,540 @@
+require('dotenv').config({ quiet: true, debug: false });
+const mqtt = require("mqtt");
+const config = process.env;
+const crypto = require('crypto');
+const mongoose = require('mongoose');
+const bcrypt = require('bcrypt');
+const mongoosePaginate = require('mongoose-paginate-v2');
+const path = require('path');
+const fs = require('fs');
+const JWT = require('jsonwebtoken');
+const { v4: uuidv4 } = require('uuid');
+const redis = require("redis");
+const axios = require("axios");
+const { ValidationError, DatabaseError } = require('./core/errors');
+
+/**
+ * Base class for Falcon workers that process background tasks and jobs.
+ * Workers are typically short-lived processes that handle specific tasks like image processing,
+ * data transformation, or batch operations. They can be spawned on-demand or run continuously.
+ * 
+ * @class FalconBaseWorker
+ * @example
+ * class ImageProcessor extends FalconBaseWorker {
+ *   constructor() {
+ *     super('image-processor');
+ *   }
+ *   
+ *   async onMessage(topic, msg) {
+ *     if (topic === 'worker_image-processor_job') {
+ *       const job = JSON.parse(msg);
+ *       await this.processImage(job);
+ *     }
+ *   }
+ *   
+ *   async run() {
+ *     const args = this.parseArgs();
+ *     if (args.jobId) {
+ *       await this.processJob(args.jobId);
+ *       process.exit(0); // Exit after single job
+ *     }
+ *     // Otherwise wait for MQTT jobs
+ *   }
+ * }
+ * 
+ * const worker = new ImageProcessor();
+ * worker.init();
+ */
+class FalconBaseWorker {
+
+    /**
+     * Creates a new Falcon worker instance.
+     * Automatically loads settings, parses command line arguments, and sets up graceful shutdown.
+     * 
+     * @param {string} workerId - Worker identifier used for MQTT topics and logging
+     * @throws {Error} Throws if worker ID is not provided
+     * 
+     * @example
+     * class MyWorker extends FalconBaseWorker {
+     *   constructor() {
+     *     super('my-worker'); // Creates topics: worker_my-worker, worker_my-worker_job, worker_my-worker_ping
+     *   }
+     * }
+     */
+    constructor(workerId) {
+        if (!workerId || typeof workerId !== 'string') {
+            throw new ValidationError('workerId must be a non-empty string');
+        }
+        
+        this.workerId = workerId;
+        this.models = {};
+        this.CONTEXT = { models: {} };
+        this.db = null;
+        this.mqttClient = null;
+        this.redisClient = null;
+        this.env = process.env;
+        this.args = process.argv.slice(2);
+
+        // Load settings from CWD
+        try {
+            const settingsPath = path.join(process.cwd(), 'settings.js');
+            if (fs.existsSync(settingsPath)) {
+                this.SETTINGS = require(settingsPath).settings;
+            } else {
+                console.warn("Settings file not found in CWD");
+                this.SETTINGS = { models: [] };
+            }
+        } catch (e) {
+            console.error("Error loading settings:", e);
+            this.SETTINGS = { models: [] };
+        }
+
+        this.setupGracefulShutdown();
+    }
+
+    /**
+     * Checks if running in development mode.
+     * @private
+     * @returns {boolean}
+     */
+    #isDev() {
+        return process.env.MODE === "DEV";
+    }
+
+    /**
+     * Parses command line arguments passed to the worker process.
+     * Supports both base64 encoded JSON (preferred) and simple key=value pairs.
+     * The main Falcon server uses base64 JSON when spawning workers.
+     * 
+     * @returns {Object} Parsed arguments object
+     * 
+     * @example
+     * // Base64 JSON (from Falcon server):
+     * // node worker.js eyJqb2JJZCI6MTIzLCJ0eXBlIjoiaW1hZ2UifQ==
+     * const args = this.parseArgs(); // { jobId: 123, type: "image" }
+     * 
+     * // Key=value pairs (manual execution):
+     * // node worker.js jobId=123 type=image
+     * const args = this.parseArgs(); // { jobId: "123", type: "image" }
+     * 
+     * // No arguments:
+     * const args = this.parseArgs(); // {}
+     */
+    parseArgs() {
+        if (this.args.length === 0) return {};
+        
+        try {
+            // Try to parse as base64 encoded JSON first
+            const decoded = Buffer.from(this.args[0], 'base64').toString('utf8');
+            return JSON.parse(decoded);
+        } catch (e) {
+            // Fallback to simple key=value parsing
+            const parsed = {};
+            this.args.forEach(arg => {
+                const [key, value] = arg.split('=');
+                if (key && value) {
+                    parsed[key] = value;
+                }
+            });
+            return parsed;
+        }
+    }
+
+    /**
+     * Loads a model by name from various possible locations.
+     * Searches in: models/mongo/, models/, workers/models/
+     * 
+     * @private
+     * @param {string} name - Model name without .js extension
+     * @throws {Error} Logs error if model loading fails but doesn't throw
+     * 
+     * @example
+     * // Searches for job.js in:
+     * // - /project/models/mongo/job.js
+     * // - /project/models/job.js  
+     * // - /project/workers/models/job.js
+     * await this.#load_model_name('job');
+     */
+    async #load_model_name(name) {
+        const cwd = process.cwd();
+        const potentialPaths = [
+            path.join(cwd, "models", "mongo", name + ".js"),
+            path.join(cwd, "models", name + ".js"),
+            path.join(cwd, "workers", "models", name + ".js")
+        ];
+
+        let modelPath = null;
+        for (const p of potentialPaths) {
+            if (fs.existsSync(p)) {
+                modelPath = p;
+                break;
+            }
+        }
+
+        if (modelPath) {
+            try {
+                const _temp = await require(modelPath)(mongoose);
+                this.models[name] = _temp;
+                this.CONTEXT["models"][name] = _temp;
+                console.info(`${name} model registered from ${modelPath}`);
+            } catch (e) {
+                console.error(`Failed to load model ${name} from ${modelPath}:`, e);
+            }
+        } else {
+            console.warn(`Model ${name} not found in any standard location.`);
+        }
+    }
+
+    /**
+     * Connects to MongoDB database.
+     * @private
+     */
+    async #startMongoDB() {
+        if (!config.MONGODB_URL) {
+            console.warn("MONGODB_URL not configured, skipping database connection");
+            return;
+        }
+
+        if (this.#isDev()) {
+            mongoose.set("debug", true);
+            console.debug("Mongoose ODM is set in Debug Mode");
+        }
+
+        try {
+            await mongoose.connect(config.MONGODB_URL, {});
+            mongoose.set("debug", (collectionName, method, query, doc) => {
+                console.info(`MONGOOSE ==> ${collectionName}.${method}`, JSON.stringify(query), doc);
+            });
+            this.db = mongoose.connection.db;
+            this.CONTEXT["db"] = this.db;
+            this.CONTEXT["mongoose"] = mongoose;
+            console.info("MongoDB connected");
+        } catch (error) {
+            console.error("MongoDB connection failed:", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Connects to Redis if enabled.
+     * @private
+     */
+    async #startRedis() {
+        if (config.REDIS_ENABLE === "true" && config.REDIS_URL) {
+            try {
+                this.redis_client = await redis.createClient({ url: config.REDIS_URL }).connect();
+                this.CONTEXT["redis"] = this.redis_client;
+                console.info("Redis connected");
+            } catch (error) {
+                console.error("Redis connection failed:", error);
+            }
+        }
+    }
+
+    /**
+     * Connects to MQTT broker.
+     * @private
+     */
+    async #startMQTT() {
+        if (!config.MQTT_URL) {
+            console.warn("MQTT_URL not configured, skipping MQTT connection");
+            return;
+        }
+
+        try {
+            this.mqtt_client = mqtt.connect(config.MQTT_URL);
+            this.mqtt_client.on("connect", this.onConnect.bind(this));
+            this.mqtt_client.on("message", this.#onMessage.bind(this));
+            this.mqtt_client.on("error", (err) => {
+                console.error("MQTT connection error:", err);
+            });
+            this.CONTEXT["mqtt_client"] = this.mqtt_client;
+        } catch (error) {
+            console.error("MQTT connection failed:", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Loads all configured models.
+     * @private
+     */
+    async #loadModels() {
+        if (!this.SETTINGS.models || this.SETTINGS.models.length === 0) {
+            console.info("No models configured");
+            return;
+        }
+
+        console.info("-----------------Registering Models----------------");
+        for (const model of this.SETTINGS.models) {
+            await this.#load_model_name(model);
+        }
+        console.info("-----------------Models Registered----------------");
+    }
+
+    /**
+     * Publishes data to websocket clients via MQTT.
+     * @param {*} data - Data to broadcast
+     */
+    publishToWebsocket(data) {
+        if (this.mqttClient) {
+            this.mqttClient.publish('websocket_broadcast', JSON.stringify(data));
+        }
+    }
+
+    /**
+     * Emits data to a specific WebSocket room/group via MQTT.
+     * 
+     * @param {string} room - Room name to emit to
+     * @param {string} event - Event name
+     * @param {*} payload - Data payload
+     */
+    emitToGroup(room, event, payload) {
+        if (this.mqttClient) {
+            this.mqttClient.publish('websocket_emit_group', JSON.stringify({
+                room,
+                event,
+                payload
+            }));
+        }
+    }
+
+    /**
+     * Emits data to a specific WebSocket client by socket ID via MQTT.
+     * 
+     * @param {string} socketId - Socket ID to emit to
+     * @param {string} event - Event name
+     * @param {*} payload - Data payload
+     */
+    emitToSocket(socketId, event, payload) {
+        if (this.mqttClient) {
+            this.mqttClient.publish('websocket_emit_socket', JSON.stringify({
+                socketId,
+                event,
+                payload
+            }));
+        }
+    }
+
+    /**
+     * Publishes data to a specific MQTT topic.
+     * Supports both string and object data (objects are JSON stringified).
+     * 
+     * @async
+     * @param {string} topic - MQTT topic to publish to
+     * @param {*} msg - Message to publish (strings sent as-is, objects JSON stringified)
+     * 
+     * @example
+     * // Send job completion status
+     * await this.publish('worker_image-processor_complete', {
+     *   jobId: 123,
+     *   status: 'completed',
+     *   result: { processedPath: '/images/processed/123.jpg' }
+     * });
+     * 
+     * // Send simple string message
+     * await this.publish('worker_status', 'ready');
+     */
+    async publish(topic, msg) {
+        if (this.mqtt_client) {
+            const message = typeof msg === 'string' ? msg : JSON.stringify(msg);
+            await this.mqtt_client.publish(topic, message);
+        }
+    }
+
+    /**
+     * Called when MQTT connection is established.
+     * Automatically subscribes to worker-specific topics for jobs and health checks.
+     * Override in subclasses to add custom subscriptions or initialization logic.
+     * 
+     * @async
+     * @virtual
+     * 
+     * @example
+     * async onConnect() {
+     *   await super.onConnect(); // Call parent to get default subscriptions
+     *   await this.mqtt_client.subscribe('worker_image-processor_priority');
+     *   console.log('Image processor worker connected');
+     * }
+     */
+    async onConnect() {
+        console.info(`Worker ${this.service_id} connected to MQTT`);
+        // Subscribe to worker-specific topics
+        await this.mqtt_client.subscribe(`worker_${this.service_id}`);
+        await this.mqtt_client.subscribe(`worker_${this.service_id}_ping`);
+        await this.mqtt_client.subscribe(`worker_${this.service_id}_job`);
+    }
+
+    /**
+     * Internal MQTT message handler.
+     * @private
+     */
+    async #onMessage(topic, msg) {
+        // Handle ping/pong for health checks
+        if (topic === `worker_${this.service_id}_ping`) {
+            await this.publish(`worker_${this.service_id}_pong`, 'pong');
+            return;
+        }
+        
+        await this.onMessage(topic, msg);
+    }
+
+    /**
+     * Override this method to handle incoming MQTT messages and job requests.
+     * Called for all subscribed topics except ping messages (handled automatically).
+     * 
+     * @async
+     * @virtual
+     * @param {string} topic - MQTT topic that received the message
+     * @param {Buffer} msg - Raw message buffer (use msg.toString() to get string)
+     * 
+     * @example
+     * async onMessage(topic, msg) {
+     *   const data = JSON.parse(msg.toString());
+     *   
+     *   switch (topic) {
+     *     case 'worker_image-processor_job':
+     *       await this.processImage(data);
+     *       break;
+     *     case 'worker_image-processor_priority':
+     *       await this.processPriorityJob(data);
+     *       break;
+     *   }
+     * }
+     */
+    async onMessage(topic, msg) {
+        // Override in subclasses
+    }
+
+    /**
+     * Override this method with your worker's main processing logic.
+     * Called after all initialization (database, MQTT, models) is complete.
+     * Can handle both one-time jobs (exit after completion) and continuous processing.
+     * 
+     * @async
+     * @virtual
+     * 
+     * @example
+     * // One-time job worker
+     * async run() {
+     *   const args = this.parseArgs();
+     *   if (args.jobId) {
+     *     await this.processJob(args.jobId);
+     *     process.exit(0); // Exit after processing
+     *   }
+     * }
+     * 
+     * // Continuous worker
+     * async run() {
+     *   console.log('Worker ready for jobs...');
+     *   // Wait for MQTT messages, process jobs as they come
+     * }
+     */
+    async run() {
+        // Override in subclasses
+    }
+
+    /**
+     * Initializes the worker with all dependencies in the correct order.
+     * Sets up MongoDB, Redis, models, MQTT connection, and then calls run().
+     * This method should be called to start the worker.
+     * 
+     * @async
+     * @throws {Error} Throws if any initialization step fails
+     * 
+     * @example
+     * const imageWorker = new ImageProcessor();
+     * await imageWorker.init(); // Worker is now running
+     */
+    async init() {
+        console.info(`Initializing worker: ${this.service_id}`);
+        await this.#startMongoDB();
+        await this.#startRedis();
+        await this.#loadModels();
+        await this.#startMQTT();
+        await this.run();
+    }
+
+    /**
+     * Starts the worker (alias for run).
+     */
+    async start() {
+        await this.run();
+    }
+
+    /**
+     * Gracefully cleans up all worker resources.
+     * Closes MQTT connection, Redis connection, and MongoDB connection in that order.
+     * Called automatically during graceful shutdown or can be called manually.
+     * 
+     * @async
+     * 
+     * @example
+     * // Manual cleanup before exit
+     * await worker.cleanup();
+     * process.exit(0);
+     * 
+     * // Automatic cleanup on process signals (already set up in constructor)
+     * process.on('SIGTERM', async () => {
+     *   await worker.cleanup();
+     *   process.exit(0);
+     * });
+     */
+    async cleanup() {
+        console.info(`Cleaning up worker: ${this.service_id}`);
+        
+        if (this.mqtt_client && this.mqtt_client.connected) {
+            await this.mqtt_client.end();
+            this.mqtt_client = null;
+        }
+
+        if (this.redis_client && this.redis_client.isOpen) {
+            await this.redis_client.quit();
+            this.redis_client = null;
+        }
+
+        if (this.db && mongoose.connection.readyState === 1) {
+            await mongoose.connection.close();
+            this.db = null;
+        }
+    }
+
+    /**
+     * Sets up graceful shutdown handlers for process signals and uncaught exceptions.
+     * Automatically handles SIGTERM, SIGINT, uncaughtException, and unhandledRejection.
+     * Called automatically in constructor - no need to call manually.
+     * 
+     * @private
+     * 
+     * @example
+     * // Automatically handles these scenarios:
+     * // - Parent process termination (SIGTERM)
+     * // - Ctrl+C in terminal (SIGINT)  
+     * // - Unhandled promise rejections
+     * // - Uncaught exceptions
+     * 
+     * // All trigger cleanup() before process exit
+     */
+    setupGracefulShutdown() {
+        const shutdown = async (signal) => {
+            console.log(`Worker ${this.service_id} received ${signal}, shutting down...`);
+            await this.cleanup();
+            process.exit(0);
+        };
+
+        process.on('SIGTERM', () => shutdown('SIGTERM'));
+        process.on('SIGINT', () => shutdown('SIGINT'));
+        process.on('uncaughtException', async (err) => {
+            console.error('Uncaught Exception:', err);
+            await this.cleanup();
+            process.exit(1);
+        });
+        process.on('unhandledRejection', async (reason) => {
+            console.error('Unhandled Rejection:', reason);
+            await this.cleanup();
+            process.exit(1);
+        });
+    }
+}
+
+module.exports = FalconBaseWorker;

package/index.js

@@ -0,0 +1,4 @@
+module.exports.FalconServer = require("./falcon");
+module.exports.FalconBaseService = require("./falconBaseService");
+module.exports.FalconBaseWorker = require("./falconBaseWorker");
+module.exports.FalconAuthPlugin = require("./FalconAuthPlugin");