# theldus/wsserver architecture

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

- Interactive diagram: https://gitdiagram.com/theldus/wsserver
- Repository: https://github.com/theldus/wsserver

## Overview

##### Main Components

a) Core WebSocket Server Components:
- Connection Handler (manages client connections)
- Event System (handles onopen, onclose, onmessage events)
- Thread Manager (for per-client thread handling)
- Frame Handler (for WebSocket frame processing)

b) Protocol Components:
- Handshake Manager (opening/closing handshakes)
- Message Processor (Text/Binary messages)
- PING/PONG Handler
- Base64 Encoder/Decoder
- SHA1 Handler
- UTF8 Validator

**┌─────────────────────────────────────────────┐**
- Application Layer              │
- (User Implementation: onopen/close/message) │
- ┤
- wsServer Library               │
- ┌─────────────┐  ┌─────────────┐          │
- Event     │  │  Connection │          │
- Handler    │←→│   Manager   │          │
- ┘  └─────────────┘          │
- ┌─────────────┐  ┌─────────────┐          │
- Frame     │  │  Protocol   │          │
- Processor  │←→│   Handler   │          │
- ┘  └─────────────┘          │
- ┤
- Socket Layer                   │
- ┘

##### Important Details to Highlight

a) Thread Management:
- How each client connection gets its own thread
- Thread pool management system

b) WebSocket Protocol Flow:
- Handshake process
- Frame processing
- Message handling
- PING/PONG mechanism

c) Integration Points:
- How user callbacks (onopen, onclose, onmessage) integrate
- External interface points (ws_socket, ws_sendframe functions)

##### Implementation Details

- src/ws.c as the core implementation
- src/handshake.c for connection establishment
- src/base64.c and src/sha1.c for protocol requirements
- src/utf8.c for message validation

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Application Layer"
        AppImpl["Application Implementation"]:::user
        click AppImpl "https://github.com/Theldus/wsServer/blob/master/examples/echo/echo.c"
        Callbacks["User Callbacks<br/>(onopen/onclose/onmessage)"]:::user
    end

    subgraph "wsServer Library Core"
        CoreWS["WebSocket Server Core"]:::core
        click CoreWS "https://github.com/Theldus/wsServer/blob/master/src/ws.c"
        EventHandler["Event System"]:::core
        ConnManager["Connection Handler"]:::core
        ThreadMgr["Thread Manager"]:::core
        FrameProc["Frame Processor"]:::core
    end

    subgraph "Protocol Handlers"
        HandshakeMgr["Handshake Manager"]:::protocol
        click HandshakeMgr "https://github.com/Theldus/wsServer/blob/master/src/handshake.c"
        MsgProcessor["Message Processor"]:::protocol
        PingPong["PING/PONG Handler"]:::protocol
        Base64["Base64 Encoder/Decoder"]:::protocol
        click Base64 "https://github.com/Theldus/wsServer/blob/master/src/base64.c"
        SHA1["SHA1 Handler"]:::protocol
        click SHA1 "https://github.com/Theldus/wsServer/blob/master/src/sha1.c"
        UTF8["UTF8 Validator"]:::protocol
        click UTF8 "https://github.com/Theldus/wsServer/blob/master/src/utf8.c"
    end

    subgraph "External Components"
        ToyWS["ToyWS Client"]:::external
        click ToyWS "https://github.com/Theldus/wsServer/blob/master/extra/toyws/toyws.c"
        Stunnel["Stunnel<br/>(Optional TLS)"]:::external
    end

    subgraph "Testing & Documentation"
        Tests["Testing Framework"]:::support
        click Tests "https://github.com/Theldus/wsServer/tree/master/tests/fuzzy/"
        Docs["Documentation"]:::support
        click Docs "https://github.com/Theldus/wsServer/tree/master/doc/"
        BuildSys["Build System"]:::support
        click BuildSys "https://github.com/Theldus/wsServer/blob/master/CMakeLists.txt"
    end

    %% Connections
    AppImpl --> Callbacks
    Callbacks --> EventHandler
    EventHandler --> CoreWS
    CoreWS --> ConnManager
    CoreWS --> ThreadMgr
    CoreWS --> FrameProc
    
    ConnManager --> HandshakeMgr
    FrameProc --> MsgProcessor
    MsgProcessor --> PingPong
    HandshakeMgr --> Base64
    HandshakeMgr --> SHA1
    MsgProcessor --> UTF8
    
    CoreWS -.-> ToyWS
    CoreWS -.-> Stunnel

    %% Styles
    classDef core fill:#a8d1f0,stroke:#333,stroke-width:2px
    classDef protocol fill:#90EE90,stroke:#333,stroke-width:2px
    classDef user fill:#FFE5B4,stroke:#333,stroke-width:2px
    classDef external fill:#E6E6FA,stroke:#333,stroke-width:2px
    classDef support fill:#F0F0F0,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Protocol Handlers"]:::protocol
        L3["User Components"]:::user
        L4["External Tools"]:::external
        L5["Support Systems"]:::support
    end
```
