odac 0.9.0 → 1.0.0

package/docs/backend/04-routing/08-middleware.md

@@ -0,0 +1,214 @@
+## 🔗 Middleware
+
+Middleware allows you to run code before your controllers execute. Perfect for authentication, logging, rate limiting, and more.
+
+### Creating Middleware
+
+Create middleware files in the `middleware/` directory:
+
+```javascript
+// middleware/auth.js
+module.exports = async (Odac) => {
+  if (!await Odac.Auth.check()) {
+    return Odac.direct('/login')  // Redirect to login
+  }
+  // No return = continue to next middleware or controller
+}
+```
+
+**Middleware Rules:**
+- Return `false` → Stop execution (403 Forbidden)
+- Return `Odac.abort(code)` → Stop with custom error code
+- Return `Odac.direct(url)` → Stop and redirect
+- Return nothing or `true` → Continue to next middleware/controller
+
+### Using Middleware
+
+#### Single Route
+```javascript
+Odac.Route
+  .use('logger')
+  .page('/contact', 'contact')
+```
+
+#### Multiple Routes
+```javascript
+Odac.Route
+  .use('cors')
+  .page('/api/users', 'api.users')
+  .page('/api/posts', 'api.posts')
+  .get('/api/stats', 'api.stats')
+```
+
+#### Multiple Middlewares
+```javascript
+Odac.Route
+  .use('cors', 'rateLimit')
+  .post('/api/upload', 'api.upload')
+```
+
+#### With Auth Routes
+
+`Odac.Route.auth` already requires authentication. You can add additional middleware on top:
+
+```javascript
+// Admin-only routes (requires login + admin role)
+Odac.Route.auth
+  .use('admin')
+  .page('/admin/dashboard', 'admin.dashboard')
+  .page('/admin/users', 'admin.users')
+  .post('/admin/settings', 'admin.settings')
+```
+
+```javascript
+// Premium user routes (requires login + premium subscription)
+Odac.Route.auth
+  .use('premium')
+  .page('/premium/content', 'premium.content')
+  .page('/premium/downloads', 'premium.downloads')
+```
+
+```javascript
+// Multiple middlewares with auth
+Odac.Route.auth
+  .use('verified', 'rateLimit')
+  .post('/api/sensitive', 'api.sensitive')
+```
+
+### Middleware Examples
+
+#### Authentication
+```javascript
+// middleware/auth.js
+module.exports = async (Odac) => {
+  if (!await Odac.Auth.check()) {
+    return Odac.direct('/login')
+  }
+}
+```
+
+#### Admin Check
+```javascript
+// middleware/admin.js
+module.exports = async (Odac) => {
+  const user = await Odac.Auth.user()
+  if (!user || user.role !== 'admin') {
+    return false  // 403 Forbidden
+  }
+}
+```
+
+#### CORS Headers
+```javascript
+// middleware/cors.js
+module.exports = async (Odac) => {
+  Odac.Request.header('Access-Control-Allow-Origin', '*')
+  Odac.Request.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE')
+}
+```
+
+#### Rate Limiting
+```javascript
+// middleware/rateLimit.js
+const requests = new Map()
+let lastCleanup = Date.now()
+
+module.exports = async (Odac) => {
+  const ip = Odac.Request.ip
+  const now = Date.now()
+  const limit = 100
+  const window = 60000
+  
+  if (now - lastCleanup > window) {
+    for (const [key, times] of requests.entries()) {
+      const recent = times.filter(time => now - time < window)
+      if (recent.length === 0) {
+        requests.delete(key)
+      } else {
+        requests.set(key, recent)
+      }
+    }
+    lastCleanup = now
+  }
+  
+  if (!requests.has(ip)) {
+    requests.set(ip, [])
+  }
+  
+  const userRequests = requests.get(ip).filter(time => now - time < window)
+  
+  if (userRequests.length >= limit) {
+    return Odac.abort(429, 'Too many requests')
+  }
+  
+  userRequests.push(now)
+  requests.set(ip, userRequests)
+}
+```
+
+> **Note:** This example uses in-memory storage for simplicity. For production environments with multiple server instances, consider using Redis or Memcached for distributed rate limiting.
+
+#### Premium Check with View
+```javascript
+// middleware/premium.js
+module.exports = async (Odac) => {
+  const user = await Odac.Auth.user()
+  
+  if (!user.isPremium) {
+    return Odac.View.render('premium/upgrade', {
+      user: user,
+      currentPage: Odac.Request.url
+    })
+  }
+}
+```
+
+#### Logging
+```javascript
+// middleware/logger.js
+module.exports = async (Odac) => {
+  console.log(`${Odac.Request.method} ${Odac.Request.url}`)
+}
+```
+
+#### Inline Middleware
+```javascript
+Odac.Route
+  .use(async (Odac) => {
+    console.log('Custom middleware')
+  })
+  .page('/special', 'special')
+```
+
+### Complete Example
+
+```javascript
+// route/www.js
+
+// Public routes
+Odac.Route.page('/', 'index')
+Odac.Route.page('/about', 'about')
+
+// API routes with CORS
+Odac.Route
+  .use('cors', 'rateLimit')
+  .get('/api/public', 'api.public')
+  .post('/api/contact', 'api.contact')
+
+// User routes (requires login)
+Odac.Route.auth
+  .page('/profile', 'profile')
+  .page('/settings', 'settings')
+  .post('/api/update', 'update')
+
+// Admin routes (requires login + admin role)
+Odac.Route.auth
+  .use('admin')
+  .page('/admin', 'admin.index')
+  .page('/admin/users', 'admin.users')
+  .post('/admin/delete', 'admin.delete')
+```
+
+### Hot Reloading
+
+Middleware files are automatically reloaded when changed (every 5 seconds), just like controllers and routes. No server restart needed during development.

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

