free-framework 4.4.0

package/runtime/client.js

@@ -0,0 +1,254 @@
+/**
+ * runtime/client.js
+ * Ultra-fast Islands Hydration & SPA Engine.
+ * Powered by Free partial rendering.
+ */
+
+(function () {
+    console.log("💎 Free Ultra Engine Activated");
+
+    const root = document.getElementById('free-app-root');
+    const loadingBar = document.createElement('div');
+    loadingBar.id = 'free-loader';
+    Object.assign(loadingBar.style, {
+        position: 'fixed',
+        top: '0',
+        left: '0',
+        height: '3px',
+        width: '0%',
+        backgroundColor: '#00ff88',
+        zIndex: '10000',
+        transition: 'width 0.3s ease, opacity 0.3s ease',
+        boxShadow: '0 0 10px #00ff88'
+    });
+    document.body.appendChild(loadingBar);
+
+    function setLoader(percent) {
+        loadingBar.style.opacity = '1';
+        loadingBar.style.width = percent + '%';
+        if (percent >= 100) {
+            setTimeout(() => {
+                loadingBar.style.opacity = '0';
+                setTimeout(() => loadingBar.style.width = '0%', 300);
+            }, 300);
+        }
+    }
+
+    async function navigate(url, push = true) {
+        setLoader(30);
+        try {
+            const response = await fetch(url, {
+                headers: { 'X-Free-Partial': 'true' }
+            });
+            setLoader(70);
+
+            if (!response.ok) throw new Error('Navigation failed');
+
+            const data = await response.json();
+
+            // SPA Transition: Fade out content
+            root.style.opacity = '0';
+            root.style.transform = 'translateY(10px)';
+            root.style.transition = 'opacity 0.2s ease, transform 0.2s ease';
+
+            setTimeout(() => {
+                root.innerHTML = data.content;
+                document.title = data.title;
+                if (push) history.pushState({ url }, data.title, url);
+
+                // Hydrate new islands
+                hydrate();
+
+                // Fade back in
+                root.style.opacity = '1';
+                root.style.transform = 'translateY(0)';
+                setLoader(100);
+                window.scrollTo(0, 0);
+            }, 200);
+
+        } catch (err) {
+            console.error("SPA Error:", err);
+            window.location.href = url; // Fallback
+        }
+    }
+
+    function hydrate() {
+        const islands = document.querySelectorAll('.free-component[data-component]');
+        islands.forEach(el => {
+            if (el.getAttribute('data-hydrated')) return;
+
+            const name = el.getAttribute('data-component');
+            const state = JSON.parse(el.getAttribute('data-state') || '{}');
+            const onMountCode = el.getAttribute('data-free-on-mount');
+            const onDestroyCode = el.getAttribute('data-free-on-destroy');
+
+            // 1. Run onMount
+            if (onMountCode && window.__free_actions && window.__free_actions[name] && window.__free_actions[name][onMountCode]) {
+                try { window.__free_actions[name][onMountCode](state); } catch (e) { console.error(`[onMount] ${name}:`, e); }
+            }
+
+            // 2. Attach event listeners
+            el.querySelectorAll('*').forEach(item => {
+                for (const attr of item.attributes) {
+                    if (attr.name.startsWith('data-on-')) {
+                        const eventName = attr.name.replace('data-on-', '');
+                        const action = attr.value;
+
+                        item.addEventListener(eventName, (event) => {
+                            const actionId = attr.value;
+                            if (window.__free_actions && window.__free_actions[name] && window.__free_actions[name][actionId]) {
+                                try {
+                                    window.__free_actions[name][actionId](state, event);
+
+                                    // Update global state attribute for synchronization
+                                    el.setAttribute('data-state', JSON.stringify(state));
+
+                                    // Optionally re-render simple text bindings as a quick reactive measure
+                                    // Since we don't know exactly what changed, we'd need a VDOM to be perfect.
+                                    // For now, simple text node updates logic if needed...
+                                } catch (e) {
+                                    console.error(`[Action] ${name} (${eventName}):`, e);
+                                }
+                            } else {
+                                console.warn(`Missing action handler for ${actionId} on ${eventName}`);
+                            }
+                        });
+                    }
+                }
+            });
+
+            el.setAttribute('data-hydrated', 'true');
+
+            if (onDestroyCode) {
+                const observer = new MutationObserver((mutations) => {
+                    mutations.forEach((mutation) => {
+                        mutation.removedNodes.forEach((node) => {
+                            if (node === el) {
+                                if (window.__free_actions && window.__free_actions[name] && window.__free_actions[name][onDestroyCode]) {
+                                    try { window.__free_actions[name][onDestroyCode](state); } catch (e) { console.error(`[onDestroy] ${name}:`, e); }
+                                }
+                                observer.disconnect();
+                            }
+                        });
+                    });
+                });
+                observer.observe(el.parentNode, { childList: true });
+            }
+        });
+    }
+
+    // SPA Router interceptor for Links
+    document.addEventListener('click', (e) => {
+        const link = e.target.closest('a');
+        if (link && link.href && link.href.startsWith(window.location.origin)) {
+            const url = new URL(link.href);
+            // Check if it's the same page but different hash? Or just standard link
+            if (url.pathname !== window.location.pathname || url.search !== window.location.search) {
+                e.preventDefault();
+                navigate(link.href);
+            }
+        }
+    });
+
+    // SPA Router interceptor for Forms
+    document.addEventListener('submit', async (e) => {
+        const form = e.target;
+        if (form && form.action && form.action.startsWith(window.location.origin)) {
+            e.preventDefault();
+            setLoader(30);
+
+            const formData = new FormData(form);
+            const data = Object.fromEntries(formData.entries());
+
+            try {
+                const response = await fetch(form.action, {
+                    method: form.method || 'POST',
+                    headers: { 'Content-Type': 'application/json', 'X-Free-Partial': 'true' },
+                    body: JSON.stringify(data),
+                    redirect: 'follow'
+                });
+                setLoader(70);
+
+                if (response.redirected) {
+                    navigate(response.url);
+                    return;
+                }
+
+                if (!response.ok) {
+                    // Try to extract an error message
+                    let errMsg = "An error occurred";
+                    try {
+                        const errData = await response.json();
+                        errMsg = errData.error || errMsg;
+                    } catch (je) { }
+
+                    // If it's the login form specifically, redirect with error
+                    if (form.action.includes('/api/login')) {
+                        navigate('/login?error=' + encodeURIComponent(errMsg));
+                    } else {
+                        navigate(window.location.pathname + "?error=" + encodeURIComponent(errMsg));
+                    }
+                    return;
+                }
+
+                // If response is OK and HTML content
+                try {
+                    const resData = await response.json();
+                    if (resData && resData.content) {
+                        root.style.opacity = '0';
+                        setTimeout(() => {
+                            root.innerHTML = resData.content;
+                            if (resData.title) document.title = resData.title;
+                            hydrate();
+                            root.style.opacity = '1';
+                            setLoader(100);
+                        }, 200);
+                    } else if (resData && resData.success) {
+                        // Action executed successfully, reload current route
+                        navigate(window.location.pathname + window.location.search);
+                    }
+                } catch (e) {
+                    // Fallback reload
+                    window.location.reload();
+                }
+
+            } catch (err) {
+                console.error("Form submit failed:", err);
+                form.submit(); // Fallback to synchronous hard submit
+            }
+        }
+    }, true);
+
+    window.addEventListener('popstate', (e) => {
+        if (e.state && e.state.url) {
+            navigate(e.state.url, false);
+        }
+    });
+
+    // Global Free helper
+    window.Free = {
+        navigate,
+        async call(actionName, data = {}) {
+            const csrfToken = document.querySelector('meta[name="csrf-token"]')?.getAttribute('content');
+            try {
+                const response = await fetch(`/_free/action/${actionName}`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken },
+                    body: JSON.stringify(data)
+                });
+                const result = await response.json();
+                if (!response.ok) throw new Error(result.error || 'Action failed');
+                return result;
+            } catch (err) {
+                console.error(`❌ Action Error [${actionName}]:`, err.message);
+                throw err;
+            }
+        }
+    };
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', hydrate);
+    } else {
+        hydrate();
+    }
+})();

