free-framework 4.4.0

package/plugins/queue.js

@@ -0,0 +1,139 @@
+/**
+ * plugins/queue.js
+ * Advanced Async Queue Plugin for Free Framework.
+ * Drivers: memory, redis.
+ * Features: concurrency control, persistence, retry with backoff, delayed jobs, cron.
+ */
+
+function QueuePlugin(config = {}) {
+    const driver = config.driver || 'memory';
+    const MAX_WORKERS = config.concurrency || 5;
+
+    const jobHandlers = {};
+    const cronJobs = {};
+    let activeWorkers = 0;
+    let processed = 0;
+    let failed = 0;
+
+    // Internal In-Memory Queue (Driver: memory)
+    const pendingLocal = [];
+
+    return {
+        install(server) {
+            let redis = null;
+            if (driver === 'redis') {
+                const Redis = (() => {
+                    try { return require('ioredis'); }
+                    catch { throw new Error('QueuePlugin redis driver: run npm install ioredis'); }
+                })();
+                redis = new Redis(config.redis || process.env.REDIS_URL || 'redis://127.0.0.1:6379');
+            }
+
+            async function runJob(job) {
+                const { name, payload, maxRetries = 3, attempt = 1 } = job;
+                const handler = jobHandlers[name];
+                if (!handler) {
+                    console.warn(`[Queue] No handler for job: "${name}"`);
+                    return;
+                }
+                try {
+                    await handler(payload, { attempt, maxRetries });
+                    processed++;
+                } catch (err) {
+                    console.error(`[Queue] Job "${name}" attempt ${attempt} failed: ${err.message}`);
+                    if (attempt <= maxRetries) {
+                        const delay = Math.pow(2, attempt - 1) * 1000;
+                        setTimeout(() => dispatchInternal(name, payload, { ...job, attempt: attempt + 1, delay }), delay);
+                    } else {
+                        failed++;
+                        console.error(`[Queue] Job "${name}" permanently failed.`);
+                    }
+                }
+            }
+
+            async function runNext() {
+                if (activeWorkers >= MAX_WORKERS) return;
+
+                let job = null;
+                if (driver === 'redis') {
+                    const raw = await redis.lpop('free:queue:pending');
+                    if (raw) job = JSON.parse(raw);
+                } else {
+                    job = pendingLocal.shift();
+                }
+
+                if (!job) return;
+
+                activeWorkers++;
+                runJob(job).finally(() => {
+                    activeWorkers--;
+                    runNext();
+                });
+            }
+
+            async function dispatchInternal(name, payload = {}, opts = {}) {
+                const job = {
+                    name,
+                    payload,
+                    maxRetries: opts.retries ?? 3,
+                    attempt: opts.attempt || 1,
+                    priority: opts.priority || 0
+                };
+
+                if (driver === 'redis') {
+                    await redis.rpush('free:queue:pending', JSON.stringify(job));
+                } else {
+                    pendingLocal.push(job);
+                    pendingLocal.sort((a, b) => (b.priority || 0) - (a.priority || 0));
+                }
+                runNext();
+            }
+
+            server.queue = {
+                register(name, handler) {
+                    jobHandlers[name] = handler;
+                    console.log(`⚡ Queue job registered: "${name}"`);
+                    // Start worker loop if not already running
+                    runNext();
+                },
+
+                dispatch(name, payload = {}, opts = {}) {
+                    if (opts.delay > 0) {
+                        setTimeout(() => dispatchInternal(name, payload, opts), opts.delay);
+                    } else {
+                        dispatchInternal(name, payload, opts);
+                    }
+                },
+
+                cron(name, intervalMs, fn) {
+                    if (cronJobs[name]) clearInterval(cronJobs[name]);
+                    cronJobs[name] = setInterval(async () => {
+                        try { await fn(); }
+                        catch (e) { console.error(`[Cron] "${name}" error:`, e.message); }
+                    }, intervalMs);
+                    console.log(`⏰ Cron "${name}" every ${intervalMs}ms`);
+                },
+
+                stats() {
+                    return {
+                        driver,
+                        activeWorkers,
+                        maxWorkers: MAX_WORKERS,
+                        processed,
+                        failed,
+                        registeredJobs: Object.keys(jobHandlers)
+                    };
+                },
+            };
+
+            console.log(`🔁 Queue Plugin installed. Driver: ${driver}, Concurrency: ${MAX_WORKERS}`);
+
+            // Initial trigger for Redis workers
+            if (driver === 'redis') {
+                setInterval(() => runNext(), 1000); // Poll every second if idle
+            }
+        }
+    };
+}
+
+module.exports = QueuePlugin;

package/plugins/search.js

