# infinitefield/yawc architecture

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

- Interactive diagram: https://gitdiagram.com/infinitefield/yawc
- Repository: https://github.com/infinitefield/yawc

## Overview

This project is a specialized WebSocket library written in Rust – “yawc” – which implements a high-performance, secure, and RFC 6455–compliant WebSocket protocol with advanced features like zero‐copy frame processing, optional compression (including permessage-deflate), and integration with both client (e.g., reqwest) and server frameworks (e.g., hyper, axum). The structure of the project (with its src, examples, autobahn, and yawcc directories) indicates that it not only provides the core library functionality but also includes practical examples and test harnesses (including Autobahn tests) to illustrate its use in both client and server scenarios.

##### Main Components
- Core WebSocket Library: Represent the core logic and modules found in the “src” directory (e.g., frame handling, codec, compression, masking, connection management, and stream processing). Label these as “Core Library Components.”
- Testing & Compliance: Include a component for the Autobahn testing suite (directory “autobahn”) which validates client and server compliance with the WebSocket RFC.
- Example Implementations & Integrations: There are multiple example implementations – for instance, Axum integration (in the “examples” and “examples/axum_proxy” directories) and a standalone client/server demo in the “yawcc” directory. Represent these as separate “Example Applications / Integration Modules.”
- External Dependencies & Frameworks: Identify the connections to crucial external technologies such as:
- HTTP clients like reqwest,
- Server frameworks like hyper and axum,
- Async runtime (Tokio),
- TLS via rustls.
These can be shown as supporting blocks that interface with your core library.

##### Relationships and Data Flow
- For the server side, illustrate how connection upgrade requests traverse from the web framework or HTTP server into the library’s upgrade and frame management functions, eventually returning a managed WebSocket connection.
- Internal flow of data: from connection handling, frame encoding/decoding (using modules like codec.rs and frame.rs), compression (compression.rs), and masking (mask.rs), all connecting together to form the complete processing pipeline.

##### Architectural Patterns and Design Principles
- Modular Design: Each functionality (e.g., compression, frame management, masking) is encapsulated in its own module, which promotes separation of concerns and testability.
- Zero-Copy Architecture: Emphasize on the efficient frame processing that minimizes memory allocations.
- Configurability via Options: The library uses an “Options” builder pattern that permits advanced settings like compression levels, client validation, and TLS integration. Represent this as connectors between configuration and behavior of core components.

##### Technologies and Technologies Labeling
- Rust programming language (base),
- Tokio as the async runtime,
- Reqwest for HTTP client usage,
- Hyper and Axum for server examples,
- rustls for TLS.
- Build tools and CI/CD (Github workflows) as peripheral components ensuring that the tests and builds maintain protocol conformance and system stability.

##### Clarity and Detail
- Do capture every essential architectural element—don’t miss out on the interplay between different core modules.

- The core WebSocket components (frame, codec, compression, etc.),
- How client and server integrations (via yawcc, Axum examples) interact with these components,
- The support structures (Autobahn tests, async runtimes, TLS support),
- And clear, well-labeled relationships between them.

