fizzpy 0.4.0__cp313-cp313-win_amd64.whl

fizzpy/__init__.py

@@ -0,0 +1,314 @@
+"""fizzpy — a low-level TLS 1.3 client toolkit built on Facebook's Fizz.
+
+The synchronous facade lives here; the asyncio facade is :mod:`fizzpy.aio`.
+Both drive the same C++ core, which runs every connection on a background
+EventBase thread.
+
+    import fizzpy
+
+    r = fizzpy.get("https://www.cloudflare.com")
+    print(r.status_code, r.headers["content-type"])
+    print(r.tls)  # negotiated TLS 1.3 parameters
+
+Certificate chains are verified against the system trust store and the
+hostname is checked against the certificate's SAN by default.
+"""
+
+from __future__ import annotations
+
+
+# start delvewheel patch
+def _delvewheel_patch_1_13_0():
+    import os
+    if os.path.isdir(libs_dir := os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, 'fizzpy.libs'))):
+        os.add_dll_directory(libs_dir)
+
+
+_delvewheel_patch_1_13_0()
+del _delvewheel_patch_1_13_0
+# end delvewheel patch
+
+import threading
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from . import _core
+from ._common import (
+    DEFAULT_ALPN,
+    DEFAULT_GROUPS,
+    DEFAULT_MAX_REDIRECTS,
+    DEFAULT_TIMEOUT_MS,
+    READ_DONE,
+    Extension,
+    Target,
+    TooManyRedirects,
+    default_ca_file,
+    next_redirect,
+    normalize_extensions,
+    parse_url,
+    strip_body_headers,
+)
+from ._core import NamedGroup
+from ._http import Headers, Response, ResponseParser, build_request
+from ._transport import run_sync
+
+__all__ = [
+    "Client",
+    "Extension",
+    "Headers",
+    "NamedGroup",
+    "Response",
+    "TlsParameters",
+    "TooManyRedirects",
+    "delete",
+    "get",
+    "head",
+    "post",
+    "put",
+    "request",
+]
+
+# Negotiated parameters are returned from the core as a plain dict; expose the
+# key set as documentation.
+TlsParameters = dict
+
+
+class _Stale(Exception):
+    """Internal: a pooled connection was dead; retry once on a fresh one."""
+
+
+class Client:
+    """A synchronous TLS HTTP client.
+
+    Idle connections are kept in a per-host pool and reused (HTTP/1.1
+    keep-alive). A pooled connection found dead on reuse is transparently
+    replaced for idempotent retries. Call :meth:`close` (or use the client as a
+    context manager) to close pooled connections.
+    """
+
+    def __init__(
+        self,
+        *,
+        verify: bool = True,
+        cafile: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_MS / 1000,
+        alpn: list[str] | None = None,
+        groups: list[_core.NamedGroup] | None = None,
+        extensions: Sequence[tuple[int, bytes]] | None = None,
+        follow_redirects: bool = True,
+        max_redirects: int = DEFAULT_MAX_REDIRECTS,
+    ) -> None:
+        self._verify = verify
+        self._cafile = cafile or default_ca_file()
+        self._timeout_ms = int(timeout * 1000)
+        self._alpn = list(alpn) if alpn is not None else list(DEFAULT_ALPN)
+        self._groups = list(groups) if groups is not None else list(DEFAULT_GROUPS)
+        self._extensions = normalize_extensions(extensions)
+        self._follow_redirects = follow_redirects
+        self._max_redirects = max_redirects
+        self._pool: dict[tuple[str, int], list[_core.TlsConnection]] = {}
+        self._lock = threading.Lock()
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        body: bytes | None = None,
+    ) -> Response:
+        method = method.upper()
+        seen = 0
+        while True:
+            response = self._perform(method, url, headers=headers, body=body)
+            response.url = url
+            nxt = (
+                next_redirect(
+                    method, url, response.status_code, response.headers.get("Location")
+                )
+                if self._follow_redirects
+                else None
+            )
+            if nxt is None:
+                return response
+            if seen >= self._max_redirects:
+                raise TooManyRedirects(
+                    f"exceeded {self._max_redirects} redirects (last: {url})"
+                )
+            new_method, url = nxt
+            if new_method != method:
+                method, body, headers = new_method, None, strip_body_headers(headers)
+            seen += 1
+
+    def _perform(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        body: bytes | None = None,
+    ) -> Response:
+        target = parse_url(url)
+        key = (target.host, target.port)
+        raw = build_request(
+            method, target.path, target.host, dict(headers) if headers else None, body
+        )
+
+        pooled = self._take(key)
+        if pooled is not None:
+            try:
+                return self._exchange(pooled, key, raw, reused=True)
+            except _Stale:
+                pooled.close()  # dead idle connection; fall through to a fresh one
+
+        return self._exchange(self._connect(target), key, raw, reused=False)
+
+    def _connect(self, target: Target) -> _core.TlsConnection:
+        conn = _core.TlsConnection()
+        run_sync(
+            lambda resolve, reject: conn.connect(
+                target.host,
+                target.port,
+                target.host,
+                self._alpn,
+                self._groups,
+                self._verify,
+                self._cafile,
+                self._timeout_ms,
+                self._extensions,
+                resolve,
+                reject,
+            )
+        )
+        return conn
+
+    def _exchange(
+        self,
+        conn: _core.TlsConnection,
+        key: tuple[str, int],
+        raw: bytes,
+        *,
+        reused: bool,
+    ) -> Response:
+        try:
+            run_sync(lambda resolve, reject: conn.write(raw, resolve, reject))
+        except Exception as exc:
+            # A reused connection that fails before the request lands was closed
+            # by the server while idle — safe to retry on a fresh one.
+            if reused:
+                raise _Stale from exc
+            raise
+
+        parser = ResponseParser()
+        received = False
+        while not parser.is_complete():
+            try:
+                chunk = run_sync(lambda resolve, reject: conn.read(resolve, reject))
+            except Exception as exc:
+                if reused and not received:
+                    raise _Stale from exc
+                raise
+            if chunk == READ_DONE:
+                if reused and not received:
+                    raise _Stale
+                parser.feed_eof()
+                break
+            received = True
+            parser.feed(chunk)
+
+        response = parser.response
+        if response is None:
+            if reused:
+                raise _Stale
+            raise ConnectionError("connection closed before a full response")
+        response.tls = conn.negotiated()
+
+        if self._reusable(parser, response):
+            self._give(key, conn)
+        else:
+            conn.close()
+        return response
+
+    @staticmethod
+    def _reusable(parser: ResponseParser, response: Response) -> bool:
+        if parser.used_close_framing or response.http_version != "HTTP/1.1":
+            return False
+        return "close" not in (response.headers.get("Connection") or "").lower()
+
+    def _take(self, key: tuple[str, int]) -> _core.TlsConnection | None:
+        with self._lock:
+            conns = self._pool.get(key)
+            return conns.pop() if conns else None
+
+    def _give(self, key: tuple[str, int], conn: _core.TlsConnection) -> None:
+        with self._lock:
+            self._pool.setdefault(key, []).append(conn)
+
+    def close(self) -> None:
+        """Close all pooled connections."""
+        with self._lock:
+            pooled = [c for conns in self._pool.values() for c in conns]
+            self._pool.clear()
+        for conn in pooled:
+            conn.close()
+
+    def get(self, url: str, **kwargs: Any) -> Response:
+        return self.request("GET", url, **kwargs)
+
+    def post(self, url: str, **kwargs: Any) -> Response:
+        return self.request("POST", url, **kwargs)
+
+    def head(self, url: str, **kwargs: Any) -> Response:
+        return self.request("HEAD", url, **kwargs)
+
+    def put(self, url: str, **kwargs: Any) -> Response:
+        return self.request("PUT", url, **kwargs)
+
+    def delete(self, url: str, **kwargs: Any) -> Response:
+        return self.request("DELETE", url, **kwargs)
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+_CLIENT_KWARGS = frozenset(
+    {
+        "verify",
+        "cafile",
+        "timeout",
+        "alpn",
+        "groups",
+        "extensions",
+        "follow_redirects",
+        "max_redirects",
+    }
+)
+
+
+def request(method: str, url: str, **kwargs: Any) -> Response:
+    """One-shot request with a throwaway :class:`Client`."""
+    client_kwargs = {k: kwargs.pop(k) for k in list(kwargs) if k in _CLIENT_KWARGS}
+    return Client(**client_kwargs).request(method, url, **kwargs)
+
+
+def get(url: str, **kwargs: Any) -> Response:
+    return request("GET", url, **kwargs)
+
+
+def post(url: str, **kwargs: Any) -> Response:
+    return request("POST", url, **kwargs)
+
+
+def head(url: str, **kwargs: Any) -> Response:
+    return request("HEAD", url, **kwargs)
+
+
+def put(url: str, **kwargs: Any) -> Response:
+    return request("PUT", url, **kwargs)
+
+
+def delete(url: str, **kwargs: Any) -> Response:
+    return request("DELETE", url, **kwargs)

