# grpc/grpc-swift-nio-transport architecture

> Architecture diagram of the GitHub repository grpc/grpc-swift-nio-transport, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grpc/grpc-swift-nio-transport
- Repository: https://github.com/grpc/grpc-swift-nio-transport

## Overview

##### Project Type and Purpose
- This is an open-source Swift library (a transport layer) implementing high-performance HTTP/2 client and server transports for gRPC Swift, built on top of SwiftNIO.
- It provides a modular, layered transport solution: a core transport abstraction, HTTP/2 framing layer, and platform-specific socket/TLS implementations, plus a C‐based zlib compressor.

##### Key Directories / Modules
- Sources/CGRPCNIOTransportZlib
- A small C library (zlib) and Swift headers for request/response compression.
- Sources/GRPCNIOTransportCore
- Core transport abstraction: connection management, load balancers, resolvers, stream handlers, message framing, compression protocol interfaces.
- Sources/GRPCNIOTransportHTTP2
- HTTP/2 framing and parsing, integrates with SwiftNIO’s NIOHTTP2.
- Sources/GRPCNIOTransportHTTP2Posix
- Posix socket bootstrap, NIOSSL integration, TLS config for client/server.
- Sources/GRPCNIOTransportHTTP2TransportServices
- Apple TransportServices bootstrap & TLS for non‐POSIX platforms.
- Tests / IntegrationTests
- Unit tests per module and end-to-end interop/performance tests using generated proto stubs.
- dev/
- Scripts for building, formatting, generating protos and running interop/perf tests.

##### How to Model This
- Application Layer (gRPC Swift client & server code)
- GRPCNIOTransportCore
– ConnectionManager, GRPCChannel, LoadBalancer, Resolver, StreamHandler, Compressor interface
- CGRPCNIOTransportZlib (zlib compressor/decompressor)
- GRPCNIOTransportHTTP2 (HTTP/2 frame encoder/decoder)
- Platform Transports (choose one at runtime):
– HTTP2TransportPosix (NIOSSL + Posix bootstrap)
– HTTP2TransportTransportServices (TransportServices + TLS)
- SwiftNIO Core
– EventLoopGroup, ChannelPipeline, NIOHTTP2Handler, SocketChannel
- Network (TCP/TLS, HTTP/2 wire)

1. Application → Core:
- Uses GRPCChannel API to open streams and send RPCs
2. Core → Compressor (optional):
- Invokes zlib via C interface for message compress/decompress
3. Core → HTTP2 Layer:
- Passes framed gRPC messages to HTTP2 encoder
4. HTTP2 Layer → Platform Transport:
- HTTP/2 frames enter ChannelPipeline with TLS handlers
5. Platform → SwiftNIO Socket:
- Bootstraps SocketChannel, applies TLS (NIOSSL or TransportServices)
6. Socket → Network:
- Over TCP/TLS carrying HTTP/2 frames

c. Architectural Patterns / Principles
- Layered modular design: Core transport, HTTP/2 framing, platform transport modules.
- Protocol-oriented abstractions (e.g., CompressionAlgorithm, NameResolver, LoadBalancer).
- Pipeline pattern (ChannelPipeline) for composable handlers (framing, TLS).
- Dependency injection of platform modules (Posix vs TransportServices).

