Function start_api_preconnect

src/utils/api_preconnect.py:73–104

Spawn a daemon thread that fires HEAD ``url``; return immediately. The thread completes (or times out) on its own. ``daemon=True`` so a slow handshake never blocks process exit.

(url: str = _DEFAULT_PRECONNECT_URL)

def start_api_preconnect(url: str = _DEFAULT_PRECONNECT_URL) -> PreconnectHandle:
    """Spawn a daemon thread that fires HEAD ``url``; return immediately.

    The thread completes (or times out) on its own. ``daemon=True`` so a
    slow handshake never blocks process exit.
    """
    if should_skip_preconnect():
        return PreconnectHandle(thread=None, skipped=True)

    def _do_preconnect() -> None:
        # Lazy import inside the thread so importing this module doesn't
        # pull in httpx on the cold-start path.
        try:
            import httpx
        except ImportError:  # pragma: no cover
            return
        try:
            with httpx.Client(timeout=_PRECONNECT_TIMEOUT_S) as client:
                # HEAD warms the handshake without transferring a body.
                # 4xx/5xx are fine — we just want the TCP+TLS session.
                client.head(url)
        except Exception:
            # Best-effort: never let preconnect failures bubble up.
            pass

    thread = threading.Thread(
        target=_do_preconnect,
        name="api-preconnect",
        daemon=True,
    )
    thread.start()
    return PreconnectHandle(thread=thread, skipped=False)