chore: ignore .claude/ dir (CLAUDE.md now lives under .claude/)

Signed-off-by: disqualifier <dev@disqualifier.me>

.gitignore

@@ -1,5 +1,5 @@
 # claude
-CLAUDE.md
+.claude/
 
 # python
 __pycache__/

README.md

@@ -22,17 +22,17 @@ you want; importing the package never fails because an extra is missing.
 `requirements.txt` (pick the extra you need):
 
 ```
-aioweb_tls[curl]  @ git+ssh://git@git.rethinkstudios.io/rethink-public/aioweb_tls.git@v0.1.0
+aioweb_tls[curl]  @ git+ssh://git@git.rethinkstudios.io/rethink-public/aioweb_tls.git@v0.1.3
-aioweb_tls[noble] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aioweb_tls.git@v0.1.0
+aioweb_tls[noble] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aioweb_tls.git@v0.1.3
-aioweb_tls[all]   @ git+ssh://git@git.rethinkstudios.io/rethink-public/aioweb_tls.git@v0.1.0
+aioweb_tls[all]   @ git+ssh://git@git.rethinkstudios.io/rethink-public/aioweb_tls.git@v0.1.3
 ```
 
 Direct:
 
 ```bash
-pip install "aioweb_tls[curl] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aioweb_tls.git@v0.1.0"
+pip install "aioweb_tls[curl] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aioweb_tls.git@v0.1.3"
-pip install "aioweb_tls[noble] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aioweb_tls.git@v0.1.0"
+pip install "aioweb_tls[noble] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aioweb_tls.git@v0.1.3"
-pip install "aioweb_tls[all] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aioweb_tls.git@v0.1.0"
+pip install "aioweb_tls[all] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aioweb_tls.git@v0.1.3"
 ```
 
 - `[curl]` → curl_cffi backend · `[noble]` → noble_tls backend · `[all]` → both.
@@ -44,6 +44,8 @@ pip install "aioweb_tls[all] @ git+ssh://git@git.rethinkstudios.io/rethink-publi
 Constructing a backend whose client isn't installed raises that `RuntimeError` at
 construction, never at import.
 
+Drop the `@v0.1.3` suffix from the line above to install the latest unpinned.
+
 ## curl_cffi backend
 
 ```python
@@ -55,8 +57,11 @@ async with TLSSession(backend=CurlCffi(impersonate="chrome"), proxies={"https":
         print(resp.json()["tls"]["ja3"])
 ```
 
-- `CurlCffi(impersonate="chrome")` sets the forged profile; override per call by
+- `CurlCffi(impersonate="chrome")` sets the forged profile; override it per call by
-  passing `impersonate=` to any request method.
+  passing `impersonate=` to the low-level `request()` (which forwards `**kwargs` to the
+  backend). `request_with_retries` has a fixed signature and does **not** accept extra
+  backend kwargs — passing `impersonate=` there raises `TypeError`; set the profile on
+  the `CurlCffi` instance for the retrying path.
 - curl_cffi forges JA3/JA4 + HTTP/2 fingerprints via the bundled curl-impersonate binary.
 
 ## noble backend
@@ -73,8 +78,8 @@ async with TLSSession(backend=Noble(client="chrome_133")) as s:
 
 - `Noble(client="chrome_133")` — accepts a `noble_tls.Client` enum or a string name.
 - noble_tls downloads a Go shared library on first use. `await s.setup()` fetches it
-  once at startup; if you skip it, the first request fetches it lazily (guarded to run
+  once at startup; if you skip it, the first request fetches it lazily. The fetch is
-  once).
+  guarded by a lock, so even concurrent first requests download it exactly once.
 
 ## Writing your own backend (the `TLSBackend` protocol)
 
@@ -170,4 +175,4 @@ are separate signals. Use this as one component, not a complete anti-bot solutio
 
 ## Versioning
 
-Tagged `vX.Y.Z`. Pin the tag in `requirements.txt`.
+Releases are tagged `vX.Y.Z`. The install line above pins a release; drop the `@vX.Y.Z` suffix to install the latest unpinned. Pin deliberately for reproducible installs.

pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aioweb_tls"
+version = "0.1.3"
+description = "TLS-fingerprinting backends (curl_cffi / noble_tls) for aioweb via one injectable TLSSession, config-free, installable."
+requires-python = ">=3.10"
+dependencies = [
+    "aioweb @ git+ssh://git@git.rethinkstudios.io/rethink-public/aioweb.git@v0.1.5",
+]
+
+[project.optional-dependencies]
+curl = ["curl_cffi>=0.15"]
+noble = ["noble-tls>=0.1.5"]
+all = ["curl_cffi>=0.15", "noble-tls>=0.1.5"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aioweb_tls"]
+
+[tool.hatch.metadata]
+allow-direct-references = true

src/aioweb_tls/__init__.py

@@ -0,0 +1,28 @@
+"""
+tls-fingerprinting backends for aioweb
+
+one session class, TLSSession, takes an injected backend that swaps the HTTP client
+(and thus the TLS/HTTP fingerprint) while inheriting every aioweb feature — header
+overwrites, domain rewriting, ephemeral headers, proxies, retries, previews —
+unchanged.
+
+    from aioweb_tls import TLSSession, CurlCffi, Noble
+
+    async with TLSSession(backend=CurlCffi(impersonate="chrome")) as s:   # [curl] extra
+        resp = await s.request_with_retries("GET", url)
+
+    async with TLSSession(backend=Noble(client="chrome_133")) as s:       # [noble] extra
+        await s.setup()                                                   # fetch Go lib once
+        resp = await s.request_with_retries("GET", url)
+
+the tls clients are optional extras, not base deps. importing this package never
+fails because an extra is missing; the matching RuntimeError is raised only when you
+construct a backend whose client isn't installed. custom backends implement the
+TLSBackend protocol and inject the same way.
+"""
+
+from .session import TLSSession
+from .backends import CurlCffi, Noble
+from .protocol import TLSBackend
+
+__all__ = ["TLSSession", "CurlCffi", "Noble", "TLSBackend"]

src/aioweb_tls/backends.py

@@ -0,0 +1,277 @@
+"""
+tls backends for TLSSession
+
+each backend is a stateless config+behavior object implementing the TLSBackend
+protocol (see protocol.py). it owns its own config vocabulary — CurlCffi takes
+impersonate=, Noble takes client= — so there is no shared kwarg-soup. TLSSession
+owns the live session object and passes it into every method here.
+
+the underlying tls clients are optional extras: constructing a backend whose client
+is not installed raises a clear RuntimeError naming the extra to install. importing
+this module never fails because an extra is missing.
+"""
+
+import asyncio
+import logging
+import math
+
+import aiohttp
+from aioweb import Response
+
+log = logging.getLogger(__name__)
+
+
+def _as_client_error(error: Exception, backend: str) -> aiohttp.ClientError:
+    """wrap a backend-native network exception as an aiohttp.ClientError
+
+    aioweb's request() only re-wraps aiohttp.ClientError; curl_cffi raises
+    RequestException(OSError) and noble_tls raises TLSClientException(IOError), neither
+    of which is an aiohttp.ClientError. translating here gives TLS backends the same
+    typed failure contract as the aiohttp path on the bare request() route.
+    """
+    return aiohttp.ClientError(f"{backend} request failed: {error}")
+
+
+try:
+    from curl_cffi import AsyncSession as _CurlAsyncSession
+    _CURL_ERROR = None
+except ImportError as error:
+    _CurlAsyncSession = None
+    _CURL_ERROR = error
+
+try:
+    import noble_tls
+    from noble_tls import Client as _NobleClient
+    _NOBLE_ERROR = None
+except ImportError as error:
+    noble_tls = None
+    _NobleClient = None
+    _NOBLE_ERROR = error
+
+
+def _coerce_timeout(value):
+    """turn aioweb's aiohttp ClientTimeout (or a number) into a plain number
+
+    aioweb.request() wraps a numeric timeout in an aiohttp.ClientTimeout before the
+    seam sees it; the tls clients want a number, so unwrap .total when present.
+    """
+    total = getattr(value, "total", value)
+    return total if isinstance(total, (int, float)) else None
+
+
+def _jar_to_dict(session):
+    """best-effort map of a requests-style cookie jar on session to a plain dict
+
+    intentionally broad: this feeds preview() only, the two backends expose differently-
+    shaped jars, and a cookie read must never crash a request — so any jar that doesn't
+    iterate cleanly degrades to {} rather than raising.
+    """
+    jar = getattr(session, "cookies", None)
+    if not jar:
+        return {}
+    try:
+        return {k: v for k, v in jar.items()}
+    except Exception:
+        return {}
+
+
+class CurlCffi:
+    """curl_cffi backend: forges JA3/JA4 + HTTP/2 via the curl-impersonate binary
+
+    config:
+        impersonate: browser profile to forge (default "chrome"); override per call
+            by passing impersonate= to the low-level request()/_raw_request path,
+            which forwards **kwargs to the backend. NOT request_with_retries — its
+            signature is fixed (no **kwargs) and would raise TypeError. for a
+            per-call profile under retries, set it on the CurlCffi instance instead.
+
+    requires the [curl] extra (pip install "aioweb_tls[curl]").
+    """
+
+    def __init__(self, impersonate: str = "chrome"):
+        if _CurlAsyncSession is None:
+            raise RuntimeError(
+                "curl_cffi is not installed; install the extra with "
+                "pip install \"aioweb_tls[curl]\""
+            ) from _CURL_ERROR
+        self.impersonate = impersonate
+
+    def create_session(self, headers, timeout, **kwargs):
+        """build the curl_cffi AsyncSession"""
+        return _CurlAsyncSession(headers=headers, timeout=timeout, **kwargs)
+
+    async def raw_request(self, session, method, url, **kwargs) -> Response:
+        """send via curl_cffi and adapt the result into an aioweb.Response"""
+        impersonate = kwargs.pop("impersonate", self.impersonate)
+
+        timeout = _coerce_timeout(kwargs.pop("timeout", None))
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+
+        proxy = kwargs.pop("proxy", None)
+        if proxy:
+            kwargs["proxy"] = proxy
+
+        try:
+            response = await session.request(method, url, impersonate=impersonate, **kwargs)
+        except aiohttp.ClientError:
+            raise
+        except asyncio.TimeoutError:
+            raise
+        except OSError as error:
+            # curl_cffi's RequestException subclasses OSError; translate the native
+            # network error into aiohttp.ClientError. narrowed from a bare Exception so a
+            # real bug (AttributeError/TypeError) isn't laundered into 'client error'
+            raise _as_client_error(error, "curl_cffi") from error
+        content = response.content if response.content is not None else b""
+        return Response(
+            status_code=response.status_code,
+            headers=dict(response.headers),
+            content=content,
+            url=str(response.url),
+            reason=getattr(response, "reason", None),
+            cookies=getattr(response, "cookies", None),
+        )
+
+    def is_closed(self, session) -> bool:
+        """whether the curl_cffi session is closed
+
+        curl_cffi tracks closed state in the private `_closed` (no public `closed`
+        property), so read that; fall back to a public `closed` if a future version
+        adds one. TLSSession's own `_closed` flag is the primary signal — this is a
+        best-effort backend check for out-of-band closes.
+        """
+        closed = getattr(session, "_closed", None)
+        if closed is None:
+            closed = getattr(session, "closed", False)
+        return bool(closed)
+
+    def cookies_for_url(self, session, url) -> dict:
+        """cookies curl_cffi would send for url (best-effort)"""
+        return _jar_to_dict(session)
+
+    async def close(self, session) -> None:
+        """close the curl_cffi session"""
+        await session.close()
+
+
+class Noble:
+    """noble_tls backend: forges a browser TLS fingerprint via the tls-client Go lib
+
+    config:
+        client: noble_tls Client profile (enum or string, default "chrome_133").
+
+    noble_tls downloads a Go shared library on first use; setup() fetches it once
+    (run via TLSSession.setup() or lazily before the first request).
+
+    requires the [noble] extra (pip install "aioweb_tls[noble]").
+    """
+
+    def __init__(self, client="chrome_133"):
+        if noble_tls is None:
+            raise RuntimeError(
+                "noble_tls is not installed; install the extra with "
+                "pip install \"aioweb_tls[noble]\""
+            ) from _NOBLE_ERROR
+        self.client = self._resolve_client(client)
+        self._updated = False
+        self._setup_lock = asyncio.Lock()
+
+    @staticmethod
+    def _resolve_client(client):
+        """turn a string or Client enum into a noble_tls Client value"""
+        if isinstance(client, str):
+            return getattr(_NobleClient, client.upper())
+        return client
+
+    async def setup(self) -> None:
+        """fetch the noble_tls Go shared library once; idempotent and concurrency-safe
+
+        uses noble_tls.download_if_necessary (the current API: it fetches the asset on
+        first use and no-ops when it already exists). older noble_tls without that name
+        is handled via update_if_necessary as a fallback.
+
+        guarded by an asyncio.Lock with a check-lock-recheck so concurrent first
+        requests don't both run the fetch: the fast path returns once _updated is
+        set, and only the first caller through the lock does the work.
+        """
+        if self._updated:
+            return
+        async with self._setup_lock:
+            if self._updated:
+                return
+            download = getattr(noble_tls, "download_if_necessary", None)
+            if download is not None:
+                await download()
+            elif hasattr(noble_tls, "update_if_necessary"):
+                await noble_tls.update_if_necessary()
+            self._updated = True
+
+    def create_session(self, headers, timeout, **kwargs):
+        """build the noble_tls Session, honoring session-default headers + timeout
+
+        noble_tls.Session takes neither headers nor timeout in its constructor, so
+        aioweb's session-default headers (and the coerced timeout) are applied after
+        construction — matching CurlCffi, which passes both through. without this a
+        TLSSession(backend=Noble(...), headers=...) would silently drop the headers.
+        """
+        session = noble_tls.Session(client=self.client, **kwargs)
+        if headers:
+            session.headers.update(headers)
+        if timeout is not None:
+            session.timeout_seconds = timeout
+        return session
+
+    async def raw_request(self, session, method, url, **kwargs) -> Response:
+        """send via noble_tls and adapt the result into an aioweb.Response"""
+        await self.setup()
+
+        timeout = _coerce_timeout(kwargs.pop("timeout", None))
+        if timeout is not None:
+            # noble takes whole seconds; round UP so a sub-second timeout (e.g. 0.5)
+            # doesn't truncate to 0 (which would mean no/instant timeout)
+            kwargs["timeout_seconds"] = max(1, math.ceil(timeout))
+
+        proxy = kwargs.pop("proxy", None)
+        if proxy:
+            kwargs["proxy"] = proxy
+
+        try:
+            response = await session.execute_request(method=method.upper(), url=url, **kwargs)
+        except aiohttp.ClientError:
+            raise
+        except asyncio.TimeoutError:
+            raise
+        except OSError as error:
+            # noble_tls's TLSClientException subclasses IOError (== OSError); translate
+            # the native network error, narrowed from bare Exception so a real bug surfaces
+            raise _as_client_error(error, "noble_tls") from error
+        content = getattr(response, "content", None)
+        if content is None:
+            text = getattr(response, "text", "") or ""
+            content = text.encode()
+        return Response(
+            status_code=response.status_code,
+            headers=dict(getattr(response, "headers", {}) or {}),
+            content=content,
+            url=str(getattr(response, "url", url)),
+            reason=getattr(response, "reason", None),
+            cookies=getattr(response, "cookies", None),
+        )
+
+    def is_closed(self, session) -> bool:
+        """noble_tls has no closed flag; closed state is tracked by TLSSession"""
+        return bool(getattr(session, "closed", False))
+
+    def cookies_for_url(self, session, url) -> dict:
+        """cookies noble_tls would send for url (best-effort)"""
+        return _jar_to_dict(session)
+
+    async def close(self, session) -> None:
+        """close the noble_tls session if it exposes a close"""
+        close = getattr(session, "close", None)
+        if close is None:
+            return
+        result = close()
+        if hasattr(result, "__await__"):
+            await result

src/aioweb_tls/protocol.py

@@ -0,0 +1,60 @@
+"""
+the tls backend protocol
+
+a backend is a stateless config+behavior object that teaches TLSSession how to talk
+to one HTTP client. TLSSession owns the live session object (built by create_session)
+and passes it into every backend call, so backends hold no per-request state.
+
+implement this protocol to add a custom backend (e.g. a local Go TLS server); inject
+it via TLSSession(backend=MyBackend(...)) and it inherits all of aioweb's domain /
+header / ephemeral / proxy / retry / preview logic unchanged — those operate on plain
+dicts and never touch the backend.
+
+required:
+    create_session(headers: dict, timeout, **kwargs) -> session
+        build and return the live client session object. TLSSession stores it as
+        self.session and hands it back to every other method below.
+
+    async raw_request(session, method, url, **kwargs) -> aioweb.Response
+        send one request with `session` and adapt the client's response into an
+        aioweb.Response built from primitives (status_code, headers, content bytes,
+        url, reason). kwargs arrive aioweb-shaped — the base has already resolved the
+        proxy into kwargs["proxy"] and merged headers into kwargs["headers"], and a
+        numeric timeout is wrapped in an aiohttp.ClientTimeout (unwrap .total).
+
+    is_closed(session) -> bool
+        whether `session` is closed.
+
+optional:
+    cookies_for_url(session, url) -> dict
+        cookies the client would send for url, for preview(). default {} (used when
+        the backend has no introspectable jar).
+
+    async setup() -> None
+        one-time async preparation (e.g. fetch a native lib). called once via
+        TLSSession.setup() and lazily before the first request; make it idempotent.
+
+    async close(session) -> None
+        close `session`. default awaits session.close() if present.
+"""
+
+from typing import Any, Protocol, runtime_checkable
+
+from aioweb import Response
+
+
+@runtime_checkable
+class TLSBackend(Protocol):
+    """the contract a TLSSession backend implements (see module docstring)"""
+
+    def create_session(self, headers: dict, timeout: Any, **kwargs) -> Any:
+        """build and return the live client session object"""
+        ...
+
+    async def raw_request(self, session: Any, method: str, url: str, **kwargs) -> Response:
+        """send one request and adapt the result into an aioweb.Response"""
+        ...
+
+    def is_closed(self, session: Any) -> bool:
+        """whether the session is closed"""
+        ...

src/aioweb_tls/session.py

@@ -0,0 +1,94 @@
+"""
+TLSSession — one aioweb session, any tls backend
+
+TLSSession subclasses aioweb.ExtendedSession and delegates only the four backend
+seams to an injected backend object (see protocol.py). everything else — header
+overwrites, domain rewriting, ephemeral headers, proxies, retries, previews — is
+inherited from aioweb unchanged, because that logic operates on plain dicts and
+never touches the backend.
+
+    from aioweb_tls import TLSSession, CurlCffi, Noble
+
+    async with TLSSession(backend=CurlCffi(impersonate="chrome")) as s:
+        resp = await s.request_with_retries("GET", "https://tls.peet.ws/api/all")
+        if resp:
+            print(resp.json()["tls"]["ja3"])
+
+    s = TLSSession(backend=Noble(client="chrome_133"))
+    await s.setup()                            # fetch noble's Go lib once
+    ...
+
+a custom backend (e.g. a local Go TLS server) injects the same way — implement the
+TLSBackend protocol and pass it as backend=. one TLSSession is the only session
+class; the backend swaps the wire, not the session.
+"""
+
+import logging
+
+from aioweb import ExtendedSession
+
+log = logging.getLogger(__name__)
+
+
+class TLSSession(ExtendedSession):
+    """aioweb session whose HTTP backend is an injected, swappable tls client"""
+
+    def __init__(self, backend, *args, **kwargs):
+        """build a session over a tls backend
+
+        args:
+            backend: a TLSBackend (CurlCffi, Noble, or a custom one); owns its own
+                config vocabulary and the four seam behaviors
+            *args, **kwargs: forwarded to aioweb.ExtendedSession
+        """
+        self.backend = backend
+        self._closed = False
+        super().__init__(*args, **kwargs)
+
+    async def setup(self) -> None:
+        """run the backend's one-time setup if it has one (idempotent)
+
+        delegates to backend.setup() when defined (e.g. noble fetching its Go lib);
+        a no-op for backends without it. also invoked lazily before the first request
+        by backends that guard their own setup, so calling this is optional but lets
+        callers pre-warm at startup.
+        """
+        setup = getattr(self.backend, "setup", None)
+        if setup is not None:
+            await setup()
+
+    # -------------------------------------------------------------------------
+    #   the four backend seams, delegated to self.backend
+
+    def _create_session(self, headers, timeout, **kwargs):
+        """delegate session creation to the backend"""
+        return self.backend.create_session(headers, timeout, **kwargs)
+
+    async def _raw_request(self, method, url, **kwargs):
+        """delegate the wire request to the backend, returning its aioweb.Response"""
+        return await self.backend.raw_request(self.session, method, url, **kwargs)
+
+    def _cookies_for_url(self, url) -> dict:
+        """delegate preview cookie lookup to the backend (default {})"""
+        cookies_for_url = getattr(self.backend, "cookies_for_url", None)
+        if cookies_for_url is None:
+            return {}
+        return cookies_for_url(self.session, url)
+
+    def _is_closed(self) -> bool:
+        """closed if explicitly closed here or the backend reports it"""
+        if self._closed:
+            return True
+        return self.backend.is_closed(self.session)
+
+    # -------------------------------------------------------------------------
+    #   lifecycle — backends close differently, so route through the backend
+
+    async def close(self) -> None:
+        """close via the backend's close (falls back to session.close)"""
+        self._closed = True
+        close = getattr(self.backend, "close", None)
+        if close is not None:
+            await close(self.session)
+        else:
+            await self.session.close()