This detailed focus will serve as an effective blueprint of yawc’s architecture, aligning both with its functionality as a high-performance WebSocket implementation and its broad use cases showcased by examples and tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Dependencies"
        E1("Rust"):::external
        E2("Tokio(AsyncRuntime)"):::external
        E3("Reqwest(HTTPClient)"):::external
        E4("Hyper(ServerFramework)"):::external
        E5("Axum(ServerFramework)"):::external
        E6("rustls(TLS)"):::external
    end

    subgraph "Core Library Components"
        C1("Connection Management (src/lib.rs)"):::core
        C2("Frame Handling (src/frame.rs)"):::core
        C3("Codec (src/codec.rs)"):::core
        C4("Compression Engine (src/compression.rs)"):::core
        C5("Masking Module (src/mask.rs)"):::core
        C6("Stream Processing (src/stream.rs)"):::core
        C7("Close Handling (src/close.rs)"):::core
    end

    subgraph "Integration & Example Applications"
        subgraph "Axum Integration Example"
            A1("Axum Example (examples/axum.rs)"):::integration
            A2("Axum Proxy (examples/axum_proxy)"):::integration
        end
        subgraph "Client/Server Example (yawcc)"
            Y1("Yawcc Client (yawcc/src/client.rs)"):::integration
            Y2("Yawcc Server (yawcc/src/server.rs)"):::integration
            Y3("Yawcc Main (yawcc/src/main.rs)"):::integration
        end
        subgraph "Additional Examples"
            E7("Autobahn Client Example (examples/autobahn_client.rs)"):::integration
            E8("Client Example (examples/client.rs)"):::integration
            E9("Echo Server Example (examples/echo_server.rs)"):::integration
            E10("Proxy Example (examples/proxy.rs)"):::integration
        end
    end

    subgraph "Testing & Compliance (Autobahn)"
        T1("Autobahn Client Test (autobahn/client-test.js)"):::test
        T2("Autobahn Server Test (autobahn/server-test.js)"):::test
        T3("Fuzzing Client (fuzzingclient.json)"):::test
        T4("Fuzzing Server (fuzzingserver.json)"):::test
    end

    %% External dependencies feed into the core library
    E1 --> C1
    E2 --> C1
    E3 --> C1
    E4 --> C1
    E5 --> C1
    E6 --> C1

    %% Testing components validate the core library
    T1 --> C1
    T2 --> C1
    T3 --> C1
    T4 --> C1

    %% Integration examples utilize the core library
    A1 --> C1
    A2 --> C1
    Y1 --> C1
    Y2 --> C1
    Y3 --> C1
    E7 --> C1
    E8 --> C1
    E9 --> C1
    E10 --> C1

    %% Internal core library processing flow
    C1 --> C2
    C2 --> C3
    C3 --> C4
    C4 --> C5
    C5 --> C6
    C6 --> C7

    %% Click Events for Core WebSocket Library Components
    click C1 "https://github.com/infinitefield/yawc/blob/master/src/lib.rs"
    click C2 "https://github.com/infinitefield/yawc/blob/master/src/frame.rs"
    click C3 "https://github.com/infinitefield/yawc/blob/master/src/codec.rs"
    click C4 "https://github.com/infinitefield/yawc/blob/master/src/compression.rs"
    click C5 "https://github.com/infinitefield/yawc/blob/master/src/mask.rs"
    click C6 "https://github.com/infinitefield/yawc/blob/master/src/stream.rs"
    click C7 "https://github.com/infinitefield/yawc/blob/master/src/close.rs"

    %% Click Events for Autobahn Testing Components
    click T1 "https://github.com/infinitefield/yawc/blob/master/autobahn/client-test.js"
    click T2 "https://github.com/infinitefield/yawc/blob/master/autobahn/server-test.js"
    click T3 "https://github.com/infinitefield/yawc/blob/master/autobahn/fuzzingclient.json"
    click T4 "https://github.com/infinitefield/yawc/blob/master/autobahn/fuzzingserver.json"

    %% Click Events for Axum Integration Example
    click A1 "https://github.com/infinitefield/yawc/blob/master/examples/axum.rs"
    click A2 "https://github.com/infinitefield/yawc/blob/master/examples/axum_proxy/main.rs"

    %% Click Events for Yawcc Client/Server Example
    click Y1 "https://github.com/infinitefield/yawc/blob/master/yawcc/src/client.rs"
    click Y2 "https://github.com/infinitefield/yawc/blob/master/yawcc/src/server.rs"
    click Y3 "https://github.com/infinitefield/yawc/blob/master/yawcc/src/main.rs"

    %% Click Events for Additional Examples
    click E7 "https://github.com/infinitefield/yawc/blob/master/examples/autobahn_client.rs"
    click E8 "https://github.com/infinitefield/yawc/blob/master/examples/client.rs"
    click E9 "https://github.com/infinitefield/yawc/blob/master/examples/echo_server.rs"
    click E10 "https://github.com/infinitefield/yawc/blob/master/examples/proxy.rs"

    %% Styles
    classDef external fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#2980b9,stroke-width:2px;
    classDef integration fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef test fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;

    class E1,E2,E3,E4,E5,E6 external;
    class C1,C2,C3,C4,C5,C6,C7 core;
    class A1,A2,Y1,Y2,Y3,E7,E8,E9,E10 integration;
    class T1,T2,T3,T4 test;
```
