# denoland/fastwebsockets architecture

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

- Interactive diagram: https://gitdiagram.com/denoland/fastwebsockets
- Repository: https://github.com/denoland/fastwebsockets

## Overview

##### Main components
a. Network I/O layer
- Tokio’s `TcpStream` or HTTP‐upgraded streams (`hyper::upgrade::Upgraded`).
- External Autobahn TestSuite server (for compliance testing).
- LLVM’s libFuzzer (for fuzz testing).
b. Handshake module (`src/handshake.rs`)
- Client‐side handshake generator/validator.
- Server‐side handshake (feature “upgrade”).
c. WebSocket core API (`src/lib.rs`, `WebSocket<Stream>`)
- Frame reading/writing (`read_frame()`, `write_frame()`).
- Configurables: `set_writev`, `set_auto_close`, `set_auto_pong`.
d. Frame processing sub‐modules
- `frame.rs`: frame structure (FIN, opcode, payload).
- `mask.rs` / `unmask.rs`: masking logic.
- `fragment.rs`: fragmentation definitions.
- `FragmentCollector` (in examples & docs) for coalescing frames.
e. HTTP upgrade integration (`src/upgrade.rs`)
- Adapter to/from Hyper & Axum routes.
f. Examples & Benchmarks
- Standalone example servers/clients (`examples/*.rs`).
- Bench scripts (`benches/`, `autobahn/`).
g. Testing & Fuzzing
- Unit & integration tests (`tests/*.rs`).
- UI tests (`tests/ui`).
- Fuzz targets (`fuzz/fuzz_targets`).

##### Relationships & data flow
- Raw TCP or HTTP-upgraded I/O → Handshake module → WebSocket core → Frame parser → (optional) FragmentCollector → Application logic → Frame writer → Network I/O.
- HTTP upgrade path: Hyper/Axum request → `upgrade::upgrade()` → produces a WebSocket future.
- Fuzzing harnesses feed arbitrary byte streams into `parse_frame`, `unmask`, `parse_frame_fragment`.
- Benchmarks measure performance of `read_frame`/`write_frame` under load.
- Autobahn TestSuite exercises end-to-end handshake + frame exchange.

