odac 1.0.0 → 1.1.0

package/.github/workflows/auto-pr-description.yml

@@ -35,6 +35,8 @@ jobs:
 
       - name: Update PR Title and Body
         uses: actions/github-script@v7
+        env:
+          PR_BODY: ${{ steps.generate_body.outputs.body }}
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -43,5 +45,5 @@ jobs:
               repo: context.repo.repo,
               pull_number: context.issue.number,
               title: 'Sync `dev` to `main`',
-              body: `${{ steps.generate_body.outputs.body }}`
+              body: process.env.PR_BODY
             });

package/CHANGELOG.md

@@ -1,3 +1,130 @@
+### Fix
+
+- Resolve WebSocket handshake error by echoing subprotocol header
+
+### Refactor
+
+- Unified WebSocket architecture and fixed race conditions
+
+### deps
+
+- update mysql2 dependency to ^3.16.0
+
+### ⚙️ Engine Tuning
+
+- Add type checks for page assignments and a null check for the `authPage` method's `authFile` parameter.
+- extract and trim validation rule names for clearer inverse rule processing.
+- extract HTML stripping logic into a private helper method and apply it to text content generation.
+- migrate custom `odac:field` tag to `odac:input` with updated parsing logic and regex patterns.
+- migrate session locking from in-memory object to `Odac.Storage` for persistence.
+- Move form message clearing logic to the beginning of form submission.
+- move middleware execution to occur after URL parameter processing.
+- pass PR body to github-script action via environment variable
+- Remove duplicate data-error-email attribute assignment.
+- rename `requestMagicLink` method to `magic` in Auth and update its usages and documentation
+- Rename authentication token and session cookie keys from 'candy' to 'odac'.
+- rename internal `Odac` class to `_odac`
+- Rename Mysql to Database and implement connection pooling
+- Update default magic link table name from 'magic_links' to 'odac_magic'.
+- Use `crypto.randomBytes` for client and session ID generation instead of MD5 hashing.
+- use `node:crypto.randomBytes` for generating unique IDs instead of `Date.now()` and `Math.random()`
+- use file descriptor for mail template reading to ensure resource closure
+
+### ✨ What's New
+
+- add `_odac/form` POST route with CSRF token validation
+- Add `!disposable` validation rule to block temporary email providers by fetching and caching a daily updated blocklist.
+- Add console error for missing controller files
+- Add custom template rendering engine with caching to Mail service and enhance magic link email options.
+- Add magic link rate limiting, expired link cleanup, and open redirect protection for magic link redirects.
+- add passwordless auto-registration for magic links, improve URL query decoding, and disable token validation for the magic link verification route.
+- Add request language property from Accept-Language header, defaulting to 'en'.
+- Add session cooldown for magic link requests and return explicit errors for rate limits, updating documentation.
+- Allow direct page route definition when a file is provided.
+- Allow specifying and using a redirect URL for magic link authentication.
+- emit 'ping' event when receiving a WebSocket PING frame
+- Enable passing variables directly in view configuration objects for page routes and update documentation.
+- Enable sending plain text and raw HTML emails without templates in the mail service.
+- HTML Mail delivery via direct ODAC Mail Server
+- Ignore database table not found errors when looking up users by email.
+- Implement and document auto-clearing of form inputs on successful submission, controllable via a `clear` attribute.
+- Implement backend-to-frontend data sharing via `Odac.share` and…
+- implement built-in IPC system with Memory and Redis drivers
+- Implement dynamic session garbage collection with simple and batch cleaning modes based on session count.
+- Implement graceful shutdown for primary and worker processes in the cluster.
+- Implement magic login functionality
+- Implement magic login functionality with new routes, internal handlers, and form processing, while removing a generic form route.
+- Implement passwordless signup by auto-registering new users during magic link verification and adding `node:crypto` for random password generation.
+- Implement server actions for forms, allowing `Controller.method` as the action and dispatching internally via a generic endpoint.
+- introduce `Odac.DB.nanoid()` helper, centralize its implementation, and update authentication ID generation strategy documentation.
+- Introduce Nano IDs for primary keys and cookie identifiers, streamlining user insertion logic.
+- introduce service classes in a dedicated directory with naming collision handling and refine route authentication logic.
+- Introduce Storage module to encapsulate LMDB operations and session garbage collection.
+- Migrate session management from in-memory to LMDB, enable server clustering, and add session garbage collection.
+- Modernize db layer with magic api and migrations
+- Modernize db layer with magic api and migrations
+- Render form success and error messages as HTML using a new `textToHtml` utility.
+- Return generic success message for user not found when auto-register is enabled to prevent enumeration.
+- Server Clustering & Persistent Session Management
+- support string-based WebSocket controller paths and update documentation
+- Update route loading to execute function-exported route definitions with Odac.
+- Update session private key hashing algorithm from MD5 to SHA256.
+
+### 📚 Documentation
+
+- Add magic links documentation.
+- Fix typo in controller classes documentation
+- overhaul README to detail new Node.js framework features, advanced capabilities, updated quick start instructions, and license.
+- remove redundant html code block tag
+- remove server documentation index.
+- Replace old database connection and MySQL guides with new getting started, query basics, advanced queries, and migrations documentation.
+- Standardize framework name capitalization from Odac to ODAC across documentation.
+- Update database interaction examples from `Odac.Mysql` to `Odac.DB`.
+- update database query examples to include `.select()` and variable assignments.
+
+### 🛠️ Fixes & Improvements
+
+- Add error handling for cache file access to ensure validation update proceeds.
+- Add explicit response termination for middleware and redirects, and pass page file path to request.
+- Adjust session key counting range
+- Consume all magic link tokens for an email instead of just the used one to prevent reuse.
+- Correct `odac` special variable path resolution by removing `/src` instead of `/framework/src`.
+- Enable `MiddlewareChain` to automatically use auth handlers when created via `Route.auth.use`.
+- Ensure all HTML tags are recursively stripped when converting HTML to plain text.
+- Ignore `data:` and `vbscript:` pseudo-protocols when processing anchor hrefs.
+- Implement form token rotation on successful form submission without redirect and update client-side form with the new token.
+- Initialize cron interval only in the primary cluster process.
+- Introduce `setSession` method for client ID initialization and optimize internal session and cookie storage.
+- log errors when ensuring the magic link table exists instead of ignoring them
+- Log Odac Auth errors when ensuring token table exists instead of ignoring them.
+- Prevent navigation to `data:` and `vbscript:` URLs.
+- re-register form submit handler when its `data-odac-form` attribute changes to ensure correct event capture.
+- recursively strip nested script and style tags when sanitizing HTML
+- Relax sameSite cookie policy to Lax and refactor redirect handling.
+- remove all socket listeners when closing or disconnecting the WebSocket.
+- Remove early exit from token hash check loop to mitigate timing attacks.
+- return non-function default connection properties directly instead of attempting to bind them
+- return registration error on unique check failure.
+- Robustly extract multipart boundary from request body.
+- serve static files via `createReadStream` and pipe streamable content to response.
+- Validate error route cache handler is a function in Request abort method.
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### 🛠️ Fixes & Improvements
+
+- Simplify project initialization by removing directory emptiness validation and extraneous comments.
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
 ### Framework
 
 - HTML Email