package/runtime/cluster.js

@@ -0,0 +1,35 @@
+/**
+ * runtime/cluster.js
+ * Multi-Core Clustering Engine for Free Ultra
+ * Forks the server process across all available CPU cores for maximum throughput.
+ */
+
+const cluster = require('cluster');
+const os = require('os');
+
+class ClusterManager {
+    static ignite(startServerCallback) {
+        if (cluster.isMaster || cluster.isPrimary) {
+            const numCPUs = os.cpus().length;
+            console.log(`\n🛡️  Free Engine Cluster Manager Intercepting...`);
+            console.log(`🔥 Igniting ${numCPUs} Worker Processes natively...\n`);
+
+            for (let i = 0; i < numCPUs; i++) {
+                cluster.fork();
+            }
+
+            cluster.on('exit', (worker, code, signal) => {
+                console.error(`❌ Worker ${worker.process.pid} died (Code: ${code}). Resurrecting...`);
+                cluster.fork(); // Auto-healing
+            });
+
+            console.log(`✅ Master Process PID: ${process.pid} is routing traffic.`);
+        } else {
+            // Workers share the TCP connection in Node.js Cluster mode
+            startServerCallback();
+            console.log(`   └─ Worker PID: ${process.pid} ready for combat.`);
+        }
+    }
+}
+
+module.exports = { ClusterManager };