@@ -0,0 +1,51 @@
+/**
+ * plugins/search.js
+ * Full-text Search Plugin for Free Framework.
+ * Abstraction layer for SQLite FTS5, Meilisearch, or Algolia.
+ */
+
+function SearchPlugin(config = {}) {
+    const driver = config.driver || 'sqlite'; // sqlite | meilisearch
+
+    return {
+        install(server) {
+            server.search = {
+                /**
+                 * Search for records in a model.
+                 * @param {Model} model - The ORM Model to search
+                 * @param {string} query - The search query string
+                 * @param {string[]} fields - Fields to search against
+                 */
+                async query(model, query, fields = ['title', 'content']) {
+                    if (driver === 'sqlite') {
+                        // Basic SQLite search fallback (using LIKE or FTS if configured)
+                        let q = model.query();
+                        fields.forEach((field, index) => {
+                            if (index === 0) q = q.where(field, 'like', `%${query}%`);
+                            else q = q.orWhere(field, 'like', `%${query}%`);
+                        });
+                        return await q.limit(20);
+                    }
+
+                    if (driver === 'meilisearch') {
+                        // Future: Integration with Meilisearch SDK
+                        return [];
+                    }
+
+                    return [];
+                },
+
+                /**
+                 * Index a record (if driver supports external indexing)
+                 */
+                async index(model, record) {
+                    // Logic for Meilisearch/Algolia
+                }
+            };
+
+            console.log(`🔍 Search Plugin installed. Driver: ${driver}`);
+        }
+    };
+}
+
+module.exports = SearchPlugin;

package/plugins/storage.js

@@ -0,0 +1,123 @@
+/**
+ * plugins/storage.js
+ * File Storage Plugin for Free Framework.
+ * Drivers: local (filesystem), s3 (AWS S3 / S3-compatible).
+ *
+ * Usage:
+ *   await server.storage.put("images/photo.jpg", fileBuffer);
+ *   await server.storage.get("images/photo.jpg");    // returns Buffer
+ *   server.storage.url("images/photo.jpg");           // public URL
+ *   await server.storage.delete("images/photo.jpg");
+ *   await server.storage.exists("images/photo.jpg"); // boolean
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const crypto = require('crypto');
+
+function StoragePlugin(config = {}) {
+    const driver = config.driver || 'local';
+
+    return {
+        install(server) {
+            let backend;
+
+            if (driver === 's3') {
+                // S3 driver — requires: npm install @aws-sdk/client-s3
+                const { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, HeadObjectCommand } = (() => {
+                    try { return require('@aws-sdk/client-s3'); }
+                    catch { throw new Error('Storage S3 driver: run npm install @aws-sdk/client-s3'); }
+                })();
+
+                const client = new S3Client({
+                    region: config.region || process.env.AWS_REGION || 'us-east-1',
+                    credentials: {
+                        accessKeyId: config.accessKeyId || process.env.AWS_ACCESS_KEY_ID,
+                        secretAccessKey: config.secretAccessKey || process.env.AWS_SECRET_ACCESS_KEY,
+                    },
+                    endpoint: config.endpoint, // for S3-compatible like MinIO
+                });
+                const bucket = config.bucket || process.env.AWS_BUCKET;
+
+                backend = {
+                    async put(key, body, contentType = 'application/octet-stream') {
+                        await client.send(new PutObjectCommand({ Bucket: bucket, Key: key, Body: body, ContentType: contentType }));
+                        return key;
+                    },
+                    async get(key) {
+                        const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+                        const chunks = [];
+                        for await (const chunk of response.Body) chunks.push(chunk);
+                        return Buffer.concat(chunks);
+                    },
+                    async delete(key) {
+                        await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+                    },
+                    async exists(key) {
+                        try { await client.send(new HeadObjectCommand({ Bucket: bucket, Key: key })); return true; }
+                        catch { return false; }
+                    },
+                    url(key) {
+                        if (config.baseUrl) return `${config.baseUrl}/${key}`;
+                        return `https://${bucket}.s3.amazonaws.com/${key}`;
+                    },
+                };
+            } else {
+                // Local filesystem driver
+                const root = path.join(process.cwd(), config.root || 'storage/app');
+                fs.ensureDirSync(root);
+
+                backend = {
+                    async put(key, body) {
+                        const dest = path.join(root, key);
+                        fs.ensureDirSync(path.dirname(dest));
+                        await fs.writeFile(dest, body);
+                        return key;
+                    },
+                    async get(key) {
+                        return fs.readFile(path.join(root, key));
+                    },
+                    async delete(key) {
+                        await fs.remove(path.join(root, key));
+                    },
+                    async exists(key) {
+                        return fs.pathExists(path.join(root, key));
+                    },
+                    url(key) {
+                        // Publicly accessible URL (assumes storage/app is served)
+                        const base = config.baseUrl || process.env.APP_URL || 'http://localhost:3000';
+                        return `${base}/storage/${key}`;
+                    },
+                };
+
+                // Serve local storage via the server
+                server.app.get('/storage/*', async (req, res) => {
+                    const key = req.path.replace('/storage/', '');
+                    const filePath = path.join(root, key);
+                    if (await fs.pathExists(filePath)) {
+                        res.send(await fs.readFile(filePath));
+                    } else {
+                        res.status(404).send('Not found');
+                    }
+                });
+            }
+
+            /**
+             * Generate a unique key for a file upload.
+             * @param {string} originalName - e.g. "photo.jpg"
+             * @param {string} [folder] - optional sub-folder, e.g. "avatars"
+             */
+            backend.generateKey = (originalName, folder = '') => {
+                const ext = path.extname(originalName);
+                const hash = crypto.randomBytes(8).toString('hex');
+                const name = `${Date.now()}-${hash}${ext}`;
+                return folder ? `${folder}/${name}` : name;
+            };
+
+            server.storage = backend;
+            console.log(`📦 Storage Plugin installed. Driver: ${driver}`);
+        }
+    };
+}
+
+module.exports = StoragePlugin;

