# gobwas/ws architecture

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

- Interactive diagram: https://gitdiagram.com/gobwas/ws
- Repository: https://github.com/gobwas/ws

## Overview

##### Main components
- Core WebSocket Functionality: This is the heart of the project, consisting of frame reading/writing, handshake/upgrade processing (files like main.go, http.go, server.go, and various protocol handling files such as cipher.go, frame.go, read.go, write.go). This shows how the library processes WebSocket connections at a low level.
- High-Level Wrappers and Utilities: Represented by the wsutil package, which provides easier-to-use utilities and wrappers on top of the core functionality. (See files like wsutil/cipher.go, wsutil/dialer.go, wsutil/upgrader.go, etc.)
- Compression Extension: The wsflate package handles per-message deflate compression, providing compression/decompression support so that the library can negotiate and process compressed frames. (Files in directory wsflate such as cbuf.go, extension.go, reader.go, writer.go are part of this.)
- Testing and Integration: The autobahn directory includes Dockerfiles and configuration for testing with the Autobahn test suite; there’s also an example directory with sample usage code. (These parts show how the library is validated and integrated with external tools.)
- Additional Components: There are several supporting files (util.go and its variants, error handling in errors.go, and others) and test files (with _test.go suffixes) that underline the unit and integration testing strategy.

##### Relationships between these components
- The Core WebSocket Functionality forms the base. All other packages (wsutil and wsflate) rely on it.
- The wsutil package wraps the core functionality to provide a higher-level API, making it easier to implement common use cases like echo servers, JSON encoding/decoding, etc.
- The wsflate package is used as an optional extension; when compression is negotiated during the WebSocket handshake (via the upgrader), the core functionality delegates the compression/decompression of frames to wsflate.
- The testing and examples (autobahn tests, examples) serve as both validation and demonstration of how to integrate and use the core, utility, and compression features.

##### Architectural patterns and design principles
- Separation of concerns: The project distinctively separates low-level protocol handling (ws package) from higher-level abstractions (wsutil) and from extensions (wsflate).
- Extensibility: By making wsflate implement standard extension interfaces (used by wsutil), the design encourages adding or modifying extensions without altering the core processing.
- Modular design: Each package (ws, wsutil, wsflate) acts as an independent module with clear responsibilities. The test suite (including Autobahn Docker-based tests) assures that each module conforms to expected behavior.

##### Relevant technologies and frameworks
- The language is Go.
- It uses Docker (inside the autobahn directory) to run integration tests.
- The standard library packages such as net/http, net, io, and compress/flate (used in wsflate) are essential to the design.
- GitHub Actions workflows and Dependabot configuration indicate continuous integration and dependency management practices.

##### Emphasizing Detail
- Do not overcomplicate—the objective is to capture the essential architectural elements. It helps to break down the flow from connection accept, handshake upgrade (with potential compression negotiation), frame reading/writing, and then high-level API handling.
- You capture the optional “compression” path (wsflate) as separate but connected to core functionality.
- It can be beneficial to mention the integration components (like Autobahn tests) as external validation modules that interact with the system.

## Diagram (Mermaid)

```mermaid
flowchart TD

    In["Incoming HTTP/TCP Connection"]:::external

    subgraph "Core WebSocket Functionality"
        A1["http.go"]:::core
        A2["server.go"]:::core
        A3["frame.go"]:::core
        A4["read.go"]:::core
        A5["write.go"]:::core
        A6["cipher.go"]:::core
        A7["dialer.go"]:::core
        A8["nonce.go"]:::core
        A9["errors.go"]:::core
    end

    subgraph "High-Level Utilities (wsutil)"
        B1["wsutil/dialer.go"]:::wsutil
        B2["wsutil/upgrader.go"]:::wsutil
        B3["wsutil/cipher.go"]:::wsutil
        B4["wsutil/handler.go"]:::wsutil
    end

    subgraph "Compression Extension (wsflate)"
        C1["wsflate/extension.go"]:::wsflate
        C2["wsflate/cbuf.go"]:::wsflate
        C3["wsflate/reader.go"]:::wsflate
        C4["wsflate/writer.go"]:::wsflate
    end

    subgraph "Testing & Integration"
        T1["autobahn/main.go"]:::test
        T2["autobahn/docker"]:::test
        T3["autobahn/config"]:::test
        T4["autobahn/script/test.sh"]:::test
        E1["example/autobahn/autobahn.go"]:::test
        E2["example/autobahn/autobahn_test.go"]:::test
    end

    In -->|"starts"| A2
    A2 -->|"wraps"| B2
    A2 -->|"compression"| C1
    T1 ---|"tests_handshake"| A2
    T1 ---|"tests_utilities"| B2
    T1 ---|"tests_compression"| C1

    click A1 "https://github.com/gobwas/ws/blob/master/http.go"
    click A2 "https://github.com/gobwas/ws/blob/master/server.go"
    click A3 "https://github.com/gobwas/ws/blob/master/frame.go"
    click A4 "https://github.com/gobwas/ws/blob/master/read.go"
    click A5 "https://github.com/gobwas/ws/blob/master/write.go"
    click A6 "https://github.com/gobwas/ws/blob/master/cipher.go"
    click A7 "https://github.com/gobwas/ws/blob/master/dialer.go"
    click A8 "https://github.com/gobwas/ws/blob/master/nonce.go"
    click A9 "https://github.com/gobwas/ws/blob/master/errors.go"

    click B1 "https://github.com/gobwas/ws/blob/master/wsutil/dialer.go"
    click B2 "https://github.com/gobwas/ws/blob/master/wsutil/upgrader.go"
    click B3 "https://github.com/gobwas/ws/blob/master/wsutil/cipher.go"
    click B4 "https://github.com/gobwas/ws/blob/master/wsutil/handler.go"

    click C1 "https://github.com/gobwas/ws/blob/master/wsflate/extension.go"
    click C2 "https://github.com/gobwas/ws/blob/master/wsflate/cbuf.go"
    click C3 "https://github.com/gobwas/ws/blob/master/wsflate/reader.go"
    click C4 "https://github.com/gobwas/ws/blob/master/wsflate/writer.go"

    click T1 "https://github.com/gobwas/ws/blob/master/autobahn/main.go"
    click T2 "https://github.com/gobwas/ws/tree/master/autobahn/docker"
    click T3 "https://github.com/gobwas/ws/tree/master/autobahn/config"
    click T4 "https://github.com/gobwas/ws/blob/master/autobahn/script/test.sh"
    click E1 "https://github.com/gobwas/ws/blob/master/example/autobahn/autobahn.go"
    click E2 "https://github.com/gobwas/ws/blob/master/example/autobahn/autobahn_test.go"

    classDef core fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef wsutil fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef wsflate fill:#ccccff,stroke:#0000cc,stroke-width:2px;
    classDef test fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#606060,stroke-width:2px;
```