package/runtime/edge.js

@@ -0,0 +1,62 @@
+/**
+ * runtime/edge.js
+ * Edge computing adaptor for Cloudflare Workers and Bun environment handling.
+ * Avoids Node-specific standard library where necessary.
+ */
+
+// A generic Request/Response handler abstraction matching Cloudflare Worker signature
+class EdgeRuntime {
+    constructor(freeApp) {
+        this.app = freeApp;
+    }
+
+    async fetch(request, env, ctx) {
+        const url = new URL(request.url);
+        const path = url.pathname;
+        const method = request.method;
+
+        // Abstracted Edge request transformation
+        const mockReq = {
+            method: method,
+            path: path,
+            url: request.url,
+            headers: Object.fromEntries(request.headers.entries()),
+            text: async () => await request.text(),
+            json: async () => await request.json()
+        };
+
+        const mockRes = {
+            statusCode: 200,
+            headers: new Headers(),
+            body: null,
+            status: function (code) { this.statusCode = code; return this; },
+            header: function (k, v) { this.headers.set(k, v); return this; },
+            send: function (data) { this.body = data; },
+            json: function (data) {
+                this.headers.set('Content-Type', 'application/json');
+                this.body = JSON.stringify(data);
+            }
+        };
+
+        // Note: Edge compatibility implies passing through mocked req/res to HyperExpress routing tree logic,
+        // or substituting HyperExpress entirely if running in CF workers (which lacks TCP sockets).
+        // This is the adaptor structural foundation for the routing engine.
+        // For Bun, we could utilize native Bun.serve().
+
+        try {
+            // Simulated minimal routing execution hook (would integrate with generator AST)
+            if (path.startsWith('/_free/action/')) {
+                // handle actions dynamically without node streams
+            }
+
+            return new Response(mockRes.body || "Free Edge Runtime active", {
+                status: mockRes.statusCode,
+                headers: mockRes.headers
+            });
+        } catch (error) {
+            return new Response("Internal Edge Error", { status: 500 });
+        }
+    }
+}
+
+module.exports = { EdgeRuntime };

package/runtime/middleware/maintenance.js

