# apple/swift-nio-transport-services architecture

> Architecture diagram of the GitHub repository apple/swift-nio-transport-services, 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/apple/swift-nio-transport-services
- Repository: https://github.com/apple/swift-nio-transport-services

## Overview

##### Project Type and Purpose
- This is a Swift package providing extensions to SwiftNIO (a non-blocking networking framework) that leverage Apple’s Network.framework and Dispatch on Apple platforms.
- It supplies an alternative EventLoop/EventLoopGroup, various Channel implementations, and Bootstrap classes, plus example HTTP client/server executables.

##### File Structure Analysis
- Top-level manifests and metadata: Package.swift, README.md, LICENSE.txt, GitHub workflows, CODE_OF_CONDUCT, CONTRIBUTING.
- Sources/ contains three distinct modules:
- NIOTSHTTPClient – a command-line HTTP client main.swift
- NIOTSHTTPServer – a command-line HTTP server main.swift
- NIOTransportServices – the core library:
– EventLoop, EventLoopGroup wrappers (NIOTSEventLoop*, NIOTSEventLoopGroup)
– Channel implementations (NIOTSConnectionChannel, NIOTSListenerChannel, Datagram channels)
– Bootstraps (NIOTSConnectionBootstrap, NIOTSListenerBootstrap, NIOTSDatagram*)
– SocketOptions, Errors, Singletons, Filter handlers
– SocketAddress+NWEndpoint bridging
- Tests/ validates each handler, channel, bootstrap, event-loop, and end-to-end behavior.
- CI workflows in .github/workflows automate builds, tests, and releases.

##### README Insights
- Describes the library’s role: “first-class support for Apple platforms” by wrapping Network.framework and Dispatch.
- Mentions key components: EventLoop, EventLoopGroup, Channels, Bootstraps.
- Usage instructions: import NIOTransportServices and swap out SwiftNIO’s defaults.
- Supported platforms, versioning, and development guidelines.

