Security hardening, async session, and extension system improvements (#8)

* fix: security hardening, async session, and foundation improvements

- Redact API key from repr output (token field repr=False)
- Warn on non-HTTPS base_url and verify_ssl=False
- Clamp negative Retry-After to zero
- Add request_id to APIError from x-request-id header
- Add async support to SessionManager (async_open/async_close/async_status/__aenter__/__aexit__)
- Raise IonQError on failed pagination instead of silent empty iterator
- Include exception type name in non-retryable connection errors

* feat: strengthen extension system for downstream SDKs

- Add on_error hook to EventHook/AsyncEventHook protocols, fired when
  the transport raises after retries are exhausted
- Fix precedence: explicit caller args > extension > defaults (was:
  extension silently overrode caller args)
- Add error_mapper to ClientExtension for downstream exception
  translation (e.g. ionq_core.NotFoundError -> QiskitError)
- Add debug_hooks flag to ClientExtension; when True, hook exceptions
  propagate instead of being swallowed
- Fix async client auth header duplication: use constants instead of
  hardcoded strings that could diverge from sync path

Author: splch

ionq_core/_exceptions.py

@@ -18,9 +18,17 @@ class APITimeoutError(APIConnectionError):
 class APIError(IonQError):
     """Raised when the IonQ API returns an error response."""
 
-    def __init__(self, status_code: int, body: dict | str | None = None, message: str | None = None) -> None:
+    def __init__(
+        self,
+        status_code: int,
+        body: dict | str | None = None,
+        message: str | None = None,
+        *,
+        request_id: str | None = None,
+    ) -> None:
         self.status_code = status_code
         self.body = body
+        self.request_id = request_id
         self.message = message or f"HTTP {status_code}"
         super().__init__(self.message)
 
@@ -50,8 +58,10 @@ def __init__(
         body: dict | str | None = None,
         message: str | None = None,
         retry_after: float | None = None,
+        *,
+        request_id: str | None = None,
     ) -> None:
-        super().__init__(status_code, body, message)
+        super().__init__(status_code, body, message, request_id=request_id)
         self.retry_after = retry_after
 
 
@@ -73,11 +83,13 @@ def raise_for_status(
     body: dict | str | None = None,
     retry_after: float | None = None,
     message: str | None = None,
+    *,
+    request_id: str | None = None,
 ) -> None:
     """Raise the appropriate exception for an error status code."""
     if status_code < 400:
         return
     exc_cls = _STATUS_TO_EXCEPTION.get(status_code, ServerError if status_code >= 500 else APIError)
     if exc_cls is RateLimitError:
-        raise RateLimitError(status_code, body, message, retry_after)
-    raise exc_cls(status_code, body, message)
+        raise RateLimitError(status_code, body, message, retry_after, request_id=request_id)
+    raise exc_cls(status_code, body, message, request_id=request_id)

ionq_core/_extensions.py

@@ -33,6 +33,10 @@ class EventHook(Protocol):
     Hooks are for observation only (logging, metrics, telemetry) - they
     must not mutate the request or response.  For mutation, use a custom
     httpx transport instead.
+
+    ``on_error`` is called when the underlying transport raises an
+    exception (after retries are exhausted).  Hooks that do not implement
+    ``on_error`` are silently skipped.
     """
 
     def on_request(self, request: httpx.Request) -> None: ...
@@ -53,6 +57,9 @@ class ClientExtension:
 
     All fields are optional and additive - they layer on top of the
     defaults that IonQClient already provides.
+
+    Explicit caller arguments to ``IonQClient()`` take precedence over
+    extension values, which in turn take precedence over factory defaults.
     """
 
     user_agent_token: str | None = None
@@ -64,35 +71,57 @@ class ClientExtension:
     timeout: httpx.Timeout | None = None
     transport_wrapper: Callable[[httpx.BaseTransport], httpx.BaseTransport] | None = None
     async_transport_wrapper: Callable[[httpx.AsyncBaseTransport], httpx.AsyncBaseTransport] | None = None
+    error_mapper: Callable[[Exception], Exception] | None = None  # return same object to skip mapping
+    debug_hooks: bool = False
 
 
-def _fire_hooks(hooks, method: str, *args) -> None:
+def _fire_hooks(hooks: tuple, method: str, *args, debug: bool = False) -> None:
     for hook in hooks:
+        fn = getattr(hook, method, None)
+        if fn is None:
+            continue
         try:
-            getattr(hook, method)(*args)
+            fn(*args)
         except Exception:
+            if debug:
+                raise
             logger.exception("%s raised; ignoring", method)
 
 
-async def _afire_hooks(hooks, method: str, *args) -> None:
+async def _afire_hooks(hooks: tuple, method: str, *args, debug: bool = False) -> None:
     for hook in hooks:
+        fn = getattr(hook, method, None)
+        if fn is None:
+            continue
         try:
-            await getattr(hook, method)(*args)
+            await fn(*args)
         except Exception:
+            if debug:
+                raise
             logger.exception("%s raised; ignoring", method)
 
 
 class HookTransport(httpx.BaseTransport):
-    """Transport decorator that invokes EventHook instances."""
+    """Transport decorator that invokes EventHook instances.
+
+    Sits between the retry transport (inner) and the user wrapper (outer).
+    Hooks observe the final request/response after retries resolve.
+    ``on_error`` fires when the inner transport raises.
+    """
 
-    def __init__(self, transport: httpx.BaseTransport, hooks: tuple[EventHook, ...]) -> None:
+    def __init__(self, transport: httpx.BaseTransport, hooks: tuple[EventHook, ...], *, debug: bool = False) -> None:
         self._transport = transport
         self._hooks = hooks
+        self._debug = debug
 
     def handle_request(self, request: httpx.Request) -> httpx.Response:
-        _fire_hooks(self._hooks, "on_request", request)
-        response = self._transport.handle_request(request)
-        _fire_hooks(self._hooks, "on_response", request, response)
+        _fire_hooks(self._hooks, "on_request", request, debug=self._debug)
+        try:
+            response = self._transport.handle_request(request)
+        except Exception as exc:
+            _fire_hooks(self._hooks, "on_error", request, exc, debug=self._debug)
+            raise
+        _fire_hooks(self._hooks, "on_response", request, response, debug=self._debug)
         return response
 
     def close(self) -> None:
@@ -102,15 +131,62 @@ def close(self) -> None:
 class AsyncHookTransport(httpx.AsyncBaseTransport):
     """Async counterpart of HookTransport."""
 
-    def __init__(self, transport: httpx.AsyncBaseTransport, hooks: tuple[AsyncEventHook, ...]) -> None:
+    def __init__(
+        self, transport: httpx.AsyncBaseTransport, hooks: tuple[AsyncEventHook, ...], *, debug: bool = False
+    ) -> None:
         self._transport = transport
         self._hooks = hooks
+        self._debug = debug
 
     async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
-        await _afire_hooks(self._hooks, "on_request", request)
-        response = await self._transport.handle_async_request(request)
-        await _afire_hooks(self._hooks, "on_response", request, response)
+        await _afire_hooks(self._hooks, "on_request", request, debug=self._debug)
+        try:
+            response = await self._transport.handle_async_request(request)
+        except Exception as exc:
+            await _afire_hooks(self._hooks, "on_error", request, exc, debug=self._debug)
+            raise
+        await _afire_hooks(self._hooks, "on_response", request, response, debug=self._debug)
         return response
 
     async def aclose(self) -> None:
         await self._transport.aclose()
+
+
+class _ErrorMapperTransport(httpx.BaseTransport):
+    """Translates exceptions via an error_mapper callback for downstream SDKs."""
+
+    def __init__(self, transport: httpx.BaseTransport, mapper: Callable[[Exception], Exception]) -> None:
+        self._transport = transport
+        self._mapper = mapper
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        try:
+            return self._transport.handle_request(request)
+        except Exception as exc:
+            mapped = self._mapper(exc)
+            if mapped is not exc:
+                raise mapped from exc
+            raise
+
+    def close(self) -> None:
+        self._transport.close()
+
+
+class _AsyncErrorMapperTransport(httpx.AsyncBaseTransport):
+    """Async counterpart of _ErrorMapperTransport."""
+
+    def __init__(self, transport: httpx.AsyncBaseTransport, mapper: Callable[[Exception], Exception]) -> None:
+        self._transport = transport
+        self._mapper = mapper
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        try:
+            return await self._transport.handle_async_request(request)
+        except Exception as exc:
+            mapped = self._mapper(exc)
+            if mapped is not exc:
+                raise mapped from exc
+            raise
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()

ionq_core/_pagination.py

@@ -6,6 +6,7 @@
 from collections.abc import AsyncIterator, Iterator
 from typing import TYPE_CHECKING
 
+from ._exceptions import IonQError
 from .api.default import get_jobs, get_session_jobs
 from .types import UNSET, Unset
 
@@ -39,7 +40,7 @@ def iter_jobs(
             next_=next_cursor,
         )
         if response is None:
-            return
+            raise IonQError("Failed to fetch jobs")
         yield from response.jobs
         if response.next_ is None:
             return
@@ -69,7 +70,7 @@ async def aiter_jobs(
             next_=next_cursor,
         )
         if response is None:
-            return
+            raise IonQError("Failed to fetch jobs")
         for job in response.jobs:
             yield job
         if response.next_ is None:
@@ -100,7 +101,7 @@ def iter_session_jobs(
             next_=next_cursor,
         )
         if response is None:
-            return
+            raise IonQError("Failed to fetch jobs")
         yield from response.jobs
         if response.next_ is None:
             return
@@ -130,7 +131,7 @@ async def aiter_session_jobs(
             next_=next_cursor,
         )
         if response is None:
-            return
+            raise IonQError("Failed to fetch jobs")
         for job in response.jobs:
             yield job
         if response.next_ is None:

ionq_core/_session.py

@@ -16,11 +16,6 @@
 
 logger = logging.getLogger("ionq_core")
 
-_SETTINGS_MAP = {
-    "_max_jobs": "job_count_limit",
-    "_max_time": "duration_limit_min",
-}
-
 
 class SessionManager:
     """Convenience wrapper around session create / end / status APIs.
@@ -56,7 +51,11 @@ def session_id(self) -> str | None:
         return self._session_id
 
     def _build_settings(self) -> SessionSettingsRequest | None:
-        kwargs = {api: getattr(self, attr) for attr, api in _SETTINGS_MAP.items() if getattr(self, attr) is not None}
+        kwargs: dict = {}
+        if self._max_jobs is not None:
+            kwargs["job_count_limit"] = self._max_jobs
+        if self._max_time is not None:
+            kwargs["duration_limit_min"] = self._max_time
         if self._max_cost is not None:
             kwargs["cost_limit"] = SessionCostLimit(unit="usd", value=self._max_cost)
         return SessionSettingsRequest(**kwargs) if kwargs else None
@@ -92,9 +91,47 @@ def status(self) -> str:
             raise IonQError(f"Failed to fetch session {self._session_id}")
         return session.status
 
+    async def async_open(self) -> None:
+        """Create a new session on the backend (async)."""
+        if self._session_id is not None:
+            raise IonQError("Session already open")
+        settings = self._build_settings()
+        body = CreateSessionRequest(backend=self._backend, **({"settings": settings} if settings else {}))
+        session = await create_session.asyncio(client=self._client, body=body)
+        if session is None:
+            raise IonQError("Failed to create session")
+        self._session_id = session.id
+        logger.info("Opened session %s", self._session_id)
+
+    async def async_close(self) -> None:
+        """End the session (async). Suppresses exceptions so cleanup is safe."""
+        if self._session_id is None:
+            return
+        try:
+            await end_session.asyncio(session_id=self._session_id, client=self._client)
+            logger.info("Closed session %s", self._session_id)
+        except Exception:
+            logger.warning("Failed to end session %s", self._session_id, exc_info=True)
+
+    async def async_status(self) -> str:
+        """Query current session status (async)."""
+        if self._session_id is None:
+            raise IonQError("No session ID; call open() first")
+        session = await get_session.asyncio(session_id=self._session_id, client=self._client)
+        if session is None:
+            raise IonQError(f"Failed to fetch session {self._session_id}")
+        return session.status
+
     def __enter__(self) -> SessionManager:
         self.open()
         return self
 
     def __exit__(self, *exc: object) -> None:
         self.close()
+
+    async def __aenter__(self) -> SessionManager:
+        await self.async_open()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.async_close()

ionq_core/_transport.py

@@ -26,7 +26,7 @@ def _parse_retry_after(response: httpx.Response) -> float | None:
     if header is None:
         return None
     try:
-        return float(header)
+        return max(0.0, float(header))
     except ValueError:
         parsed = email.utils.parsedate(header)
         if parsed is not None:
@@ -43,7 +43,6 @@ def _backoff_delays(max_retries: int) -> Iterator[float]:
 
 def _parse_error_body(response: httpx.Response) -> dict | str | None:
     try:
-        response.read()
         return response.json()
     except Exception:
         text = response.text
@@ -55,7 +54,8 @@ def _raise_for_response(response: httpx.Response) -> None:
         return
     body = _parse_error_body(response)
     message = body.get("message") or body.get("error") if isinstance(body, dict) else None
-    raise_for_status(response.status_code, body, _parse_retry_after(response), message)
+    request_id = response.headers.get("x-request-id")
+    raise_for_status(response.status_code, body, _parse_retry_after(response), message, request_id=request_id)
 
 
 def _retry_delay(delay: float, last_response: httpx.Response | None) -> float:
@@ -127,7 +127,7 @@ def handle_request(self, request: httpx.Request) -> httpx.Response:
                 response = self._transport.handle_request(request)
             except Exception as exc:
                 if not _is_retryable_exc(request, exc):
-                    raise APIConnectionError(str(exc)) from exc
+                    raise APIConnectionError(f"{type(exc).__name__}: {exc}") from exc
                 last_exc, last_response = exc, None
                 continue
 
@@ -171,7 +171,7 @@ async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
                 response = await self._transport.handle_async_request(request)
             except Exception as exc:
                 if not _is_retryable_exc(request, exc):
-                    raise APIConnectionError(str(exc)) from exc
+                    raise APIConnectionError(f"{type(exc).__name__}: {exc}") from exc
                 last_exc, last_response = exc, None
                 continue
 

ionq_core/client.py

@@ -177,7 +177,7 @@ class AuthenticatedClient:
     _client: httpx.Client | None = field(default=None, init=False)
     _async_client: httpx.AsyncClient | None = field(default=None, init=False)
 
-    token: str
+    token: str = field(repr=False)
     prefix: str = "Bearer"
     auth_header_name: str = "Authorization"