package/plugins/upload.js

@@ -0,0 +1,62 @@
+/**
+ * plugins/upload.js
+ * High-performance Multipart Upload plugin for Free Framework.
+ */
+const fs = require('fs-extra');
+const path = require('path');
+
+function UploadPlugin(name, config) {
+    return {
+        install(server) {
+            const destPath = path.join(process.cwd(), config.path || 'uploads');
+            fs.ensureDirSync(destPath);
+
+            // maxSize is parsed logic: '10mb' -> bytes
+            let MAX_SIZE_BYTES = 10 * 1024 * 1024; // Default 10mb
+            if (config.maxSize && config.maxSize.toLowerCase().endsWith('mb')) {
+                MAX_SIZE_BYTES = parseInt(config.maxSize) * 1024 * 1024;
+            } else if (config.maxSize && config.maxSize.toLowerCase().endsWith('gb')) {
+                MAX_SIZE_BYTES = parseInt(config.maxSize) * 1024 * 1024 * 1024;
+            }
+
+            server.registerMiddleware(`upload_${name}`, async (req, res, next) => {
+                req.files = {};
+                try {
+                    await req.multipart(async (field) => {
+                        if (field.file) {
+                            const ext = path.extname(field.file.name);
+                            const newFilename = `${Date.now()}-${Math.round(Math.random() * 1E9)}${ext}`;
+                            const savePath = path.join(destPath, newFilename);
+
+                            // Prevent memory bloat, write directly to disk via streams
+                            await field.write(savePath);
+
+                            req.files[field.name] = {
+                                name: field.file.name,
+                                path: savePath,
+                                size: fs.statSync(savePath).size
+                            };
+
+                            // Size validation logic
+                            if (req.files[field.name].size > MAX_SIZE_BYTES) {
+                                fs.unlinkSync(savePath); // Delete oversized
+                                throw new Error('File too large');
+                            }
+                        } else {
+                            // Collect text fields
+                            if (!req.body) req.body = {};
+                            req.body[field.name] = field.value;
+                        }
+                    });
+                    next();
+                } catch (e) {
+                    res.status(400).send("Upload Failed: " + e.message);
+                }
+            });
+
+            console.log(`📁 Upload Plugin installed. 'upload_${name}' middleware created.`);
+        }
+    };
+}
+
+module.exports = UploadPlugin;

package/router/router.js

@@ -0,0 +1,57 @@
+/**
+ * router/router.js
+ * Advanced Router with support for Groups, Prefixes, and Middleware chaining.
+ */
+
+class Router {
+    constructor(server, prefix = '', middleware = []) {
+        this.server = server;
+        this.prefix = prefix;
+        this.middleware = middleware;
+    }
+
+    /**
+     * Create a new route group
+     * @param {Object} options - { prefix, middleware }
+     * @param {Function} callback - Group definition callback
+     */
+    group(options, callback) {
+        const newPrefix = this.prefix + (options.prefix || '');
+        const newMiddleware = [...this.middleware, ...(options.middleware || [])];
+        const subRouter = new Router(this.server, newPrefix, newMiddleware);
+        callback(subRouter);
+    }
+
+    _add(method, path, middlewares, handler) {
+        const fullPath = (this.prefix + path).replace(/\/+/g, '/') || '/';
+        const fullMiddleware = [...this.middleware, ...middlewares];
+        this.server.route(method, fullPath, fullMiddleware, handler);
+    }
+
+    get(path, ...args) {
+        const handler = args.pop();
+        this._add('GET', path, args, handler);
+    }
+
+    post(path, ...args) {
+        const handler = args.pop();
+        this._add('POST', path, args, handler);
+    }
+
+    put(path, ...args) {
+        const handler = args.pop();
+        this._add('PUT', path, args, handler);
+    }
+
+    delete(path, ...args) {
+        const handler = args.pop();
+        this._add('DELETE', path, args, handler);
+    }
+
+    patch(path, ...args) {
+        const handler = args.pop();
+        this._add('PATCH', path, args, handler);
+    }
+}
+
+module.exports = { Router };

package/runtime/app.js

@@ -0,0 +1,14 @@
+/**
+ * runtime/app.js
+ * Entry point for any Free application runtime.
+ */
+
+const { FreeServer } = require("./server");
+const { Router } = require("../router/router");
+const { Model } = require("../database/model");
+
+module.exports = {
+    FreeServer,
+    Router,
+    Model
+};