@@ -0,0 +1,54 @@
+/**
+ * runtime/middleware/maintenance.js
+ * Enterprise Maintenance Mode Guard.
+ */
+
+module.exports = function maintenanceMiddleware(req, res, next) {
+    const isMaintenance = process.env.MAINTENANCE_MODE === 'true';
+    const bypassToken = process.env.MAINTENANCE_BYPASS;
+
+    // Allow bypassing with a specific query token or if disabled
+    if (!isMaintenance || (bypassToken && req.query.bypass === bypassToken)) {
+        return next();
+    }
+
+    // Identify if it's an API request or HTML
+    const acceptsHtml = req.headers['accept']?.includes('text/html');
+
+    if (acceptsHtml) {
+        // Render the high-end Maintenance page from the registry
+        // Note: The registry is attached to the server instance (res.app in HyperExpress context, but we need the server)
+        // For now, we'll return a premium standalone HTML fallback if the registry isn't easily accessible
+        res.status(503).send(`
+            <!DOCTYPE html>
+            <html lang="en">
+            <head>
+                <meta charset="UTF-8">
+                <title>System Evolution | Free Ultra</title>
+                <link href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;700;900&display=swap" rel="stylesheet">
+                <style>
+                    body { margin:0; font-family:'Outfit',sans-serif; background:#050505; color:white; overflow:hidden; }
+                    .center { height:100vh; display:flex; align-items:center; justify-content:center; flex-direction:column; text-align:center; }
+                    .glow { width:400px; height:400px; background:radial-gradient(circle, rgba(0,255,136,0.15) 0%, transparent 70%); position:absolute; z-index:-1; animation: pulse 4s infinite; }
+                    h1 { font-size:4rem; font-weight:900; letter-spacing:-2px; margin:0; }
+                    p { color:#888; font-size:1.2rem; max-width:500px; line-height:1.6; }
+                    @keyframes pulse { 0%, 100% { transform: scale(1); opacity:0.5; } 50% { transform: scale(1.2); opacity:0.8; } }
+                </style>
+            </head>
+            <body>
+                <div class="center">
+                    <div class="glow"></div>
+                    <h1>SYSTEM <span style="color:#00ff88">EVOLUTION</span></h1>
+                    <p style="margin-top:20px;">We're currently upgrading the core engine to provide unprecedented performance and security. We'll be back online shortly.</p>
+                </div>
+            </body>
+            </html>
+        `);
+    } else {
+        res.status(503).json({
+            success: false,
+            status: 'maintenance',
+            message: 'Enterprise System is under scheduled maintenance.'
+        });
+    }
+};

package/runtime/middleware/security.js

@@ -0,0 +1,30 @@
+/**
+ * runtime/middleware/security.js
+ * Enterprise-grade Security Headers Middleware.
+ */
+
+module.exports = function securityMiddleware(req, res, next) {
+    // 1. Core Security Headers
+    res.setHeader('X-Powered-By', 'Free-Ultra/Enterprise');
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('X-Frame-Options', 'DENY');
+    res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+
+    // 2. Content Security Policy (Optimized for Free runtime)
+    res.setHeader('Content-Security-Policy',
+        "default-src 'self'; " +
+        "script-src 'self' 'unsafe-inline' blob: https://cdn.jsdelivr.net; " +
+        "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
+        "font-src 'self' data: https://fonts.gstatic.com; " +
+        "img-src 'self' data: blob:;"
+    );
+
+    // 3. Modern Browser Protections
+    res.setHeader('X-XSS-Protection', '1; mode=block');
+    res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+
+    // 4. Permissions Policy (Hardware restrictions)
+    res.setHeader('Permissions-Policy', 'camera=(), microphone=(), geolocation=(), interest-cohort=()');
+
+    next();
+};

package/runtime/server.js

