ws

gopilot:ws — Add WebSocket Support

You are adding WebSocket support for real-time features. The backend manages a hub with rooms/subscriptions, and the frontend gets a typed client.

Before Starting

1. Read skills/_shared/go-patterns.md for conventions
2. Check if WebSocket hub already exists at backend/internal/ws/

Phase 1: WebSocket Hub (if not exists)

Create backend/internal/ws/:

hub.go

package ws

import "sync"

type Hub struct {
    mu          sync.RWMutex
    clients     map[string]*Client       // connID -> client
    rooms       map[string]map[string]*Client // roomID -> connID -> client
}

func NewHub() *Hub { ... }
func (h *Hub) Register(client *Client) { ... }
func (h *Hub) Unregister(client *Client) { ... }
func (h *Hub) Subscribe(client *Client, room string) { ... }
func (h *Hub) Unsubscribe(client *Client, room string) { ... }
func (h *Hub) Broadcast(room string, msg []byte) { ... }
func (h *Hub) SendTo(connID string, msg []byte) { ... }

client.go

package ws

import "github.com/gorilla/websocket"

type Client struct {
    ID     string
    UserID string
    Conn   *websocket.Conn
    Hub    *Hub
    Send   chan []byte
}

func (c *Client) ReadPump() { ... }  // reads from WS, routes to handler
func (c *Client) WritePump() { ... } // writes from Send channel to WS

messages.go — Typed Protocol

package ws

type MessageType string

const (
    // Client → Server
    MsgSubscribe   MessageType = "subscribe"
    MsgUnsubscribe MessageType = "unsubscribe"
    // Add feature-specific message types here
)

type IncomingMessage struct {
    Type    MessageType     `json:"type"`
    Payload json.RawMessage `json:"payload"`
}

type OutgoingMessage struct {
    Type    MessageType `json:"type"`
    Payload interface{} `json:"payload"`
}

Phase 2: Register WebSocket Endpoint

In backend/internal/api/router.go, add:

hub := ws.NewHub()
r.Get("/ws", handleWebSocket(hub))

Tag WebSocket operations in Huma for OpenAPI generation so the SDK generator can create typed clients.

Phase 3: Frontend WebSocket Client

The SDK generator will handle this via /gopilot:sdk. The generated client will have:

• Typed send*() methods matching server message types
• Typed on*() handlers matching server broadcast types
• Auto-reconnect with exponential backoff
• Room subscription management

What NOT to Do

• Do NOT use raw string message types — always typed constants
• Do NOT skip the hub pattern — direct connection management doesn't scale
• Do NOT put business logic in WebSocket handlers — call services