spot-sdk-python 2.0.0b6__py3-none-any.whl → 2.0.0b8__py3-none-any.whl

spot_sdk/__init__.py

@@ -47,7 +47,7 @@ if TYPE_CHECKING:
     from .knowledge import KnowledgeClient, KnowledgeDocument, chunk_text, content_hash
     from .llm import LLMClient, LLMOutputError, LLMToolCall, LLMToolCalls, LLMToolRound
 
-# The modules that import FastAPI, Starlette or httpx load on first use, so importing
+# The modules that import FastAPI, Starlette or httpx2 load on first use, so importing
 # `spot_sdk.mime` or the models stays light (PEP 562).
 _LAZY = {
     **dict.fromkeys(("PluginHealth", "SyncState", "create_plugin_app"), ".app"),

spot_sdk/app.py

@@ -15,6 +15,10 @@ An ``async def`` handler, or an object whose ``__call__`` is ``async def``,
 runs on the event loop; any other callable runs in a worker thread, so it may
 block. Either way the clients send the call's ``X-Correlation-ID`` on to SPOT.
 
+A plugin that loads a model gives ``load``: run in a daemon thread once the app
+starts, it makes the plugin ``starting`` until it returns, and the analyzer
+answers ``unknown`` meanwhile; then ``analyze`` gets what it returned.
+
 Neither the logs nor the error answers hold the request's content: a
 handler's exception is logged by its type and place only, and an invalid
 request is answered with the fields refused, never the values sent.
@@ -29,11 +33,12 @@ from __future__ import annotations
 import asyncio
 import hmac
 import inspect
+import threading
 import traceback
-from collections.abc import Awaitable, Callable, Iterator
-from contextlib import contextmanager
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from contextlib import asynccontextmanager, contextmanager
 from datetime import UTC, datetime
-from typing import Any, Literal, TypeAlias, TypeVar
+from typing import Any, Generic, Literal, TypeAlias, TypeVar, overload
 
 from fastapi import APIRouter, Depends, FastAPI, HTTPException, Request, Response
 from fastapi.responses import JSONResponse
@@ -55,6 +60,7 @@ logger = get_logger(__name__)
 
 SettingsT = TypeVar("SettingsT", bound=PluginSettings)
 ModelT = TypeVar("ModelT", bound=BaseModel)
+LoadedT = TypeVar("LoadedT")
 
 AnalyzeHandler: TypeAlias = Callable[
     [AnalyzeRequest, SettingsT], AnalyzerVerdict | Awaitable[AnalyzerVerdict]
@@ -74,6 +80,12 @@ action idempotent (a ticket keyed by the job id).
 """
 SyncHandler: TypeAlias = Callable[[SettingsT], int | Awaitable[int]]
 """``sync(settings) -> int``: the number of documents written."""
+Loader: TypeAlias = Callable[[SettingsT], LoadedT]
+"""``load(settings) -> object``: a model, say, loaded once in a daemon thread."""
+LoadedAnalyzeHandler: TypeAlias = Callable[
+    [AnalyzeRequest, SettingsT, LoadedT], AnalyzerVerdict | Awaitable[AnalyzerVerdict]
+]
+"""``analyze(request, settings, loaded) -> AnalyzerVerdict``, with what ``load`` returned."""
 
 
 class SyncState(BaseModel):
@@ -117,6 +129,13 @@ class PluginHealth(BaseModel):
     )
 
 
+class HealthAnswer(PluginHealth):
+    """``GET /health``'s body: the plugin's state and the version of its
+    manifest. ``reason`` is left out when there is none."""
+
+    version: str = Field(description="The manifest's version")
+
+
 class ErrorAnswer(BaseModel):
     """An error the app answers itself: 401 without the plugin's own token, 500
     when the handler fails. It never holds the request's content."""
@@ -152,8 +171,10 @@ _SCHEMAS = "#/components/schemas/{model}"
 _HEALTH_CHECK_FAILED = PluginHealth(
     status="unhealthy", reason="the health check failed"
 )
+_LOADING = PluginHealth(status="starting", reason="loading")
 
 
+@overload
 def create_plugin_app(
     manifest: Manifest,
     settings_cls: type[SettingsT],
@@ -163,12 +184,40 @@ def create_plugin_app(
     sync: SyncHandler[SettingsT] | None = None,
     lifespan: Lifespan[FastAPI] | None = None,
     health: HealthCheck | None = None,
+    load: None = None,
+) -> FastAPI: ...
+
+
+@overload
+def create_plugin_app(
+    manifest: Manifest,
+    settings_cls: type[SettingsT],
+    *,
+    load: Loader[SettingsT, LoadedT],
+    analyze: LoadedAnalyzeHandler[SettingsT, LoadedT],
+    respond: RespondHandler[SettingsT] | None = None,
+    sync: SyncHandler[SettingsT] | None = None,
+    lifespan: Lifespan[FastAPI] | None = None,
+    health: HealthCheck | None = None,
+) -> FastAPI: ...
+
+
+def create_plugin_app(
+    manifest: Manifest,
+    settings_cls: type[SettingsT],
+    *,
+    analyze: Callable[..., AnalyzerVerdict | Awaitable[AnalyzerVerdict]] | None = None,
+    respond: RespondHandler[SettingsT] | None = None,
+    sync: SyncHandler[SettingsT] | None = None,
+    lifespan: Lifespan[FastAPI] | None = None,
+    health: HealthCheck | None = None,
+    load: Loader[SettingsT, Any] | None = None,
 ) -> FastAPI:
     """Build the plugin's app; the settings are read once, here.
 
-    Each kind the manifest declares needs its handler (analyzer: ``analyze``,
-    responder: ``respond``, context provider: ``sync``; a mail retriever has
-    none), and each handler its kind, or ``ValueError`` is raised.
+    The manifest's kind needs its handler (analyzer: ``analyze``, responder:
+    ``respond``, context provider: ``sync``; a mail retriever has none), and
+    each handler its kind, or ``ValueError`` is raised.
 
     ``lifespan`` is passed to FastAPI as is: an async context manager run
     around the app's life, to load a model at startup, say.
@@ -181,6 +230,16 @@ def create_plugin_app(
     ``PluginHealth``, makes the plugin ``unhealthy`` for a fixed reason, and
     is logged as the handlers are: never with the exception's message.
 
+    ``load(settings)``, a plain function, loads what the analyzer needs (a
+    model) once the app starts, after ``lifespan``'s startup, in a daemon
+    thread: the app answers meanwhile. Until it returns, the plugin is
+    ``starting`` (``loading``) and ``/internal/analyze`` answers ``unknown``;
+    when it raises, ``unhealthy`` for good, with the exception's type
+    (``the load failed (OSError)``), logged as the handlers' failures are.
+    Then ``analyze(request, settings, loaded)`` gets what it returned, and
+    ``health``, if given, reports the plugin's state. ``load`` needs
+    ``analyze``, and may not be async, or ``ValueError`` is raised.
+
     ``POST /internal/sync`` answers 202 at once and runs ``sync`` in the
     background. While a sync runs, another call starts nothing and answers
     202 with the running sync's state.
@@ -189,7 +248,7 @@ def create_plugin_app(
     components of that document alone, so read it from this app: another
     FastAPI app that includes its routes leaves their ``$ref`` dangling.
     """
-    _check_kinds(manifest, {"analyze": analyze, "respond": respond, "sync": sync})
+    _check_kind(manifest, {"analyze": analyze, "respond": respond, "sync": sync})
     settings = settings_cls()
     if not settings.spot_plugin_token.get_secret_value():
         logger.warning(
@@ -197,6 +256,17 @@ def create_plugin_app(
             "mounts it as /run/secrets/spot_plugin_token; outside a container, set "
             "SPOT_PLUGIN_TOKEN."
         )
+    if load is not None:
+        if analyze is None:
+            raise ValueError(
+                "load is given, but no analyze handler to get what it loads"
+            )
+        if _is_async(load):
+            raise ValueError("load runs in a thread: a plain function, not async")
+        loading = _BackgroundLoad(load, settings)
+        lifespan = loading.lifespan(lifespan)
+        health = loading.health(health)
+        analyze = loading.analyze(analyze)
     app = _PluginApp(
         title=manifest.id,
         version=manifest.version,
@@ -204,13 +274,10 @@ def create_plugin_app(
         lifespan=lifespan,
     )
 
-    @app.get("/health")
-    async def health_route() -> dict[str, str]:
+    @app.get("/health", response_model_exclude_none=True)
+    async def health_route() -> HealthAnswer:
         state = await _health(health)
-        answer = {"status": state.status, "version": manifest.version}
-        if state.reason is not None:
-            answer["reason"] = state.reason
-        return answer
+        return HealthAnswer(**state.model_dump(), version=manifest.version)
 
     @app.get("/manifest")
     async def get_manifest() -> Manifest:
@@ -331,10 +398,10 @@ _HANDLER_KINDS = {
 """The kind each handler serves; a mail retriever has no handler."""
 
 
-def _check_kinds(manifest: Manifest, handlers: dict[str, object]) -> None:
-    """Each kind the manifest declares has its handler, and each handler its kind."""
+def _check_kind(manifest: Manifest, handlers: dict[str, object]) -> None:
+    """The manifest's kind has its handler, and each handler its kind."""
     for name, kind in _HANDLER_KINDS.items():
-        declared = kind in manifest.kinds
+        declared = kind is manifest.kind
         given = handlers[name] is not None
         if declared and not given:
             raise ValueError(
@@ -346,6 +413,75 @@ def _check_kinds(manifest: Manifest, handlers: dict[str, object]) -> None:
             )
 
 
+class _BackgroundLoad(Generic[LoadedT]):
+    """Runs ``load`` in a daemon thread once the app starts, and holds what it
+    returned; the plugin's state is ``starting`` until then."""
+
+    _loaded: LoadedT
+
+    def __init__(self, load: Loader[Any, LoadedT], settings: PluginSettings) -> None:
+        self._load = load
+        self._settings = settings
+        self.state = _LOADING
+
+    def lifespan(self, lifespan: Lifespan[FastAPI] | None) -> Lifespan[FastAPI]:
+        """``lifespan``, with the load started after its startup: once the
+        plugin has set its logging up, say."""
+
+        @asynccontextmanager
+        async def loading(app: FastAPI) -> AsyncIterator[Any]:
+            if lifespan is None:
+                self._start()
+                yield None
+                return
+            async with lifespan(app) as state:
+                self._start()
+                yield state
+
+        return loading
+
+    def health(self, check: HealthCheck | None) -> HealthCheck:
+        """The plugin's state: the load's until it succeeded, then ``check``'s."""
+
+        async def health() -> PluginHealth:
+            if self.state.status != "healthy":
+                return self.state
+            return await _health(check)
+
+        return health
+
+    def analyze(
+        self, handler: LoadedAnalyzeHandler[Any, LoadedT]
+    ) -> AnalyzeHandler[Any]:
+        """``handler``, given what the load returned; ``unknown`` until then."""
+
+        async def analyze(
+            request: AnalyzeRequest, settings: PluginSettings
+        ) -> AnalyzerVerdict:
+            state = self.state
+            if state.status != "healthy":
+                return AnalyzerVerdict.unknown(state.reason or state.status)
+            verdict: AnalyzerVerdict = await _run(
+                handler, request, settings, self._loaded
+            )
+            return verdict
+
+        return analyze
+
+    def _start(self) -> None:
+        threading.Thread(target=self._run, name="load", daemon=True).start()
+
+    def _run(self) -> None:
+        try:
+            self._loaded = self._load(self._settings)
+        except Exception as error:
+            _log_failure("load", error)
+            reason = f"the load failed ({type(error).__name__})"
+            self.state = PluginHealth(status="unhealthy", reason=reason)
+        else:
+            self.state = _HEALTHY
+
+
 class _SyncRunner:
     """Runs the sync handler in the background, one run at a time."""
 
@@ -443,18 +579,20 @@ async def _parse(request: Request, model: type[ModelT]) -> ModelT:
 
 
 async def _run(handler: Callable[..., Any], *args: Any) -> Any:
-    """Await an async handler; run any other in a worker thread, in this context.
-
-    A handler is async when it is an ``async def`` function, or an object whose
-    ``__call__`` is one, as FastAPI tells them apart.
-    """
-    if inspect.iscoroutinefunction(handler) or inspect.iscoroutinefunction(
-        getattr(handler, "__call__", None)
-    ):
+    """Await an async handler; run any other in a worker thread, in this context."""
+    if _is_async(handler):
         return await handler(*args)
     return await run_in_threadpool(handler, *args)
 
 
+def _is_async(handler: Callable[..., Any]) -> bool:
+    """Whether ``handler`` is an ``async def`` function, or an object whose
+    ``__call__`` is one, as FastAPI tells them apart."""
+    return inspect.iscoroutinefunction(handler) or inspect.iscoroutinefunction(
+        getattr(handler, "__call__", None)
+    )
+
+
 @contextmanager
 def _correlated(request: Request) -> Iterator[None]:
     """Make the call's ``X-Correlation-ID`` the one the clients send."""

spot_sdk/artifacts.py

@@ -0,0 +1,205 @@
+"""A model's files, from a local path or an archive downloaded once.
+
+``fetch(url)`` turns what a setting names into a local path: a local path as
+it is, or the directory an http(s) archive (``.tar.gz``, ``.tgz``, ``.tar`` or
+``.zip``) is extracted into. An archive is downloaded once into a cache, one
+directory per URL. It is downloaded and extracted in a temporary directory
+beside the cache, then renamed into place: a stop half-way leaves nothing that
+the next start would take for the model.
+
+A URL's userinfo, query and fragment, where its credentials or a presigned
+URL's signature are, never reach a log line or an error.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import shutil
+import stat
+import tarfile
+import tempfile
+import urllib.error
+import urllib.request
+import zipfile
+from pathlib import Path
+from typing import IO, Literal
+from urllib.parse import urlsplit
+
+from .logging import get_logger
+from .urls import redact
+
+logger = get_logger(__name__)
+
+CACHE = Path.home() / ".cache" / "spot-sdk" / "artifacts"
+"""Where ``fetch`` keeps archives by default, one directory per URL."""
+
+# How an archive is opened, by the end of its URL's path: a tarfile mode, or zip
+_TarMode = Literal["r:gz", "r:"]
+_ArchiveFormat = _TarMode | Literal["zip"]
+_FORMATS: dict[str, _ArchiveFormat] = {
+    ".tar.gz": "r:gz",
+    ".tgz": "r:gz",
+    ".tar": "r:",
+    ".zip": "zip",
+}
+# A URL's scheme (RFC 3986): a local path has none
+_SCHEME = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*:")
+# How long the server may stay silent during the download, in seconds
+_TIMEOUT_S = 60
+# The file types a zip member may have: none given, a file, a directory
+_ZIP_KINDS = (0, stat.S_IFREG, stat.S_IFDIR)
+
+
+class FetchError(Exception):
+    """An archive could not be fetched. The message names the URL without its
+    userinfo, query and fragment, and why: of a failed download, the error's
+    type only, as its text can quote the whole URL."""
+
+
+def fetch(url: str, *, cache: Path = CACHE) -> Path:
+    """A local path for ``url``: itself when it is no URL, else the
+    directory its archive is extracted into, under ``cache``.
+
+    A URL is anything with a scheme, or that starts with ``//``. It must be
+    one ``spot_sdk.urls.redact`` can show safely, be http or https, name a
+    host, hold no credentials (a presigned URL gives access), and its path
+    end with ``.tar.gz``, ``.tgz``, ``.tar`` or ``.zip``. The archive is
+    downloaded once: the next call with the same URL returns the same
+    directory at once, and so does a call that finds another process put it
+    in place meanwhile. Only files and directories are extracted: a member
+    that would land outside the directory, a link or a special file is
+    refused, and nothing is kept. ``FetchError`` says why, and is logged at
+    ERROR, as a plugin logs a failed load by its type only.
+    """
+    if not (_SCHEME.match(url) or url.startswith("//")):
+        return Path(url)
+    try:
+        shown = redact(url)
+    except ValueError as error:
+        # Its text quotes nothing of the URL
+        raise _failure(f"fetch refuses the URL: {error}") from None
+    parts = urlsplit(url)
+    if parts.scheme not in ("http", "https") or not parts.hostname:
+        raise _failure(f"{shown}: not an http or https URL with a host")
+    if "@" in parts.netloc:
+        raise _failure(
+            f"{shown}: a URL's credentials are never sent: give access with a "
+            "presigned URL"
+        )
+    archive_format = _archive_format(parts.path)
+    if archive_format is None:
+        raise _failure(f"{shown}: not a .tar.gz, .tgz, .tar or .zip archive")
+    entry = cache / hashlib.sha256(url.encode()).hexdigest()
+    if entry.is_dir():
+        return entry
+    cache.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix=".", dir=cache) as temporary:
+        archive = Path(temporary) / "archive"
+        extracted = Path(temporary) / "extracted"
+        logger.info("Downloading %s", shown)
+        try:
+            _download(url, archive)
+        except Exception as error:
+            # The type only: the error's text can quote the URL, credentials
+            # included (http.client's InvalidURL does)
+            raise _failure(
+                f"{shown} could not be downloaded ({type(error).__name__})"
+            ) from None
+        try:
+            _extract(archive, extracted, archive_format)
+        except Exception as error:
+            # A local file's error: its text holds nothing of the URL
+            raise _failure(f"{shown} could not be extracted: {error}") from error
+        try:
+            extracted.rename(entry)
+        except OSError as error:
+            # Another process put the same URL's archive in place meanwhile
+            if not entry.is_dir():
+                raise _failure(f"{shown} could not be cached: {error}") from error
+    logger.info("Extracted %s into %s", shown, entry)
+    return entry
+
+
+def _failure(message: str) -> FetchError:
+    """``FetchError(message)``, logged."""
+    logger.error("%s", message)
+    return FetchError(message)
+
+
+def _archive_format(path: str) -> _ArchiveFormat | None:
+    """The archive's format, by the end of the URL's path; ``None`` for
+    another file."""
+    name = path.lower()
+    for suffix, archive_format in _FORMATS.items():
+        if name.endswith(suffix):
+            return archive_format
+    return None
+
+
+def _download(url: str, archive: Path) -> None:
+    try:
+        answer = urllib.request.urlopen(url, timeout=_TIMEOUT_S)
+    except urllib.error.HTTPError as error:
+        error.close()  # it holds the server's answer, and its connection
+        raise
+    with answer, archive.open("wb") as file:
+        shutil.copyfileobj(answer, file)
+
+
+def _extract(archive: Path, target: Path, archive_format: _ArchiveFormat) -> None:
+    """Extract the archive's files and directories into ``target``."""
+    target.mkdir()
+    if archive_format == "zip":
+        _extract_zip(archive, target)
+    else:
+        _extract_tar(archive, target, archive_format)
+
+
+def _extract_zip(archive: Path, target: Path) -> None:
+    with zipfile.ZipFile(archive) as zipped:
+        for info in zipped.infolist():
+            path = _destination(target, info.filename)
+            # The file type, as the member's external attributes give it: none
+            # from a zip made elsewhere than Unix, which holds files only
+            if stat.S_IFMT(info.external_attr >> 16) not in _ZIP_KINDS:
+                raise _not_a_file(info.filename)
+            if info.is_dir():
+                path.mkdir(parents=True, exist_ok=True)
+                continue
+            with zipped.open(info) as data:
+                _write(path, data)
+
+
+def _extract_tar(archive: Path, target: Path, mode: _TarMode) -> None:
+    with tarfile.open(archive, mode) as tarred:
+        for member in tarred:
+            path = _destination(target, member.name)
+            if member.isdir():
+                path.mkdir(parents=True, exist_ok=True)
+                continue
+            data = tarred.extractfile(member) if member.isfile() else None
+            if data is None:
+                raise _not_a_file(member.name)
+            with data:
+                _write(path, data)
+
+
+def _not_a_file(name: str) -> ValueError:
+    return ValueError(f"the member {name!r} is neither a file nor a directory")
+
+
+def _destination(target: Path, name: str) -> Path:
+    """Where the member ``name`` lands in ``target``; refused outside it."""
+    path = (target / name).resolve()
+    if not path.is_relative_to(target.resolve()):
+        raise ValueError(
+            f"the member {name!r} would land outside the archive's directory"
+        )
+    return path
+
+
+def _write(path: Path, data: IO[bytes]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("wb") as file:
+        shutil.copyfileobj(data, file)

spot_sdk/clients.py

@@ -14,6 +14,7 @@ content.
 
 from __future__ import annotations
 
+import asyncio
 import base64
 import json
 from contextvars import ContextVar
@@ -21,7 +22,7 @@ from typing import Any, TypeVar
 from urllib.parse import quote
 from uuid import UUID
 
-import httpx
+import httpx2
 from pydantic import BaseModel, SecretStr, ValidationError
 
 from .email import Envelope
@@ -29,6 +30,11 @@ from .orchestrator import OrchestrationResult
 from .retriever import IngestionPriority, IngestionRequest, IngestionResult
 from .settings import PluginSettings
 
+# The bytes of a raw message encoded at a time: a few milliseconds of a thread
+# holding the GIL, between which the event loop runs. A multiple of 3, so that
+# the pieces' base64 texts join into the message's.
+_INGEST_PIECE = 768 * 1024
+
 ModelT = TypeVar("ModelT", bound=BaseModel)
 
 correlation_id: ContextVar[str | None] = ContextVar("spot_correlation_id", default=None)
@@ -50,7 +56,7 @@ class SpotAPIError(Exception):
 
 
 def read_answer(
-    model: type[ModelT], response: httpx.Response, method: str, path: str
+    model: type[ModelT], response: httpx2.Response, method: str, path: str
 ) -> ModelT:
     """SPOT's answer as ``model``. One that does not validate raises
     ``SpotAPIError`` after the handler, so no validation error, which quotes
@@ -64,8 +70,8 @@ def read_answer(
 
 def json_body(value: Any) -> bytes:
     """``value`` as ASCII JSON, lone surrogates escaped, for a body sent with
-    ``Content-Type: application/json``: the bytes do not depend on the httpx
-    version (0.28 encodes a ``json=`` body as UTF-8 and refuses them)."""
+    ``Content-Type: application/json``: httpx2 encodes a ``json=`` body as UTF-8
+    and refuses lone surrogates, so the SDK encodes the body itself."""
     return json.dumps(value).encode()
 
 
@@ -76,19 +82,23 @@ async def spot_request(
     path: str,
     *,
     json: Any = None,
+    content: bytes | None = None,
     timeout: float,
-    transport: httpx.AsyncBaseTransport | None = None,
-) -> httpx.Response:
-    """Call a SPOT service as a plugin; an error status raises ``SpotAPIError``."""
+    transport: httpx2.AsyncBaseTransport | None = None,
+) -> httpx2.Response:
+    """Call a SPOT service as a plugin; an error status raises ``SpotAPIError``.
+
+    The body is ``json`` encoded by :func:`json_body`, or ``content``, a JSON
+    body the caller has already encoded."""
     headers = {"Authorization": f"Bearer {token.get_secret_value()}"}
     current = correlation_id.get()
     if current is not None:
         headers["X-Correlation-ID"] = current
-    content = None
     if json is not None:
-        headers["Content-Type"] = "application/json"
         content = json_body(json)
-    async with httpx.AsyncClient(timeout=timeout, transport=transport) as client:
+    if content is not None:
+        headers["Content-Type"] = "application/json"
+    async with httpx2.AsyncClient(timeout=timeout, transport=transport) as client:
         response = await client.request(
             method, base_url + path, content=content, headers=headers
         )
@@ -118,6 +128,36 @@ def ingestion_request(
     )
 
 
+def ingestion_body(
+    raw: bytes,
+    *,
+    envelope: Envelope | None = None,
+    workflow_id: str | None = None,
+    priority: IngestionPriority = "normal",
+    wait_for_verdict: bool = False,
+    timeout_ms: int = 30_000,
+) -> bytes:
+    """The JSON bytes of ``ingestion_request(raw, ...)``, built so that a large
+    message holds the GIL for a few milliseconds at a time: the message is
+    encoded in pieces and spliced into the JSON, since the base64 alphabet
+    needs no escaping. The request is validated as ``ingestion_request``
+    does, on the first piece: an empty message is refused."""
+    pieces = [
+        base64.b64encode(raw[start : start + _INGEST_PIECE])
+        for start in range(0, len(raw), _INGEST_PIECE)
+    ]
+    request = IngestionRequest(
+        raw=(pieces[0] if pieces else b"").decode("ascii"),
+        envelope=envelope,
+        workflow_id=workflow_id,
+        priority=priority,
+        wait_for_verdict=wait_for_verdict,
+        timeout_ms=timeout_ms,
+    )
+    others = json_body(request.model_dump(mode="json", exclude={"raw"}))
+    return b"".join([b'{"raw": "', *pieces, b'", ', others[1:]])
+
+
 class SpotClient:
     """The api-gateway's plugin routes, called with the plugin's own token."""
 
@@ -129,12 +169,12 @@ class SpotClient:
         token: SecretStr,
         *,
         timeout: float = DEFAULT_TIMEOUT,
-        transport: httpx.AsyncBaseTransport | None = None,
+        transport: httpx2.AsyncBaseTransport | None = None,
     ) -> None:
         """Build a client of the gateway at ``base_url``.
 
         ``timeout`` bounds each call, in seconds; ``transport`` replaces the
-        network, for tests (``httpx.MockTransport``).
+        network, for tests (``httpx2.MockTransport``).
         """
         self.base_url = base_url.rstrip("/")
         self.token = token
@@ -161,8 +201,14 @@ class SpotClient:
         With ``wait_for_verdict``, the gateway answers once the workflow
         decides, or with status ``timeout`` after ``timeout_ms``; the call
         then waits that long on top of the client's timeout.
+
+        The whole request body, base64 encoding and JSON included, is built in
+        a worker thread, in pieces of a few milliseconds, whatever the
+        message's size: a large message does not hold up the caller's event
+        loop. Only sending the bytes is left to it.
         """
-        request = ingestion_request(
+        content = await asyncio.to_thread(
+            ingestion_body,
             raw,
             envelope=envelope,
             workflow_id=workflow_id,
@@ -174,7 +220,7 @@ class SpotClient:
         response = await self._call(
             "POST",
             "/internal/ingest",
-            json=request.model_dump(mode="json"),
+            content=content,
             timeout=timeout,
         )
         return read_answer(IngestionResult, response, "POST", "/internal/ingest")
@@ -198,14 +244,19 @@ class SpotClient:
         return read_answer(OrchestrationResult, response, "GET", path)
 
     async def _call(
-        self, method: str, path: str, *, json: Any = None, timeout: float | None = None
-    ) -> httpx.Response:
+        self,
+        method: str,
+        path: str,
+        *,
+        content: bytes | None = None,
+        timeout: float | None = None,
+    ) -> httpx2.Response:
         return await spot_request(
             self.base_url,
             self.token,
             method,
             path,
-            json=json,
+            content=content,
             timeout=timeout or self.timeout,
             transport=self._transport,
         )