@@ -0,0 +1,130 @@
+/**
+ * runtime/server.js
+ * Core server class for the Free Engine.
+ * Powered by HyperExpress (uWebSockets.js) for maximum performance.
+ */
+
+const HyperExpress = require('hyper-express');
+const nodePath = require('path');
+const fs = require('fs');
+const crypto = require('crypto');
+const securityMiddleware = require('./middleware/security');
+const maintenanceMiddleware = require('./middleware/maintenance');
+
+const { LRUCache } = require('lru-cache');
+
+class FreeServer {
+    constructor() {
+        this.app = new HyperExpress.Server();
+        this.namedMiddlewares = {};
+        this.errorViews = {};
+        this.plugins = [];
+        this.viewsPath = process.env.VIEWS_PATH || nodePath.join(process.cwd(), 'views');
+
+        // Static Asset Serving - GET fallback for priority
+        const publicPath = nodePath.join(process.cwd(), 'public');
+        this.app.get('/*', (req, res, next) => {
+            const lookupPath = req.path.startsWith('/') ? req.path.substring(1) : req.path;
+            if (!lookupPath) return next();
+
+            const fullPath = nodePath.join(publicPath, lookupPath);
+            if (fs.existsSync(fullPath) && fs.statSync(fullPath).isFile()) {
+                const content = fs.readFileSync(fullPath);
+                const ext = nodePath.extname(fullPath);
+                const mimes = { '.js': 'application/javascript', '.css': 'text/css', '.png': 'image/png' };
+                return res.type(mimes[ext] || 'application/javascript').send(content);
+            }
+            next();
+        });
+
+        this.app.get('/test-static', (req, res) => res.send('Static serving test'));
+
+        // Extreme SSR Cache (LRU)
+        this.cache = new LRUCache({
+            max: 500,
+            ttl: 1000 * 60 * 5,
+        });
+
+        // 2. Ultra-Fast InMemory Rate Limiting (DDoS Shield)
+        this.rateLimits = new LRUCache({
+            max: 100000,
+            ttl: 1000 * 60,
+        });
+
+        // Apply Global Middleware
+        this.app.use(maintenanceMiddleware);
+        this.app.use(securityMiddleware);
+
+        this.app.use((req, res, next) => {
+            const ip = req.ip || req.headers['x-forwarded-for'] || 'unknown';
+            const reqCount = this.rateLimits.get(ip) || 0;
+
+            if (reqCount >= 5000) {
+                res.status(429);
+                res.setHeader('Retry-After', '60');
+                return res.send('Too Many Requests - Under DDoS Protection');
+            }
+
+            this.rateLimits.set(ip, reqCount + 1);
+            next();
+        });
+    }
+
+    route(method, path, middlewares = [], handler) {
+        const routeMethod = method.toLowerCase();
+        const mwFns = middlewares.map(m => this.namedMiddlewares[m]).filter(Boolean);
+
+        const routeHandler = async (req, res) => {
+            try {
+                const cacheKey = `${method}:${req.url}`;
+                if (this.cache.has(cacheKey)) {
+                    res.header('X-Free-Cache', 'HIT');
+                    res.header('Content-Type', 'text/html');
+                    return res.send(this.cache.get(cacheKey));
+                }
+
+                res.header('X-Free-Cache', 'MISS');
+                res.context = res.context || {};
+                res.context.props = {
+                    params: req.path_parameters || {},
+                    query: req.query_parameters || {},
+                };
+
+                const originalSend = res.send.bind(res);
+                res.send = (body) => {
+                    if (res.statusCode === 200) this.cache.set(cacheKey, body);
+                    return originalSend(body);
+                };
+
+                await handler(req, res);
+            } catch (e) {
+                console.error(`[Free Engine] Error ${method} ${path}:`, e);
+                res.status(e.status || 500).header('Content-Type', 'text/html').send('Internal Error');
+            }
+        };
+
+        this.app[routeMethod](path, ...mwFns, routeHandler);
+        if (routeMethod === 'get') this.app.head(path, ...mwFns, routeHandler);
+    }
+
+    middleware(fn) { this.app.use(fn); }
+    registerMiddleware(name, fn) { this.namedMiddlewares[name] = fn; }
+    use(plugin) { plugin.install(this); this.plugins.push(plugin); }
+
+    setErrorView(code, view) {
+        this.app.set_not_found_handler((req, res) => {
+            if (code.toString() === '404') {
+                res.status(404).send(`<!-- error ${view} -->`);
+            }
+        });
+    }
+
+    start(port = 3000) {
+        this.app.get('/health', (req, res) => res.send('OK'));
+        this.app.listen(port).then(() => {
+            console.log(`⚡ Free Engine Ignite: http://localhost:${port}`);
+        });
+    }
+}
+
+module.exports = { FreeServer };

