syshttp 0.1.0__py3-none-any.whl

syshttp/proxy.py

@@ -0,0 +1,341 @@
+"""Proxy routing: syshttp's settings as one proxylib proxy map.
+
+Settings are read through an :class:`~syshttp.env.HTTPEnv` (``env=``, default
+``HTTPEnv()``), each name under each of its prefixes (``SYSHTTP_PREFIX``);
+below they are named as written, under the empty prefix.
+
+:func:`proxy_map` is a proxylib ``ProxyMap`` that reads the settings at every
+lookup and answers, in order:
+
+1. **``SYSHTTP_PROXY``** -- a proxy for this package's traffic, distinct from
+   the machine's so other tools (git, npm, corporate CLIs) are not forced
+   through it. Its credential is ``SYSHTTP_PROXY_AUTH`` (a header value sent
+   verbatim, in ``SYSHTTP_PROXY_AUTH_HEADER``, default
+   ``Proxy-Authorization``), else the URL's userinfo as Basic.
+   ``SYSHTTP_PROXY_TYPE=prefix[:/endpoint]`` makes it a
+   URL-prefix gateway: ``GET https://api.example.com/x`` becomes
+   ``GET <proxy><endpoint>https://api.example.com/x``.
+2. **The machine's proxy**: the ``*_PROXY`` variables when any is set (per
+   scheme, as proxylib's ``EnvProxyConfig`` reads them, the lowercase
+   spelling first under each prefix), else the system's configuration for
+   the URL (WinHTTP on Windows, CFNetwork on macOS, libproxy or the desktop's
+   settings elsewhere; PAC scripts and WPAD included), unless
+   ``SYSHTTP_SYSTEM_PROXY`` is off. ``HTTP_PROXY_AUTH`` is its credential
+   (``Proxy-Authorization``).
+3. **DIRECT.**
+
+``NO_PROXY`` / ``no_proxy`` hosts go direct before any of it (proxylib's
+``BypassRules``: suffixes, CIDR, ports, loopback). An answer is a list
+(``PROXY a; PROXY b; DIRECT``): proxylib's client integrations try it in
+order and raise the last error when no entry connects; a client that sends
+through one proxy only (urllib, a curl command line) takes it through
+``proxylib.Probed``, which raises :class:`NoReachableProxyError`.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import Any, Dict, Optional, Tuple
+
+import proxylib
+from proxylib import NoReachableProxyError, Proxy
+
+from .env import HTTPEnv
+from .exceptions import ConfigurationError
+
+__all__ = (
+    "DEFAULT_AUTH_HEADER",
+    "MACHINE_AUTH_VAR",
+    "NoReachableProxyError",
+    "PROXY",
+    "PROXY_AUTH",
+    "PROXY_AUTH_HEADER",
+    "PROXY_TYPE",
+    "SYSTEM_PROXY",
+    "SYSTEM_PROXY_MAX_AGE",
+    "auth_header",
+    "configured_proxy",
+    "proxy_map",
+    "proxy_type",
+    "system_map",
+    "system_proxy_enabled",
+)
+
+#: The settings this module reads, each under every prefix.
+PROXY = "SYSHTTP_PROXY"
+PROXY_AUTH = "SYSHTTP_PROXY_AUTH"
+#: The header the credential rides in; default the standard one. A gateway
+#: that wants it under another name (``X-Proxy-Token``) sets this.
+PROXY_AUTH_HEADER = "SYSHTTP_PROXY_AUTH_HEADER"
+#: How the proxy is spoken to: ``connect`` (default) or ``prefix[:/endpoint]``.
+PROXY_TYPE = "SYSHTTP_PROXY_TYPE"
+DEFAULT_AUTH_HEADER = "Proxy-Authorization"
+#: Whether the system's proxy configuration is consulted, as a boolean
+#: (``1``/``true``/``yes``/``on`` or their opposites; unset or empty: on).
+SYSTEM_PROXY = "SYSHTTP_SYSTEM_PROXY"
+#: The machine proxy's header value.
+MACHINE_AUTH_VAR = "HTTP_PROXY_AUTH"
+#: How long (seconds) the system's configuration, and its answer for one URL,
+#: are reused before they are read again.
+SYSTEM_PROXY_MAX_AGE = 60
+
+_log = logging.getLogger(__name__)
+_TRUE = ("1", "true", "yes", "on")
+_FALSE = ("0", "false", "no", "off")
+_system_lock = threading.Lock()
+_system: Any = None
+_system_at = 0.0
+
+
+def _env(env: Optional[HTTPEnv]) -> HTTPEnv:
+    return HTTPEnv() if env is None else env
+
+
+def _var(env: HTTPEnv, setting: str) -> str:
+    """The variable to name in a message about ``setting``: the one set, else
+    the name under the first prefix."""
+    found = env.find(setting)
+    return found[0] if found else env.name(setting)
+
+
+def system_proxy_enabled(*, env: Optional[HTTPEnv] = None) -> bool:
+    """``SYSHTTP_SYSTEM_PROXY`` as a boolean, default on. Any other value than
+    ``1``/``true``/``yes``/``on`` or ``0``/``false``/``no``/``off`` (any case)
+    is a ``ValueError`` naming the variable."""
+    env = _env(env)
+    raw = env.get(SYSTEM_PROXY)
+    if raw is None:
+        return True
+    if raw.lower() in _TRUE:
+        return True
+    if raw.lower() in _FALSE:
+        return False
+    raise ConfigurationError("%s must be one of %s, not %r" % (_var(env, SYSTEM_PROXY), "/".join(_TRUE + _FALSE), raw))
+
+
+def auth_header(*, env: Optional[HTTPEnv] = None) -> str:
+    """The name of the header ``SYSHTTP_PROXY_AUTH`` is sent in:
+    ``SYSHTTP_PROXY_AUTH_HEADER``, else ``Proxy-Authorization``. A value with
+    a colon or whitespace is not a header name: a ``ValueError``."""
+    env = _env(env)
+    name = env.get(PROXY_AUTH_HEADER)
+    if not name:
+        return DEFAULT_AUTH_HEADER
+    if ":" in name or any(ch.isspace() for ch in name):
+        raise ConfigurationError("%s must be a header name, not %r" % (_var(env, PROXY_AUTH_HEADER), name))
+    return name
+
+
+def proxy_type(*, env: Optional[HTTPEnv] = None) -> Tuple[str, Optional[str]]:
+    """``("connect", None)`` for a standard proxy, or ``("prefix", "/endpoint")``
+    for a URL-prefix gateway (endpoint defaults to ``/``), from
+    ``SYSHTTP_PROXY_TYPE``. Anything else is a configuration error, raised."""
+    env = _env(env)
+    raw = env.get(PROXY_TYPE)
+    if not raw:
+        return "connect", None
+    kind, _, endpoint = raw.partition(":")
+    kind = kind.strip().lower()
+    if kind == "connect":
+        return "connect", None
+    if kind != "prefix":
+        raise ConfigurationError("%s must be 'connect' or 'prefix[:/endpoint]', not %r" % (_var(env, PROXY_TYPE), raw))
+    endpoint = endpoint.strip() or "/"
+    if not endpoint.startswith("/"):
+        endpoint = "/" + endpoint
+    return "prefix", endpoint
+
+
+def _checked(variable: str, value: str) -> str:
+    """``value``, the credential read from ``variable``, unless it holds a CR,
+    LF or NUL, which would end the header. The message names the variable,
+    never the value (a secret)."""
+    if any(ch in value for ch in "\r\n\0"):
+        raise ConfigurationError("%s must not contain a carriage return, line feed or NUL character" % variable)
+    return value
+
+
+def _with_credential(proxy: Proxy, header: str, value: str) -> Proxy:
+    """``proxy`` sending ``value`` in ``header`` instead of its userinfo."""
+    headers = proxy.headers
+    headers[header] = value
+    return Proxy(proxy.scheme, proxy.host, proxy.port, path=proxy.path, headers=headers)
+
+
+def _with_user(proxy: Proxy, user: str) -> Proxy:
+    """``proxy`` with curl's ``-U user:password`` as its only credential."""
+    name, _, password = user.partition(":")
+    return Proxy(proxy.scheme, proxy.host, proxy.port, name, password, path=proxy.path)
+
+
+def configured_proxy(*, env: Optional[HTTPEnv] = None) -> Optional[Proxy]:
+    """``SYSHTTP_PROXY`` as a proxylib ``Proxy`` with its credential and kind,
+    or ``None`` when it is unset. ``SYSHTTP_PROXY_AUTH`` replaces the URL's
+    userinfo; ``SYSHTTP_PROXY_TYPE=prefix`` makes a gateway. A malformed value
+    raises ``ValueError`` (``ProxyParseError`` for the URL)."""
+    env = _env(env)
+    raw = env.get(PROXY)
+    if not raw:
+        return None
+    found = Proxy.parse(raw)
+    kind, endpoint = proxy_type(env=env)
+    if kind == "prefix":
+        if found.scheme not in ("http", "https"):
+            raise ConfigurationError("%s=prefix needs an http or https %s" % (_var(env, PROXY_TYPE), _var(env, PROXY)))
+        found = Proxy("prefix+" + found.scheme, found.host, found.port, found.username, found.password, path=endpoint)
+    value = env.get(PROXY_AUTH)
+    if not value:
+        return found
+    return _with_credential(found, auth_header(env=env), _checked(_var(env, PROXY_AUTH), value))
+
+
+#: The conventional proxy variables, lower-cased.
+_PROXY_VARIABLES = tuple(s + "_proxy" for s in ("http", "https", "ftp", "ws", "wss", "all"))
+
+
+def _proxy_environ(env: HTTPEnv) -> Dict[str, str]:
+    """The conventional proxy variables as ``EnvProxyConfig`` reads them,
+    each found through ``env``'s prefixes (lowercase spelling first)."""
+    found = {}
+    for name in _PROXY_VARIABLES:
+        value = env.get(name, name.upper())
+        if value:
+            found[name] = value
+    return found
+
+
+class _Quiet:
+    """The system's map with its failures as "no opinion": a configuration
+    that cannot be read or run is DIRECT, never a failed request."""
+
+    def __init__(self, inner: Any) -> None:
+        self.inner = inner
+
+    def __getitem__(self, url: str) -> Any:
+        try:
+            return proxylib.lookup(self.inner, url)
+        except KeyError:
+            raise
+        except Exception as exc:
+            _log.debug("the system proxy configuration failed for a URL: %s", exc)
+            raise KeyError(url) from None
+
+    def close(self) -> None:
+        close = getattr(self.inner, "close", None)
+        if close is not None:
+            close()
+
+
+def system_map() -> Any:
+    """The system's proxy configuration as a proxylib ``ProxyMap``
+    (``proxylib.auto_proxy`` with no environment variables: the OS resolver,
+    then the OS settings), read once per :data:`SYSTEM_PROXY_MAX_AGE` seconds,
+    each URL's answer kept as long. ``None`` when it cannot be read (logged at
+    DEBUG). A URL it cannot answer raises ``KeyError``."""
+    global _system, _system_at
+    with _system_lock:
+        now = time.monotonic()
+        if _system_at and now - _system_at <= SYSTEM_PROXY_MAX_AGE:
+            return _system
+        try:
+            _system = proxylib.Cached(_Quiet(proxylib.auto_proxy(environ={})), ttl=SYSTEM_PROXY_MAX_AGE)
+        except Exception as exc:
+            _log.debug("the system proxy configuration could not be read: %s", exc)
+            _system = None
+        _system_at = now
+        return _system
+
+
+class _Credential:
+    """Every proxy ``inner`` answers, given ``Proxy-Authorization: value``
+    (SOCKS entries, which take no header, and DIRECT as they are)."""
+
+    def __init__(self, inner: Any, value: str) -> None:
+        self.inner = inner
+        self.value = value
+
+    def __getitem__(self, url: str) -> Tuple[Optional[Proxy], ...]:
+        return tuple(
+            (
+                entry
+                if entry is None or entry.scheme.startswith("socks")
+                else _with_credential(entry, DEFAULT_AUTH_HEADER, self.value)
+            )
+            for entry in proxylib.lookup(self.inner, url)
+        )
+
+
+class _SettingsMap:
+    """:func:`proxy_map`'s map: the settings read again at every lookup."""
+
+    def __init__(self, proxy: Optional[str], noproxy: Optional[str], proxy_user: Optional[str], env: Any) -> None:
+        self.proxy = proxy
+        self.noproxy = noproxy
+        self.proxy_user = proxy_user
+        self.env = env
+
+    def __repr__(self) -> str:
+        return "proxy_map(%s)" % ("proxy=%r" % Proxy.parse(self.proxy).url if self.proxy else "")
+
+    def _inner(self, env: HTTPEnv) -> Any:
+        if self.proxy is not None:
+            # curl's -x: always a plain proxy, its credential its own.
+            return proxylib.SimpleProxyMap(Proxy.parse(self.proxy) if self.proxy else None)
+        configured = configured_proxy(env=env)
+        if configured is not None:
+            return proxylib.SimpleProxyMap(configured)
+        environ = _proxy_environ(env)
+        machine: Any = None
+        if environ or not system_proxy_enabled(env=env):
+            # Its variables alone decide, as urllib.request.getproxies() has it;
+            # --noproxy replaces NO_PROXY in the variables' own map too.
+            no_proxy = env.get("no_proxy", "NO_PROXY")
+            if no_proxy:
+                environ["no_proxy"] = no_proxy
+            machine = proxylib.EnvProxyConfig(environ, no_proxy=self.noproxy)
+        else:
+            machine = system_map()
+        chain = proxylib.ChainProxyMap(*(m for m in (machine, proxylib.SimpleProxyMap()) if m is not None))
+        found = env.find(MACHINE_AUTH_VAR)
+        return _Credential(chain, _checked(*found)) if found else chain
+
+    def _no_proxy(self, env: HTTPEnv) -> Optional[str]:
+        return self.noproxy if self.noproxy is not None else env.get("no_proxy", "NO_PROXY")
+
+    def __getitem__(self, url: str) -> Tuple[Optional[Proxy], ...]:
+        env = _env(self.env)
+        inner = self._inner(env)
+        no_proxy = self._no_proxy(env)
+        if no_proxy:
+            inner = proxylib.Bypass(inner, no_proxy)
+        answer = proxylib.lookup(inner, url)
+        if self.proxy_user is not None:
+            answer = tuple(None if entry is None else _with_user(entry, self.proxy_user) for entry in answer)
+        return answer
+
+    def close(self) -> None:
+        """Nothing to free: the system's map is shared."""
+
+
+def proxy_map(
+    proxy: Optional[str] = None,
+    noproxy: Optional[str] = None,
+    proxy_user: Optional[str] = None,
+    *,
+    env: Optional[HTTPEnv] = None,
+) -> Any:
+    """syshttp's routing as a proxylib ``ProxyMap`` (``proxylib.lookup(m,
+    url)`` reads it; every proxylib integration takes it). The settings are
+    read at every lookup, so one map serves a long-lived client. It always
+    answers (never ``KeyError``).
+
+    ``proxy`` (curl's ``-x``) replaces the settings with that proxy, always a
+    plain one whose credential is its own userinfo, never the configured
+    ``SYSHTTP_PROXY_AUTH``; ``""`` means direct. ``noproxy`` (``--noproxy``)
+    replaces ``NO_PROXY``. ``proxy_user`` (``-U user:password``) becomes the
+    credential of whichever proxy answers, replacing the configured one. A
+    malformed setting raises ``ValueError`` at lookup, only when it would be
+    used."""
+    return _SettingsMap(proxy, noproxy, proxy_user, env)

