# httprb/http architecture

> Architecture diagram of the GitHub repository httprb/http, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/httprb/http
- Repository: https://github.com/httprb/http

## Overview

http.rb is a Ruby HTTP client: callers configure a chainable session, construct requests, exchange them over managed connections, and receive parsed, streamable responses. The graph includes the documented persistent-session, redirect, timeout, retry, feature, and form-encoding capabilities. Sampled excerpts support the session/client, request-building, response-parsing, and retry relationships; unsampled subsystem links are limited to those documented or directly evident from the tree.

Main entry points: [`lib/http/session.rb`](https://github.com/httprb/http/blob/main/lib/http/session.rb) (Session), [`lib/http/client.rb`](https://github.com/httprb/http/blob/main/lib/http/client.rb) (HTTP client), [`lib/http/feature.rb`](https://github.com/httprb/http/blob/main/lib/http/feature.rb) (Feature middleware), [`lib/http/request/builder.rb`](https://github.com/httprb/http/blob/main/lib/http/request/builder.rb) (Request builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_entry["HTTP API<br/>[http.rb]"]
  node_chain["Chainable config<br/>[chainable.rb]"]
  node_session["Session<br/>[session.rb]"]
  node_options["Options<br/>[definitions.rb]"]
end

subgraph group_request["Request Processing"]
  node_builder["Request builder<br/>[builder.rb]"]
  node_request_obj["Request<br/>[request.rb]"]
  node_forms["Form encoding<br/>[form_data.rb]"]
  node_uri["URI handling<br/>[parsing.rb]"]
end

subgraph group_transport["Transport and Response"]
  node_client["HTTP client<br/>[client.rb]"]
  node_connection["Connection<br/>[connection.rb]"]
  node_writer["Request writer<br/>[writer.rb]"]
  node_parser["Response parser<br/>[parser.rb]"]
  node_response["Response<br/>[response.rb]"]
  node_response_body["Streaming body<br/>[body.rb]"]
  node_timeout["Timeout handling<br/>[per_operation.rb]"]
end

subgraph group_capabilities["Client Capabilities"]
  node_redirect["Redirector<br/>[redirector.rb]"]
  node_retry["Retry performer<br/>[performer.rb]"]
  node_features["Feature middleware<br/>[feature.rb]"]
  node_digest["Digest auth<br/>[digest_auth.rb]"]
  node_cache["Response caching<br/>[caching.rb]"]
  node_cache_store[("Memory cache<br/>[in_memory_store.rb]")]
  node_compression["Compression<br/>[auto_deflate.rb]"]
  node_logging["Logging and metrics<br/>[instrumentation.rb]"]
end

node_caller(("Ruby caller"))

node_caller -->|"calls"| node_entry
node_entry -->|"exposes"| node_chain
node_chain -->|"configures"| node_session
node_session -->|"merges options"| node_options
node_session -->|"builds request"| node_builder
node_builder -->|"resolves URI"| node_uri
node_builder -->|"encodes form"| node_forms
node_builder -->|"creates request"| node_request_obj
node_session -->|"performs request"| node_client
node_client -->|"processes request"| node_request_obj
node_client -->|"uses connection"| node_connection
node_connection -->|"writes request"| node_writer
node_connection -->|"feeds response bytes"| node_parser
node_parser -->|"parses response"| node_response
node_response -->|"provides body"| node_response_body
node_client -->|"delegates retries"| node_retry
node_client -->|"applies features"| node_features
node_session -->|"follows redirects"| node_redirect
node_connection -->|"uses I/O timeouts"| node_timeout
node_features -->|"registers feature"| node_digest
node_features -->|"registers feature"| node_cache
node_cache -->|"stores entries"| node_cache_store
node_features -->|"registers feature"| node_compression
node_features -->|"registers feature"| node_logging

click node_entry "https://github.com/httprb/http/blob/main/lib/http.rb"
click node_chain "https://github.com/httprb/http/blob/main/lib/http/chainable.rb"
click node_session "https://github.com/httprb/http/blob/main/lib/http/session.rb"
click node_options "https://github.com/httprb/http/blob/main/lib/http/options/definitions.rb"
click node_builder "https://github.com/httprb/http/blob/main/lib/http/request/builder.rb"
click node_request_obj "https://github.com/httprb/http/blob/main/lib/http/request.rb"
click node_forms "https://github.com/httprb/http/blob/main/lib/http/form_data.rb"
click node_uri "https://github.com/httprb/http/blob/main/lib/http/uri/parsing.rb"
click node_client "https://github.com/httprb/http/blob/main/lib/http/client.rb"
click node_connection "https://github.com/httprb/http/blob/main/lib/http/connection.rb"
click node_writer "https://github.com/httprb/http/blob/main/lib/http/request/writer.rb"
click node_parser "https://github.com/httprb/http/blob/main/lib/http/response/parser.rb"
click node_response "https://github.com/httprb/http/blob/main/lib/http/response.rb"
click node_response_body "https://github.com/httprb/http/blob/main/lib/http/response/body.rb"
click node_timeout "https://github.com/httprb/http/blob/main/lib/http/timeout/per_operation.rb"
click node_redirect "https://github.com/httprb/http/blob/main/lib/http/redirector.rb"
click node_retry "https://github.com/httprb/http/blob/main/lib/http/retriable/performer.rb"
click node_features "https://github.com/httprb/http/blob/main/lib/http/feature.rb"
click node_digest "https://github.com/httprb/http/blob/main/lib/http/features/digest_auth.rb"
click node_cache "https://github.com/httprb/http/blob/main/lib/http/features/caching.rb"
click node_cache_store "https://github.com/httprb/http/blob/main/lib/http/features/caching/in_memory_store.rb"
click node_compression "https://github.com/httprb/http/blob/main/lib/http/features/auto_deflate.rb"
click node_logging "https://github.com/httprb/http/blob/main/lib/http/features/instrumentation.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_chain,node_session,node_options toneBlue
class node_builder,node_request_obj,node_forms,node_uri toneAmber
class node_client,node_connection,node_writer,node_parser,node_response,node_response_body,node_timeout toneMint
class node_redirect,node_retry,node_features,node_digest,node_cache,node_cache_store,node_compression,node_logging toneRose
class node_caller toneIndigo
```

## Components

### Public API

- [HTTP API](https://github.com/httprb/http/blob/main/lib/http.rb): `lib/http.rb`
- [Chainable config](https://github.com/httprb/http/blob/main/lib/http/chainable.rb): `lib/http/chainable.rb`
- [Session](https://github.com/httprb/http/blob/main/lib/http/session.rb): `lib/http/session.rb`
- [Options](https://github.com/httprb/http/blob/main/lib/http/options/definitions.rb): `lib/http/options/definitions.rb`

### Request Processing

- [Request builder](https://github.com/httprb/http/blob/main/lib/http/request/builder.rb): `lib/http/request/builder.rb`
- [Request](https://github.com/httprb/http/blob/main/lib/http/request.rb): `lib/http/request.rb`
- [Form encoding](https://github.com/httprb/http/blob/main/lib/http/form_data.rb): `lib/http/form_data.rb`
- [URI handling](https://github.com/httprb/http/blob/main/lib/http/uri/parsing.rb): `lib/http/uri/parsing.rb`

### Transport and Response

- [HTTP client](https://github.com/httprb/http/blob/main/lib/http/client.rb): `lib/http/client.rb`
- [Connection](https://github.com/httprb/http/blob/main/lib/http/connection.rb): `lib/http/connection.rb`
- [Request writer](https://github.com/httprb/http/blob/main/lib/http/request/writer.rb): `lib/http/request/writer.rb`
- [Response parser](https://github.com/httprb/http/blob/main/lib/http/response/parser.rb): `lib/http/response/parser.rb`
- [Response](https://github.com/httprb/http/blob/main/lib/http/response.rb): `lib/http/response.rb`
- [Streaming body](https://github.com/httprb/http/blob/main/lib/http/response/body.rb): `lib/http/response/body.rb`
- [Timeout handling](https://github.com/httprb/http/blob/main/lib/http/timeout/per_operation.rb): `lib/http/timeout/per_operation.rb`

### Client Capabilities

- [Redirector](https://github.com/httprb/http/blob/main/lib/http/redirector.rb): `lib/http/redirector.rb`
- [Retry performer](https://github.com/httprb/http/blob/main/lib/http/retriable/performer.rb): `lib/http/retriable/performer.rb`
- [Feature middleware](https://github.com/httprb/http/blob/main/lib/http/feature.rb): `lib/http/feature.rb`
- [Digest auth](https://github.com/httprb/http/blob/main/lib/http/features/digest_auth.rb): `lib/http/features/digest_auth.rb`
- [Response caching](https://github.com/httprb/http/blob/main/lib/http/features/caching.rb): `lib/http/features/caching.rb`
- [Memory cache](https://github.com/httprb/http/blob/main/lib/http/features/caching/in_memory_store.rb): `lib/http/features/caching/in_memory_store.rb`
- [Compression](https://github.com/httprb/http/blob/main/lib/http/features/auto_deflate.rb): `lib/http/features/auto_deflate.rb`
- [Logging and metrics](https://github.com/httprb/http/blob/main/lib/http/features/instrumentation.rb): `lib/http/features/instrumentation.rb`

### Other components

- **Ruby caller**

## Connections

- Ruby caller → HTTP API: calls
- HTTP API → Chainable config: exposes
- Chainable config → Session: configures
- Session → Options: merges options
- Session → Request builder: builds request
- Request builder → URI handling: resolves URI
- Request builder → Form encoding: encodes form
- Request builder → Request: creates request
- Session → HTTP client: performs request
- HTTP client → Request: processes request
- HTTP client → Connection: uses connection
- Connection → Request writer: writes request
- Connection → Response parser: feeds response bytes
- Response parser → Response: parses response
- Response → Streaming body: provides body
- HTTP client → Retry performer: delegates retries
- HTTP client → Feature middleware: applies features
- Session → Redirector: follows redirects
- Connection → Timeout handling: uses I/O timeouts
- Feature middleware → Digest auth: registers feature
- Feature middleware → Response caching: registers feature
- Response caching → Memory cache: stores entries
- Feature middleware → Compression: registers feature
- Feature middleware → Logging and metrics: registers feature