odac 0.9.0 → 1.0.0

package/docs/backend/04-routing/09-websocket.md

@@ -0,0 +1,298 @@
+# WebSocket Routes
+
+Odac provides built-in WebSocket support for real-time bidirectional communication.
+
+## Route Definition
+
+WebSocket routes are defined in your route files (e.g., `route/www.js` or `route/websocket.js`) using `Odac.Route.ws()`:
+
+```javascript
+// route/websocket.js
+Odac.Route.ws('/chat', Odac => {
+  Odac.ws.send({type: 'welcome', message: 'Connected!'})
+
+  Odac.ws.on('message', data => {
+    console.log('Received:', data)
+    Odac.ws.send({type: 'echo', data})
+  })
+
+  Odac.ws.on('close', () => {
+    console.log('Client disconnected')
+  })
+})
+```
+
+**Handler Signature:**
+
+The handler receives the `Odac` instance as the only parameter. The WebSocket client is accessible via `Odac.ws`, providing a consistent API with HTTP routes where everything is accessed through the `Odac` object.
+
+**CSRF Token Protection:**
+
+By default, WebSocket routes require a valid CSRF token (like `Route.get()` and `Route.post()`). The token is sent via the `Sec-WebSocket-Protocol` header during the initial handshake.
+
+**Disable token requirement:**
+```javascript
+Odac.Route.ws('/public', Odac => {
+  Odac.ws.send({type: 'public'})
+}, {token: false})
+```
+
+**Route File Structure:**
+```
+web/
+├── route/
+│   ├── www.js          # HTTP routes
+│   └── websocket.js    # WebSocket routes (recommended)
+```
+
+## WebSocket Client API (Odac.ws)
+
+The WebSocket client is accessible via `Odac.ws` in your handler, providing a consistent API pattern with HTTP routes.
+
+### Sending Messages
+
+```javascript
+Odac.ws.send({type: 'message', text: 'Hello'})  // JSON object
+Odac.ws.send('Plain text message')               // String
+Odac.ws.sendBinary(buffer)                       // Binary data
+```
+
+### Event Handlers
+
+```javascript
+Odac.ws.on('message', data => {})  // Incoming message
+Odac.ws.on('close', () => {})      // Connection closed
+Odac.ws.on('error', err => {})     // Error occurred
+```
+
+### Connection Management
+
+```javascript
+Odac.ws.close()           // Close connection
+Odac.ws.ping()            // Send ping frame
+Odac.ws.id                // Unique client ID
+```
+
+## Rooms
+
+Group clients into rooms for targeted broadcasting:
+
+```javascript
+Odac.Route.ws('/game', Odac => {
+  const roomId = Odac.Request.data.url.room || 'lobby'
+  
+  Odac.ws.join(roomId)
+  
+  Odac.ws.on('message', data => {
+    Odac.ws.to(roomId).send({
+      type: 'chat',
+      message: data.message
+    })
+  })
+
+  Odac.ws.on('close', () => {
+    Odac.ws.leave(roomId)
+  })
+})
+```
+
+## Broadcasting
+
+```javascript
+// Send to all clients except sender
+Odac.ws.broadcast({type: 'notification', text: 'New user joined'})
+
+// Send to all clients in a room
+Odac.ws.to('room-name').send({type: 'update', data: {}})
+```
+
+## URL Parameters
+
+WebSocket routes support dynamic parameters:
+
+```javascript
+Odac.Route.ws('/room/{roomId}/user/{userId}', Odac => {
+  const {roomId, userId} = Odac.Request.data.url
+  
+  Odac.ws.join(roomId)
+  Odac.ws.data.userId = userId
+})
+```
+
+## Authentication
+
+### Manual Authentication Check
+
+```javascript
+Odac.Route.ws('/secure', async Odac => {
+  const isAuthenticated = await Odac.Auth.check()
+  
+  if (!isAuthenticated) {
+    Odac.ws.close(4001, 'Unauthorized')
+    return
+  }
+
+  const user = await Odac.Auth.user()
+  Odac.ws.data.user = user
+})
+```
+
+### Using auth.ws() (Recommended)
+
+Automatically requires authentication (also requires token by default):
+
+```javascript
+Odac.Route.auth.ws('/secure', async Odac => {
+  const user = await Odac.Auth.user()
+  Odac.ws.data.user = user
+  
+  Odac.ws.send({
+    type: 'welcome',
+    user: user.name
+  })
+})
+```
+
+If the user is not authenticated, the connection is automatically closed with code `4001`.
+
+### Options
+
+```javascript
+Odac.Route.ws('/path', handler, {
+  token: true  // Require CSRF token (default: true)
+})
+```
+
+**Examples:**
+
+```javascript
+// Public WebSocket (no token, no auth)
+Odac.Route.ws('/public', handler, {token: false})
+
+// Token required, no auth (default)
+Odac.Route.ws('/chat', handler)
+
+// Both token and auth required
+Odac.Route.auth.ws('/secure', handler)
+```
+
+## Middleware
+
+WebSocket routes support middleware just like HTTP routes:
+
+```javascript
+// Define middleware
+Odac.Route.use('auth-check', 'rate-limit').ws('/chat', Odac => {
+  Odac.ws.send({type: 'welcome'})
+})
+```
+
+**Middleware behavior:**
+- If middleware returns `false`, connection closes with code `4003` (Forbidden)
+- If middleware returns anything other than `true` or `undefined`, connection closes with code `4000`
+- Middleware runs before the WebSocket handler
+
+**Example with custom middleware:**
+
+```javascript
+// middleware/websocket-auth.js
+module.exports = async Odac => {
+  const token = Odac.Request.header('Authorization')
+  if (!token) return false
+  
+  const user = await validateToken(token)
+  if (!user) return false
+  
+  Odac.Auth.setUser(user)
+  return true
+}
+
+// route/websocket.js
+Odac.Route.use('websocket-auth').ws('/secure', Odac => {
+  Odac.ws.send({type: 'authenticated'})
+})
+```
+
+## Client Data Storage
+
+Store per-connection data:
+
+```javascript
+Odac.ws.data.username = 'john'
+Odac.ws.data.joinedAt = Date.now()
+```
+
+## Intervals and Timeouts
+
+Use `Odac.setInterval()` and `Odac.setTimeout()` instead of global functions. They are automatically cleaned up when the WebSocket connection closes:
+
+```javascript
+Odac.Route.ws('/live-updates', Odac => {
+  Odac.setInterval(() => {
+    Odac.ws.send({
+      type: 'update',
+      timestamp: Date.now()
+    })
+  }, 1000)
+
+  Odac.setTimeout(() => {
+    Odac.ws.send({type: 'delayed-message'})
+  }, 5000)
+})
+```
+
+**Why use Odac.setInterval/setTimeout?**
+- Prevents memory leaks by auto-cleanup on disconnect
+- No need to manually track and clear intervals
+- Works seamlessly with WebSocket lifecycle
+
+**Manual cleanup (if needed):**
+
+```javascript
+const intervalId = Odac.setInterval(() => {}, 1000)
+Odac.clearInterval(intervalId)
+
+const timeoutId = Odac.setTimeout(() => {}, 5000)
+Odac.clearTimeout(timeoutId)
+```
+
+## Real-Time Notifications Example
+
+```javascript
+Odac.Route.ws('/notifications', async Odac => {
+  const user = await Odac.Auth.user()
+  if (!user) {
+    Odac.ws.close(4001, 'Unauthorized')
+    return
+  }
+
+  Odac.ws.data.userId = user.id
+  Odac.ws.join(`user-${user.id}`)
+
+  Odac.ws.on('close', () => {
+    console.log(`User ${user.id} disconnected`)
+  })
+})
+
+// Send notification to specific user from anywhere in your app
+function notifyUser(userId, message) {
+  const wsServer = Odac.Route.wsServer
+  wsServer.toRoom(`user-${userId}`, {
+    type: 'notification',
+    message
+  })
+}
+```
+
+## Client-Side Usage
+
+Frontend clients can use shared connections across tabs:
+
+```javascript
+// All browser tabs share one connection
+const ws = Odac.ws('/notifications', {shared: true})
+
+ws.on('message', data => {
+  console.log('Notification:', data)
+})
+```

