odac 0.9.0 → 1.0.0

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

@@ -0,0 +1,381 @@
+# WebSocket Examples
+
+Complete examples for common WebSocket use cases.
+
+## Echo Server
+
+Simple echo server that sends back received messages:
+
+```javascript
+// route/websocket.js
+Odac.Route.ws('/echo', Odac => {
+  Odac.ws.send({type: 'welcome', message: 'Connected!'})
+
+  Odac.ws.on('message', data => {
+    Odac.ws.send({type: 'echo', data})
+  })
+})
+```
+
+**Client:**
+```javascript
+const ws = Odac.ws('/echo')
+ws.on('message', data => console.log(data))
+ws.send({message: 'Hello!'})
+```
+
+## Authenticated Chat Room
+
+### Using auth.ws() (Recommended)
+
+```javascript
+Odac.Route.auth.ws('/chat', async Odac => {
+  const user = await Odac.Auth.user()
+
+  Odac.ws.join('general')
+  Odac.ws.data.user = user
+
+  Odac.ws.to('general').send({
+    type: 'user_joined',
+    user: user.name
+  })
+
+  Odac.ws.on('message', data => {
+    Odac.ws.to('general').send({
+      type: 'message',
+      user: user.name,
+      text: data.text
+    })
+  })
+
+  Odac.ws.on('close', () => {
+    Odac.ws.to('general').send({
+      type: 'user_left',
+      user: user.name
+    })
+  })
+})
+```
+
+### Manual Authentication Check
+
+```javascript
+Odac.Route.ws('/chat', async Odac => {
+  const user = await Odac.Auth.user()
+  
+  if (!user) {
+    Odac.ws.close(4001, 'Unauthorized')
+    return
+  }
+
+  Odac.ws.join('general')
+  Odac.ws.data.user = user
+
+  Odac.ws.to('general').send({
+    type: 'user_joined',
+    user: user.name
+  })
+
+  Odac.ws.on('message', data => {
+    Odac.ws.to('general').send({
+      type: 'message',
+      user: user.name,
+      text: data.text
+    })
+  })
+
+  Odac.ws.on('close', () => {
+    Odac.ws.to('general').send({
+      type: 'user_left',
+      user: user.name
+    })
+  })
+})
+```
+
+**Client:**
+```javascript
+const chat = Odac.ws('/chat')
+
+chat.on('message', data => {
+  if (data.type === 'message') {
+    console.log(`${data.user}: ${data.text}`)
+  }
+})
+
+chat.send({text: 'Hello everyone!'})
+```
+
+## Room-Based Chat with URL Parameters
+
+Dynamic rooms using URL parameters:
+
+```javascript
+Odac.Route.ws('/room/{roomId}', async Odac => {
+  const {roomId} = Odac.Request.data.url
+  const user = await Odac.Auth.user()
+
+  if (!user) {
+    Odac.ws.close(4001, 'Unauthorized')
+    return
+  }
+
+  Odac.ws.join(roomId)
+  Odac.ws.data.roomId = roomId
+
+  Odac.ws.send({
+    type: 'joined',
+    room: roomId
+  })
+
+  Odac.ws.on('message', data => {
+    Odac.ws.to(roomId).send({
+      type: 'message',
+      user: user.name,
+      text: data.text,
+      room: roomId
+    })
+  })
+})
+```
+
+**Client:**
+```javascript
+const room = Odac.ws('/room/gaming')
+room.on('message', data => console.log(data))
+room.send({text: 'Hi from gaming room!'})
+```
+
+## Real-Time Notifications
+
+User-specific notification system:
+
+```javascript
+Odac.Route.ws('/notifications', async Odac => {
+  const user = await Odac.Auth.user()
+
+  if (!user) {
+    Odac.ws.close(4001, 'Unauthorized')
+    return
+  }
+
+  Odac.ws.join(`user-${user.id}`)
+  Odac.ws.data.userId = user.id
+
+  Odac.ws.send({
+    type: 'connected',
+    unreadCount: await getUnreadCount(user.id)
+  })
+})
+
+// Send notification from anywhere in your app
+async function notifyUser(userId, notification) {
+  const wsServer = Odac.Route.wsServer
+  wsServer.toRoom(`user-${userId}`, {
+    type: 'notification',
+    ...notification
+  })
+}
+```
+
+**Client (with cross-tab sharing):**
+```javascript
+const notifications = Odac.ws('/notifications', {
+  shared: true,
+  autoReconnect: true
+})
+
+notifications.on('message', data => {
+  if (data.type === 'notification') {
+    showNotification(data.title, data.message)
+  }
+})
+```
+
+## Broadcasting System
+
+Broadcast messages to all connected clients:
+
+```javascript
+Odac.Route.ws('/broadcast', Odac => {
+  Odac.ws.on('message', data => {
+    if (data.type === 'broadcast') {
+      Odac.ws.broadcast({
+        type: 'announcement',
+        message: data.message,
+        timestamp: Date.now()
+      })
+    }
+  })
+})
+```
+
+**Client:**
+```javascript
+const broadcast = Odac.ws('/broadcast')
+
+broadcast.on('message', data => {
+  if (data.type === 'announcement') {
+    alert(data.message)
+  }
+})
+
+// Send to all clients
+broadcast.send({
+  type: 'broadcast',
+  message: 'Server maintenance in 5 minutes'
+})
+```
+
+## Live Dashboard
+
+Real-time data updates for dashboards:
+
+```javascript
+Odac.Route.ws('/dashboard', async Odac => {
+  const user = await Odac.Auth.user()
+
+  if (!user || !user.isAdmin) {
+    Odac.ws.close(4001, 'Unauthorized')
+    return
+  }
+
+  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)
+  })
+})
+```
+
+**Client:**
+```javascript
+const dashboard = Odac.ws('/dashboard')
+
+dashboard.on('message', data => {
+  if (data.type === 'stats') {
+    updateDashboard(data.data)
+  }
+})
+```
+
+## WebSocket with Middleware
+
+Use middleware for rate limiting, authentication, or custom logic:
+
+```javascript
+// middleware/rate-limit.js
+const connections = new Map()
+
+module.exports = async Odac => {
+  const ip = Odac.Request.ip
+  const now = Date.now()
+  
+  if (connections.has(ip)) {
+    const lastConnection = connections.get(ip)
+    if (now - lastConnection < 1000) {
+      return false // Too many connections
+    }
+  }
+  
+  connections.set(ip, now)
+  return true
+}
+
+// route/websocket.js
+Odac.Route.use('rate-limit').ws('/chat', Odac => {
+  Odac.ws.send({type: 'connected'})
+})
+```
+
+**Multiple Middleware:**
+
+```javascript
+Odac.Route.use('auth', 'rate-limit', 'log-connection').ws('/secure', Odac => {
+  Odac.ws.send({type: 'authenticated'})
+})
+```
+
+## Multiplayer Game
+
+Simple multiplayer game state synchronization:
+
+```javascript
+Odac.Route.ws('/game/{gameId}', async Odac => {
+  const {gameId} = Odac.Request.data.url
+  const user = await Odac.Auth.user()
+
+  if (!user) {
+    Odac.ws.close(4001, 'Unauthorized')
+    return
+  }
+
+  Odac.ws.join(`game-${gameId}`)
+  Odac.ws.data.gameId = gameId
+  Odac.ws.data.playerId = user.id
+
+  Odac.ws.to(`game-${gameId}`).send({
+    type: 'player_joined',
+    playerId: user.id,
+    name: user.name
+  })
+
+  Odac.ws.on('message', data => {
+    switch (data.type) {
+      case 'move':
+        Odac.ws.to(`game-${gameId}`).send({
+          type: 'player_moved',
+          playerId: user.id,
+          position: data.position
+        })
+        break
+      
+      case 'action':
+        Odac.ws.to(`game-${gameId}`).send({
+          type: 'player_action',
+          playerId: user.id,
+          action: data.action
+        })
+        break
+    }
+  })
+
+  Odac.ws.on('close', () => {
+    Odac.ws.to(`game-${gameId}`).send({
+      type: 'player_left',
+      playerId: user.id
+    })
+  })
+})
+```
+
+**Client:**
+```javascript
+const game = Odac.ws('/game/room-123')
+
+game.on('message', data => {
+  switch (data.type) {
+    case 'player_joined':
+      addPlayer(data.playerId, data.name)
+      break
+    case 'player_moved':
+      updatePlayerPosition(data.playerId, data.position)
+      break
+    case 'player_action':
+      handlePlayerAction(data.playerId, data.action)
+      break
+  }
+})
+
+// Send player movement
+game.send({
+  type: 'move',
+  position: {x: 100, y: 200}
+})
+```

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