– Bootstraps
– EventLoopGroup → EventLoop → DispatchQueue
– Channel implementations → ChannelPipeline
3. To the right, show Apple frameworks:
– Network.framework components (NWListener, NWConnection)
– Dispatch (DispatchQueue)
7. Optionally overlay the test suite verifying each component.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application Layer"
        direction TB
        NIOTSHTTPClient["NIOTSHTTPClient"]:::application
        NIOTSHTTPServer["NIOTSHTTPServer"]:::application
    end

    %% Library Layer
    subgraph "NIOTransportServices Core Library"
        direction TB
        subgraph "Bootstraps"
            NIOTSConnectionBootstrap["NIOTSConnectionBootstrap"]:::library
            NIOTSListenerBootstrap["NIOTSListenerBootstrap"]:::library
            NIOTSDatagramConnectionBootstrap["NIOTSDatagramConnectionBootstrap"]:::library
            NIOTSDatagramListenerBootstrap["NIOTSDatagramListenerBootstrap"]:::library
            NIOTSBootstraps["Bootstraps Aggregator"]:::library
        end

        subgraph "Event Loop"
            NIOTSEventLoopGroup["NIOTSEventLoopGroup"]:::library
            NIOTSEventLoop["NIOTSEventLoop"]:::library
            DispatchQueueCyl[(DispatchQueue)]:::apple
        end

        subgraph "Channels & Pipeline"
            NIOTSConnectionChannel["NIOTSConnectionChannel"]:::library
            NIOTSListenerChannel["NIOTSListenerChannel"]:::library
            NIOTSDatagramConnectionChannel["NIOTSDatagramConnectionChannel"]:::library
            NIOTSDatagramListenerChannel["NIOTSDatagramListenerChannel"]:::library
            NIOFilterEmptyWritesHandler["NIOFilterEmptyWritesHandler"]:::library
            NIOTSChannelOptions["NIOTSChannelOptions"]:::library
            SocketAddressNWEndpoint["SocketAddress+NWEndpoint"]:::library
        end

        subgraph "Utilities"
            NIOTSErrors["NIOTSErrors"]:::library
            NIOTSSingletons["NIOTSSingletons"]:::library
            NIOTSNetworkEvents["NIOTSNetworkEvents"]:::library
            TCPOptions["TCPOptions+SocketChannelOption"]:::library
            UDPOptions["UDPOptions+SocketChannelOption"]:::library
            StateManagedChannel["StateManagedChannel"]:::library
            StateManagedListenerChannel["StateManagedListenerChannel"]:::library
            StateManagedNWConnectionChannel["StateManagedNWConnectionChannel"]:::library
        end
    end

    %% External Dependencies
    subgraph "Apple Frameworks"
        direction TB
        NWConnection["NWConnection"]:::apple
        NWListener["NWListener"]:::apple
        NWEndpoint["NWEndpoint"]:::apple
    end

    subgraph "SwiftNIO Core"
        direction TB
        SNIOEventLoopGroup["EventLoopGroup"]:::nio
        SNIOChannel["Channel"]:::nio
        SNIOBootstrap["Bootstrap"]:::nio
    end

    %% Connections
    NIOTSHTTPClient -->|"uses"| NIOTSConnectionBootstrap
    NIOTSHTTPServer -->|"uses"| NIOTSListenerBootstrap

    NIOTSConnectionBootstrap -->|"configures"| NIOTSBootstraps
    NIOTSListenerBootstrap -->|"configures"| NIOTSBootstraps
    NIOTSDatagramConnectionBootstrap -->|"configures"| NIOTSBootstraps
    NIOTSDatagramListenerBootstrap -->|"configures"| NIOTSBootstraps

    NIOTSBootstraps -->|"creates"| NIOTSEventLoopGroup
    NIOTSEventLoopGroup -->|"spawns"| NIOTSEventLoop
    NIOTSEventLoop -->|"runs on"| DispatchQueueCyl

    NIOTSConnectionBootstrap -->|"bind/connect"| NWConnection
    NIOTSListenerBootstrap -->|"bind"| NWListener
    NIOTSDatagramListenerBootstrap -->|"bind"| NWListener
    NIOTSDatagramConnectionBootstrap -->|"connect"| NWConnection

    NWConnection -->|"data bytes"| NIOTSConnectionChannel
    NWListener -->|"incoming"| NIOTSListenerChannel
    NWConnection -->|"data bytes"| NIOTSDatagramConnectionChannel
    NWListener -->|"incoming"| NIOTSDatagramListenerChannel

    NIOTSConnectionChannel -->|"pipeline"| NIOFilterEmptyWritesHandler
    NIOTSListenerChannel -->|"pipeline"| NIOFilterEmptyWritesHandler
    NIOTSDatagramConnectionChannel -->|"pipeline"| NIOFilterEmptyWritesHandler
    NIOTSDatagramListenerChannel -->|"pipeline"| NIOFilterEmptyWritesHandler

    NIOTSChannelOptions -->|"applied to"| NIOTSConnectionChannel
    SocketAddressNWEndpoint -->|"translates"| NWEndpoint

    %% Fallback to SwiftNIO Core
    NIOTSBootstraps -.->|"fallback"| SNIOBootstrap
    SNIOBootstrap -->|"socket path"| SNIOEventLoopGroup
    SNIOEventLoopGroup -->|"spawns"| SNIOEventLoopGroup

    %% Click Events
    click NIOTSHTTPClient "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTSHTTPClient/main.swift"
    click NIOTSHTTPServer "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTSHTTPServer/main.swift"
    click NIOTSEventLoop "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/NIOTSEventLoop.swift"
    click NIOTSEventLoopGroup "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/NIOTSEventLoopGroup.swift"
    click NIOTSConnectionChannel "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/NIOTSConnectionChannel.swift"
    click NIOTSListenerChannel "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/NIOTSListenerChannel.swift"
    click NIOTSDatagramConnectionChannel "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/Datagram/NIOTSDatagramConnectionChannel.swift"
    click NIOTSDatagramListenerChannel "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/Datagram/NIOTSDatagramListenerChannel.swift"
    click NIOTSConnectionBootstrap "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/NIOTSConnectionBootstrap.swift"
    click NIOTSListenerBootstrap "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/NIOTSListenerBootstrap.swift"
    click NIOTSDatagramConnectionBootstrap "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/Datagram/NIOTSDatagramConnectionBootstrap.swift"
    click NIOTSDatagramListenerBootstrap "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/Datagram/NIOTSDatagramListenerBootstrap.swift"
    click NIOTSBootstraps "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/NIOTSBootstraps.swift"
    click NIOFilterEmptyWritesHandler "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/NIOFilterEmptyWritesHandler.swift"
    click NIOTSChannelOptions "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/NIOTSChannelOptions.swift"
    click TCPOptions "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/TCPOptions+SocketChannelOption.swift"
    click UDPOptions "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/UDPOptions+SocketChannelOption.swift"
    click NIOTSErrors "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/NIOTSErrors.swift"
    click NIOTSSingletons "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/NIOTSSingletons.swift"
    click NIOTSNetworkEvents "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/NIOTSNetworkEvents.swift"
    click SocketAddressNWEndpoint "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/SocketAddress+NWEndpoint.swift"
    click StateManagedChannel "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/StateManagedChannel.swift"
    click StateManagedListenerChannel "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/StateManagedListenerChannel.swift"
    click StateManagedNWConnectionChannel "https://github.com/apple/swift-nio-transport-services/blob/main/Sources/NIOTransportServices/StateManagedNWConnectionChannel.swift"

    %% Styles
    classDef application fill:#FFF89A,stroke:#333,stroke-width:1px
    classDef library fill:#7DE2D1,stroke:#333,stroke-width:1px
    classDef apple fill:#FFB56B,stroke:#333,stroke-width:1px
    classDef nio fill:#A4D0F5,stroke:#333,stroke-width:1px
```