fizzpy/_common.py

@@ -0,0 +1,170 @@
+"""Shared request plumbing used by both the sync and async facades."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import NamedTuple
+from urllib.parse import urljoin, urlsplit
+
+from . import _core  # pyright: ignore[reportPrivateUsage]  # our own extension module
+
+DEFAULT_ALPN = ["http/1.1"]
+DEFAULT_TIMEOUT_MS = 30_000
+DEFAULT_MAX_REDIRECTS = 10
+READ_DONE = b""
+
+
+def default_ca_file() -> str:
+    """Path to the CA bundle used when a caller doesn't supply one.
+
+    The extension bundles its own OpenSSL, whose compiled-in trust-store path
+    doesn't exist on most hosts (and not at all in minimal images), so the
+    OpenSSL default verifies nothing out of the box. certifi gives every
+    install the Mozilla root set with no system setup. If certifi is somehow
+    unavailable we return "" and fall back to OpenSSL's default store.
+    """
+    try:
+        import certifi
+
+        return certifi.where()
+    except Exception:
+        return ""
+
+
+# Status codes that carry a Location and request a follow-up request.
+REDIRECT_CODES = frozenset({301, 302, 303, 307, 308})
+
+
+class TooManyRedirects(Exception):
+    """Raised when a request exceeds the client's redirect limit."""
+
+
+# Offer the standardized post-quantum hybrid group first, with classical x25519
+# as fallback — mirroring how Chrome/Firefox send both key shares by default.
+# A server without ML-KEM support simply selects x25519 from our shares.
+DEFAULT_GROUPS = [_core.NamedGroup.x25519_mlkem768, _core.NamedGroup.x25519]
+
+
+class Extension(NamedTuple):
+    """A custom TLS ClientHello extension: a type code and its opaque payload."""
+
+    type: int
+    data: bytes
+
+
+# Extension types Fizz assembles into the ClientHello itself (from
+# fizz/record/Types.h and the ClientHello build in ClientProtocol.cpp). Injecting
+# any of these would duplicate or contradict Fizz's own, so they're refused.
+FIZZ_MANAGED_EXTENSIONS = frozenset(
+    {
+        0,  # server_name
+        10,  # supported_groups
+        13,  # signature_algorithms
+        16,  # application_layer_protocol_negotiation
+        41,  # pre_shared_key
+        42,  # early_data
+        43,  # supported_versions
+        44,  # cookie
+        45,  # psk_key_exchange_modes
+        47,  # certificate_authorities
+        50,  # signature_algorithms_cert
+        51,  # key_share
+        0xFE0D,  # encrypted_client_hello
+    }
+)
+
+
+def normalize_extensions(
+    extensions: Sequence[tuple[int, bytes]] | None,
+) -> list[tuple[int, bytes]]:
+    """Validate and coerce caller extensions to ``list[(int, bytes)]``.
+
+    Accepts any iterable of ``(type, data)`` pairs (e.g. :class:`Extension`).
+    Raises ``ValueError`` for an out-of-range type, oversized data, a Fizz-managed
+    type, or a duplicate type — naming the offender.
+    """
+    if not extensions:
+        return []
+    out: list[tuple[int, bytes]] = []
+    seen: set[int] = set()
+    for item in extensions:
+        etype, data = item
+        etype = int(etype)
+        if not 0 <= etype <= 0xFFFF:
+            raise ValueError(f"extension type {etype} out of range 0..65535")
+        data = bytes(data)
+        if len(data) > 0xFFFF:
+            raise ValueError(
+                f"extension {etype} data is {len(data)} bytes; max is 65535"
+            )
+        if etype in FIZZ_MANAGED_EXTENSIONS:
+            raise ValueError(
+                f"extension type {etype} is managed by Fizz and cannot be injected"
+            )
+        if etype in seen:
+            raise ValueError(f"duplicate extension type {etype}")
+        seen.add(etype)
+        out.append((etype, data))
+    return out
+
+
+class Target(NamedTuple):
+    """A parsed request target: where to connect and what to ask for."""
+
+    host: str
+    port: int
+    path: str
+
+
+def next_redirect(
+    method: str, url: str, status_code: int, location: str | None
+) -> tuple[str, str] | None:
+    """Resolve a redirect into the next ``(method, absolute_url)`` to request.
+
+    Returns ``None`` when the response is not a redirect or carries no
+    ``Location``. Method rewriting follows what browsers and ``requests`` do:
+    303 forces a GET; 301/302 downgrade POST to GET; 307/308 preserve the
+    original method (and the caller's body).
+    """
+    if status_code not in REDIRECT_CODES or not location:
+        return None
+
+    target = urljoin(url, location)
+    method = method.upper()
+    if (status_code == 303 and method != "HEAD") or (
+        status_code in (301, 302) and method == "POST"
+    ):
+        method = "GET"
+    return method, target
+
+
+def strip_body_headers(
+    headers: Mapping[str, str] | None,
+) -> dict[str, str] | None:
+    """Drop body-specific headers when a redirect downgrades a request to GET."""
+    if not headers:
+        return None
+    return {
+        k: v
+        for k, v in headers.items()
+        if k.lower() not in ("content-length", "content-type", "transfer-encoding")
+    }
+
+
+def parse_url(url: str) -> Target:
+    """Split an ``https://`` URL into connection target + request path.
+
+    Only TLS is supported — this is a TLS client. ``http://`` is rejected so a
+    plaintext request can never silently happen.
+    """
+    parts = urlsplit(url)
+    if parts.scheme != "https":
+        raise ValueError(f"fizzpy only supports https:// URLs, got {parts.scheme!r}")
+    if not parts.hostname:
+        raise ValueError(f"no host in URL: {url!r}")
+
+    path = parts.path or "/"
+    if parts.query:
+        path = f"{path}?{parts.query}"
+
+    return Target(host=parts.hostname, port=parts.port or 443, path=path)