syshttp/retry.py

@@ -0,0 +1,34 @@
+"""What counts as transient -- the one list the client's
+retries and a curl front end's ``--retry`` both use. Dependency-free."""
+
+from __future__ import annotations
+
+import time
+from typing import Iterable, Optional, Tuple
+
+from ._parse import ascii_int, http_date
+
+__all__ = (
+    "TRANSIENT_STATUSES",
+    "retry_after",
+)
+
+#: The HTTP statuses curl calls transient: request timeout, too many
+#: requests, and the 5xx a retry can fix.
+TRANSIENT_STATUSES: Tuple[int, ...] = (408, 429, 500, 502, 503, 504)
+
+
+def retry_after(headers: Iterable[Tuple[str, str]], now: Optional[float] = None) -> Optional[float]:
+    """A response's ``Retry-After`` in seconds -- a number, or an HTTP date
+    from now -- or ``None`` when absent or unreadable. ``headers`` are
+    ``(name, value)`` pairs."""
+    value = next((v for k, v in headers if k.lower() == "retry-after"), "").strip()
+    if not value:
+        return None
+    seconds = ascii_int(value)
+    if seconds is not None:
+        return float(seconds)
+    when = http_date(value)
+    if when is None:
+        return None
+    return max(0.0, when - (time.time() if now is None else now))

