javi-forge 0.1.0

package/ai-config/skills/backend/websockets/SKILL.md

@@ -0,0 +1,532 @@
+---
+name: websockets
+description: >
+  WebSocket real-time communication patterns for Go and TypeScript.
+  Trigger: websocket, real-time, pubsub, hub pattern, live updates
+tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+metadata:
+  author: plataforma-industrial
+  version: "2.0"
+  tags: [websocket, realtime, go, typescript, pubsub]
+  language: go
+  updated: "2026-02"
+---
+
+# WebSockets
+
+> Real-time bidirectional communication with Hub pattern
+
+## When to Use
+
+- [ ] Building live dashboards with real-time updates
+- [ ] Implementing chat or notification systems
+- [ ] Streaming sensor data to web clients
+- [ ] Push updates without polling
+
+## Stack
+
+```yaml
+# Go Server
+gorilla/websocket: "1.5+"
+nhooyr.io/websocket: "1.8+"
+
+# TypeScript Client
+Native WebSocket API
+@tanstack/react-query (for cache sync)
+
+# Rust
+tokio-tungstenite: "0.21+"
+```
+
+## Go Server - Hub Pattern
+
+### Hub Structure
+
+```go
+package ws
+
+import (
+    "encoding/json"
+    "sync"
+    "time"
+
+    "github.com/gorilla/websocket"
+)
+
+const (
+    writeWait      = 10 * time.Second
+    pongWait       = 60 * time.Second
+    pingPeriod     = (pongWait * 9) / 10
+    maxMessageSize = 512 * 1024
+)
+
+type Message struct {
+    Type    string          `json:"type"`
+    Payload json.RawMessage `json:"payload"`
+}
+
+type Client struct {
+    hub      *Hub
+    conn     *websocket.Conn
+    send     chan []byte
+    tenantID string
+    userID   string
+    rooms    map[string]bool
+    mu       sync.RWMutex
+}
+
+type Hub struct {
+    clients    map[*Client]bool
+    byTenant   map[string]map[*Client]bool
+    byRoom     map[string]map[*Client]bool
+    register   chan *Client
+    unregister chan *Client
+    broadcast  chan BroadcastMessage
+    mu         sync.RWMutex
+}
+
+type BroadcastMessage struct {
+    TenantID string
+    Room     string
+    Data     []byte
+}
+
+func NewHub() *Hub {
+    return &Hub{
+        clients:    make(map[*Client]bool),
+        byTenant:   make(map[string]map[*Client]bool),
+        byRoom:     make(map[string]map[*Client]bool),
+        register:   make(chan *Client),
+        unregister: make(chan *Client),
+        broadcast:  make(chan BroadcastMessage, 256),
+    }
+}
+```
+
+### Hub Run Loop
+
+```go
+func (h *Hub) Run(ctx context.Context) {
+    for {
+        select {
+        case <-ctx.Done():
+            return
+
+        case client := <-h.register:
+            h.mu.Lock()
+            h.clients[client] = true
+            if h.byTenant[client.tenantID] == nil {
+                h.byTenant[client.tenantID] = make(map[*Client]bool)
+            }
+            h.byTenant[client.tenantID][client] = true
+            h.mu.Unlock()
+
+        case client := <-h.unregister:
+            h.mu.Lock()
+            if _, ok := h.clients[client]; ok {
+                delete(h.clients, client)
+                delete(h.byTenant[client.tenantID], client)
+                for room := range client.rooms {
+                    delete(h.byRoom[room], client)
+                }
+                close(client.send)
+            }
+            h.mu.Unlock()
+
+        case msg := <-h.broadcast:
+            h.mu.RLock()
+            var targets map[*Client]bool
+            if msg.Room != "" {
+                targets = h.byRoom[msg.Room]
+            } else {
+                targets = h.byTenant[msg.TenantID]
+            }
+            for client := range targets {
+                select {
+                case client.send <- msg.Data:
+                default:
+                    close(client.send)
+                    delete(h.clients, client)
+                }
+            }
+            h.mu.RUnlock()
+        }
+    }
+}
+```
+
+### Room Management
+
+```go
+func (h *Hub) JoinRoom(client *Client, room string) {
+    h.mu.Lock()
+    defer h.mu.Unlock()
+
+    if h.byRoom[room] == nil {
+        h.byRoom[room] = make(map[*Client]bool)
+    }
+    h.byRoom[room][client] = true
+
+    client.mu.Lock()
+    client.rooms[room] = true
+    client.mu.Unlock()
+}
+
+func (h *Hub) BroadcastToRoom(room string, msgType string, payload interface{}) error {
+    data, err := json.Marshal(Message{Type: msgType, Payload: mustMarshal(payload)})
+    if err != nil { return err }
+
+    h.broadcast <- BroadcastMessage{Room: room, Data: data}
+    return nil
+}
+```
+
+### Client Read/Write Pumps
+
+```go
+func (c *Client) readPump() {
+    defer func() {
+        c.hub.unregister <- c
+        c.conn.Close()
+    }()
+
+    c.conn.SetReadLimit(maxMessageSize)
+    c.conn.SetReadDeadline(time.Now().Add(pongWait))
+    c.conn.SetPongHandler(func(string) error {
+        c.conn.SetReadDeadline(time.Now().Add(pongWait))
+        return nil
+    })
+
+    for {
+        _, message, err := c.conn.ReadMessage()
+        if err != nil { break }
+        c.handleMessage(message)
+    }
+}
+
+func (c *Client) writePump() {
+    ticker := time.NewTicker(pingPeriod)
+    defer func() {
+        ticker.Stop()
+        c.conn.Close()
+    }()
+
+    for {
+        select {
+        case message, ok := <-c.send:
+            c.conn.SetWriteDeadline(time.Now().Add(writeWait))
+            if !ok {
+                c.conn.WriteMessage(websocket.CloseMessage, []byte{})
+                return
+            }
+            w, _ := c.conn.NextWriter(websocket.TextMessage)
+            w.Write(message)
+            // Coalesce queued messages
+            for i := 0; i < len(c.send); i++ {
+                w.Write([]byte{'\n'})
+                w.Write(<-c.send)
+            }
+            w.Close()
+
+        case <-ticker.C:
+            c.conn.SetWriteDeadline(time.Now().Add(writeWait))
+            c.conn.WriteMessage(websocket.PingMessage, nil)
+        }
+    }
+}
+```
+
+### HTTP Upgrade Handler
+
+```go
+var upgrader = websocket.Upgrader{
+    ReadBufferSize:  1024,
+    WriteBufferSize: 1024,
+    CheckOrigin: func(r *http.Request) bool {
+        origin := r.Header.Get("Origin")
+        return origin == "https://app.example.com" || origin == "http://localhost:4321"
+    },
+}
+
+func (h *Hub) HandleWebSocket(w http.ResponseWriter, r *http.Request) {
+    tenantID := r.Context().Value("tenant_id").(string)
+    userID := r.Context().Value("user_id").(string)
+
+    conn, err := upgrader.Upgrade(w, r, nil)
+    if err != nil { return }
+
+    client := &Client{
+        hub:      h,
+        conn:     conn,
+        send:     make(chan []byte, 256),
+        tenantID: tenantID,
+        userID:   userID,
+        rooms:    make(map[string]bool),
+    }
+
+    h.register <- client
+    go client.writePump()
+    go client.readPump()
+}
+```
+
+## TypeScript Client
+
+### WebSocket Hook
+
+```typescript
+import { useEffect, useRef, useState, useCallback } from 'react';
+
+interface WebSocketMessage<T = unknown> {
+  type: string;
+  payload: T;
+}
+
+export function useWebSocket(options: {
+  onMessage?: (msg: WebSocketMessage) => void;
+  onConnect?: () => void;
+  reconnect?: boolean;
+} = {}) {
+  const { onMessage, onConnect, reconnect = true } = options;
+  const ws = useRef<WebSocket | null>(null);
+  const [isConnected, setIsConnected] = useState(false);
+
+  const connect = useCallback(() => {
+    if (ws.current?.readyState === WebSocket.OPEN) return;
+
+    ws.current = new WebSocket(import.meta.env.PUBLIC_WS_URL);
+
+    ws.current.onopen = () => {
+      setIsConnected(true);
+      onConnect?.();
+    };
+
+    ws.current.onclose = () => {
+      setIsConnected(false);
+      if (reconnect) setTimeout(connect, 3000);
+    };
+
+    ws.current.onmessage = (event) => {
+      const message = JSON.parse(event.data);
+      onMessage?.(message);
+    };
+  }, [onMessage, onConnect, reconnect]);
+
+  const send = useCallback((type: string, payload: unknown) => {
+    if (ws.current?.readyState === WebSocket.OPEN) {
+      ws.current.send(JSON.stringify({ type, payload }));
+    }
+  }, []);
+
+  const subscribe = useCallback((room: string) => send('subscribe', { room }), [send]);
+  const unsubscribe = useCallback((room: string) => send('unsubscribe', { room }), [send]);
+
+  useEffect(() => {
+    connect();
+    return () => ws.current?.close();
+  }, [connect]);
+
+  return { isConnected, send, subscribe, unsubscribe };
+}
+```
+
+### React Query Integration
+
+```typescript
+import { useQueryClient } from '@tanstack/react-query';
+import { useWebSocket } from './useWebSocket';
+
+interface SensorReading {
+  sensorId: string;
+  value: number;
+  timestamp: number;
+}
+
+export function useRealtimeSensors(sensorIds: string[]) {
+  const queryClient = useQueryClient();
+
+  const handleMessage = useCallback((msg: { type: string; payload: unknown }) => {
+    if (msg.type === 'sensor.reading') {
+      const reading = msg.payload as SensorReading;
+
+      // Update individual sensor cache
+      queryClient.setQueryData(['sensor', reading.sensorId, 'latest'], reading);
+
+      // Update list cache
+      queryClient.setQueryData<SensorReading[]>(['sensors', 'latest'], (old) => {
+        if (!old) return [reading];
+        const index = old.findIndex((r) => r.sensorId === reading.sensorId);
+        if (index >= 0) {
+          const updated = [...old];
+          updated[index] = reading;
+          return updated;
+        }
+        return [...old, reading];
+      });
+    }
+  }, [queryClient]);
+
+  const { isConnected, subscribe, unsubscribe } = useWebSocket({
+    onMessage: handleMessage,
+    onConnect: () => sensorIds.forEach((id) => subscribe(`sensor:${id}`)),
+  });
+
+  useEffect(() => {
+    if (isConnected) sensorIds.forEach((id) => subscribe(`sensor:${id}`));
+    return () => sensorIds.forEach((id) => unsubscribe(`sensor:${id}`));
+  }, [sensorIds, isConnected]);
+
+  return { isConnected };
+}
+```
+
+## Reconnection with Exponential Backoff
+
+```typescript
+class ReconnectingWebSocket {
+  private ws: WebSocket | null = null;
+  private reconnectAttempts = 0;
+  private maxAttempts = 10;
+  private heartbeatInterval: NodeJS.Timeout | null = null;
+  private missedHeartbeats = 0;
+
+  constructor(
+    private url: string,
+    private onMessage: (data: unknown) => void,
+    private onStateChange: (connected: boolean) => void
+  ) {
+    this.connect();
+  }
+
+  private connect() {
+    this.ws = new WebSocket(this.url);
+
+    this.ws.onopen = () => {
+      this.reconnectAttempts = 0;
+      this.missedHeartbeats = 0;
+      this.onStateChange(true);
+      this.startHeartbeat();
+    };
+
+    this.ws.onclose = () => {
+      this.onStateChange(false);
+      this.stopHeartbeat();
+      this.scheduleReconnect();
+    };
+
+    this.ws.onmessage = (event) => {
+      const data = JSON.parse(event.data);
+      if (data.type === 'pong') {
+        this.missedHeartbeats = 0;
+        return;
+      }
+      this.onMessage(data);
+    };
+  }
+
+  private startHeartbeat() {
+    this.heartbeatInterval = setInterval(() => {
+      if (this.missedHeartbeats >= 3) {
+        this.ws?.close();
+        return;
+      }
+      this.ws?.send(JSON.stringify({ type: 'ping' }));
+      this.missedHeartbeats++;
+    }, 30000);
+  }
+
+  private scheduleReconnect() {
+    if (this.reconnectAttempts >= this.maxAttempts) return;
+
+    const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30000);
+    this.reconnectAttempts++;
+    setTimeout(() => this.connect(), delay);
+  }
+}
+```
+
+## Best Practices
+
+### Use Rooms for Targeted Broadcasts
+
+```go
+// ✅ Send only to interested clients
+hub.BroadcastToRoom("sensor:temp-1", "reading", reading)
+
+// ❌ Broadcast to everyone
+hub.BroadcastToTenant(tenantID, "reading", reading)
+```
+
+### Implement Heartbeats
+
+```typescript
+// Detect stale connections
+setInterval(() => ws.send(JSON.stringify({ type: 'ping' })), 30000);
+```
+
+### Coalesce Messages
+
+```go
+// Combine pending messages in single write
+n := len(c.send)
+for i := 0; i < n; i++ {
+    w.Write(<-c.send)
+}
+```
+
+### Exponential Backoff
+
+```typescript
+const delay = Math.min(1000 * Math.pow(2, attempts), 30000);
+```
+
+## Quick Reference
+
+| Task | Go Server |
+|------|-----------|
+| Create hub | `hub := NewHub()` |
+| Run hub | `go hub.Run(ctx)` |
+| Join room | `hub.JoinRoom(client, "room")` |
+| Broadcast | `hub.BroadcastToRoom("room", "type", data)` |
+| Upgrade | `upgrader.Upgrade(w, r, nil)` |
+
+| Task | TypeScript Client |
+|------|-------------------|
+| Connect | `new WebSocket(url)` |
+| Send | `ws.send(JSON.stringify(msg))` |
+| Subscribe | `send('subscribe', { room })` |
+| Close | `ws.close()` |
+
+## Message Protocol
+
+```json
+// Subscribe to room
+{"type": "subscribe", "payload": {"room": "sensor:temp-1"}}
+
+// Unsubscribe
+{"type": "unsubscribe", "payload": {"room": "sensor:temp-1"}}
+
+// Heartbeat
+{"type": "ping"}
+{"type": "pong"}
+
+// Data message
+{"type": "sensor.reading", "payload": {"sensorId": "temp-1", "value": 25.5}}
+```
+
+## Resources
+
+- [gorilla/websocket](https://github.com/gorilla/websocket)
+- [MDN WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+- [RFC 6455 WebSocket Protocol](https://tools.ietf.org/html/rfc6455)
+
+## Related Skills
+
+- `tokio-async`: Async WebSocket handling
+- `chi-router`: Go WebSocket integration
+- `fastapi`: Python WebSocket endpoints
+- `mqtt-rumqttc`: IoT data streaming