@@ -0,0 +1,211 @@
+# WebSocket Quick Reference
+
+Quick reference for Odac WebSocket API.
+
+## Backend API
+
+### Route Definition
+```javascript
+Odac.Route.ws('/path', Odac => {
+  // Handler - WebSocket client accessible via Odac.ws
+})
+```
+
+### WebSocket Client Methods (Odac.ws)
+
+| Method | Description |
+|--------|-------------|
+| `Odac.ws.send(data)` | Send JSON data to client |
+| `Odac.ws.sendBinary(buffer)` | Send binary data |
+| `Odac.ws.close(code, reason)` | Close connection |
+| `Odac.ws.ping()` | Send ping frame |
+| `Odac.ws.join(room)` | Join a room |
+| `Odac.ws.leave(room)` | Leave a room |
+| `Odac.ws.to(room).send(data)` | Send to room |
+| `Odac.ws.broadcast(data)` | Send to all clients |
+| `Odac.ws.on(event, handler)` | Add event listener |
+| `Odac.ws.off(event, handler)` | Remove event listener |
+
+### WebSocket Client Properties
+
+| Property | Description |
+|----------|-------------|
+| `Odac.ws.id` | Unique client ID |
+| `Odac.ws.rooms` | Array of joined rooms |
+| `Odac.ws.data` | Custom data storage |
+
+### Events
+
+| Event | Description |
+|-------|-------------|
+| `message` | Incoming message |
+| `close` | Connection closed |
+| `error` | Error occurred |
+| `pong` | Pong received |
+
+### Server Methods
+
+| Method | Description |
+|--------|-------------|
+| `Odac.Route.wsServer.clients` | Map of all clients |
+| `Odac.Route.wsServer.clientCount` | Number of clients |
+| `Odac.Route.wsServer.toRoom(room, data)` | Send to room |
+| `Odac.Route.wsServer.broadcast(data)` | Broadcast to all |
+
+## Frontend API
+
+### Connection
+```javascript
+const ws = Odac.ws('/path', options)
+```
+
+### Backend Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `token` | `true` | Require CSRF token |
+
+### Client Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `autoReconnect` | `true` | Auto-reconnect on disconnect |
+| `reconnectDelay` | `3000` | Delay between reconnects (ms) |
+| `maxReconnectAttempts` | `10` | Max reconnect attempts |
+| `shared` | `false` | Share across browser tabs |
+| `token` | `true` | Send CSRF token |
+
+### Client Methods
+
+| Method | Description |
+|--------|-------------|
+| `ws.send(data)` | Send data to server |
+| `ws.close()` | Close connection |
+| `ws.on(event, handler)` | Add event listener |
+| `ws.off(event, handler)` | Remove event listener |
+
+### Client Properties
+
+| Property | Description |
+|----------|-------------|
+| `ws.connected` | Connection status (boolean) |
+| `ws.state` | WebSocket state |
+
+### Events
+
+| Event | Description |
+|-------|-------------|
+| `open` | Connection opened |
+| `message` | Message received |
+| `close` | Connection closed |
+| `error` | Error occurred |
+
+## Common Patterns
+
+### Echo Server
+```javascript
+// With token (default)
+Odac.Route.ws('/echo', Odac => {
+  Odac.ws.on('message', data => Odac.ws.send(data))
+})
+
+// Public (no token)
+Odac.Route.ws('/public-echo', Odac => {
+  Odac.ws.on('message', data => Odac.ws.send(data))
+}, {token: false})
+```
+
+### Authenticated Route
+```javascript
+// Using auth.ws() (recommended)
+Odac.Route.auth.ws('/secure', async Odac => {
+  const user = await Odac.Auth.user()
+  // Handle connection
+})
+
+// Manual check
+Odac.Route.ws('/secure', async Odac => {
+  if (!await Odac.Auth.check()) {
+    return Odac.ws.close(4001, 'Unauthorized')
+  }
+  // Handle connection
+})
+```
+
+### With Middleware
+```javascript
+Odac.Route.use('auth', 'rate-limit').ws('/chat', Odac => {
+  Odac.ws.send({type: 'welcome'})
+})
+```
+
+### Room Broadcasting
+```javascript
+Odac.Route.ws('/chat', Odac => {
+  Odac.ws.join('room-1')
+  Odac.ws.on('message', data => {
+    Odac.ws.to('room-1').send(data)
+  })
+})
+```
+
+### URL Parameters
+```javascript
+Odac.Route.ws('/room/{id}', Odac => {
+  const {id} = Odac.Request.data.url
+  Odac.ws.join(id)
+})
+```
+
+### Shared Connection (Client)
+```javascript
+const ws = Odac.ws('/chat', {shared: true})
+// All tabs share one connection
+```
+
+## Status Codes
+
+| Code | Description |
+|------|-------------|
+| `1000` | Normal closure |
+| `1001` | Going away |
+| `1002` | Protocol error |
+| `1003` | Unsupported data |
+| `1006` | Abnormal closure |
+| `4000` | Middleware rejected |
+| `4001` | Unauthorized |
+| `4002` | Invalid/missing token |
+| `4003` | Forbidden (middleware) |
+
+## Best Practices
+
+1. **Always handle authentication**
+   ```javascript
+   if (!await Odac.Auth.check()) {
+     return Odac.ws.close(4001, 'Unauthorized')
+   }
+   ```
+
+2. **Use rooms for targeted messaging**
+   ```javascript
+   Odac.ws.join(`user-${userId}`)
+   ```
+
+3. **Clean up on close**
+   ```javascript
+   Odac.ws.on('close', () => {
+     clearInterval(interval)
+     Odac.ws.leave('room')
+   })
+   ```
+
+4. **Store per-connection data**
+   ```javascript
+   Odac.ws.data.userId = user.id
+   Odac.ws.data.joinedAt = Date.now()
+   ```
+
+5. **Use shared connections for notifications**
+   ```javascript
+   const ws = Odac.ws('/notifications', {shared: true})
+   ```