# vapor/http architecture

> Architecture diagram of the GitHub repository vapor/http, 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/vapor/http
- Repository: https://github.com/vapor/http

## Overview

##### Project Type and Purpose
- This is an open-source Swift library (“HTTPKit”) providing both HTTP client and server APIs, plus WebSocket support, built on top of Swift NIO. It is not a runnable application but a reusable toolset for Vapor and other Swift network frameworks to perform HTTP operations at a low level.

##### File Structure Analysis
- Top-level:
- Package.swift, README.md, LICENSE, .gitignore
- Sources/HTTPKit – core library code
- Sources/HTTPKitExample – minimal usage example
- Tests/HTTPKitTests – unit tests for client, server, headers, cookies, WebSockets
- certs/, circle.yml, docker-compose.yml – CI and testing utilities, TLS material
- Under Sources/HTTPKit:
- Client – HTTP client pipeline components
- Server – HTTP server pipeline components
- Message – shared HTTPMessage, HTTPRequest, HTTPResponse, cookies, bodies
- Headers – HTTPHeaders and header value abstractions
- WebSocket – client and server WebSocket upgrade & frame handling
- Utilities – ancillary types (errors, RFC1123 date, file I/O, string utils)
- The repeated “Handler” and “Encoder/Decoder” suffixes indicate a channel-pipeline architecture (typical of Swift NIO) where inbound/outbound data flows through a chain of handlers that encode, decode, upgrade, or proxy.

##### Key Components to Plot
- HTTPKit Module (umbrella)
- HTTPClient
‑ HTTPClientRequestEncoder
‑ HTTPClientResponseDecoder
‑ HTTPClientHandler / ProxyHandler / UpgradeHandler
‑ HTTPClient.swift (entry point)
- HTTPServer
‑ HTTPRequestPartDecoder
‑ HTTPResponsePartEncoder
‑ HTTPServerHandler / UpgradeHandler
‑ HTTPServer.swift (entry point)
- Message & Headers
‑ HTTPMessage, HTTPRequest, HTTPResponse
‑ HTTPHeaders, HTTPHeaderValue, MediaTypes, Cookies, URL extensions
- WebSocket
‑ WebSocketFrameSequence, WebSocketHandler
‑ HTTPRequest+WebSocket, HTTPResponse+WebSocket
‑ WebSocket+Client, WebSocket+Server
- Utilities
‑ CaseInsensitiveString, File I/O, HTTPError, RFC1123, IP address checks

##### Relationships and Data Flows
- Client flow: Caller invokes HTTPClient → Pipeline: RequestEncoder → Network I/O → ResponseDecoder → Handler surfaces HTTPResponse to caller
- Server flow: Inbound bytes from socket → RequestPartDecoder → Handler constructs HTTPRequest → User-supplied handler returns HTTPResponse → ResponsePartEncoder → Socket write
- WebSocket flow (both client & server): HTTP upgrade handshake (via the HTTPClientUpgradeHandler or HTTPServerUpgradeHandler) → On successful upgrade, raw bytes flow to WebSocketHandler → FrameSequence parser/serializer
- Shared Message types (HTTPRequest/HTTPResponse) pass between client/server pipelines and utility components.