syshttp/tls.py

@@ -0,0 +1,60 @@
+"""The system's TLS client as an ``SSLContext`` -- what the client
+(``syshttp.client``) and a curl front end both connect with.
+
+With neither ``cafile`` nor ``capath`` the context is
+``sslcontext.system_context()``: certificates are verified by the operating
+system's own verifier on Python 3.10+ (CryptoAPI on Windows, the Security
+framework on macOS, OpenSSL over the system's store elsewhere), so
+intermediate fetching, enterprise roots and policy apply as they do for the
+system's own clients; on 3.9 by OpenSSL over the default store. A server that
+asks for a client certificate gets one from the OS store (Windows Personal
+store and smart cards, the macOS keychains, the default PKCS#11 module), chosen
+as a browser chooses, or none. A ``cafile`` / ``capath`` replaces the store: a
+plain ``ssl`` context trusting only them. No ``certifi`` bundle is involved."""
+
+from __future__ import annotations
+
+import ssl
+import time
+from typing import Optional
+
+import sslcontext
+
+__all__ = (
+    "OS_CONTEXT_MAX_AGE",
+    "new_os_context",
+    "os_ssl_context",
+)
+
+#: How long the shared context is reused (seconds) before it is rebuilt, so a
+#: certificate added to the system store is picked up.
+OS_CONTEXT_MAX_AGE = 60
+_os_context: "Optional[ssl.SSLContext]" = None
+_os_context_at = 0.0
+
+
+def new_os_context(
+    cafile: Optional[str] = None, capath: Optional[str] = None, *, client_certificates: bool = True
+) -> "ssl.SSLContext":
+    """A fresh verifying client context: on ``cafile`` / ``capath`` when given
+    (they replace the OS store), else the system's (``sslcontext.system_context``).
+    ``client_certificates=False`` never offers a certificate from the OS store:
+    pass it before loading a client certificate of your own, which a store
+    certificate would otherwise replace."""
+    if cafile or capath:
+        return ssl.create_default_context(cafile=cafile, capath=capath)
+    return sslcontext.system_context(selector=None if client_certificates else False)
+
+
+def os_ssl_context() -> "ssl.SSLContext":
+    """The system's ``SSLContext`` (:func:`new_os_context`), shared for
+    :data:`OS_CONTEXT_MAX_AGE` seconds. Shared, because urllib3 keys its
+    connection pools by the context object: one per request would never reuse
+    a connection. Never load a client certificate into it: use
+    :func:`new_os_context` with ``client_certificates=False``."""
+    global _os_context, _os_context_at
+    now = time.monotonic()
+    if _os_context is None or now - _os_context_at > OS_CONTEXT_MAX_AGE:
+        _os_context = new_os_context()
+        _os_context_at = now
+    return _os_context

