websocket-relay/.agents/summary/data_models.md

Data Models

Configuration Model

classDiagram
    class Config {
        +Server ServerConfig
        +Metrics MetricsConfig
    }
    class ServerConfig {
        +int Port
        +TLSConfig TLS
    }
    class TLSConfig {
        +bool Enabled
        +string CertFile
        +string KeyFile
    }
    class MetricsConfig {
        +bool Enabled
        +int Port
    }

    Config --> ServerConfig
    Config --> MetricsConfig
    ServerConfig --> TLSConfig

Config Struct Definition

type Config struct {
    Server struct {
        Port int    `yaml:"port"`
        TLS  struct {
            Enabled  bool   `yaml:"enabled"`
            CertFile string `yaml:"cert_file"`
            KeyFile  string `yaml:"key_file"`
        } `yaml:"tls"`
    } `yaml:"server"`
    Metrics struct {
        Enabled bool `yaml:"enabled"`
        Port    int  `yaml:"port"`
    } `yaml:"metrics"`
}

Default Configuration Values

Field	Default	Notes
server.port	8443	Standard alternate HTTPS port
server.tls.enabled	false (config.yaml) / true (example)	Toggle TLS
server.tls.cert_file	cert.pem	Relative to working directory
server.tls.key_file	key.pem	Relative to working directory
metrics.enabled	true	Prometheus metrics
metrics.port	9090	Standard Prometheus port

---

Hub State Model

classDiagram
    class Hub {
        -map~*websocket.Conn, bool~ clients
        -chan []byte broadcast
        -chan *websocket.Conn register
        -chan *websocket.Conn unregister
        -sync.RWMutex mu
        +New() Hub
        +Run()
        +HandleWebSocket(w, r)
        +ClientCount() int
    }

Channel Types

Channel	Direction	Payload	Buffer
register	Handler → Hub	*websocket.Conn	Unbuffered
unregister	Reader → Hub	*websocket.Conn	Unbuffered
broadcast	Reader → Hub	[]byte	Unbuffered

---

Message Model

The relay server does not impose any message structure. Messages are raw []byte payloads passed through as WebSocket text frames.

graph LR
    A[Client A sends bytes] --> B[Hub broadcast channel]
    B --> C[Written as TextMessage to all clients]

The example HTML client uses an informal format:

{name}<br>{message_text}

But this is purely client-side convention — the server is format-agnostic.

---

Metrics Model

classDiagram
    class PrometheusMetrics {
        +Gauge ConnectedClients
        +Gauge MessagesTotal
        +Gauge ConnectionsTotal
        +Gauge DisconnectionsTotal
    }

Metric	Update Trigger
ConnectedClients	Set on register/unregister (absolute count)
MessagesTotal	Incremented on each broadcast
ConnectionsTotal	Incremented on register
DisconnectionsTotal	Incremented on unregister

---

Connection State Machine

stateDiagram-v2
    [*] --> Connecting: HTTP request to /
    Connecting --> Connected: WebSocket upgrade success
    Connecting --> Failed: Upgrade error
    Connected --> Active: Registered in Hub
    Active --> Active: Sending/Receiving messages
    Active --> Disconnecting: Read error or client close
    Disconnecting --> Closed: Unregistered from Hub
    Failed --> [*]
    Closed --> [*]