@triophore/falconjs 1.0.0

package/falconAuthPlugin.js

@@ -0,0 +1,17 @@
+class falconAuthPlugin {
+  constructor() {
+    this.name = "falconAuthPlugin";
+  }
+
+  init() {
+    // Initialize the plugin
+  }
+
+  authenticate(username, password) {
+    // Authenticate the user
+  }
+
+  authorize(user, resource, action) {
+    // Authorize the user for the given resource and action
+  }
+}

package/falconBaseService.js

@@ -0,0 +1,532 @@
+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 services that run as separate processes.
+ * Provides MQTT communication, database access, and model loading.
+ * Services are long-running processes that handle specific business logic.
+ * 
+ * @class FalconBaseService
+ * @example
+ * class EmailService extends FalconBaseService {
+ *   constructor() {
+ *     super('email');
+ *   }
+ *   
+ *   async onMessage(topic, msg) {
+ *     if (topic === 'service_email') {
+ *       await this.sendEmail(JSON.parse(msg));
+ *     }
+ *   }
+ *   
+ *   async run() {
+ *     console.log('Email service running...');
+ *   }
+ * }
+ * 
+ * const service = new EmailService();
+ * service.init();
+ */
+class FalconBaseService {
+
+    /**
+     * Creates a new Falcon service instance.
+     * Automatically loads settings, sets up graceful shutdown, and initializes context.
+     * 
+     * @param {string} serviceId - Service identifier used for MQTT topics and logging
+     * @throws {Error} Throws if service ID is not provided
+     * 
+     * @example
+     * class MyService extends FalconBaseService {
+     *   constructor() {
+     *     super('my-service'); // Creates topics: service_my-service, service_my-service_ping
+     *   }
+     * }
+     */
+    constructor(serviceId) {
+        if (!serviceId || typeof serviceId !== 'string') {
+            throw new ValidationError('serviceId must be a non-empty string');
+        }
+        
+        this.serviceId = serviceId;
+        this.models = {};
+        this.CONTEXT = { models: {} };
+        this.db = null;
+        this.mqttClient = null;
+        this.redisClient = null;
+
+        // 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";
+    }
+
+    /**
+     * Loads a model by name from various possible locations.
+     * Searches in: models/mongo/, models/, services/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 user.js in:
+     * // - /project/models/mongo/user.js
+     * // - /project/models/user.js  
+     * // - /project/services/models/user.js
+     * await this.#load_model_name('user');
+     */
+    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, "services", "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 using MONGODB_URL environment variable.
+     * Sets up Mongoose with debug logging in development mode.
+     * 
+     * @private
+     * @async
+     * @throws {Error} Throws if MongoDB connection fails
+     * 
+     * @example
+     * // Requires MONGODB_URL environment variable
+     * // mongodb://localhost:27017/mydb
+     * await this.#startMongoDB();
+     */
+    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 via REDIS_ENABLE=true and REDIS_URL environment variables.
+     * Redis connection is optional and service will continue without it if not configured.
+     * 
+     * @private
+     * @async
+     * 
+     * @example
+     * // Requires environment variables:
+     * // REDIS_ENABLE=true
+     * // REDIS_URL=redis://localhost:6379
+     * await this.#startRedis();
+     */
+    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 using MQTT_URL environment variable.
+     * Sets up event handlers for connect, message, and error events.
+     * 
+     * @private
+     * @async
+     * @throws {Error} Throws if MQTT connection fails
+     * 
+     * @example
+     * // Requires MQTT_URL environment variable
+     * // mqtt://localhost:1883
+     * await this.#startMQTT();
+     */
+    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 models specified in settings.models array.
+     * Models are loaded from various locations and registered in this.models and this.CONTEXT.models.
+     * 
+     * @private
+     * @async
+     * 
+     * @example
+     * // settings.js: { models: ['user', 'product', 'order'] }
+     * await this.#loadModels();
+     * // Now available as: this.models.user, this.models.product, etc.
+     */
+    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 the 'websocket_broadcast' MQTT topic.
+     * The main Falcon server listens to this topic and forwards to connected websocket clients.
+     * 
+     * @param {*} data - Data to broadcast (will be JSON stringified)
+     * 
+     * @example
+     * this.publishToWebsocket({
+     *   type: 'notification',
+     *   message: 'Service started',
+     *   timestamp: new Date()
+     * });
+     */
+    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
+     * 
+     * @example
+     * this.emitToGroup('user_123', 'notification', { message: 'Hello!' });
+     */
+    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
+     * 
+     * @example
+     * this.emitToSocket('socket_abc123', 'private_message', { text: 'Hello!' });
+     */
+    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.
+     * Data is automatically JSON stringified before publishing.
+     * 
+     * @param {*} data - Data to publish (objects will be JSON stringified)
+     * @param {string} topic - MQTT topic to publish to
+     * 
+     * @example
+     * // Send status update
+     * this.publish({ status: 'completed', jobId: 123 }, 'job_status');
+     * 
+     * // Send to another service
+     * this.publish({ action: 'process' }, 'service_image-processor');
+     */
+    publish(data, topic) {
+        if (this.mqtt_client) {
+            this.mqtt_client.publish(topic, JSON.stringify(data));
+        }
+    }
+
+    /**
+     * Called when MQTT connection is established.
+     * Automatically subscribes to service-specific topics for communication 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('custom_topic');
+     *   console.log('Custom service connected');
+     * }
+     */
+    async onConnect() {
+        console.info(`Service ${this.service_id} connected to MQTT`);
+        // Subscribe to service-specific topic
+        await this.mqtt_client.subscribe(`service_${this.service_id}`);
+        await this.mqtt_client.subscribe(`service_${this.service_id}_ping`);
+    }
+
+    /**
+     * Internal MQTT message handler.
+     * @private
+     */
+    async #onMessage(topic, msg) {
+        // Handle ping/pong for health checks
+        if (topic === `service_${this.service_id}_ping`) {
+            this.publish('pong', `service_${this.service_id}_pong`);
+            return;
+        }
+        
+        await this.onMessage(topic, msg);
+    }
+
+    /**
+     * Override this method to handle incoming MQTT messages.
+     * 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 'service_email':
+     *       await this.sendEmail(data);
+     *       break;
+     *     case 'service_email_bulk':
+     *       await this.sendBulkEmail(data);
+     *       break;
+     *   }
+     * }
+     */
+    async onMessage(topic, msg) {
+        // Override in subclasses
+    }
+
+    /**
+     * Override this method with your service's main business logic.
+     * Called after all initialization (database, MQTT, models) is complete.
+     * This method should contain the core functionality of your service.
+     * 
+     * @async
+     * @virtual
+     * 
+     * @example
+     * async run() {
+     *   console.log('Email service starting...');
+     *   
+     *   // Set up periodic tasks
+     *   setInterval(() => {
+     *     this.checkPendingEmails();
+     *   }, 30000);
+     *   
+     *   // Service is now ready to handle requests
+     *   this.publish({ status: 'ready' }, 'service_status');
+     * }
+     */
+    async run() {
+        // Override in subclasses
+    }
+
+    /**
+     * Initializes the service 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 service.
+     * 
+     * @async
+     * @throws {Error} Throws if any initialization step fails
+     * 
+     * @example
+     * const emailService = new EmailService();
+     * await emailService.init(); // Service is now running
+     */
+    async init() {
+        console.info(`Initializing service: ${this.service_id}`);
+        await this.#startMongoDB();
+        await this.#startRedis();
+        await this.#loadModels();
+        await this.#startMQTT();
+        await this.run();
+    }
+
+    /**
+     * Starts the service (alias for run).
+     */
+    async start() {
+        await this.run();
+    }
+
+    /**
+     * Gracefully cleans up all service 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
+     * await service.cleanup();
+     * 
+     * // Automatic cleanup on process signals (already set up in constructor)
+     * process.on('SIGTERM', async () => {
+     *   await service.cleanup();
+     *   process.exit(0);
+     * });
+     */
+    async cleanup() {
+        console.info(`Cleaning up service: ${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:
+     * // - Docker container stop (SIGTERM)
+     * // - Ctrl+C in terminal (SIGINT)  
+     * // - Unhandled promise rejections
+     * // - Uncaught exceptions
+     * 
+     * // All trigger cleanup() before process exit
+     */
+    setupGracefulShutdown() {
+        const shutdown = async (signal) => {
+            console.log(`Service ${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 = FalconBaseService;