fizzpy/_core.pyi

@@ -0,0 +1,116 @@
+"""Type stub for the compiled ``fizzpy._core`` extension.
+
+Hand-authored from the pybind11 bindings in ``_core.cpp``. The real extension is
+built by scikit-build-core; a stubgen-generated stub needs that build, so this
+stub is maintained by hand and must track the bindings. It exists so the pure
+Python facades type-check strictly against the native boundary.
+"""
+
+from collections.abc import Callable
+from enum import IntEnum
+
+class ProtocolVersion(IntEnum):
+    tls_1_0 = ...
+    tls_1_1 = ...
+    tls_1_2 = ...
+    tls_1_3 = ...
+    tls_1_3_23 = ...
+    tls_1_3_23_fb = ...
+    tls_1_3_26 = ...
+    tls_1_3_26_fb = ...
+    tls_1_3_28 = ...
+
+class NamedGroup(IntEnum):
+    secp256r1 = ...
+    secp384r1 = ...
+    secp521r1 = ...
+    x25519 = ...
+    x448 = ...
+    mlkem512 = ...
+    mlkem768 = ...
+    mlkem1024 = ...
+    secp256r1_mlkem768 = ...
+    x25519_mlkem768 = ...
+
+class PskKeyExchangeMode(IntEnum):
+    psk_ke = ...
+    psk_dhe_ke = ...
+
+class CipherSuite(IntEnum):
+    TLS_AES_128_GCM_SHA256 = ...
+    TLS_AES_256_GCM_SHA384 = ...
+    TLS_CHACHA20_POLY1305_SHA256 = ...
+
+class SignatureScheme(IntEnum):
+    ecdsa_secp256r1_sha256 = ...
+    ecdsa_secp384r1_sha384 = ...
+    ecdsa_secp521r1_sha512 = ...
+    rsa_pss_sha256 = ...
+    rsa_pss_sha384 = ...
+    rsa_pss_sha512 = ...
+    ed25519 = ...
+    ed448 = ...
+
+class SendKeyShare(IntEnum):
+    Always = ...
+    WhenNecessary = ...
+
+class FizzClientContext:
+    def __init__(self) -> None: ...
+    def setSupportedVersions(self, versions: list[ProtocolVersion]) -> None: ...
+    def getSupportedVersions(self) -> list[ProtocolVersion]: ...
+    def setSupportedCiphers(self, ciphers: list[CipherSuite]) -> None: ...
+    def getSupportedCiphers(self) -> list[CipherSuite]: ...
+    def setSupportedSigSchemes(self, schemes: list[SignatureScheme]) -> None: ...
+    def getSupportedSigSchemes(self) -> list[SignatureScheme]: ...
+    def setSupportedGroups(self, groups: list[NamedGroup]) -> None: ...
+    def getSupportedGroups(self) -> list[NamedGroup]: ...
+    def setSupportedPskModes(self, modes: list[PskKeyExchangeMode]) -> None: ...
+    def getSupportedPskModes(self) -> list[PskKeyExchangeMode]: ...
+    def setSupportedAlpns(self, alpns: list[str]) -> None: ...
+    def getSupportedAlpns(self) -> list[str]: ...
+    def setSendEarlyData(self, send: bool) -> None: ...
+    def getSendEarlyData(self) -> bool: ...
+    def setSendKeyShare(self, mode: SendKeyShare) -> None: ...
+    def getSendKeyShare(self) -> SendKeyShare: ...
+
+# Negotiated TLS parameters returned by ``TlsConnection.negotiated``. Keys:
+# version, cipher, group, alpn, sni, peer_cert (str) and group_code (the numeric
+# NamedGroup codepoint, int). Typed with an object value to stay a plain dict.
+NegotiatedParams = dict[str, object]
+
+class TlsConnection:
+    """A single TLS 1.3 connection driven on the shared EventBase thread.
+
+    Every async method takes a ``(resolve, reject)`` callback pair the core
+    invokes (holding the GIL) from its background thread when the op completes.
+    """
+
+    def __init__(self) -> None: ...
+    def connect(
+        self,
+        host: str,
+        port: int,
+        sni: str,
+        alpns: list[str],
+        groups: list[NamedGroup],
+        verify: bool,
+        ca_file: str,
+        timeout_ms: int,
+        extensions: list[tuple[int, bytes]],
+        resolve: Callable[[None], None],
+        reject: Callable[[BaseException], None],
+    ) -> None: ...
+    def write(
+        self,
+        data: bytes,
+        resolve: Callable[[None], None],
+        reject: Callable[[BaseException], None],
+    ) -> None: ...
+    def read(
+        self,
+        resolve: Callable[[bytes], None],
+        reject: Callable[[BaseException], None],
+    ) -> None: ...
+    def negotiated(self) -> NegotiatedParams: ...
+    def close(self) -> None: ...