d. Technologies & Frameworks
- SwiftNIO (EventLoopGroup, ChannelPipeline)
- NIOHTTP2 (HTTP/2 codec)
- NIOSSL or Apple TransportServices (TLS)
- zlib (C library for compression)
- Swift Package Manager (multi-module SPM)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Integration Tests
    subgraph "Integration Tests" 
        Interop["gRPC Interop Tests"]:::tests
        Performance["gRPC Performance Tests"]:::tests
    end
    click Interop "https://github.com/grpc/grpc-swift-nio-transport/tree/main/IntegrationTests/grpc-interop-tests"
    click Performance "https://github.com/grpc/grpc-swift-nio-transport/tree/main/IntegrationTests/grpc-performance-tests"

    %% Application Layer
    Application["gRPC Swift Client & Server"]:::application

    %% Core Transport Layer
    subgraph "GRPCNIOTransportCore" 
        Core["Core Transport Abstraction"]:::core
        subgraph "Core Modules"
            Client["Client"]:::core
            Server["Server"]:::core
            Compression["Compression Interfaces"]:::core
            Internal["Internal Utilities"]:::core
        end
    end
    click Core "https://github.com/grpc/grpc-swift-nio-transport/tree/main/Sources/GRPCNIOTransportCore"
    click Client "https://github.com/grpc/grpc-swift-nio-transport/tree/main/Sources/GRPCNIOTransportCore/Client"
    click Server "https://github.com/grpc/grpc-swift-nio-transport/tree/main/Sources/GRPCNIOTransportCore/Server"
    click Compression "https://github.com/grpc/grpc-swift-nio-transport/tree/main/Sources/GRPCNIOTransportCore/Compression"
    click Internal "https://github.com/grpc/grpc-swift-nio-transport/tree/main/Sources/GRPCNIOTransportCore/Internal"

    %% Zlib Compressor
    Zlib["CGRPCNIOTransportZlib"]:::zlib
    click Zlib "https://github.com/grpc/grpc-swift-nio-transport/tree/main/Sources/CGRPCNIOTransportZlib"

    %% HTTP/2 Framing Layer
    subgraph "GRPCNIOTransportHTTP2"
        HTTP2["HTTP/2 Framing & Parsing"]:::http2
    end
    click HTTP2 "https://github.com/grpc/grpc-swift-nio-transport/tree/main/Sources/GRPCNIOTransportHTTP2"

    %% Platform Transports
    subgraph "Platform Transports"
        Posix["HTTP2TransportPosix"]:::platform
        TS["HTTP2TransportTransportServices"]:::platform
    end
    click Posix "https://github.com/grpc/grpc-swift-nio-transport/tree/main/Sources/GRPCNIOTransportHTTP2Posix"
    click TS "https://github.com/grpc/grpc-swift-nio-transport/tree/main/Sources/GRPCNIOTransportHTTP2TransportServices"

    %% SwiftNIO Core
    SwiftNIO["SwiftNIO Core\n(EventLoopGroup, ChannelPipeline,\nNIOHTTP2Handler, SocketChannel)"]:::swiftnio

    %% Network
    Network["Network (TCP/TLS)"]:::network

    %% Dev Scripts
    Dev["dev/ Scripts"]:::dev
    click Dev "https://github.com/grpc/grpc-swift-nio-transport/tree/main/dev/"

    %% Data Flow
    Interop -->|uses public API| Application
    Performance -->|uses public API| Application
    Application -->|GRPCChannel API| Core
    Core -->|CompressionProtocol| Compression
    Compression -->|C calls| Zlib
    Core -->|framed messages| HTTP2
    HTTP2 -->|HTTP/2 frames| Posix
    HTTP2 -->|HTTP/2 frames| TS
    Posix -->|bootstrap + TLS| SwiftNIO
    TS -->|bootstrap + TLS| SwiftNIO
    SwiftNIO -->|TCP/TLS| Network

    %% Styles
    classDef application fill:#D7BDE2,stroke:#884EA0,color:#1A5276;
    classDef core fill:#AED6F1,stroke:#2874A6,color:#1B2631;
    classDef zlib fill:#D5D8DC,stroke:#7F8C8D,color:#1B2631,shape:cylinder;
    classDef http2 fill:#A9DFBF,stroke:#229954,color:#1B2631;
    classDef platform fill:#F5CBA7,stroke:#CA6F1E,color:#1B2631;
    classDef swiftnio fill:#FCF3CF,stroke:#B7950B,color:#1B2631;
    classDef network fill:#F5B7B1,stroke:#C0392B,color:#1B2631,shape:cylinder;
    classDef tests fill:#E8DAEF,stroke:#6C3483,color:#1B2631,stroke-dasharray: 5 5;
    classDef dev fill:#F2F3F4,stroke:#717D7E,color:#1B2631,stroke-dasharray: 2 2;
```
