[Backlog] WebSocket Handler Support

[sazardev]

Overview

Implement WebSocket handler support to enable real-time bidirectional communication in Goca-generated applications while maintaining Clean Architecture separation.

Background

Many modern applications require real-time features such as chat, notifications, live updates, and collaborative editing. WebSocket support will enable these use cases while maintaining architectural integrity.

Scope

In Scope

• WebSocket server generation
• WebSocket handler generation
• Connection management
• Message routing
• Room/channel support
• Authentication integration
• Heartbeat and reconnection
• Message validation

Out of Scope

• WebSocket clustering and scaling
• Message persistence
• Complex pub/sub patterns
• WebRTC support

Requirements

Functional Requirements

• Generate WebSocket server setup
• Create WebSocket handlers
• Implement connection lifecycle management
• Support message routing
• Enable room-based broadcasting
• Integrate with existing authentication
• Validate incoming messages
• Generate client connection examples

Non-Functional Requirements

• Support thousands of concurrent connections
• Low latency message delivery
• Graceful connection handling
• Memory efficient
• Clean Architecture compliance

Technical Design

Handler Structure

type UserWebSocketHandler struct {
    usecase usecase.UserUseCase
    hub     *WebSocketHub
}

func (h *UserWebSocketHandler) HandleConnection(conn *websocket.Conn) {
    client := &Client{
        hub:  h.hub,
        conn: conn,
        send: make(chan []byte, 256),
    }
    
    client.hub.register <- client
    
    go client.writePump()
    go client.readPump()
}

func (h *UserWebSocketHandler) HandleMessage(msg Message) error {
    switch msg.Type {
    case "user.create":
        return h.handleUserCreate(msg)
    case "user.update":
        return h.handleUserUpdate(msg)
    }
    return nil
}

Hub Structure

type WebSocketHub struct {
    clients    map[*Client]bool
    broadcast  chan []byte
    register   chan *Client
    unregister chan *Client
    rooms      map[string]map[*Client]bool
}

func (h *WebSocketHub) Run() {
    for {
        select {
        case client := <-h.register:
            h.clients[client] = true
        case client := <-h.unregister:
            if _, ok := h.clients[client]; ok {
                delete(h.clients, client)
                close(client.send)
            }
        case message := <-h.broadcast:
            for client := range h.clients {
                select {
                case client.send <- message:
                default:
                    close(client.send)
                    delete(h.clients, client)
                }
            }
        }
    }
}

Message Protocol

{
  "type": "user.create",
  "id": "unique-message-id",
  "timestamp": "2026-01-01T00:00:00Z",
  "data": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Implementation Plan

Phase 1: Core WebSocket Support

• Implement WebSocket server
• Create handler templates
• Add connection management

Phase 2: Advanced Features

• Implement room support
• Add message routing
• Create authentication integration

Phase 3: Integration

• Add to handler generation
• Create WebSocket-specific commands
• Update documentation

CLI Usage

goca feature User --handler websocket
goca handler User --type websocket --rooms

Acceptance Criteria

• WebSocket handlers generated correctly
• Connections managed properly
• Messages routed correctly
• Room-based broadcasting works
• Authentication integrated
• Client examples provided
• Documentation includes WebSocket guide
• Performance tests show scalability
• Examples demonstrate common patterns

Priority and Classification

Priority: Medium-High
Category: Feature Enhancement
Section: Code Generation
Release Target: Backlog (Post v2.0.0)
Estimated Effort: 3-4 weeks
Complexity: Medium-High
Dependencies: Handler generation system

Related Issues

• Complements REST and gRPC support
• Enables real-time applications
• Part of multi-protocol support strategy

Additional Notes

WebSocket support will enable Goca-generated applications to handle real-time use cases while maintaining architectural integrity and scalability.