package/docs/backend/05-controllers/01-how-to-build-a-controller.md

@@ -1,6 +1,6 @@
 ## 🏗️ How to Build a Controller
 
-A controller is just a JavaScript module that exports a function. This function automatically gets the magical `Candy` context object we talked about in the overview.
+A controller is just a JavaScript module that exports a function. This function automatically gets the magical `Odac` context object we talked about in the overview.
 
 #### A Simple "Hello World" Controller
 
@@ -8,9 +8,9 @@ Check out this basic example from `controller/page/index.js`:
 
 ```javascript
 // This function is our controller!
-module.exports = function (Candy) {
+module.exports = function (Odac) {
   // It simply returns a string.
-  return 'Welcome to my awesome CandyPack server!'
+  return 'Welcome to my awesome Odac server!'
 }
 ```
 

package/docs/backend/05-controllers/02-your-trusty-odac-assistant.md

@@ -0,0 +1,41 @@
+## 🤝 Your trusty `Odac` Assistant
+
+Remember the `Odac` object? It's your best friend inside a controller. It's passed to your controller function and gives you all the tools you need for the current request.
+
+#### Awesome Services at Your Fingertips
+
+*   `Odac.Request`: Info about the user's request.
+*   `Odac.View`: Renders your HTML pages.
+*   `Odac.Auth`: Manages user logins.
+*   `Odac.Token`: Protects your forms.
+*   `Odac.Lang`: Helps with different languages.
+
+#### Handy Helper Functions
+
+*   `Odac.return(data)`: Send back a response.
+*   `Odac.direct(url)`: Redirect the user to a new page.
+*   `Odac.cookie(key, value)`: Set a browser cookie.
+*   `Odac.validator()`: Check user input easily.
+*   `Odac.setInterval(callback, delay)`: Schedule repeating tasks (auto-cleanup).
+*   `Odac.setTimeout(callback, delay)`: Schedule one-time tasks (auto-cleanup).
+*   `Odac.stream(input)`: Create streaming responses (SSE).
+
+#### Memory-Safe Timers
+
+Always use `Odac.setInterval()` and `Odac.setTimeout()` instead of global functions:
+
+```javascript
+module.exports = async (Odac) => {
+  // ✅ Good - automatically cleaned up
+  Odac.setInterval(() => {
+    // This stops when request ends
+  }, 1000)
+  
+  // ❌ Bad - memory leak!
+  setInterval(() => {
+    // This runs forever
+  }, 1000)
+}
+```
+
+With controllers and the `Odac` object, you have everything you need to start building powerful application logic!

