Skip to content

Core Components

This page documents the core classes and functions in httptap.

HTTPTapAnalyzer

The main analyzer class that orchestrates HTTP request analysis.

Constructor

HTTPTapAnalyzer(
    dns_resolver: DNSResolverProtocol | None = None,
    tls_inspector: TLSInspectorProtocol | None = None,
    timing_provider: TimingProviderProtocol | None = None
)

Parameters:

  • dns_resolver - Custom DNS resolver implementation (optional)
  • tls_inspector - Custom TLS inspector implementation (optional)
  • timing_provider - Custom timing provider implementation (optional)

If not provided, default implementations are used.

Methods

analyze_url()

def analyze_url(
    self,
    url: str,
    *,
    headers: dict[str, str] | None = None,
    follow_redirects: bool = False
) -> list[RequestStep]

Analyze an HTTP request and return detailed timing information.

Parameters:

  • url - The URL to analyze (must include scheme: http:// or https://)
  • headers - Optional custom HTTP headers
  • follow_redirects - Whether to follow HTTP redirects

Returns:

  • list[RequestStep] - List of request steps (one per redirect)

Raises:

  • ValueError - If URL is invalid
  • TimeoutError - If request times out
  • ConnectionError - If connection fails

Example:

from httptap import HTTPTapAnalyzer

analyzer = HTTPTapAnalyzer()
steps = analyzer.analyze_url(
    "https://httpbin.io",
    headers={"Accept": "application/json"},
    follow_redirects=True
)

Data Models

RequestStep

Represents a single HTTP request/response cycle.

@dataclass
class RequestStep:
    url: str                    # Request URL
    step_number: int           # Step number in redirect chain
    timing: TimingInfo         # Timing information
    network: NetworkInfo       # Network details
    response: ResponseInfo     # Response data
    error: str | None          # Error message if failed
    note: str | None           # Additional notes

TimingInfo

Contains detailed timing breakdown for the request.

@dataclass
class TimingInfo:
    dns_ms: float              # DNS resolution time
    connect_ms: float          # TCP connection time
    tls_ms: float              # TLS handshake time
    ttfb_ms: float             # Time to first byte
    total_ms: float            # Total request time
    wait_ms: float             # Server processing time
    xfer_ms: float             # Body transfer time
    is_estimated: bool         # Whether timing is estimated

NetworkInfo

Contains network-level details about the connection.

@dataclass
class NetworkInfo:
    ip: str                    # IP address
    ip_family: str             # "IPv4" or "IPv6"
    http_version: str          # HTTP protocol version
    tls_version: str           # TLS protocol version
    tls_cipher: str            # Cipher suite name
    cert_cn: str               # Certificate common name
    cert_days_left: int        # Days until certificate expires

ResponseInfo

Contains HTTP response metadata.

@dataclass
class ResponseInfo:
    status: int                # HTTP status code
    bytes: int                 # Response body size
    content_type: str | None   # Content-Type header
    server: str | None         # Server header
    date: str | None           # Response date
    location: str | None       # Location header (redirects)
    headers: dict[str, str]    # All response headers

Utility Functions

format_duration()

Format duration in milliseconds to human-readable string.

from httptap.utils import format_duration

formatted = format_duration(1234.56)  # "1234.6ms"

parse_certificate()

Extract certificate information from SSL connection.

from httptap.utils import parse_certificate

cert_info = parse_certificate(ssl_cert_dict)
# Returns: (common_name, days_until_expiry)

detect_ip_family()

Determine if an IP address is IPv4 or IPv6.

from httptap.utils import detect_ip_family

family = detect_ip_family("192.168.1.1")     # "IPv4"
family = detect_ip_family("2001:db8::1")     # "IPv6"

Constants

Default Timeouts

from httptap.constants import (
    DEFAULT_TIMEOUT,        # 30.0 seconds
    DNS_TIMEOUT,           # 5.0 seconds
    TLS_TIMEOUT,           # 10.0 seconds
    REQUEST_TIMEOUT        # 30.0 seconds
)

HTTP Settings

from httptap.constants import (
    DEFAULT_USER_AGENT,    # "httptap/X.Y.Z"
    MAX_REDIRECTS,         # 10
    MAX_BODY_SIZE          # 10 MB
)

Example: Complete Usage

from httptap import HTTPTapAnalyzer
from httptap.implementations import SystemDNSResolver, SocketTLSInspector

# Create analyzer with custom components
resolver = SystemDNSResolver()
inspector = SocketTLSInspector()

analyzer = HTTPTapAnalyzer(
    dns_resolver=resolver,
    tls_inspector=inspector
)

# Analyze with custom headers
steps = analyzer.analyze_url(
    "https://httpbin.io/bearer",
    headers={
        "Authorization": "Bearer token123",
        "Accept": "application/json",
        "User-Agent": "MyApp/1.0"
    },
    follow_redirects=True
)

# Process results
for step in steps:
    print(f"Step {step.step_number}: {step.url}")
    print(f"  Status: {step.response.status}")
    print(f"  DNS: {step.timing.dns_ms:.2f}ms")
    print(f"  Connect: {step.timing.connect_ms:.2f}ms")
    print(f"  TLS: {step.timing.tls_ms:.2f}ms")
    print(f"  TTFB: {step.timing.ttfb_ms:.2f}ms")
    print(f"  Total: {step.timing.total_ms:.2f}ms")
    print(f"  IP: {step.network.ip} ({step.network.ip_family})")
    print(f"  HTTP: {step.network.http_version}")
    print(f"  TLS: {step.network.tls_version}")
    print(f"  Certificate: {step.network.cert_cn} "
          f"(expires in {step.network.cert_days_left} days)")

What's Next?