horaa-tls 0.1.0__tar.gz

horaa_tls-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amit Haina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

horaa_tls-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: horaa-tls
+Version: 0.1.0
+Summary: Advanced HTTP client with low-level TLS and browser fingerprint spoofing based on Go tls-client FFI
+Author: Amit Haina
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 🌌 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 evade anti-bot security layers (such as Cloudflare Turnstile, Akamai, Imperva, and DataDome). 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 at both the TLS socket and HTTP/2 layer.
+
+---
+
+## 💡 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:
+
+```python
+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()
+```
+
+---
+
+## 🛠️ 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:
+
+```python
+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.register(
+    ProxyRotatorMiddleware(proxies=proxies, mode="failover", max_failovers=3)
+)
+
+# 2. Exponential backoff retry handler for transport/network drops
+session.middleware_pipeline.register(
+    RetryMiddleware(max_retries=3, backoff_factor=2.0, status_forcelist=[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:
+
+```python
+# 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:
+
+```python
+# 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": "/"}
+])
+```

horaa_tls-0.1.0/README.md

@@ -0,0 +1,97 @@
+# 🌌 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 evade anti-bot security layers (such as Cloudflare Turnstile, Akamai, Imperva, and DataDome). 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 at both the TLS socket and HTTP/2 layer.
+
+---
+
+## 💡 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:
+
+```python
+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()
+```
+
+---
+
+## 🛠️ 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:
+
+```python
+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.register(
+    ProxyRotatorMiddleware(proxies=proxies, mode="failover", max_failovers=3)
+)
+
+# 2. Exponential backoff retry handler for transport/network drops
+session.middleware_pipeline.register(
+    RetryMiddleware(max_retries=3, backoff_factor=2.0, status_forcelist=[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:
+
+```python
+# 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:
+
+```python
+# 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": "/"}
+])
+```

horaa_tls-0.1.0/__init__.py

@@ -0,0 +1,13 @@
+from horaa_tls.client import Session, ClientProfile
+from horaa_tls.response import Response, CaseInsensitiveDict
+from horaa_tls.exceptions import HoraaTLSError, BackendError, NetworkError
+
+__all__ = [
+    "Session",
+    "ClientProfile",
+    "Response",
+    "CaseInsensitiveDict",
+    "HoraaTLSError",
+    "BackendError",
+    "NetworkError",
+]

horaa_tls-0.1.0/backend/base.py