package/README.md

@@ -1,57 +1,60 @@
-<p align="center">
-  <img src="https://odac.run/assets/img/github/header.png?v=1" alt="Odac Header">
-</p>
 
-# ⚡ Odac
+# ⚡ ODAC.JS
 
-**Odac** is a lightweight yet powerful server + framework toolkit for building and deploying modern web apps with ease — with built-in automation and a developer-first philosophy.
+**ODAC** is a lightweight, high-performance Node.js framework designed to build modern, scalable web applications with ease. It allows developers to focus on building features rather than configuring boilerplate, offering a complete toolkit for web development.
 
 ## ✨ Key Features
 
-### Core Server Features
-
-*   ⚡ **Blazing Fast & Ultra Light:** Optimized for performance, Odac is significantly lighter and faster than traditional server solutions, ensuring maximum performance with minimal resource usage.
-*   🚀 **Zero-Config Hosting:** Leave the complex server configurations to Odac and focus solely on your code. Get your web applications up and running in minutes.
-*   🌐 **One Server, Many Domains:** Easily host and manage multiple websites on a single Odac instance, each with its own domain and resources.
-*   🔒 **SSL in Seconds:** Secure all your websites in seconds with free, auto-renewing SSL certificates.
-*   📬 **Native Mail Server:** A full-featured, built-in mail server (IMAP/SMTP) that allows you to create and manage email accounts for your domains without needing an external service.
-*   ⚙️ **Process & CLI Monitor:** Keep your applications running smoothly with the integrated process manager and monitor your server from anywhere with the powerful command-line tool.
-
-### Integrated Web Framework
-
-*   🔗 **Custom URLs & Infinite Pages:** Easily create clean, custom URLs and an unlimited number of pages thanks to the powerful routing and skeleton system.
-*   ✨ **No-Code AJAX:** Automatically enable AJAX for form submissions and page transitions without writing any custom JavaScript, providing your users with a seamless single-page application (SPA) experience.
-*   🛡️ **Safe Requests:** Automatically secure all your endpoints against common vulnerabilities like CSRF with built-in token verification for POST and GET requests.
-*   🔐 **Auth Made Easy:** Implement user authentication in minutes with built-in session management, password hashing, and ready-to-use login/register forms.
-*   🌍 **Global Ready:** Reach a worldwide audience with built-in, automatic multi-language support. The framework simplifies internationalization (i18n).
-*   ⏰ **Built-in Cron Jobs:** Schedule and automate recurring tasks with the integrated cron system, perfect for background jobs, data cleanup, and scheduled operations.
+*   🚀 **Developer Friendly:** Simple setup and intuitive API design let you start building immediately.
+*   🔗 **Powerful Routing:** Create clean, custom URLs and manage infinite pages with a flexible routing system.
+*   ✨ **Seamless SPA Experience:** Automatic AJAX handling for forms and page transitions eliminates the need for complex client-side code.
+*   🛡️ **Built-in Security:** Automatic CSRF protection and secure default headers keep your application safe.
+*   🔐 **Authentication:** Ready-to-use session management, password hashing, and authentication helpers.
+*   🗄️ **Database Agnostic:** Integrated support for major databases (PostgreSQL, MySQL, SQLite) and Redis via Knex.js.
+*   🌍 **i18n Support:** Native multi-language support to help you reach a global audience.
+*   ⏰ **Task Scheduling:** Built-in Cron job system for handling background tasks and recurring operations.
+
+## 🛠️ Advanced Capabilities
+
+### ⚡ Cluster-Ready IPC
+Built for scale from day one, ODAC includes a powerful Inter-Process Communication (IPC) system.
+*   **Unified API:** Use the same `get`, `set`, `publish`, and `subscribe` methods regardless of the underlying driver.
+*   **Zero-Config Clustering:** The default `memory` driver automatically syncs data between Node.js cluster workers without external dependencies.
+*   **Redis Support:** Switch to the `redis` driver with a single config change to scale horizontally across multiple servers.
+
+### 🔌 Native WebSocket Support
+Real-time features are a first-class citizen in ODAC.
+*   **Integrated Server:** No need for third-party libraries; ODAC features a lightweight, native WebSocket implementation.
+*   **Room System:** Easily manage user groups with built-in `join`, `leave`, and `broadcast` to room functionality.
+*   **Route Integration:** define WebSocket endpoints directly in your router alongside HTTP routes.
+
+### 🎨 Powerful Templating
+ODAC's view engine combines the power of JavaScript with intuitive HTML tags.
+*   **Logic Tags:** Use `<odac:if>`, `<odac:for>`, and `<odac:else>` for clean control flow.
+*   **Async Support:** Fully asynchronous rendering allows fetching data directly within your views using `await`.
+*   **Safety:** Automatic escaping prevents XSS while allowing raw HTML output when explicitly requested.
 
 ## 🚀 Quick Start
 
