# omjadas/hudsucker architecture

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

- Interactive diagram: https://gitdiagram.com/omjadas/hudsucker
- Repository: https://github.com/omjadas/hudsucker

## Overview

Hudsucker is a Rust MITM HTTP/S proxy. Its principal workflow accepts client connections, dispatches requests for HTTP forwarding or CONNECT/WebSocket interception, lets configured handlers modify traffic, and returns the result to the client. Certificate authorities provide per-host TLS server configuration; optional decoder helpers and the shared body type support handler-level message processing. The excerpts show the runtime entry and portions of dispatch, but omit some forwarding details, so uncertain wiring is left out.

Main entry points: [`src/proxy/internal.rs`](https://github.com/omjadas/hudsucker/blob/main/src/proxy/internal.rs) (Connection dispatch), [`src/lib.rs`](https://github.com/omjadas/hudsucker/blob/main/src/lib.rs) (HTTP handler), [`src/certificate_authority/mod.rs`](https://github.com/omjadas/hudsucker/blob/main/src/certificate_authority/mod.rs) (Certificate authority), [`src/proxy/mod.rs`](https://github.com/omjadas/hudsucker/blob/main/src/proxy/mod.rs) (Proxy server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Proxy runtime"]
  node_proxy_builder["Proxy builder<br/>[builder.rs]"]
  node_proxy["Proxy server<br/>[mod.rs]"]
end

subgraph group_interception["Traffic handling"]
  node_dispatch["Connection dispatch<br/>[internal.rs]"]
  node_http_handler["HTTP handler<br/>[lib.rs]"]
  node_websocket_handler["WebSocket handler<br/>[lib.rs]"]
  node_http_connector["HTTP connector<br/>[builder.rs]"]
  node_noop["No-op handler<br/>[noop.rs]"]
end

subgraph group_certificates["Certificate issuance"]
  node_tls_authority["Certificate authority<br/>[mod.rs]"]
  node_rcgen_authority["Rcgen authority<br/>[rcgen_authority.rs]"]
  node_openssl_authority["OpenSSL authority"]
end

subgraph group_message["Message utilities"]
  node_body["HTTP body<br/>[body.rs]"]
  node_decoder["Body decoder<br/>[decoder.rs]"]
  node_rewind["Body rewind<br/>[rewind.rs]"]
  node_tee["Body tee<br/>[tee.rs]"]
end

node_client(("Proxy client"))
node_upstream(("Upstream server"))

node_client -->|"connects"| node_proxy
node_proxy_builder -->|"builds"| node_proxy
node_proxy -->|"dispatches"| node_dispatch
node_dispatch -->|"invokes"| node_http_handler
node_dispatch -->|"forwards HTTP"| node_http_connector
node_http_connector -->|"sends request"| node_upstream
node_dispatch -->|"opens tunnel"| node_upstream
node_dispatch -->|"requests TLS config"| node_tls_authority
node_tls_authority -.->|"implemented by"| node_rcgen_authority
node_tls_authority -.->|"implemented by"| node_openssl_authority
node_dispatch -->|"forwards messages"| node_websocket_handler
node_http_handler -->|"handles bodies"| node_body
node_websocket_handler -->|"returns messages"| node_client
node_upstream -->|"returns traffic"| node_dispatch
node_dispatch -->|"returns response"| node_client
node_http_handler -.->|"may decode"| node_decoder
node_proxy_builder -->|"defaults handlers"| node_noop
node_dispatch --> node_rewind
node_dispatch --> node_tee

click node_proxy_builder "https://github.com/omjadas/hudsucker/blob/main/src/proxy/builder.rs"
click node_proxy "https://github.com/omjadas/hudsucker/blob/main/src/proxy/mod.rs"
click node_dispatch "https://github.com/omjadas/hudsucker/blob/main/src/proxy/internal.rs"
click node_http_handler "https://github.com/omjadas/hudsucker/blob/main/src/lib.rs"
click node_websocket_handler "https://github.com/omjadas/hudsucker/blob/main/src/lib.rs"
click node_http_connector "https://github.com/omjadas/hudsucker/blob/main/src/proxy/builder.rs"
click node_tls_authority "https://github.com/omjadas/hudsucker/blob/main/src/certificate_authority/mod.rs"
click node_rcgen_authority "https://github.com/omjadas/hudsucker/blob/main/src/certificate_authority/rcgen_authority.rs"
click node_openssl_authority "https://github.com/omjadas/hudsucker/blob/main/src/certificate_authority/openssl_authority.rs"
click node_body "https://github.com/omjadas/hudsucker/blob/main/src/body.rs"
click node_decoder "https://github.com/omjadas/hudsucker/blob/main/src/decoder.rs"
click node_noop "https://github.com/omjadas/hudsucker/blob/main/src/noop.rs"
click node_rewind "https://github.com/omjadas/hudsucker/blob/main/src/rewind.rs"
click node_tee "https://github.com/omjadas/hudsucker/blob/main/src/tee.rs"

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_proxy_builder,node_proxy,node_client toneBlue
class node_dispatch,node_http_handler,node_websocket_handler,node_http_connector,node_noop toneAmber
class node_tls_authority,node_rcgen_authority,node_openssl_authority,node_upstream toneMint
class node_body,node_decoder,node_rewind,node_tee toneRose
```

## Components

### Proxy runtime

- [Proxy builder](https://github.com/omjadas/hudsucker/blob/main/src/proxy/builder.rs): `src/proxy/builder.rs`
- [Proxy server](https://github.com/omjadas/hudsucker/blob/main/src/proxy/mod.rs): `src/proxy/mod.rs`

### Traffic handling

- [Connection dispatch](https://github.com/omjadas/hudsucker/blob/main/src/proxy/internal.rs): `src/proxy/internal.rs`
- [HTTP handler](https://github.com/omjadas/hudsucker/blob/main/src/lib.rs): `src/lib.rs`
- [WebSocket handler](https://github.com/omjadas/hudsucker/blob/main/src/lib.rs): `src/lib.rs`
- [HTTP connector](https://github.com/omjadas/hudsucker/blob/main/src/proxy/builder.rs): `src/proxy/builder.rs`
- [No-op handler](https://github.com/omjadas/hudsucker/blob/main/src/noop.rs): `src/noop.rs`

### Certificate issuance

- [Certificate authority](https://github.com/omjadas/hudsucker/blob/main/src/certificate_authority/mod.rs): `src/certificate_authority/mod.rs`
- [Rcgen authority](https://github.com/omjadas/hudsucker/blob/main/src/certificate_authority/rcgen_authority.rs): `src/certificate_authority/rcgen_authority.rs`
- [OpenSSL authority](https://github.com/omjadas/hudsucker/blob/main/src/certificate_authority/openssl_authority.rs): `src/certificate_authority/openssl_authority.rs`

### Message utilities

- [HTTP body](https://github.com/omjadas/hudsucker/blob/main/src/body.rs): `src/body.rs`
- [Body decoder](https://github.com/omjadas/hudsucker/blob/main/src/decoder.rs): `src/decoder.rs`
- [Body rewind](https://github.com/omjadas/hudsucker/blob/main/src/rewind.rs): `src/rewind.rs`
- [Body tee](https://github.com/omjadas/hudsucker/blob/main/src/tee.rs): `src/tee.rs`

### Other components

- **Proxy client**
- **Upstream server**

## Connections

- Proxy client → Proxy server: connects
- Proxy builder → Proxy server: builds
- Proxy server → Connection dispatch: dispatches
- Connection dispatch → HTTP handler: invokes
- Connection dispatch → HTTP connector: forwards HTTP
- HTTP connector → Upstream server: sends request
- Connection dispatch → Upstream server: opens tunnel
- Connection dispatch → Certificate authority: requests TLS config
- Certificate authority → Rcgen authority: implemented by
- Certificate authority → OpenSSL authority: implemented by
- Connection dispatch → WebSocket handler: forwards messages
- HTTP handler → HTTP body: handles bodies
- WebSocket handler → Proxy client: returns messages
- Upstream server → Connection dispatch: returns traffic
- Connection dispatch → Proxy client: returns response
- HTTP handler → Body decoder: may decode
- Proxy builder → No-op handler: defaults handlers
- Connection dispatch → Body rewind
- Connection dispatch → Body tee