gufi-cli 0.1.50 → 0.1.52

package/docs/dev-guide/2-04-realtime.md

@@ -0,0 +1,401 @@
+---
+id: realtime
+title: "Real-Time & WebSocket"
+description: "Live updates with PostgreSQL LISTEN/NOTIFY"
+icon: Wifi
+category: dev
+part: 2
+---
+
+# Real-Time & WebSocket
+
+Live updates with PostgreSQL LISTEN/NOTIFY
+
+## Architecture
+
+Gufi uses PostgreSQL's LISTEN/NOTIFY for real-time updates, providing reliable, database-level event propagation.
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    Real-Time System                          │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐ │
+│  │   Database   │     │   WebSocket  │     │   Clients    │ │
+│  │   Trigger    │────▶│    Server    │────▶│   (React)    │ │
+│  │   + NOTIFY   │     │    :4000     │     │              │ │
+│  └──────────────┘     └──────────────┘     └──────────────┘ │
+│                                                              │
+│  INSERT/UPDATE/DELETE                                        │
+│         │                                                    │
+│         ▼                                                    │
+│  pg_notify('company_146_m360_t4589', '{"type":"INSERT"...}') │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## How It Works
+
+### Database Triggers
+
+When data changes, triggers fire NOTIFY:
+
+```sql
+-- Trigger function (created automatically)
+CREATE FUNCTION notify_table_change() RETURNS TRIGGER AS $$
+BEGIN
+  PERFORM pg_notify(
+    'company_' || current_setting('app.company_id') || '_' || TG_TABLE_NAME,
+    json_build_object(
+      'type', TG_OP,
+      'table', TG_TABLE_NAME,
+      'id', COALESCE(NEW.id, OLD.id),
+      'data', CASE TG_OP
+        WHEN 'DELETE' THEN row_to_json(OLD)
+        ELSE row_to_json(NEW)
+      END
+    )::text
+  );
+  RETURN COALESCE(NEW, OLD);
+END;
+$$ LANGUAGE plpgsql;
+```
+
+### WebSocket Server
+
+Listens to PostgreSQL channels and broadcasts:
+
+```javascript
+// Simplified WebSocket server logic
+const pg = require('pg');
+const WebSocket = require('ws');
+
+// Listen to all company channels
+const listenClient = new pg.Client();
+await listenClient.connect();
+
+// Subscribe to channels dynamically
+async function subscribeToCompany(companyId, tableId) {
+  const channel = `company_${companyId}_${tableId}`;
+  await listenClient.query(`LISTEN ${channel}`);
+}
+
+// Handle notifications
+listenClient.on('notification', (msg) => {
+  const data = JSON.parse(msg.payload);
+  const [, companyId, tableId] = msg.channel.split('_');
+
+  // Broadcast to subscribed clients
+  broadcast(companyId, tableId, data);
+});
+```
+
+### Client Connection
+
+```typescript
+// React hook for WebSocket
+import { useWebSocket } from '@/contexts/WebSocketContext';
+
+function MyComponent() {
+  const { subscribe, isConnected } = useWebSocket();
+
+  useEffect(() => {
+    const unsubscribe = subscribe('m360_t4589', (event) => {
+      if (event.type === 'INSERT') {
+        // New record created
+        refetch();
+      } else if (event.type === 'UPDATE') {
+        // Record updated
+        updateLocalCache(event.id, event.data);
+      } else if (event.type === 'DELETE') {
+        // Record deleted
+        removeFromCache(event.id);
+      }
+    });
+
+    return () => unsubscribe();
+  }, []);
+}
+```
+
+## Using Real-Time in Views
+
+### Basic Subscription
+
+```typescript
+export default function MyView({ gufi }: Props) {
+  const { websocket, context } = gufi;
+  const [records, setRecords] = useState([]);
+
+  useEffect(() => {
+    const tableId = context.viewSpec?.ordersTable;
+    if (!tableId) return;
+
+    const unsubscribe = websocket.subscribeToTable(tableId, (event) => {
+      switch (event.type) {
+        case 'INSERT':
+          setRecords(prev => [...prev, event.data]);
+          break;
+        case 'UPDATE':
+          setRecords(prev =>
+            prev.map(r => r.id === event.id ? event.data : r)
+          );
+          break;
+        case 'DELETE':
+          setRecords(prev =>
+            prev.filter(r => r.id !== event.id)
+          );
+          break;
+      }
+    });
+
+    return () => unsubscribe();
+  }, [context.viewSpec?.ordersTable]);
+
+  return <RecordsList records={records} />;
+}
+```
+
+### With SDK Hook
+
+```typescript
+const { data, loading, refetch } = useViewData({
+  gufi,
+  tableKey: 'ordersTable',
+  realtime: true // Enable auto-refresh on changes
+});
+```
+
+## Event Types
+
+### INSERT
+
+```json
+{
+  "type": "INSERT",
+  "table": "m360_t4589",
+  "id": 123,
+  "data": {
+    "id": 123,
+    "name": "New Product",
+    "price": 99.99,
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+### UPDATE
+
+```json
+{
+  "type": "UPDATE",
+  "table": "m360_t4589",
+  "id": 123,
+  "data": {
+    "id": 123,
+    "name": "Updated Product",
+    "price": 89.99,
+    "updated_at": "2024-01-15T11:00:00Z"
+  }
+}
+```
+
+### DELETE
+
+```json
+{
+  "type": "DELETE",
+  "table": "m360_t4589",
+  "id": 123,
+  "data": {
+    "id": 123,
+    "name": "Deleted Product"
+  }
+}
+```
+
+## Broadcasting Custom Events
+
+### From Views
+
+```typescript
+// Broadcast to other users viewing the same view
+websocket.broadcastToView('selection-changed', {
+  selectedIds: [1, 2, 3]
+});
+
+// Listen for broadcasts
+websocket.onViewBroadcast('selection-changed', (data) => {
+  console.log('Another user selected:', data.selectedIds);
+});
+```
+
+### From Backend
+
+```javascript
+// Send custom notification
+const notifyClients = async (companyId, event) => {
+  await pool.query(
+    `SELECT pg_notify($1, $2)`,
+    [`company_${companyId}_custom`, JSON.stringify(event)]
+  );
+};
+```
+
+## Connection Management
+
+### Connection Status
+
+```typescript
+const { isConnected, reconnect } = useWebSocket();
+
+if (!isConnected) {
+  return (
+    <div className="text-yellow-600">
+      <AlertCircle /> Connection lost. Reconnecting...
+      <button onClick={reconnect}>Retry Now</button>
+    </div>
+  );
+}
+```
+
+### Automatic Reconnection
+
+WebSocket client handles:
+
+- Automatic reconnection on disconnect
+- Exponential backoff (1s, 2s, 4s, 8s...)
+- Re-subscription to channels after reconnect
+- Heartbeat every 30 seconds
+
+### Manual Subscription Management
+
+```typescript
+// Subscribe to multiple tables
+const subscriptions = [
+  websocket.subscribeToTable(ordersTable, handleOrders),
+  websocket.subscribeToTable(productsTable, handleProducts),
+];
+
+// Cleanup
+return () => {
+  subscriptions.forEach(unsub => unsub());
+};
+```
+
+## Performance Considerations
+
+### Debouncing Updates
+
+For high-frequency changes:
+
+```typescript
+const [debouncedData, setDebouncedData] = useState(data);
+
+useEffect(() => {
+  const timer = setTimeout(() => {
+    setDebouncedData(data);
+  }, 100); // 100ms debounce
+
+  return () => clearTimeout(timer);
+}, [data]);
+```
+
+### Selective Subscriptions
+
+Only subscribe to what you need:
+
+```typescript
+// Good: Subscribe to specific table
+websocket.subscribeToTable(ordersTable, callback);
+
+// Avoid: Don't subscribe to everything
+// websocket.subscribeToAll(callback);
+```
+
+### Batching Updates
+
+```typescript
+const pendingUpdates = useRef([]);
+
+useEffect(() => {
+  const processBatch = setInterval(() => {
+    if (pendingUpdates.current.length > 0) {
+      setRecords(prev => [...prev, ...pendingUpdates.current]);
+      pendingUpdates.current = [];
+    }
+  }, 500);
+
+  return () => clearInterval(processBatch);
+}, []);
+
+// In websocket handler
+const handleEvent = (event) => {
+  pendingUpdates.current.push(event.data);
+};
+```
+
+## Scaling
+
+### Redis Pub/Sub
+
+For horizontal scaling (multiple WebSocket servers):
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  WS Server  │     │  WS Server  │     │  WS Server  │
+│     #1      │     │     #2      │     │     #3      │
+└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
+       │                   │                   │
+       └───────────────────┼───────────────────┘
+                           │
+                    ┌──────▼──────┐
+                    │    Redis    │
+                    │   Pub/Sub   │
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │ PostgreSQL  │
+                    │   NOTIFY    │
+                    └─────────────┘
+```
+
+### Configuration
+
+```javascript
+// WebSocket server with Redis
+const Redis = require('ioredis');
+const redis = new Redis(process.env.REDIS_URL);
+
+// Publish to all servers
+redis.publish('gufi:events', JSON.stringify(event));
+
+// Subscribe on each server
+redis.subscribe('gufi:events');
+redis.on('message', (channel, message) => {
+  broadcastToLocalClients(JSON.parse(message));
+});
+```
+
+## Troubleshooting
+
+### No Updates Received
+
+1. Check WebSocket connection status
+2. Verify table triggers exist
+3. Check channel name matches
+4. Look for errors in browser console
+
+### Delayed Updates
+
+1. Check PostgreSQL connection
+2. Monitor WebSocket server logs
+3. Verify network latency
+4. Check for batching/debouncing
+
+### Memory Issues
+
+1. Ensure subscriptions are cleaned up
+2. Check for memory leaks in callbacks
+3. Monitor connection count
+4. Use pagination for large datasets