##### Architectural Patterns & Principles
- Pipeline / Chain of Responsibility (Swift NIO handlers)
- Single Responsibility per handler (encode, decode, upgrade, proxy)
- Modular layering: Core protocol model (Message + Headers) sits between transport (handlers) and user API (HTTPClient/HTTPServer)
- Extension points for custom handlers (user can inject additional NIO channel handlers)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "HTTPClient Module"
        HTTPClient["HTTPClient"]:::api
        HTTPClientRequestEncoder["HTTPClientRequestEncoder"]:::client
        HTTPClientResponseDecoder["HTTPClientResponseDecoder"]:::client
        HTTPClientHandler["HTTPClientHandler"]:::client
        HTTPClientProxyHandler["HTTPClientProxyHandler"]:::client
        HTTPClientUpgradeHandler["HTTPClientUpgradeHandler"]:::client
        HTTPClientProtocolUpgrader["HTTPClientProtocolUpgrader"]:::client
    end

    subgraph "HTTPServer Module"
        HTTPServer["HTTPServer"]:::api
        HTTPRequestPartDecoder["HTTPRequestPartDecoder"]:::server
        HTTPServerHandler["HTTPServerHandler"]:::server
        HTTPResponsePartEncoder["HTTPResponsePartEncoder"]:::server
        HTTPServerUpgradeHandler["HTTPServerUpgradeHandler"]:::server
    end

    subgraph "Shared Message & Headers"
        HTTPMessage["HTTPMessage"]:::core
        HTTPRequestType["HTTPRequest"]:::core
        HTTPResponseType["HTTPResponse"]:::core
        HTTPBody["HTTPBody"]:::core
        HTTPCookies["HTTPCookies"]:::core
        HTTPHeaderValue["HTTPHeaderValue"]:::core
        HTTPHeadersBasic["HTTPHeaders+Basic"]:::core
        HTTPHeadersBearer["HTTPHeaders+Bearer"]:::core
        HTTPHeadersName["HTTPHeaders+Name"]:::core
        HTTPMediaType["HTTPMediaType"]:::core
    end

    subgraph "WebSocket Extension"
        WebSocketCore["WebSocket"]:::ws
        WebSocketFrameSequence["WebSocketFrameSequence"]:::ws
        WebSocketHandler["WebSocketHandler"]:::ws
        HTTPRequestWebSocket["HTTPRequest+WebSocket"]:::ws
        HTTPResponseWebSocket["HTTPResponse+WebSocket"]:::ws
        WebSocketClientExt["WebSocket+Client"]:::ws
        WebSocketServerExt["WebSocket+Server"]:::ws
    end

    NetworkIO["Network I/O"]:::network

    %% Client Flow
    HTTPClient --> HTTPClientRequestEncoder -->|"encodes to HTTPMessage"| HTTPMessage
    HTTPClientRequestEncoder --> NetworkIO
    NetworkIO --> HTTPClientResponseDecoder -->|"decodes from HTTPMessage"| HTTPMessage
    HTTPClientResponseDecoder --> HTTPClientHandler
    HTTPClientUpgradeHandler --> WebSocketHandler
    HTTPClientProtocolUpgrader --> WebSocketHandler

    %% Server Flow
    NetworkIO --> HTTPRequestPartDecoder -->|"parses to HTTPRequest"| HTTPRequestType
    HTTPRequestPartDecoder --> HTTPServerHandler -->|"produces HTTPResponse"| HTTPResponseType
    HTTPResponseType --> HTTPResponsePartEncoder --> NetworkIO
    HTTPServerUpgradeHandler --> WebSocketHandler

    %% Core Usage
    HTTPServerHandler --> HTTPMessage
    HTTPClientHandler --> HTTPMessage

    %% Styles
    classDef client fill:#cffafe,stroke:#0ea5e9
    classDef server fill:#dcfce7,stroke:#22c55e
    classDef core fill:#e5e7eb,stroke:#6b7280
    classDef ws fill:#ffedd5,stroke:#f97316
    classDef network fill:#e0e7ff,stroke:#4338ca
    classDef api fill:#bfdbfe,stroke:#3b82f6

    %% Click Events
    click HTTPClient "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Client/HTTPClient.swift"
    click HTTPClientRequestEncoder "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Client/HTTPClientRequestEncoder.swift"
    click HTTPClientResponseDecoder "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Client/HTTPClientResponseDecoder.swift"
    click HTTPClientHandler "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Client/HTTPClientHandler.swift"
    click HTTPClientProxyHandler "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Client/HTTPClientProxyHandler.swift"
    click HTTPClientUpgradeHandler "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Client/HTTPClientUpgradeHandler.swift"
    click HTTPClientProtocolUpgrader "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Client/HTTPClientProtocolUpgrader.swift"
    click HTTPServer "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Server/HTTPServer.swift"
    click HTTPRequestPartDecoder "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Server/HTTPRequestPartDecoder.swift"
    click HTTPResponsePartEncoder "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Server/HTTPResponsePartEncoder.swift"
    click HTTPServerHandler "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Server/HTTPServerHandler.swift"
    click HTTPServerUpgradeHandler "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Server/HTTPServerUpgradeHandler.swift"
    click HTTPMessage "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Message/HTTPMessage.swift"
    click HTTPRequestType "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Message/HTTPRequest.swift"
    click HTTPResponseType "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Message/HTTPResponse.swift"
    click HTTPBody "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Message/HTTPBody.swift"
    click HTTPCookies "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Message/HTTPCookies.swift"
    click HTTPHeaderValue "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Headers/HTTPHeaderValue.swift"
    click HTTPHeadersBasic "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Headers/HTTPHeaders+Basic.swift"
    click HTTPHeadersBearer "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Headers/HTTPHeaders+Bearer.swift"
    click HTTPHeadersName "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Headers/HTTPHeaders+Name.swift"
    click HTTPMediaType "https://github.com/vapor/http/blob/main/Sources/HTTPKit/Headers/HTTPMediaType.swift"
    click WebSocketCore "https://github.com/vapor/http/blob/main/Sources/HTTPKit/WebSocket/WebSocket.swift"
    click WebSocketFrameSequence "https://github.com/vapor/http/blob/main/Sources/HTTPKit/WebSocket/WebSocketFrameSequence.swift"
    click WebSocketHandler "https://github.com/vapor/http/blob/main/Sources/HTTPKit/WebSocket/WebSocketHandler.swift"
    click HTTPRequestWebSocket "https://github.com/vapor/http/blob/main/Sources/HTTPKit/WebSocket/HTTPRequest+WebSocket.swift"
    click HTTPResponseWebSocket "https://github.com/vapor/http/blob/main/Sources/HTTPKit/WebSocket/HTTPResponse+WebSocket.swift"
    click WebSocketClientExt "https://github.com/vapor/http/blob/main/Sources/HTTPKit/WebSocket/WebSocket+Client.swift"
    click WebSocketServerExt "https://github.com/vapor/http/blob/main/Sources/HTTPKit/WebSocket/WebSocket+Server.swift"
```
