🌌 Horaa TLS

State-of-the-art in-process browser fingerprint emulation and HTTP client for Python.

horaa-tls is a high-performance HTTP client designed to spoof browser TLS and HTTP/2 characteristics. By interfacing directly with a precompiled Go-based BoringSSL networking backend via a ctypes FFI wrapper, it maintains a footprint indistinguishable from a real web browser to evade fingerprint-based anti-bot detection.

⚙️ Installation

Install horaa-tls directly from PyPI:

pip install horaa-tls

🛡️ Capabilities & Limitations

• What it DOES bypass: Bypasses passive fingerprinting blocks (such as JA3/JA4 TLS signatures, HTTP/2 frames configuration, and User-Agent/Client Hint alignment) enforced by Cloudflare, Akamai, and Imperva.
• What it DOES NOT bypass: As a socket-level HTTP client, it does not run a browser engine or execute JavaScript. It cannot automatically solve interactive browser challenges (like Cloudflare Turnstile checkboxes or JS challenge walls). To access pages protected by active challenges, you must solve them using browser automation (or a solver) and pass the resulting session cookies/tokens to the client.

💡 Why Horaa TLS?

• Zero External Dependencies: Automatically detects your OS and architecture, downloads the matching precompiled Go libraries, and initializes everything dynamically without requiring third-party pip dependencies.
• Cryptographic Emulation: Leverages preset browser profiles (Chrome 133, Firefox 133, etc.) to negotiate matching TLS extensions, cipher suites, key share curves, and HTTP/2 settings.
• Aligned User-Agents & Client Hints: Keeps HTTP/2 Client Hints (Sec-Ch-Ua, Sec-Ch-Ua-Mobile, Sec-Ch-Ua-Platform) perfectly aligned with the selected browser TLS version to prevent anti-bot detection signals.
• Decoupled Middleware Hooks: Register asynchronous or synchronous middleware layers (such as rotators and retries) directly in the request-response cycle.

🚀 Quick Start (The One-Minute Tour)

Initialize a session mimicking a Chrome 133 browser:

from horaa_tls import Session, ClientProfile

# Create a stateful, browser-emulating session
session = Session(profile=ClientProfile.CHROME_133)

try:
    # Perform a request (headers, JA3/JA4, and Client Hints are automatically injected)
    response = session.get("https://httpbingo.org/get")
    print(f"Status Code: {response.status_code}")
    print(response.json())
finally:
    # Always close the session to release low-level FFI memory allocations
    session.close()

📦 Public API (What You Can Import)

Everything below is available directly from the top-level horaa_tls package:

from horaa_tls import (
    Session,             # main worker: sends requests, holds cookies/state
    ClientProfile,       # enum of browser profiles to emulate
    Response,            # object returned by requests (.status_code, .json(), .text, .cookies)
    CaseInsensitiveDict, # header container where key case doesn't matter
    Protocol,            # HTTP protocol enum (H1 / HTTP/1.1 / HTTP/2)
    HoraaTLSError,       # base exception for the library
    BackendError,        # raised when the Go FFI layer fails
    NetworkError,        # raised on transport failures / HTTP error status
)

Tip: you can pass profiles as the enum (ClientProfile.CHROME_133) or as a plain string ("chrome_133"), both work.

🛠️ Core Concepts & Advanced Guide

🧬 Aligned Browser Profiles

horaa-tls currently offers pre-configured emulation profiles:

• Chrome Series: chrome_103, chrome_110, chrome_120, chrome_133
• Firefox Series: firefox_117, firefox_123, firefox_133
• Safari Series: safari_16_0, safari_ios_17_0
• Opera Series: opera_90

🏗️ Stateful Middleware Pipeline

You can easily intercept, modify, or retry requests using the built-in middleware engine. Registering rotators or exponential backoffs is straightforward:

from horaa_tls import Session, ClientProfile
from horaa_tls.middleware.proxy import ProxyRotatorMiddleware
from horaa_tls.middleware.retry import RetryMiddleware

session = Session(profile=ClientProfile.CHROME_133)

# 1. State-aware proxy rotator with failover recovery
proxies = ["http://proxy1.example.com:8080", "http://proxy2.example.com:8080"]
session.middleware_pipeline.add(
    ProxyRotatorMiddleware(proxies=proxies, mode="failover", max_failovers=3)
)

# 2. Exponential backoff retry handler for transport/network drops
session.middleware_pipeline.add(
    RetryMiddleware(max_retries=3, backoff_factor=2.0, retry_on_status=(500, 502, 503, 504))
)

# Request executes automatically through the middleware pipeline
res = session.get("https://httpbingo.org/get")
session.close()

📦 Session Snapshots (Persistence)

Export and restore session states (cookies, custom headers, active proxies, and middleware indicators) to distribute scraper instances across servers or queues:

# Save current state
session_state_json = session.to_json()

# Recreate an identical session in a different worker/process
restored_session = Session.from_json(session_state_json)

🍪 Direct FFI Cookie Management

Interact directly with the Go-layer cookie jar for fine-grained token/session management:

# Read active cookies stored in the Go memory layer
cookies = session.get_cookies_from_backend("https://example.com")

# Inject cookies directly into the Go-layer FFI engine
session.add_cookies_to_backend("https://example.com", [
    {"name": "session_token", "value": "token_value", "domain": ".example.com", "path": "/"}
])

Contributing

Pull requests are welcome. If you open one, please describe your changes properly in the PR description so it's clear what you changed and why.

Contact