# enkeyz/websocket architecture

> Architecture diagram of the GitHub repository enkeyz/websocket, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/enkeyz/websocket
- Repository: https://github.com/enkeyz/websocket

## Overview

##### Project Type and Purpose
- Type: A Go-language library implementing RFC-6455 (WebSocket protocol).
- Purpose: Provide API primitives (Dialer, Upgrader, Conn, etc.) to establish, read from, and write to WebSocket connections, with full support for masking, fragmentation, compression, and control frames.

##### File Structure
- Top‐level Go source files define core functionality:
– client.go, server.go: APIs for client and server side.
– conn.go / conn_*.go: Core Conn struct, read/write loops, and broadcast support.
– compression.go: permessage-deflate compression negotiation and implementation.
– mask.go / mask_safe.go: Masking/unmasking of client-to-server payloads.
– prepared.go: PreparedMessage support for efficient frame reuse.
– proxy.go / x_net_proxy.go: Optional proxy support.
– tls_handshake.go: TLS handshake wrappers.
– json.go, util.go, join.go: Helpers for JSON messaging and utility functions.
- examples/: sample applications (chat, echo, command, filewatch, Autobahn test client), showing how consumers embed the library.

##### README Insights
- Confirms compliance with Autobahn Test Suite (via examples/autobahn).
- Emphasizes stable API, full protocol coverage, and use cases (chat, echo, filewatch, etc.).

##### Main Components and Their Relationships
A. Application Layer
– User application code (examples/chat/main.go, examples/echo/server.go, etc.)
– Calls into the library’s public APIs: Dialer (client) or Upgrader (HTTP server).
B. API Layer
– Dialer: establishes outbound WebSocket connections over TCP/TLS.
– Upgrader: performs HTTP handshake to upgrade inbound HTTP requests to WebSockets.
C. Connection Layer (Conn abstraction)
– Conn struct: maintains the underlying net.Conn, read/write pumps, close/error handling, broadcasting.
– PreparedMessage: optional pre-encoded frames for perf.
D. Frame Processing Subsystem
– Frame Encoder/Decoder: splits and merges messages into frames, handles fragmentation.
– Masking Module: applies or removes client-side masking (mask.go).
– Compression Module: negotiates and applies permessage-deflate (compression.go).
E. Transport & Protocol Layer
– Underlying net.Conn (TCP).
– Optional TLS handshake (tls_handshake.go).
– Optional Proxy layer (proxy.go, x_net_proxy.go).
F. External Dependencies & Tests
– HTTP package (net/http) for server side.
– Autobahn Test Suite (examples/autobahn) for protocol compliance.
– CircleCI and Go modules (go.mod) for build/test automation.

- From Application → Dialer/Upgrader
- Dialer/Upgrader → Conn constructor
- Conn ↔ Frame Processing (bidirectional)
- Frame Processing → Masking & Compression (bidirectional)
- Conn → net.Conn (TCP/TLS)
- Tests/Examples harness hooking into API Layer

##### Architectural Patterns & Design Principles
- Layered design: clear separation of API, connection management, frame processing, and transport.
- Pluggable modules: masking, compression, and proxy code live in separate files for ease of maintenance and replacement.
- Concurrency via Go routines: read/write pumps inside Conn.
- Interface‐based extensibility: net.Conn and HTTP Handler.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        direction TB
        Chat["examples/chat/main.go"]:::example
        Echo["examples/echo/server.go"]:::example
        Command["examples/command/main.go"]:::example
        FileWatch["examples/filewatch/main.go"]:::example
        AutobahnExample["examples/autobahn/server.go"]:::example
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        Dialer["Dialer (client.go)"]:::api
        Upgrader["Upgrader (server.go)"]:::api
    end

    %% Connection Layer
    subgraph "Connection Layer"
        direction TB
        Conn["Conn (conn.go)"]:::internal
        PreparedMsg["PreparedMessage (prepared.go)"]:::internal
    end

    %% Frame Processing Subsystem
    subgraph "Frame Processing Subsystem"
        direction TB
        FrameProc["Frame Encoder/Decoder"]:::internal
        Masking["Masking Module (mask.go)"]:::internal
        Compression["Compression Module (compression.go)"]:::internal
        Utilities["Utilities (json.go, util.go, join.go)"]:::internal
    end

    %% Transport & Protocol Layer
    subgraph "Transport & Protocol Layer"
        direction TB
        NetConn["Underlying net.Conn (TCP)"]:::transport
        TLS["TLS Handshake (tls_handshake.go)"]:::transport
        Proxy["Proxy Support (proxy.go)"]:::transport
    end

    %% External Dependencies & Tests
    subgraph "External Dependencies & Tests"
        direction TB
        HTTP["HTTP (net/http)"]:::transport
        Autobahn["Autobahn Test Suite"]:::example
        CI["CI & Build (.circleci/config.yml, go.mod)"]:::example
    end

    %% Connections
    Chat -->|uses| Dialer
    Echo -->|uses| Upgrader
    Command -->|uses| Dialer
    FileWatch -->|uses| Dialer
    AutobahnExample -->|tests via| Upgrader

    Dialer -->|creates| Conn
    Upgrader -->|creates| Conn

    Conn -->|"read/write"| FrameProc
    FrameProc -->|"encodes/decodes"| Conn

    FrameProc -->|"calls"| Masking
    Masking -->|"returns"| FrameProc

    FrameProc -->|"calls"| Compression
    Compression -->|"returns"| FrameProc

    FrameProc -->|"uses"| Utilities

    Conn -->|dial/connect| NetConn
    Conn -->|wraps| TLS
    Conn -->|wraps| Proxy

    Upgrader -->|depends on| HTTP
    AutobahnExample -->|harness| Autobahn
    CI -->|builds/tests| Conn

    %% Click Events
    click Chat "https://github.com/enkeyz/websocket/blob/master/examples/chat/main.go"
    click Echo "https://github.com/enkeyz/websocket/blob/master/examples/echo/server.go"
    click Command "https://github.com/enkeyz/websocket/blob/master/examples/command/main.go"
    click FileWatch "https://github.com/enkeyz/websocket/blob/master/examples/filewatch/main.go"
    click AutobahnExample "https://github.com/enkeyz/websocket/blob/master/examples/autobahn/server.go"
    click Dialer "https://github.com/enkeyz/websocket/blob/master/client.go"
    click Upgrader "https://github.com/enkeyz/websocket/blob/master/server.go"
    click Conn "https://github.com/enkeyz/websocket/blob/master/conn.go"
    click PreparedMsg "https://github.com/enkeyz/websocket/blob/master/prepared.go"
    click Compression "https://github.com/enkeyz/websocket/blob/master/compression.go"
    click Masking "https://github.com/enkeyz/websocket/blob/master/mask.go"
    click Utilities "https://github.com/enkeyz/websocket/blob/master/json.go"
    click TLS "https://github.com/enkeyz/websocket/blob/master/tls_handshake.go"
    click Proxy "https://github.com/enkeyz/websocket/blob/master/proxy.go"
    click Autobahn "https://github.com/enkeyz/websocket/tree/master/examples/autobahn/"
    click CI "https://github.com/enkeyz/websocket/blob/master/.circleci/config.yml"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef internal fill:#DFFFE0,stroke:#228A00,color:#228A00;
    classDef transport fill:#F0F0F0,stroke:#666666,color:#333333;
    classDef example fill:#FFF4E5,stroke:#D9822B,color:#D9822B;
```
