snowflake-sandbox-python 0.2.1a1__py3-none-any.whl

snowflake/sandbox/_sync_transport.py

@@ -0,0 +1,737 @@
+"""Synchronous HTTP transport for ``snowflake.sandbox``.
+
+Mirrors ``_transport.Transport`` but uses ``httpx.Client`` (blocking) instead
+of ``httpx.AsyncClient``. Used by ``Sandbox`` (sync) while ``AsyncSandbox``
+uses the async transport.
+"""
+
+from __future__ import annotations
+
+import random
+import socket
+import threading
+import time
+from collections.abc import Callable, Iterator, Mapping
+from typing import Any, BinaryIO, Protocol
+
+import httpx
+
+from snowflake.sandbox._retry import (
+    DEFAULT_500_DELAYS_S,
+    DEFAULT_COLD_START_DELAYS_S,
+    compute_backoff,
+)
+from snowflake.sandbox._sse import (
+    SSEEvent,
+    _sse_open_retry_delay,
+    parse_sse_event,
+)
+from snowflake.sandbox._transport import (
+    _FILE_CHUNK_BYTES,
+    _IDEMPOTENT_METHODS,
+    _RESERVED_HEADER_NAMES,
+    _SENT_ERRORS,
+    _UNSENT_ERRORS,
+    _USER_AGENT,
+    _cws_transform,
+    _RequestAuth,
+    _RetryState,
+    _seekable_size,
+    _status_retry_delay,
+    _transport_error_delay,
+)
+from snowflake.sandbox._transport_errors import (
+    _is_reauth_response,
+    _status_to_error,
+)
+from snowflake.sandbox.config import (
+    Config,
+    current_config,
+    refresh_config,
+    refresh_credential,
+)
+from snowflake.sandbox.exceptions import (
+    SandboxAuthError,
+    SandboxTransportError,
+)
+
+# ``shutdown_sync`` was defined here as a one-line alias for
+# ``reset_sync_transport()``; it now lives in ``lifecycle`` next to its async twin
+# ``shutdown()`` so both halves of the sync/async lifecycle axis share one public home.
+# Re-exported here so existing ``_sync_transport.shutdown_sync`` callers keep working.
+# ``lifecycle`` imports this module only inside its function bodies, so this edge does
+# not close a module-scope cycle.
+from snowflake.sandbox.lifecycle import shutdown_sync
+
+__all__ = [
+    "SSEEvent",
+    "SyncTransport",
+    "get_sync_transport",
+    "reset_sync_transport",
+    "shutdown_sync",
+]
+
+
+class _Shutdownable(Protocol):
+    """The one method `StreamAbort` needs from the underlying socket.
+
+    Typed as a structural `Protocol` rather than ``socket.socket`` because httpx's
+    ``network_stream.get_extra_info("socket")`` can hand back a plain socket OR an
+    ``ssl.SSLSocket`` (which is not a ``socket.socket`` subclass); both expose
+    ``shutdown``, which is all the abort path calls.
+    """
+
+    def shutdown(self, how: int, /) -> object: ...
+
+
+class StreamAbort:
+    """Lets one thread interrupt an SSE read that another thread is blocked in.
+
+    ``terminate()`` used to leave an in-flight `exec_stream` hanging until the HTTP
+    read timeout expired -- ``exec_budget + 30s``, so up to 630s on the default
+    budget. The reading thread sits in a blocking ``recv()`` inside
+    ``resp.iter_lines()``, and nothing that runs on the terminating thread reaches
+    it:
+
+    * ``generator.close()`` throws ``GeneratorExit`` at the generator's *suspension
+      point*, which Python cannot deliver until the C-level read returns.
+    * ``httpx.Response.close()`` marks the response closed and returns the
+      connection to the pool, but does not disturb an in-progress ``recv()``.
+      Measured: the reader thread stayed alive.
+
+    ``socket.shutdown(SHUT_RDWR)`` is the one thing that does interrupt it -- the
+    POSIX behaviour is that a blocked ``recv()`` on a shut-down socket returns
+    immediately. Measured: the reader unblocks at once, and the shared
+    ``httpx.Client`` remains usable afterwards because httpx discards the broken
+    connection rather than returning it to the pool.
+
+    The read ends at EOF rather than raising, so the caller ALSO has to know an
+    abort happened: a clean close with no terminal frame is indistinguishable from
+    the ordinary ~180s ingress cut, which the stream is supposed to resume from.
+    Hence `aborted`, which the reconnect loop checks before resuming.
+    """
+
+    __slots__ = ("_event", "_lock", "_sock")
+
+    def __init__(self) -> None:
+        self._event = threading.Event()
+        self._lock = threading.Lock()
+        self._sock: _Shutdownable | None = None
+
+    def bind(self, resp: httpx.Response) -> None:
+        """Remember the socket under *resp* for the duration of the read.
+
+        Best-effort: the ``network_stream`` extension is not part of httpx's public
+        API surface and is absent on some transports. When it cannot be reached the
+        handle still records the abort, so the stream stops at its read timeout as
+        it did before -- degraded, not broken.
+        """
+        sock = None
+        try:
+            network_stream = resp.extensions.get("network_stream")
+            if network_stream is not None:
+                sock = network_stream.get_extra_info("socket")
+        except Exception:  # pragma: no cover - transport-shape dependent
+            sock = None
+        with self._lock:
+            self._sock = sock
+        if self._event.is_set():
+            # Raced: abort() ran between the request opening and this bind, so it
+            # saw no socket. Shut this one down now or the read blocks anyway.
+            self._shutdown()
+
+    def unbind(self) -> None:
+        """Forget the socket once the read is over."""
+        with self._lock:
+            self._sock = None
+
+    def abort(self) -> None:
+        """Mark aborted and interrupt any read currently blocked on the socket."""
+        self._event.set()
+        self._shutdown()
+
+    def _shutdown(self) -> None:
+        with self._lock:
+            sock = self._sock
+        if sock is None:
+            return
+        try:
+            sock.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass  # already closed, or never connected
+
+    @property
+    def aborted(self) -> bool:
+        return self._event.is_set()
+
+
+def _iter_file(f: BinaryIO) -> Iterator[bytes]:
+    """Yield a file's bytes in chunks."""
+    while True:
+        chunk = f.read(_FILE_CHUNK_BYTES)
+        if not chunk:
+            return
+        yield chunk
+
+
+class SyncTransport:
+    """Synchronous HTTP transport using httpx.Client.
+
+    Mirrors the async ``Transport`` class but with blocking methods.
+    """
+
+    def __init__(self, config: Config | None = None, role_key: str | None = None) -> None:
+        self._config_override = config
+        # With no explicit config this transport is the AMBIENT one: it re-resolves
+        # through current_config() on every request. ``role_key`` is the role to resolve
+        # AT, so its requests carry that role's token rather than the default's.
+        self._role_key = role_key if config is None else None
+        self._client: httpx.Client | None = None
+        self._client_lock = threading.Lock()
+        self._rng = random.Random()
+        self._refresh_lock = threading.Lock()
+
+    @property
+    def config(self) -> Config:
+        return self._config_override or current_config(role=self._role_key)
+
+    def _get_client(self) -> httpx.Client:
+        """Return the HTTP client, creating it lazily.
+
+        Uses HTTP/1.1 (not HTTP/2) so the client is safe to share across threads.
+        ``httpx.Client`` with HTTP/2 multiplexes all requests over a single TCP
+        connection and is not thread-safe for concurrent writes from multiple
+        threads — simultaneous frame writes corrupt the H2 stream, causing the
+        server to disconnect (sandbox-api#164). HTTP/1.1 uses a connection pool
+        that is thread-safe by design. The async transport keeps HTTP/2 because
+        ``httpx.AsyncClient`` runs in a single asyncio event-loop thread where
+        concurrent-stream multiplexing is safe.
+        """
+        with self._client_lock:
+            if self._client is None:
+                cfg = self.config
+                limits = httpx.Limits(
+                    max_connections=cfg.max_connections,
+                    max_keepalive_connections=cfg.max_connections,
+                )
+                self._client = httpx.Client(
+                    base_url=cfg.base_url,
+                    http2=False,  # HTTP/1.1: thread-safe; see docstring above
+                    trust_env=not cfg.cws_dev,
+                    timeout=cfg.timeout_s,
+                    verify=cfg.verify,
+                    limits=limits,
+                    headers={"User-Agent": _USER_AGENT},
+                )
+            return self._client
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        with self._client_lock:
+            if self._client is not None:
+                self._client.close()
+                self._client = None
+
+    def _auth_headers(
+        self, extra: Mapping[str, str] | None = None, *, cfg: Config | None = None
+    ) -> dict[str, str]:
+        cfg = cfg if cfg is not None else self.config
+        # Live-read the connection's current token (see Transport._auth_headers).
+        token = cfg.resolve_pat()
+        if not token:
+            raise SandboxAuthError(
+                "no Snowflake credential resolved: set SNOWFLAKE_PAT or "
+                "SNOWFLAKE_TOKEN, name a connection in ~/.snowflake/connections.toml, "
+                "or pass connection= on the call"
+            )
+        if cfg.cws_dev:
+            h: dict[str, str] = {
+                "Authorization": f'Snowflake Token="{token}"',
+                "Accept": "application/json",
+            }
+            if cfg.cws_gs_host:
+                h["Host"] = cfg.cws_gs_host
+        else:
+            if token.startswith("ver:"):
+                auth_val = f'Snowflake Token="{token}"'
+            else:
+                auth_val = f"Bearer {token}"
+            h = {
+                "Authorization": auth_val,
+                "Accept": "application/json",
+            }
+        for k, v in cfg.extra_headers.items():
+            if k.lower() in _RESERVED_HEADER_NAMES:
+                import warnings
+
+                warnings.warn(
+                    f"ignoring header {k!r} from SNOWFLAKE_CWS_EXTRA_HEADERS: it may "
+                    "not override the request's Authorization or Host.",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+                continue
+            h[k] = v
+        if extra:
+            for k, v in extra.items():
+                h[k] = v
+        return h
+
+    def _refresh_auth(self, stale_pat: str | None) -> str | None:
+        """Re-mint the token after a reauth response; the new token, or ``None``.
+
+        Counterpart of ``Transport._refresh_auth``: an explicit-config transport
+        refreshes THAT config (deduped on ``_refresh_lock``); the default transport
+        refreshes the process-wide active config (deduped in the config layer).
+        """
+        if stale_pat is None:
+            return None
+        if self._config_override is None:
+            return refresh_credential(stale_pat)
+        return self._refresh_override(stale_pat)
+
+    def _refresh_override(self, stale_pat: str) -> str | None:
+        """Deduped re-mint of this transport's explicit config override. Re-reads
+        under ``_refresh_lock`` so two racers don't double-mint or clobber a newer
+        token with an older one. The blocking twin of ``Transport._refresh_override``
+        (which the async side hands to ``asyncio.to_thread``); kept as its own method
+        so both transports decompose reauth the same way."""
+        with self._refresh_lock:
+            ov = self._config_override
+            if ov is None:
+                return None
+            current = ov.resolve_pat()
+            if current != stale_pat:
+                return current  # already refreshed by a racer
+            new = refresh_config(ov, stale_pat)
+            new_token = new.resolve_pat()
+            if new_token is None or new_token == stale_pat:
+                return None
+            if new is not ov:
+                self._config_override = new
+            return new_token
+
+    def _ensure_pat(self) -> None:
+        """Lazy-mint a CWS dev session token if no PAT is configured."""
+        cfg = self.config
+        if cfg.pat or not cfg.cws_dev:
+            return
+        # CWS dev token minting is async-only; for sync we require explicit PAT
+        raise SandboxAuthError("CWS dev mode requires SNOWFLAKE_PAT to be set for sync transport")
+
+    def _full_path(self, endpoint: str) -> str:
+        if endpoint.startswith("http://") or endpoint.startswith("https://"):
+            return endpoint
+        if endpoint.startswith("/"):
+            return endpoint
+        return f"{self.config.base_path}/{endpoint}"
+
+    def request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        json_body: Any = None,
+        content: bytes | BinaryIO | None = None,
+        params: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+        retry_not_found: bool = True,
+        retry_500_delays: tuple[float, ...] = DEFAULT_500_DELAYS_S,
+    ) -> httpx.Response:
+        """Issue a request with retry + error mapping (blocking).
+
+        ``retry_500_delays`` overrides the (idempotent-only) 500 retry budget for a
+        single call — e.g. the read-only logs route passes a longer schedule to ride
+        out a transient upstream 500. Default is the one-shot ``DEFAULT_500_DELAYS_S``.
+        """
+        if self.config.cws_dev:
+            endpoint, json_body = _cws_transform(method, endpoint, json_body, timeout)
+        self._ensure_pat()
+        client = self._get_client()
+        path = self._full_path(endpoint)
+        cfg = self.config
+        headers = self._auth_headers(extra_headers, cfg=cfg)
+        if json_body is not None:
+            headers.setdefault("Content-Type", "application/json")
+
+        file_body: BinaryIO | None = None if isinstance(content, bytes) else content
+        if file_body is not None:
+            headers["Content-Length"] = str(_seekable_size(file_body))
+
+        idempotent = method.upper() in _IDEMPOTENT_METHODS
+        state = _RetryState()
+        # See Transport.request(): re-mint the live token once on a reauth response.
+        auth = _RequestAuth(headers=headers, sent_pat=cfg.resolve_pat())
+
+        while True:
+            send_content: bytes | Iterator[bytes] | None = None
+            if file_body is not None:
+                file_body.seek(0)
+                send_content = _iter_file(file_body)
+            elif isinstance(content, bytes):
+                send_content = content
+
+            try:
+                resp = client.request(
+                    method,
+                    path,
+                    json=json_body,
+                    content=send_content,
+                    params=params,
+                    headers=auth.headers,
+                    timeout=timeout if timeout is not None else self.config.timeout_s,
+                )
+            except _UNSENT_ERRORS as exc:
+                delay = _transport_error_delay(
+                    exc,
+                    sent=False,
+                    idempotent=idempotent,
+                    method=method,
+                    path=path,
+                    state=state,
+                    rng=self._rng,
+                )
+                time.sleep(delay)
+                continue
+            except _SENT_ERRORS as exc:
+                delay = _transport_error_delay(
+                    exc,
+                    sent=True,
+                    idempotent=idempotent,
+                    method=method,
+                    path=path,
+                    state=state,
+                    rng=self._rng,
+                )
+                time.sleep(delay)
+                continue
+
+            if resp.status_code < 400:
+                # A 2xx can still be a legacy reauth envelope (see request()).
+                if _is_reauth_response(resp) and self._reauth(
+                    auth, extra_headers=extra_headers, json_body=json_body, file_body=file_body
+                ):
+                    continue
+                return resp
+
+            # Per-status retry POLICY (cold-start 503/409, 429, 500, 404) — see
+            # Transport.request(); shared via _status_retry_delay.
+            retry_delay = _status_retry_delay(
+                self._rng,
+                resp,
+                method=method,
+                path=path,
+                idempotent=idempotent,
+                retry_not_found=retry_not_found,
+                retry_500_delays=retry_500_delays,
+                state=state,
+            )
+            if retry_delay is not None:
+                time.sleep(retry_delay)
+                continue
+
+            # A reauth response (401/403, or a 4xx reauth envelope): re-mint once
+            # and retry. See Transport.request() for the full rationale.
+            if _is_reauth_response(resp) and self._reauth(
+                auth, extra_headers=extra_headers, json_body=json_body, file_body=file_body
+            ):
+                continue
+            raise _status_to_error(resp.status_code, resp.text)
+
+    def _reauth(
+        self,
+        auth: _RequestAuth,
+        *,
+        extra_headers: Mapping[str, str] | None,
+        json_body: Any,
+        file_body: BinaryIO | None,
+    ) -> bool:
+        """Blocking counterpart of ``Transport._reauth``: re-mint the token once on
+        a reauth response and rebuild *auth*'s headers, returning True to retry."""
+        if auth.refreshed:
+            return False
+        auth.refreshed = True
+        new_pat = self._refresh_auth(auth.sent_pat)
+        if new_pat is None or new_pat == auth.sent_pat:
+            return False
+        auth.sent_pat = new_pat
+        auth.headers = self._auth_headers(extra_headers)  # fresh read: new token
+        if json_body is not None:
+            auth.headers.setdefault("Content-Type", "application/json")
+        if file_body is not None:
+            auth.headers["Content-Length"] = str(_seekable_size(file_body))
+        return True
+
+    def download(
+        self,
+        endpoint: str,
+        sink: Callable[[bytes], object],
+        *,
+        params: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+        retry_not_found: bool = True,
+    ) -> httpx.Response:
+        """GET endpoint and hand each chunk to sink (blocking)."""
+        self._ensure_pat()
+        client = self._get_client()
+        path = self._full_path(endpoint)
+        cfg = self.config
+        headers = self._auth_headers(cfg=cfg)
+        sent_pat = cfg.resolve_pat()
+        auth_refreshed = False
+        open_attempt = 0
+
+        while True:
+            try:
+                with client.stream(
+                    "GET",
+                    path,
+                    params=params,
+                    headers=headers,
+                    timeout=timeout if timeout is not None else self.config.timeout_s,
+                ) as resp:
+                    if resp.status_code >= 400:
+                        body = resp.read()
+                        # Full body: _status_to_error unwraps the error envelope
+                        # and truncates any non-envelope fallback itself.
+                        text = body.decode("utf-8", errors="replace")
+                        open_attempt += 1
+                        delay = _sse_open_retry_delay(
+                            resp.status_code,
+                            resp,
+                            open_attempt,
+                            self._rng,
+                            retry_not_found=retry_not_found,
+                        )
+                        if delay is not None:
+                            time.sleep(delay)
+                            continue
+                        if _is_reauth_response(resp) and not auth_refreshed:
+                            auth_refreshed = True
+                            new_pat = self._refresh_auth(sent_pat)
+                            if new_pat is not None and new_pat != sent_pat:
+                                sent_pat = new_pat
+                                headers = self._auth_headers()
+                                continue
+                        raise _status_to_error(resp.status_code, text)
+                    for chunk in resp.iter_bytes():
+                        sink(chunk)
+                    return resp
+            except _UNSENT_ERRORS as exc:
+                open_attempt += 1
+                delay = compute_backoff(
+                    open_attempt, delays=DEFAULT_COLD_START_DELAYS_S, rng=self._rng
+                )
+                if delay is None:
+                    raise SandboxTransportError(f"transport error after retries: {exc}") from exc
+                time.sleep(delay)
+            except _SENT_ERRORS as exc:
+                raise SandboxTransportError(f"transport error mid-download: {exc}") from exc
+
+    def stream_sse(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        json_body: Any = None,
+        timeout: float | None = None,
+        retry_not_found: bool = True,
+        abort: StreamAbort | None = None,
+    ) -> Iterator[SSEEvent]:
+        """Open an SSE stream and yield parsed events (blocking).
+
+        *abort* lets another thread interrupt the read -- see `StreamAbort`. Without
+        it a reader stays blocked until the HTTP read timeout, which on the default
+        exec budget is 630s.
+        """
+        self._ensure_pat()
+        path = self._full_path(endpoint)
+        cfg = self.config
+        headers = self._auth_headers({"Accept": "text/event-stream"}, cfg=cfg)
+        if json_body is not None:
+            headers.setdefault("Content-Type", "application/json")
+        client = self._get_client()
+        sent_pat = cfg.resolve_pat()
+        auth_refreshed = False
+        open_attempt = 0
+
+        while True:
+            # Nothing to open if terminate() already fired.
+            if abort is not None and abort.aborted:
+                return
+            try:
+                with client.stream(
+                    method,
+                    path,
+                    json=json_body,
+                    headers=headers,
+                    timeout=timeout if timeout is not None else self.config.timeout_s,
+                ) as resp:
+                    if resp.status_code >= 400:
+                        body = resp.read()
+                        # Full body: _status_to_error unwraps the error envelope
+                        # and truncates any non-envelope fallback itself.
+                        text = body.decode("utf-8", errors="replace")
+                        open_attempt += 1
+                        delay = _sse_open_retry_delay(
+                            resp.status_code,
+                            resp,
+                            open_attempt,
+                            self._rng,
+                            retry_not_found=retry_not_found,
+                        )
+                        if delay is not None:
+                            time.sleep(delay)
+                            continue
+                        if _is_reauth_response(resp) and not auth_refreshed:
+                            auth_refreshed = True
+                            new_pat = self._refresh_auth(sent_pat)
+                            if new_pat is not None and new_pat != sent_pat:
+                                sent_pat = new_pat
+                                headers = self._auth_headers({"Accept": "text/event-stream"})
+                                if json_body is not None:
+                                    headers.setdefault("Content-Type", "application/json")
+                                continue
+                        raise _status_to_error(resp.status_code, text)
+                    if abort is not None:
+                        abort.bind(resp)
+                    try:
+                        yield from _iter_sse_frames_sync(resp)
+                    finally:
+                        if abort is not None:
+                            abort.unbind()
+                    return
+            except _UNSENT_ERRORS as exc:
+                open_attempt += 1
+                delay = compute_backoff(
+                    open_attempt, delays=DEFAULT_COLD_START_DELAYS_S, rng=self._rng
+                )
+                if delay is None:
+                    raise SandboxTransportError(f"SSE transport error: {exc}") from exc
+                time.sleep(delay)
+            except _SENT_ERRORS as exc:
+                raise SandboxTransportError(f"SSE transport error: {exc}") from exc
+
+
+def _iter_sse_frames_sync(resp: httpx.Response) -> Iterator[SSEEvent]:
+    """Yield parsed SSE frames from a sync response."""
+    buf: list[str] = []
+    for line in resp.iter_lines():
+        if line == "":
+            if buf:
+                evt = parse_sse_event("\n".join(buf))
+                buf = []
+                if evt is not None:
+                    yield evt
+        else:
+            buf.append(line)
+
+
+_sync_transport_lock = threading.Lock()
+# Transport pool, keyed ``(role, scope)``: ``role`` is the uppercased Snowflake role
+# (``None`` for no role override) and ``scope`` is the identity of an enclosing
+# ``using()`` connection (``None`` outside one). Created lazily on first
+# get_sync_transport() call.
+#
+# ``scope`` is part of the key because an ``httpx.Client`` bakes ``base_url`` and
+# ``verify`` in at construction: a transport that merely re-read the config per
+# request would keep talking to whichever host it was first used against, and would
+# send a scoped account's token to the previous account's host.
+_sync_transport_pool: dict[tuple[str | None, str | None], SyncTransport] = {}
+
+
+def get_sync_transport_for_config(config: Config, role: str | None = None) -> SyncTransport:
+    """Return the pooled sync transport for an explicitly-resolved `Config`.
+
+    The sync half of `_transport.get_transport_for_config`; see that docstring. Both
+    ``connection=`` on an entry point and a ``using()`` block arrive here.
+    """
+    from snowflake.sandbox.config import _scope_key
+
+    key: str | None = role.upper() if role else None
+    with _sync_transport_lock:
+        entry = (key, _scope_key(config))
+        if entry not in _sync_transport_pool:
+            _sync_transport_pool[entry] = SyncTransport(config=config, role_key=None)
+        return _sync_transport_pool[entry]
+
+
+def get_sync_transport(role: str | None = None) -> SyncTransport:
+    """Return the process-wide sync transport for the given role, creating it lazily.
+
+    ``role=None`` (the default) returns the no-role transport. Passing a role returns
+    a transport that resolves the ambient connection AT that role, so concurrent agents
+    using different roles never share a transport.
+
+    Inside a ``using()`` block, returns that block's transport instead -- the ambient
+    transport is only for callers who named no connection at all.
+    """
+    from snowflake.sandbox.config import _scoped_config
+
+    cfg = _scoped_config(role)
+    if cfg is not None:
+        return get_sync_transport_for_config(cfg, role)
+    key: str | None = role.upper() if role else None
+    with _sync_transport_lock:
+        entry = (key, None)
+        if entry not in _sync_transport_pool:
+            # The ambient transport re-resolves through ``current_config(role=...)``.
+            _sync_transport_pool[entry] = SyncTransport(role_key=key)
+        return _sync_transport_pool[entry]
+
+
+def reset_scoped_sync_transports() -> None:
+    """Drop every ``using()``-scoped sync transport, closing their HTTP clients.
+
+    The sync half of `_transport.reset_scoped_transports`; see that docstring for why
+    ``close_connections()`` has to do this for explicitly-bound transports and not for the
+    ambient one.
+    """
+    with _sync_transport_lock:
+        doomed = [k for k in _sync_transport_pool if k[1] is not None]
+        entries = [_sync_transport_pool.pop(k) for k in doomed]
+    for t in entries:
+        t.close()
+
+
+def close_scoped_sync_transports_for(scope_key: str) -> None:
+    """Close only the scoped sync transports built for ONE credential scope.
+
+    The narrow counterpart of `reset_scoped_sync_transports`, for
+    ``using(..., close=True)``: that call releases the connection the block opened, so it
+    must not also close a SIBLING scope's transport or a ``connection=``-bound one. Those
+    would recover (the client is recreated lazily) but would pay an avoidable TLS
+    handshake, and a scoped verb reaching outside its scope is the wrong default even when
+    the cost is only latency.
+    """
+    with _sync_transport_lock:
+        doomed = [k for k in _sync_transport_pool if k[1] == scope_key]
+        entries = [_sync_transport_pool.pop(k) for k in doomed]
+    for t in entries:
+        t.close()
+
+
+def reset_sync_transport(role: str | None = None) -> None:
+    """Drop one (or all) sync transports from the pool, closing their HTTP clients.
+
+    Called with no arguments (or ``role=None``) to close **all** pool entries.
+
+    Called with a specific role, it closes **every** entry for that role — the ambient
+    one and each connection a ``using()`` block or a ``connection=`` argument bound,
+    since the pool is keyed ``(role, credential)``. Other roles are untouched. The
+    broader-than-it-looks blast radius is deliberate: a caller asking for a role's
+    clients to be released means all of them, not whichever one happened to be ambient.
+    """
+    key: str | None = role.upper() if role else None
+    with _sync_transport_lock:
+        if role is None:
+            entries = list(_sync_transport_pool.values())
+            _sync_transport_pool.clear()
+        else:
+            # Every scope's slot for this role, not just the ambient one: the caller
+            # asked for this role's clients to be released.
+            doomed = [k for k in _sync_transport_pool if k[0] == key]
+            entries = [_sync_transport_pool.pop(k) for k in doomed]
+    for t in entries:
+        t.close()