# lxin/quic architecture

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

- Interactive diagram: https://gitdiagram.com/lxin/quic
- Repository: https://github.com/lxin/quic

## Overview

##### Project Type and Purpose
- This is a hybrid full-stack/networking project that implements the QUIC protocol partly in user space (libquic) for TLS handshake and entirely in kernel space (modules/net/quic) for the core QUIC transport and integration with Linux socket APIs.
- The README confirms its goal: expose IPPROTO_QUIC sockets in the kernel, offload TLS handshake messages to user space via netlink, and provide zero-copy, ALPN routing, and crypto offloading capabilities.

##### High-Level Components
a. Userspace Layer
- Applications (APP1, APP2, etc.)
- libquic: wraps gnutls to create/process raw TLS handshake messages
- tlshd (ktls-utils): daemon handling kernel handshake requests via netlink
b. Kernel Layer
- Socket interface: IPPROTO_QUIC socket type over UDP tunnels
- Protocol core (modules/net/quic): submodules for packet, frame, crypto, connid, stream, congestion control, pnspace, path, timer, input/output queues
- Netlink handshake API: upcalls from kernel to tlshd for TLS handshake
- Kernel consumers: SMB, NFS, other kernel subsystems using QUIC sockets
c. External/Infrastructure
- gnutls library in user space
- NIC crypto offload (future)
- Docker-based interop test environments (tests/interop)

##### Component Relationships and Data Flows
- Application → libquic (send/recvmsg + cmsg handshake info) → kernel QUIC socket
- Kernel QUIC socket → protocol core → UDP tunnels → network
- For handshake: Kernel issues netlink calls → tlshd → gnutls handshake → netlink response → kernel completes QUIC handshake
- Kernel consumers (SMB, NFS) call kernel QUIC APIs like sendmsg/recvmsg or the up-call handshake netlink

##### Architectural Patterns and Design Principles
- Layered architecture: clear separation between handshake (user space) and transport (kernel space)
- Protocol module within Linux net stack: analogous to TCP/MPTCP but under a new protocol family
- Extensibility: modular subcomponents (crypto, congestion, packetization, streams)
- Zero-copy & offload-friendly: socket buffer reuse, CMSG/SOCKOPT for secrets, future NIC offload hooks