package/runtime/validator.js

@@ -0,0 +1,102 @@
+/**
+ * runtime/validator.js
+ * Built-in request validation for Free Framework.
+ * Supports: required, email, min:N, max:N, string, number, boolean, url, regex.
+ */
+
+const RULES = {
+    required: (val) => val !== undefined && val !== null && val !== '',
+    email: (val) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(val)),
+    string: (val) => typeof val === 'string',
+    number: (val) => !isNaN(Number(val)) && val !== '',
+    boolean: (val) => val === 'true' || val === 'false' || typeof val === 'boolean',
+    url: (val) => { try { new URL(val); return true; } catch { return false; } },
+    min: (val, param) => String(val).length >= parseInt(param),
+    max: (val, param) => String(val).length <= parseInt(param),
+    regex: (val, param) => new RegExp(param).test(String(val)),
+};
+
+const MESSAGES = {
+    required: (field) => `${field} is required.`,
+    email: (field) => `${field} must be a valid email address.`,
+    string: (field) => `${field} must be a string.`,
+    number: (field) => `${field} must be a number.`,
+    boolean: (field) => `${field} must be a boolean.`,
+    url: (field) => `${field} must be a valid URL.`,
+    min: (field, param) => `${field} must be at least ${param} characters.`,
+    max: (field, param) => `${field} must be at most ${param} characters.`,
+    regex: (field) => `${field} is not in the correct format.`,
+};
+
+/**
+ * Validate a data object against a rules map.
+ * @param {Object} data  - { field: value }
+ * @param {Object} rules - { field: ['required', 'email', 'min:8'] }
+ * @returns {{ valid: boolean, errors: { field: string[] } }}
+ */
+function validate(data, rules) {
+    const errors = {};
+
+    for (const [field, fieldRules] of Object.entries(rules)) {
+        const value = data[field];
+        const fieldErrors = [];
+
+        for (const rule of fieldRules) {
+            const [ruleName, ruleParam] = rule.split(':');
+            const ruleHandler = RULES[ruleName];
+
+            if (!ruleHandler) {
+                console.warn(`[Free Validator] Unknown rule: "${ruleName}"`);
+                continue;
+            }
+
+            // Skip non-required rules if the field is empty (only fail on 'required')
+            if (ruleName !== 'required' && (value === undefined || value === null || value === '')) {
+                continue;
+            }
+
+            const passed = ruleHandler(value, ruleParam);
+            if (!passed) {
+                const msgFn = MESSAGES[ruleName] || (() => `${field} failed ${ruleName} validation.`);
+                fieldErrors.push(msgFn(field, ruleParam));
+            }
+        }
+
+        if (fieldErrors.length > 0) {
+            errors[field] = fieldErrors;
+        }
+    }
+
+    const valid = Object.keys(errors).length === 0;
+    return { valid, errors };
+}
+
+/**
+ * Create an Express/HyperExpress middleware from a rules map.
+ * Returns 422 JSON response if validation fails.
+ */
+function validationMiddleware(rules) {
+    return async (req, res, next) => {
+        let body = {};
+        try {
+            body = await req.json();
+        } catch {
+            try { body = await req.urlencoded(); } catch { body = {}; }
+        }
+
+        const { valid, errors } = validate(body, rules);
+
+        if (!valid) {
+            return res.status(422).json({
+                success: false,
+                message: 'Validation failed.',
+                errors,
+            });
+        }
+
+        req.validated = body;
+        next();
+    };
+}
+
+module.exports = { validate, validationMiddleware };