@@ -0,0 +1,292 @@
+# WebSocket Authentication & Middleware
+
+Advanced authentication and middleware patterns for WebSocket routes.
+
+## Authentication Methods
+
+### 1. Using auth.ws() (Recommended)
+
+The simplest way to require authentication:
+
+```javascript
+Odac.Route.auth.ws('/secure', async Odac => {
+  const user = await Odac.Auth.user()
+  
+  Odac.ws.send({
+    type: 'authenticated',
+    user: user.name
+  })
+})
+```
+
+**Behavior:**
+- Automatically checks authentication before handler runs
+- Closes connection with code `4001` if not authenticated
+- No need for manual auth checks
+
+### 2. Manual Authentication Check
+
+For custom authentication logic:
+
+```javascript
+Odac.Route.ws('/custom-auth', async Odac => {
+  const token = Odac.Request.header('Authorization')
+  
+  if (!token) {
+    Odac.ws.close(4001, 'Missing token')
+    return
+  }
+
+  const user = await validateCustomToken(token)
+  
+  if (!user) {
+    Odac.ws.close(4001, 'Invalid token')
+    return
+  }
+
+  Odac.ws.data.user = user
+  Odac.ws.send({type: 'authenticated'})
+})
+```
+
+## Middleware Support
+
+### Basic Middleware
+
+```javascript
+Odac.Route.use('rate-limit').ws('/chat', Odac => {
+  Odac.ws.send({type: 'connected'})
+})
+```
+
+### Multiple Middleware
+
+Middleware runs in order:
+
+```javascript
+Odac.Route.use('auth', 'rate-limit', 'log').ws('/chat', Odac => {
+  Odac.ws.send({type: 'ready'})
+})
+```
+
+### Creating WebSocket Middleware
+
+**middleware/websocket-rate-limit.js:**
+
+```javascript
+const connections = new Map()
+const RATE_LIMIT = 5
+const WINDOW = 60000
+
+module.exports = async Odac => {
+  const ip = Odac.Request.ip
+  const now = Date.now()
+  
+  if (!connections.has(ip)) {
+    connections.set(ip, [])
+  }
+  
+  const userConnections = connections.get(ip)
+  const recentConnections = userConnections.filter(time => now - time < WINDOW)
+  
+  if (recentConnections.length >= RATE_LIMIT) {
+    return false
+  }
+  
+  recentConnections.push(now)
+  connections.set(ip, recentConnections)
+  
+  return true
+}
+```
+
+**Usage:**
+
+```javascript
+Odac.Route.use('websocket-rate-limit').ws('/chat', Odac => {
+  Odac.ws.send({type: 'connected'})
+})
+```
+
+### Middleware Return Values
+
+| Return Value | Behavior |
+|--------------|----------|
+| `true` or `undefined` | Continue to next middleware/handler |
+| `false` | Close connection with code `4003` (Forbidden) |
+| Any other value | Close connection with code `4000` |
+
+### Advanced Middleware Example
+
+**middleware/websocket-auth.js:**
+
+```javascript
+module.exports = async Odac => {
+  const token = Odac.Request.header('X-WS-Token')
+  
+  if (!token) {
+    console.log('WebSocket connection rejected: No token')
+    return false
+  }
+  
+  try {
+    const user = await verifyToken(token)
+    
+    if (!user) {
+      console.log('WebSocket connection rejected: Invalid token')
+      return false
+    }
+    
+    Odac.Auth.setUser(user)
+    return true
+    
+  } catch (error) {
+    console.error('WebSocket auth error:', error)
+    return false
+  }
+}
+```
+
+## Combining Auth and Middleware
+
+You can combine `auth.ws()` with middleware:
+
+```javascript
+// This won't work - auth.ws() doesn't support chaining
+// Odac.Route.use('rate-limit').auth.ws('/chat', handler)
+
+// Instead, use middleware that includes auth check
+Odac.Route.use('websocket-auth', 'rate-limit').ws('/chat', Odac => {
+  const user = Odac.Auth.user()
+  Odac.ws.send({user: user.name})
+})
+
+// Or use auth.ws() without middleware
+Odac.Route.auth.ws('/chat', Odac => {
+  const user = Odac.Auth.user()
+  Odac.ws.send({user: user.name})
+})
+```
+
+## Real-World Examples
+
+### Rate-Limited Chat
+
+```javascript
+// middleware/chat-rate-limit.js
+const userMessages = new Map()
+
+module.exports = async Odac => {
+  const user = await Odac.Auth.user()
+  if (!user) return false
+  
+  const userId = user.id
+  const now = Date.now()
+  
+  if (!userMessages.has(userId)) {
+    userMessages.set(userId, [])
+  }
+  
+  const messages = userMessages.get(userId)
+  const recentMessages = messages.filter(time => now - time < 10000)
+  
+  if (recentMessages.length >= 10) {
+    return false
+  }
+  
+  recentMessages.push(now)
+  userMessages.set(userId, recentMessages)
+  
+  return true
+}
+
+// route/websocket.js
+Odac.Route.use('chat-rate-limit').auth.ws('/chat', async Odac => {
+  const user = await Odac.Auth.user()
+  Odac.ws.join('general')
+  
+  Odac.ws.on('message', data => {
+    Odac.ws.to('general').send({
+      user: user.name,
+      text: data.text
+    })
+  })
+})
+```
+
+### Admin-Only WebSocket
+
+```javascript
+// middleware/admin-only.js
+module.exports = async Odac => {
+  const user = await Odac.Auth.user()
+  
+  if (!user || !user.isAdmin) {
+    return false
+  }
+  
+  return true
+}
+
+// route/websocket.js
+Odac.Route.use('admin-only').ws('/admin-dashboard', Odac => {
+  const sendStats = async () => {
+    const stats = await getSystemStats()
+    Odac.ws.send({type: 'stats', data: stats})
+  }
+  
+  sendStats()
+  const interval = setInterval(sendStats, 5000)
+  
+  Odac.ws.on('close', () => clearInterval(interval))
+})
+```
+
+### IP Whitelist
+
+```javascript
+// middleware/ip-whitelist.js
+const ALLOWED_IPS = ['127.0.0.1', '192.168.1.100']
+
+module.exports = async Odac => {
+  const ip = Odac.Request.ip
+  
+  if (!ALLOWED_IPS.includes(ip)) {
+    console.log(`WebSocket connection rejected from ${ip}`)
+    return false
+  }
+  
+  return true
+}
+
+// route/websocket.js
+Odac.Route.use('ip-whitelist').ws('/internal', Odac => {
+  Odac.ws.send({type: 'internal-access-granted'})
+})
+```
+
+## Error Handling
+
+Middleware errors should be handled gracefully:
+
+```javascript
+module.exports = async Odac => {
+  try {
+    const result = await someAsyncOperation()
+    return result.isValid
+  } catch (error) {
+    console.error('Middleware error:', error)
+    return false
+  }
+}
+```
+
+## Best Practices
+
+1. **Always return a value** from middleware (true/false/undefined)
+2. **Log rejections** for debugging
+3. **Clean up resources** in middleware if needed
+4. **Use auth.ws()** for simple authentication
+5. **Use middleware** for complex logic (rate limiting, logging, etc.)
+6. **Combine middleware** for layered security
+7. **Test middleware** independently before using in routes