##### Architectural patterns & design principles
– Modular decomposition: each protocol step in its own Rust module.
– Zero-copy or minimal‐copy data handling (mask/unmask, writev).
– Asynchronous I/O via Tokio & Hyper executors.
– Feature‐flagged extensions (e.g., “upgrade”, “with_axum”).
– Extensibility: raw frame parser vs high-level message collector.
– Strong testing: unit tests, fuzzing, compliance suite.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems"
        Autobahn(("Autobahn TestSuite")):::external
        LibFuzzer(("LLVM libFuzzer")):::external
    end

    %% Examples
    subgraph "Examples" 
        ExamplesDir["examples/"]:::examples
        click ExamplesDir "https://github.com/denoland/fastwebsockets/tree/main/examples/"
        EchoServer["echo_server.rs"]:::examples
        click EchoServer "https://github.com/denoland/fastwebsockets/blob/main/examples/echo_server.rs"
        EchoSplit["echo_server_split.rs"]:::examples
        click EchoSplit "https://github.com/denoland/fastwebsockets/blob/main/examples/echo_server_split.rs"
        TLSClient["tls_client.rs"]:::examples
        click TLSClient "https://github.com/denoland/fastwebsockets/blob/main/examples/tls_client.rs"
        TLSServer["tls_server.rs"]:::examples
        click TLSServer "https://github.com/denoland/fastwebsockets/blob/main/examples/tls_server.rs"
        AutobahnClient["autobahn_client.rs"]:::examples
        click AutobahnClient "https://github.com/denoland/fastwebsockets/blob/main/examples/autobahn_client.rs"
    end

    %% Testing & Benchmarking
    subgraph "Testing & Benchmarking"
        subgraph Benchmarks
            Benches["benches/"]:::benchmark
            click Benches "https://github.com/denoland/fastwebsockets/tree/main/benches/"
            LoadTest["load_test.c"]:::benchmark
            click LoadTest "https://github.com/denoland/fastwebsockets/blob/main/benches/load_test.c"
            UnmaskBench["unmask.rs"]:::benchmark
            click UnmaskBench "https://github.com/denoland/fastwebsockets/blob/main/benches/unmask.rs"
            RunJS["run.js"]:::benchmark
            click RunJS "https://github.com/denoland/fastwebsockets/blob/main/benches/run.js"
        end
        subgraph Tests
            TestsDir["tests/"]:::benchmark
            click TestsDir "https://github.com/denoland/fastwebsockets/tree/main/tests/"
            TestsUI["tests/ui/"]:::benchmark
            click TestsUI "https://github.com/denoland/fastwebsockets/tree/main/tests/ui/"
        end
        subgraph "Fuzz Targets"
            FuzzDir["fuzz/fuzz_targets/"]:::benchmark
            click FuzzDir "https://github.com/denoland/fastwebsockets/tree/main/fuzz/fuzz_targets/"
            ParseFrameFT["parse_frame.rs"]:::benchmark
            click ParseFrameFT "https://github.com/denoland/fastwebsockets/blob/main/fuzz/fuzz_targets/parse_frame.rs"
            ParseFragFT["parse_frame_fragment.rs"]:::benchmark
            click ParseFragFT "https://github.com/denoland/fastwebsockets/blob/main/fuzz/fuzz_targets/parse_frame_fragment.rs"
            UnmaskFT["unmask.rs"]:::benchmark
            click UnmaskFT "https://github.com/denoland/fastwebsockets/blob/main/fuzz/fuzz_targets/unmask.rs"
        end
    end

    %% Integration Layers
    subgraph "Integration Layers"
        HTTPUpgrade["src/upgrade.rs"]:::integration
        click HTTPUpgrade "https://github.com/denoland/fastwebsockets/blob/main/src/upgrade.rs"
        AxumExample["examples/axum.rs"]:::integration
        click AxumExample "https://github.com/denoland/fastwebsockets/blob/main/examples/axum.rs"
    end

    %% Protocol Core
    subgraph "Protocol Core"
        Handshake["src/handshake.rs"]:::core
        click Handshake "https://github.com/denoland/fastwebsockets/blob/main/src/handshake.rs"
        WebSocket["src/lib.rs\n(WebSocket<Stream>)"]:::core
        click WebSocket "https://github.com/denoland/fastwebsockets/blob/main/src/lib.rs"
        Frame["src/frame.rs"]:::core
        click Frame "https://github.com/denoland/fastwebsockets/blob/main/src/frame.rs"
        Mask["src/mask.rs"]:::core
        click Mask "https://github.com/denoland/fastwebsockets/blob/main/src/mask.rs"
        Fragment["src/fragment.rs"]:::core
        click Fragment "https://github.com/denoland/fastwebsockets/blob/main/src/fragment.rs"
        FragmentCollector["FragmentCollector\n(optional)"]:::core
        FrameReader["read_frame()"]:::core
        FrameWriter["write_frame()"]:::core
        AppLogic["Application Logic\n(user code)"]:::core
    end

    %% Core Pipeline
    Autobahn -->|"Handshake Test"| Handshake
    LibFuzzer -->|"Fuzz input"| Frame
    AxumExample -->|"HTTP Upgrade Req"| HTTPUpgrade
    HTTPUpgrade -->|"WebSocket Future"| WebSocket

    Handshake -->|"Validated Stream"| WebSocket
    WebSocket -->|"Frames"| FrameReader
    FrameReader -->|"Parsed Frame"| Frame
    Frame -->|"Mask/Unmask"| Mask
    Mask -->|"Payload"| Frame
    Frame -->|"Fragment Info"| Fragment
    Fragment -->|"Fragments"| FragmentCollector
    FragmentCollector -->|"Messages"| AppLogic
    AppLogic -->|"Data"| FrameWriter
    FrameWriter -->|"Raw Bytes"| WebSocket
    WebSocket -->|"Writes"| FrameWriter

    %% Examples to Network I/O
    EchoServer -->|"TCP I/O"| WebSocket
    EchoSplit -->|"TCP I/O"| WebSocket
    TLSClient -->|"TLS I/O"| WebSocket
    TLSServer -->|"TLS I/O"| WebSocket

    %% Benchmarks usage
    Benches -->|"measure read_frame"| FrameReader
    Benches -->|"measure write_frame"| FrameWriter

    %% Tests usage
    TestsDir -->|"unit/integration"| Handshake
    TestsDir -->|"unit/integration"| Frame
    TestsUI -->|"UI Tests"| AppLogic

    %% Fuzz targets usage
    ParseFrameFT -->|"fuzz parse_frame"| Frame
    ParseFragFT -->|"fuzz parse_fragment"| Fragment
    UnmaskFT -->|"fuzz unmask"| Mask

    %% Legend
    subgraph Legend
        L1["Core Modules"]:::core
        L2["Integration/Adapters"]:::integration
        L3["Tests & Benchmarks"]:::benchmark
        L4["Examples"]:::examples
        L5["External Systems"]:::external
    end

    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef integration fill:#90EE90,stroke:#333,stroke-width:1px
    classDef benchmark fill:#FFA500,stroke:#333,stroke-width:1px
    classDef examples fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#C2F0C2,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