syshttp-0.1.0.dist-info/METADATA

@@ -0,0 +1,219 @@
+Metadata-Version: 2.5
+Name: syshttp
+Version: 0.1.0
+Summary: HTTP plumbing that follows the system: the system proxy (PAC, WPAD) and the OS certificate verifier by default, proxy credentials and prefix gateways, Netscape cookie jars, OS trust-store TLS, URL hooks, and an HTTP client on the standard library
+Project-URL: Homepage, https://github.com/jose-pr/syshttp
+Project-URL: Documentation, https://jose-pr.github.io/syshttp/
+Project-URL: Issues, https://github.com/jose-pr/syshttp/issues
+Author-email: jose-pr <jose-pr@coqui.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: importpatch<0.3,>=0.2.1
+Requires-Dist: proxylib<3,>=2.0.2
+Requires-Dist: sslcontext<3,>=2.1.0
+Provides-Extra: dev
+Requires-Dist: aiohttp; extra == 'dev'
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: mypy<2; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: requests; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: pac
+Requires-Dist: proxylib[pac]<3,>=2.0.2; extra == 'pac'
+Description-Content-Type: text/markdown
+
+# syshttp
+
+[![Version](https://img.shields.io/pypi/v/syshttp.svg)](https://pypi.org/project/syshttp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/syshttp.svg)](https://pypi.org/project/syshttp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/syshttp/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/syshttp/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/syshttp/test.yml)](https://github.com/jose-pr/syshttp/actions/workflows/test.yml)
+
+**HTTP plumbing that behaves the same in every client you build on it**:
+which proxy to use, with which credential, for which hosts; how a prefix
+gateway is spoken to; which cookies and tokens go with which origin; and TLS
+through the operating system's own certificate verifier. By default it
+routes the way the system does: the system's proxy configuration, PAC scripts
+and WPAD included, unless a proxy variable says otherwise. An HTTP client on the
+standard library puts all of them together; `requests` is needed by none of
+it. Documentation: <https://jose-pr.github.io/syshttp/>.
+
+## Features
+
+- **Routing is [proxylib](https://pypi.org/project/proxylib/)'s** —
+  `proxy.proxy_map()` turns the settings below into one proxylib proxy map,
+  and proxylib's client integrations send through it.
+- **The system's proxy, by default** — with no proxy variable set, the
+  system's configuration decides per URL: WinHTTP on Windows, CFNetwork on
+  macOS, libproxy or the desktop's settings elsewhere, PAC and WPAD included.
+  A list (`PROXY a; PROXY b; DIRECT`) is tried in order, the next entry when
+  one does not connect; with no proxy connecting and no DIRECT the request
+  fails rather than going direct.
+- **Proxies with credentials** — a proxy URL from `SYSHTTP_PROXY`, else the
+  usual `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` for the request's scheme.
+  The credential is a header value sent verbatim to that proxy only, so any
+  scheme works (`Basic`, `Bearer`, `Negotiate`). `NO_PROXY` is honoured
+  (CIDR included), and every redirect hop is decided again.
+- **Prefix gateways** — `SYSHTTP_PROXY_TYPE=prefix:/fetch/` sends
+  `GET https://api.example.com/x` to `<proxy>/fetch/https://api.example.com/x`
+  (the client, requests, httpx and urllib; the client sends an `https:` origin
+  through an `https` gateway only). Responses, redirects and cookies still use
+  the caller's URL.
+- **Prefixes of a tool's own** — `SYSHTTP_PREFIX=MYTOOL_` makes the package
+  read `MYTOOL_HTTPS_PROXY`, `MYTOOL_SYSHTTP_HOME` and so on instead of the
+  defaults; `MYTOOL_:` falls back to them, variable by variable. An
+  `HTTPEnv("MYTOOL_")` object keeps one configuration apart from another in
+  the same process.
+- **Cookie and token jars** — Netscape cookie files with curl's matching
+  rules, plus per-host token files. Both are chosen by the origin's host,
+  never by the proxy's or the gateway's.
+- **URL hooks** — `SYSHTTP_HOOKS_<KEY>=<regex>` plus `_PY=module:callable`
+  runs your code before matching requests: a login, a signature, a canned
+  response.
+- **The system's TLS client, or your own TLS context** — by default
+  [sslcontext](https://pypi.org/project/sslcontext/)'s system context: the
+  operating system verifies certificates (CryptoAPI, the Security framework),
+  with no `certifi` bundle involved, and a server that asks for a client
+  certificate gets one from the OS store (smart cards included), chosen as a
+  browser chooses. Or `HTTPClient(ssl_context=...)` for a given identity, a
+  cipher list or a pinned protocol version.
+- **An HTTP client on the standard library** — `HTTPClient` and `fetch()`:
+  retry with backoff, redirects that keep a credential with its origin, and
+  all of the above, on `http.client` and `ssl` alone. Its transport is
+  replaceable: any object with `send()` (a `requests` or `httpx` one, a fake
+  in a test), chosen per client or by `SYSHTTP_DEFAULT_TRANSPORT`.
+- **Other programs' clients, patched on import** — `SYSHTTP_IMPORTPATCH=1`
+  (or `requests:urllib:httpx:aiohttp:pip`) makes those libraries route and
+  verify the same way in any program of the environment, through
+  [importpatch](https://pypi.org/project/importpatch/); what a caller sets
+  itself still wins.
+
+## Installation
+
+```bash
+pip install syshttp
+```
+
+| Extra | Adds | Needed for |
+| --- | --- | --- |
+| `pac` | a JavaScript engine for proxylib | PAC scripts proxylib evaluates itself (Linux without libproxy) |
+
+syshttp depends on proxylib (the system proxy), sslcontext (the system's
+TLS client: the OS verifier through truststore on Python 3.10+, OpenSSL over
+the default store on 3.9) and importpatch (its `.pth` hooks imports at
+interpreter start; nothing is patched unless `SYSHTTP_IMPORTPATCH` says so).
+
+## Quick start
+
+Ask where a request would go, the way every client here does:
+
+```python
+import proxylib
+from syshttp import proxy
+
+for entry in proxylib.lookup(proxy.proxy_map(), "https://api.example.com/"):
+    print("DIRECT" if entry is None else entry.url)   # tried in this order
+```
+
+One request, routed and verified the way the system does (no extra to install):
+
+```python
+from syshttp import fetch
+
+response = fetch("https://api.example.com/thing")
+print(response.status, response.json())
+```
+
+A client with file-backed cookies and tokens, kept across requests:
+
+```python
+from syshttp.client import HTTPClient
+
+with HTTPClient(cookies=True, tokens=True) as client:
+    response = client.request("GET", "https://api.example.com/thing")
+```
+
+A separate configuration, isolated from the process environment:
+
+```python
+from syshttp import HTTPEnv, fetch
+
+env = HTTPEnv("MYTOOL_", environ={"MYTOOL_SYSHTTP_PROXY": "http://proxy.internal:3128"})
+response = fetch("https://api.example.com/thing", env=env)
+```
+
+## API overview
+
+| Module | Purpose |
+| --- | --- |
+| `syshttp.env` | `HTTPEnv`: the prefixes and mapping every setting is read from |
+| `syshttp.proxy` | `proxy_map()`: the settings as one proxylib proxy map |
+| `syshttp.client` | `HTTPClient` and `fetch()`: the HTTP client, its transport protocol and response |
+| `syshttp.jar` | file and memory cookie/token jars |
+| `syshttp.cookies` | Netscape cookie files and curl's cookie rules |
+| `syshttp.hooks` | URL hooks declared in the environment |
+| `syshttp.tls` | the OS verifier as an `SSLContext` |
+| `syshttp.autopatch` | requests, urllib, httpx, aiohttp and pip patched on import |
+| `syshttp.retry` | the transient statuses, `Retry-After` |
+
+## Settings
+
+Every setting is read as `<PREFIX><NAME>` for each prefix of
+`SYSHTTP_PREFIX` (`:`-separated; default none, the names as written). The
+full list is on the docs site:
+<https://jose-pr.github.io/syshttp/settings/>.
+
+| Variable | Sets |
+| --- | --- |
+| `SYSHTTP_PREFIX` | the prefixes every other setting is read under |
+| `SYSHTTP_PROXY` | the proxy URL; else `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, else the system's |
+| `SYSHTTP_SYSTEM_PROXY` | `0` to stop consulting the system's proxy configuration |
+| `SYSHTTP_PROXY_AUTH` | the proxy credential, sent verbatim; else `HTTP_PROXY_AUTH` |
+| `SYSHTTP_PROXY_AUTH_HEADER` | the header it is sent in (default `Proxy-Authorization`) |
+| `SYSHTTP_PROXY_TYPE` | `connect` (default) or `prefix[:/endpoint]` |
+| `SYSHTTP_HOME` | the jar directory (default: the per-user state directory) |
+| `SYSHTTP_IMPORTPATCH` | `1`, or `:`-separated names: the client libraries patched on import |
+| `SYSHTTP_HOOKS_<KEY>` | a URL hook's pattern, with `_PY` / `_CURL` targets |
+| `SYSHTTP_DEFAULT_TRANSPORT` | `module:attr` or `<file>.py:attr`: the transport of a client given none (it names code to import) |
+| `CA_BUNDLE` | the CA bundle a client verifies with (default: the OS verifier) |
+
+## Development
+
+```bash
+dotagents pyvenv            # or any Python 3.9+ virtual environment
+.pyvenv/<tag>/Scripts/python -m pip install -e ".[dev]"
+.pyvenv/<tag>/Scripts/python -m pytest -q
+```
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](https://github.com/jose-pr/syshttp/blob/main/CHANGELOG.md).
+Pushing a tag matching `v*` triggers the release workflow: test gate → build
+(checking the tag names the version built) → a strict docs build as a gate →
+GitHub release → publish. The release workflow never deploys the docs site
+itself: for a final release its last job dispatches the docs workflow at the
+tag, which owns every Pages deploy.
+
+## License
+
+MIT — see [LICENSE](https://github.com/jose-pr/syshttp/blob/main/LICENSE).