-> 🔥 **Install with a single command. Works on Linux, macOS, and Windows.**
+Get your new ODAC project up and running in seconds using our CLI.
 
-#### Linux & macOS
+### Create a new project
 
 ```bash
-curl -sL https://odac.run/install | sudo bash
+npx odac init my-app
 ```
 
-#### Windows (PowerShell)
+### Start development
 
-```powershell
-irm https://odac.run/install | iex
+```bash
+cd my-app
+npm run dev
 ```
 
-This command:
-
-- Installs Node.js (v18+) if missing
-- Installs Odac globally via npm
-- Prepares your system for development or deployment
-
 ## 📚 Documentation
 
-For more detailed information and API reference, please check out our [official documentation website](https://docs.odac.run).
+For detailed guides, API references, and examples, visit our [official documentation](https://docs.odac.run).
 
 ## 📄 License
 
-This project is licensed under the AGPL-3.0 License. See the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

package/bin/odac.js

@@ -20,31 +20,14 @@ async function run() {
         const projectName = args[0] || '.'
         const targetDir = path.resolve(process.cwd(), projectName)
 
-        // 1. Validate Target Directory
-        if (fs.existsSync(targetDir)) {
-            const files = fs.readdirSync(targetDir)
-            const isNotEmpty = files.some(file =>
-                !['.git', '.DS_Store', '.gitignore', '.idea', '.vscode'].includes(file)
-            )
-
-            if (isNotEmpty) {
-                console.error(`❌ Error: Directory "${projectName === '.' ? 'Current directory' : projectName}" is not empty.`)
-                console.error('   Please run in an empty directory or specify a new project name.')
-                process.exit(1)
-            }
-        } else {
-            fs.mkdirSync(targetDir, { recursive: true })
-        }
+        if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true })
 
-        // 4. Copy Template
         console.log(`🚀 Initializing new Odac project in: ${targetDir}`)
         const templateDir = path.resolve(__dirname, '../template')
 
         try {
-            // Recursive copy
             fs.cpSync(templateDir, targetDir, { recursive: true })
 
-            // Update package.json
             const pkgPath = path.join(targetDir, 'package.json')
             const frameworkPkg = require('../package.json')
 
@@ -52,7 +35,6 @@ async function run() {
             pkg.name = projectName === '.' ? path.basename(targetDir) : projectName
             pkg.version = '0.0.1'
 
-            // Inject framework dependency
             if (!pkg.dependencies) pkg.dependencies = {}
             pkg.dependencies[frameworkPkg.name] = `^${frameworkPkg.version}`
 
@@ -70,24 +52,12 @@ async function run() {
             }
 
             console.log('\n✨ Project initialized successfully!')
-            console.log('\n🚀 Starting server...')
-
-            try {
-                execSync('npm run dev', {
-                    stdio: 'inherit',
-                    cwd: targetDir
-                })
-            } catch (err) {
-                // User probably cancelled with Ctrl+C
-                console.log('\n👋 Server stopped.')
-            }
 
         } catch (error) {
             console.error('❌ Error initializing project:', error.message)
         }
 
     } else if (command === 'dev') {
-        // Start the framework
         require('../index.js')
     } else {
         console.log('Usage:')