@@ -0,0 +1,32 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+
+class BaseBackend(ABC):
+    """Abstract Base Class for pluggable request engines."""
+
+    @abstractmethod
+    def execute(self, request_payload: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Executes an HTTP request synchronously.
+        
+        Args:
+            request_payload: A dictionary of parameters matching the backend requirements.
+            
+        Returns:
+            A dictionary containing response details.
+        """
+        pass
+
+    @abstractmethod
+    async def execute_async(self, request_payload: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Executes an HTTP request asynchronously.
+        
+        Args:
+            request_payload: A dictionary of parameters matching the backend requirements.
+            
+        Returns:
+            A dictionary containing response details.
+        """
+        pass

horaa_tls-0.1.0/backend/ctypes_go.py

@@ -0,0 +1,158 @@
+import ctypes
+import json
+import asyncio
+from typing import Any, Dict
+
+from horaa_tls.backend.base import BaseBackend
+from horaa_tls.exceptions import BackendError
+from horaa_tls.utils.updater import update_if_necessary
+
+
+class CtypesGoBackend(BaseBackend):
+    """
+    Backend implementation that loads the compiled Go tls-client library
+    via ctypes and invokes it in-process.
+    """
+
+    _lib = None
+
+    @classmethod
+    def get_library(cls):
+        """Loads and returns the ctypes Go dynamic library, initializing it on first use."""
+        if cls._lib is None:
+            try:
+                # Retrieve (and download if needed) the precompiled binary
+                lib_path = update_if_necessary()
+                lib = ctypes.cdll.LoadLibrary(lib_path)
+
+                # Define argtypes and restypes for Go-exported C functions
+                lib.request.argtypes = [ctypes.c_char_p]
+                lib.request.restype = ctypes.c_char_p
+
+                lib.freeMemory.argtypes = [ctypes.c_char_p]
+                lib.freeMemory.restype = ctypes.c_char_p
+
+                lib.getCookiesFromSession.argtypes = [ctypes.c_char_p]
+                lib.getCookiesFromSession.restype = ctypes.c_char_p
+
+                lib.addCookiesToSession.argtypes = [ctypes.c_char_p]
+                lib.addCookiesToSession.restype = ctypes.c_char_p
+
+                lib.destroySession.argtypes = [ctypes.c_char_p]
+                lib.destroySession.restype = ctypes.c_char_p
+
+                lib.destroyAll.argtypes = []
+                lib.destroyAll.restype = ctypes.c_char_p
+
+                cls._lib = lib
+            except Exception as e:
+                raise BackendError(f"Failed to load and initialize Go shared library: {e}")
+        return cls._lib
+
+    def _execute_sync(self, request_payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Wrapper around the ctypes C call to request and free memory in Go."""
+        lib = self.get_library()
+        # Clean request payload by removing private keys starting with '_' (used for Python middleware state)
+        clean_payload = {k: v for k, v in request_payload.items() if not k.startswith("_")}
+        payload_bytes = json.dumps(clean_payload).encode("utf-8")
+        
+        # Call Go library to execute request
+        response_ptr = lib.request(payload_bytes)
+        if not response_ptr:
+            raise BackendError("Null pointer returned from Go request execution.")
+
+        try:
+            # Read from C string pointer
+            response_bytes = ctypes.string_at(response_ptr)
+            response_data = json.loads(response_bytes.decode("utf-8"))
+        except Exception as e:
+            raise BackendError(f"Failed to parse Go response: {e}")
+        finally:
+            # Always call freeMemory to release the C-string allocated by Go FFI
+            if "response_data" in locals() and isinstance(response_data, dict) and "id" in response_data:
+                response_id = response_data["id"].encode("utf-8")
+                lib.freeMemory(response_id)
+
+        return response_data
+
+    def execute(self, request_payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Execute request synchronously."""
+        return self._execute_sync(request_payload)
+
+    async def execute_async(self, request_payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Execute request asynchronously by running the blocking ctypes call in an executor."""
+        loop = asyncio.get_running_loop()
+        # run_in_executor runs the synchronous FFI block in a background thread to prevent GIL stalling
+        return await loop.run_in_executor(None, self._execute_sync, request_payload)
+
+    def get_cookies(self, session_id: str, url: str) -> list:
+        """Fetch cookies stored in the Go session memory for a given URL."""
+        lib = self.get_library()
+        payload = json.dumps({"sessionId": session_id, "url": url}).encode("utf-8")
+        response_ptr = lib.getCookiesFromSession(payload)
+        
+        if not response_ptr:
+            return []
+
+        try:
+            response_bytes = ctypes.string_at(response_ptr)
+            res_obj = json.loads(response_bytes.decode("utf-8"))
+            cookies = res_obj.get("cookies", [])
+            return cookies
+        finally:
+            if "res_obj" in locals() and isinstance(res_obj, dict) and "id" in res_obj:
+                lib.freeMemory(res_obj["id"].encode("utf-8"))
+
+    def add_cookies(self, session_id: str, url: str, cookies: list) -> list:
+        """Add cookies into Go session memory for a given URL."""
+        lib = self.get_library()
+        payload = json.dumps({
+            "sessionId": session_id,
+            "url": url,
+            "cookies": cookies
+        }).encode("utf-8")
+        response_ptr = lib.addCookiesToSession(payload)
+        
+        if not response_ptr:
+            return []
+
+        try:
+            response_bytes = ctypes.string_at(response_ptr)
+            res_obj = json.loads(response_bytes.decode("utf-8"))
+            return res_obj.get("cookies", [])
+        finally:
+            if "res_obj" in locals() and isinstance(res_obj, dict) and "id" in res_obj:
+                lib.freeMemory(res_obj["id"].encode("utf-8"))
+
+    def destroy_session(self, session_id: str) -> bool:
+        """Destroys the session inside Go memory, releasing connections."""
+        lib = self.get_library()
+        payload = json.dumps({"sessionId": session_id}).encode("utf-8")
+        response_ptr = lib.destroySession(payload)
+        
+        if not response_ptr:
+            return False
+
+        try:
+            response_bytes = ctypes.string_at(response_ptr)
+            res_obj = json.loads(response_bytes.decode("utf-8"))
+            return res_obj.get("success", False)
+        finally:
+            if "res_obj" in locals() and isinstance(res_obj, dict) and "id" in res_obj:
+                lib.freeMemory(res_obj["id"].encode("utf-8"))
+
+    def destroy_all_sessions(self) -> bool:
+        """Destroys all active sessions inside Go memory."""
+        lib = self.get_library()
+        response_ptr = lib.destroyAll()
+        
+        if not response_ptr:
+            return False
+
+        try:
+            response_bytes = ctypes.string_at(response_ptr)
+            res_obj = json.loads(response_bytes.decode("utf-8"))
+            return res_obj.get("success", False)
+        finally:
+            if "res_obj" in locals() and isinstance(res_obj, dict) and "id" in res_obj:
+                lib.freeMemory(res_obj["id"].encode("utf-8"))