# encode/httpcore architecture

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

- Interactive diagram: https://gitdiagram.com/encode/httpcore
- Repository: https://github.com/encode/httpcore

## Overview

##### Project type and purpose
- HTTP Core is a low-level, language-native HTTP client library (an open-source tool), providing only request/response mechanics, connection pooling, proxy support, and HTTP/1.1 & HTTP/2 implementations. It exposes both synchronous and asynchronous APIs to serve as a foundational building block for higher-level HTTP clients.

##### File structure
- Top-level directories:
- httpcore/            ← main package
- docs/                ← user documentation
- scripts/             ← helper scripts (build, test, lint, etc.)
- tests/               ← test suites (sync, async, benchmark)
- Inside httpcore/:
- _api.py              ← public-facing convenience functions
- _async/              ← async interfaces & implementations
- _sync/               ← sync interfaces & implementations
- _backends/           ← pluggable network-backend abstractions
- _models.py           ← shared data structures (Request, Response)
- _exceptions.py       ← error definitions
- _ssl.py, _utils.py   ← supporting utilities
- _synchronization.py  ← concurrency primitives
- _trace.py            ← instrumentation/tracing hooks
- Configuration files:
- pyproject.toml, requirements.txt, mkdocs.yml
- .github/workflows/*.yml

##### README for additional insights
- Emphasizes the split between “networking code” and “client logic.”
- Supports optional extras: anyio, trio, h2, socksio.
- Targets Python 3.8+, uses SEMVER, intended as a backend for higher‐level clients (e.g., HTTPX).

1) Public API Layer
– httpcore.request() and ConnectionPool constructors
2) Interface Layer
– Sync Interface (httpcore._sync)
– Async Interface (httpcore._async)
3) Connection Pool
– Manages connection lifecycles, pools per origin
4) Protocol Layer
– HTTP/1.1 handler (h11)
– HTTP/2 handler (h2)
5) Proxy Layer
– HTTP proxy, SOCKS proxy implementations
6) Backend Abstraction
– anyio, asyncio, trio, sync backends
7) External Dependencies
– h11, h2, socksio, certifi
8) Network I/O
– OS sockets, TLS handshake
9) Remote Services
– Internet host, optional Proxy servers

– Client code → Public API Layer → selects Sync vs Async → Connection Pool
– Connection Pool → Protocol Layer → Proxy Layer (if configured) → Backend
– Backend → OS socket calls → Remote Service (HTTP server or Proxy)
– Responses flow back along the same path in reverse

c. Architectural patterns
– Layered pattern: clear separation of concerns (API, pooling, protocol, transport)
– Adapter pattern: pluggable backends (asyncio/trio/anyio/sync)
– Factory/injection: optional extras loaded dynamically for HTTP2 or SOCKS

d. Relevant technologies & frameworks
– Python’s async/await, anyio, asyncio, trio
– h11 for HTTP/1.1
– h2 for HTTP/2
– socksio for SOCKS proxy
– certifi for TLS trust store

##### Essential elements
- Component labels matching actual package paths (e.g., httpcore._async.connection_pool).
- Notes on optional paths (HTTP2 vs HTTP1.1, proxy vs direct).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Utilities and Support
    subgraph "Core Utilities & Support"
        Models["httpcore/_models.py"]:::internal
        Exceptions["httpcore/_exceptions.py"]:::internal
        SyncPrims["httpcore/_synchronization.py"]:::internal
        Trace["httpcore/_trace.py"]:::internal
        SSL["httpcore/_ssl.py"]:::internal
        Utils["httpcore/_utils.py"]:::internal
    end

    %% Public API Layer
    API["httpcore/_api.py"]:::internal

    %% Interface Layer
    subgraph "Interface Layer"
        SyncLayer["Sync Interface\nhttpcore/_sync"]:::internal
        AsyncLayer["Async Interface\nhttpcore/_async"]:::internal
    end

    %% Connection Pool Layer
    subgraph "Connection Pool Layer"
        SyncPool["Sync ConnectionPool\n_sync/connection_pool.py"]:::internal
        AsyncPool["Async ConnectionPool\n_async/connection_pool.py"]:::internal
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        HTTP11Sync["HTTP/1.1 Sync\n_sync/http11.py"]:::internal
        HTTP2Sync["HTTP/2 Sync\n_sync/http2.py"]:::internal
        HTTP11Async["HTTP/1.1 Async\n_async/http11.py"]:::internal
        HTTP2Async["HTTP/2 Async\n_async/http2.py"]:::internal
    end

    %% Proxy Layer
    subgraph "Proxy Layer"
        HTTPProxySync["HTTP Proxy Sync\n_sync/http_proxy.py"]:::internal
        SOCKSProxySync["SOCKS Proxy Sync\n_sync/socks_proxy.py"]:::internal
        HTTPProxyAsync["HTTP Proxy Async\n_async/http_proxy.py"]:::internal
        SOCKSProxyAsync["SOCKS Proxy Async\n_async/socks_proxy.py"]:::internal
    end

    %% Backend Abstraction
    Backends["httpcore/_backends"]:::internal

    %% External Dependencies
    subgraph "External Dependencies"
        H11["h11"]:::external
        H2["h2"]:::external
        SocksIO["socksio"]:::external
        Certifi["certifi"]:::external
        AnyIO["anyio"]:::external
        TrioLib["trio"]:::external
        AsyncIO["asyncio"]:::external
    end

    %% Network I/O
    subgraph "Network I/O"
        OSSocket["OS Sockets & TLS Handshake"]:::network
    end

    %% Remote Services
    subgraph "Remote Services"
        Origin["Origin HTTP Server"]:::external
        ProxyServer["Proxy Server"]:::external
    end

    %% Connections
    API -->|"calls"| SyncLayer
    API -->|"calls"| AsyncLayer

    SyncLayer -->|"uses"| SyncPool
    AsyncLayer -->|"uses"| AsyncPool

    SyncPool -->|"dispatch to"| HTTP11Sync
    SyncPool -->|"dispatch to"| HTTP2Sync
    AsyncPool -->|"dispatch to"| HTTP11Async
    AsyncPool -->|"dispatch to"| HTTP2Async

    HTTP11Sync -->|"through proxy?"| HTTPProxySync
    HTTP11Sync -->|"direct"| Backends
    HTTP2Sync -->|"through proxy?"| HTTPProxySync
    HTTP2Sync -->|"direct"| Backends

    HTTP11Async -->|"through proxy?"| HTTPProxyAsync
    HTTP11Async -->|"direct"| Backends
    HTTP2Async -->|"through proxy?"| HTTPProxyAsync
    HTTP2Async -->|"direct"| Backends

    HTTPProxySync -->|"adapter to"| Backends
    SOCKSProxySync -->|"adapter to"| Backends
    HTTPProxyAsync -->|"adapter to"| Backends
    SOCKSProxyAsync -->|"adapter to"| Backends

    Backends -->|"executes I/O"| OSSocket
    OSSocket -->|"network I/O"| Origin
    OSSocket -->|"network I/O"| ProxyServer

    %% Utilities usage
    SyncLayer --> Models
    AsyncLayer --> Models
    SyncLayer --> Exceptions
    AsyncLayer --> Exceptions
    SyncLayer --> SyncPrims
    AsyncLayer --> SyncPrims
    SyncLayer --> Trace
    AsyncLayer --> Trace
    SyncLayer --> SSL
    AsyncLayer --> SSL
    SyncLayer --> Utils
    AsyncLayer --> Utils

    %% Click Events
    click API "https://github.com/encode/httpcore/blob/master/httpcore/_api.py"
    click SyncLayer "https://github.com/encode/httpcore/tree/master/httpcore/_sync/"
    click AsyncLayer "https://github.com/encode/httpcore/tree/master/httpcore/_async/"
    click SyncPool "https://github.com/encode/httpcore/blob/master/httpcore/_sync/connection_pool.py"
    click AsyncPool "https://github.com/encode/httpcore/blob/master/httpcore/_async/connection_pool.py"
    click HTTP11Sync "https://github.com/encode/httpcore/blob/master/httpcore/_sync/http11.py"
    click HTTP2Sync "https://github.com/encode/httpcore/blob/master/httpcore/_sync/http2.py"
    click HTTP11Async "https://github.com/encode/httpcore/blob/master/httpcore/_async/http11.py"
    click HTTP2Async "https://github.com/encode/httpcore/blob/master/httpcore/_async/http2.py"
    click HTTPProxySync "https://github.com/encode/httpcore/blob/master/httpcore/_sync/http_proxy.py"
    click SOCKSProxySync "https://github.com/encode/httpcore/blob/master/httpcore/_sync/socks_proxy.py"
    click HTTPProxyAsync "https://github.com/encode/httpcore/blob/master/httpcore/_async/http_proxy.py"
    click SOCKSProxyAsync "https://github.com/encode/httpcore/blob/master/httpcore/_async/socks_proxy.py"
    click Backends "https://github.com/encode/httpcore/tree/master/httpcore/_backends/"
    click Models "https://github.com/encode/httpcore/blob/master/httpcore/_models.py"
    click Exceptions "https://github.com/encode/httpcore/blob/master/httpcore/_exceptions.py"
    click SyncPrims "https://github.com/encode/httpcore/blob/master/httpcore/_synchronization.py"
    click Trace "https://github.com/encode/httpcore/blob/master/httpcore/_trace.py"
    click SSL "https://github.com/encode/httpcore/blob/master/httpcore/_ssl.py"
    click Utils "https://github.com/encode/httpcore/blob/master/httpcore/_utils.py"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#1f4e79,color:#000
    classDef external fill:#ccffcc,stroke:#27632a,color:#000
    classDef network fill:#ffebcc,stroke:#b35b00,color:#000
```