package/docs/backend/05-controllers/03-controller-classes.md

@@ -4,25 +4,25 @@ While simple function exports work great for basic controllers, you can also org
 
 #### Creating a Controller Class
 
-A controller class receives the `Candy` object in its constructor, giving you access to all services throughout your class methods:
+A controller class receives the `Odac` object in its constructor, giving you access to all services throughout your class methods:
 
 ```javascript
 // controller/User.js
 class User {
-  constructor(Candy) {
-    this.Candy = Candy
+  constructor(Odac) {
+    this.Odac = Odac
   }
 
   async getProfile() {
-    const user = await this.Candy.Auth.user()
-    return this.Candy.return({
+    const user = await this.Odac.Auth.user()
+    return this.Odac.return({
       success: true,
       user: user
     })
   }
 
   async updateProfile() {
-    const validator = this.Candy.validator()
+    const validator = this.Odac.validator()
     validator.post('name').required().min(3)
     validator.post('email').required().email()
 
@@ -30,17 +30,17 @@ class User {
       return validator.result()
     }
 
-    const name = await this.Candy.request('name')
-    const email = await this.Candy.request('email')
+    const name = await this.Odac.request('name')
+    const email = await this.Odac.request('email')
 
     // Update user in database
-    await this.Candy.Mysql.query('UPDATE users SET name = ?, email = ? WHERE id = ?', [
+    await this.Odac.Mysql.query('UPDATE users SET name = ?, email = ? WHERE id = ?', [
       name,
       email,
-      this.Candy.Auth.user().id
+      this.Odac.Auth.user().id
     ])
 
-    return this.Candy.return({
+    return this.Odac.return({
       success: true,
       message: 'Profile updated successfully'
     })
@@ -56,23 +56,23 @@ Once you've created a controller class, you can use it in your routes just like
 
 ```javascript
 // route/www.js
-Candy.Route.buff = 'www'
+Odac.Route.buff = 'www'
 
 // Access class methods using dot notation
-Candy.Route.get('/profile', 'User.getProfile')
-Candy.Route.post('/profile/update', 'User.updateProfile')
+Odac.Route.get('/profile', 'User.getProfile')
+Odac.Route.post('/profile/update', 'User.updateProfile')
 ```
 
 #### Accessing Classes in Controllers
 
-Controller classes are automatically instantiated for each request and attached to the `Candy` object. You can access them from any controller:
+Controller classes are automatically instantiated for each request and attached to the `Odac` object. You can access them from any controller:
 
 ```javascript
-module.exports = async function (Candy) {
+module.exports = async function (Odac) {
   // Access your User class
-  const profile = await Candy.User.getProfile()
+  const profile = await Odac.User.getProfile()
   
-  return Candy.return(profile)
+  return Odac.return(profile)
 }
 ```
 
@@ -81,7 +81,7 @@ module.exports = async function (Candy) {
 - **Organization**: Group related methods together
 - **Reusability**: Share logic between different routes
 - **Maintainability**: Easier to manage complex controllers
-- **Context**: The `Candy` object is always available via `this.Candy`
+- **Context**: The `Odac` object is always available via `this.Odac`
 
 #### Class vs Function Controllers