##### Detail
- Every major subcomponent as its own block in the Protocol Core

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Userspace Layer
    subgraph "Userspace Layer"
        Apps["Applications (APP1, APP2)"]:::user
        LibQuic["libquic"]:::user
        TLSD["tlshd Daemon (ktls-utils)"]:::user
    end

    %% Kernel Layer
    subgraph "Kernel Layer"
        KSocket["IPPROTO_QUIC Socket Interface"]:::kernel
        Netlink["Netlink Handshake API"]:::kernel
        Consumers["Kernel Consumers (SMB, NFS)"]:::kernel

        subgraph "Protocol Core"
            ProtocolEP["Protocol Entry Points"]:::kernel
            Stream["Stream Management"]:::kernel
            Packet["Packetization"]:::kernel
            Frame["Framing"]:::kernel
            ConnID["ConnID Management"]:::kernel
            Cong["Congestion Control"]:::kernel
            Crypto["Crypto Integration"]:::kernel
            PNSpace["Packet-Number Spaces"]:::kernel
            Path["Path Management"]:::kernel
            Timer["Timers"]:::kernel
            InQ["Input Queue"]:::kernel
            OutQ["Output Queue"]:::kernel
        end

        subgraph "Common & Family"
            Family["Protocol Family & Registration"]:::kernel
            Common["Common Utilities"]:::kernel
        end

        subgraph "Headers"
            IntHdr["linux/quic.h"]:::kernel
            UAPIHdr["uapi/linux/quic.h"]:::kernel
        end

        subgraph "Tests (Kernel)"
            UT["unit_test.c"]:::kernel
            ST["sample_test.c"]:::kernel
        end

        UDP["UDP Tunnels"]:::kernel
    end

    %% External/Infrastructure
    subgraph "External/Infrastructure"
        GnuTLS["GnuTLS Library"]:::external
        Network["Network / NIC"]:::external
        Interop["Interop Test Env"]:::external
        IT["interop_test.c"]:::external
    end

    %% Flows
    Apps -->|sendmsg/recvmsg + CMSG_HANDSHAKE_INFO| LibQuic
    Apps -->|set/getsockopt| LibQuic
    LibQuic -->|sendmsg/recvmsg| KSocket
    KSocket -->|forward to core| ProtocolEP

    ProtocolEP --> Stream
    ProtocolEP --> Packet
    ProtocolEP --> Frame
    ProtocolEP --> ConnID
    ProtocolEP --> Cong
    ProtocolEP --> Crypto
    ProtocolEP --> PNSpace
    ProtocolEP --> Path
    ProtocolEP --> Timer
    ProtocolEP --> InQ
    ProtocolEP --> OutQ

    ProtocolEP -->|encapsulate| UDP
    UDP -->|UDP Tunnels| Network

    KSocket -->|NETLINK_TLS_HANDSHAKE| Netlink
    Netlink -->|TLS handshake requests| TLSD
    TLSD -->|uses GnuTLS| GnuTLS
    TLSD -->|NETLINK_TLS_HANDSHAKE reply| Netlink
    Netlink -->|complete handshake| KSocket

    Consumers -->|kernel_sendmsg/kernel_recvmsg| ProtocolEP

    Family --> ProtocolEP
    Common --> ProtocolEP
    IntHdr --> ProtocolEP
    UAPIHdr --> KSocket

    UT --> ProtocolEP
    ST --> ProtocolEP

    Interop --> IT

    %% Click Events
    click LibQuic "https://github.com/lxin/quic/tree/main/libquic/"
    click KSocket "https://github.com/lxin/quic/blob/main/modules/net/quic/socket.c"
    click KSocket "https://github.com/lxin/quic/blob/main/modules/net/quic/socket.h"
    click ProtocolEP "https://github.com/lxin/quic/blob/main/modules/net/quic/protocol.c"
    click Packet "https://github.com/lxin/quic/blob/main/modules/net/quic/packet.c"
    click Frame "https://github.com/lxin/quic/blob/main/modules/net/quic/frame.c"
    click ConnID "https://github.com/lxin/quic/blob/main/modules/net/quic/connid.c"
    click Stream "https://github.com/lxin/quic/blob/main/modules/net/quic/stream.c"
    click Cong "https://github.com/lxin/quic/blob/main/modules/net/quic/cong.c"
    click Crypto "https://github.com/lxin/quic/blob/main/modules/net/quic/crypto.c"
    click PNSpace "https://github.com/lxin/quic/blob/main/modules/net/quic/pnspace.c"
    click Path "https://github.com/lxin/quic/blob/main/modules/net/quic/path.c"
    click Timer "https://github.com/lxin/quic/blob/main/modules/net/quic/timer.c"
    click InQ "https://github.com/lxin/quic/blob/main/modules/net/quic/inqueue.c"
    click OutQ "https://github.com/lxin/quic/blob/main/modules/net/quic/outqueue.c"
    click Family "https://github.com/lxin/quic/blob/main/modules/net/quic/family.c"
    click Common "https://github.com/lxin/quic/blob/main/modules/net/quic/common.c"
    click IntHdr "https://github.com/lxin/quic/blob/main/modules/include/linux/quic.h"
    click UAPIHdr "https://github.com/lxin/quic/blob/main/modules/include/uapi/linux/quic.h"
    click UT "https://github.com/lxin/quic/blob/main/modules/net/quic/test/unit_test.c"
    click ST "https://github.com/lxin/quic/blob/main/modules/net/quic/test/sample_test.c"
    click IT "https://github.com/lxin/quic/blob/main/tests/interop/interop_test.c"

    %% Styles
    classDef user fill:#ADD8E6,stroke:#000;
    classDef kernel fill:#90EE90,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
