ailogger-client-dev 0.1.51__py3-none-any.whl

ailogger_client/queued_methods.py

@@ -0,0 +1,247 @@
+"""
+Queued commands: submit a job, observe it, and return its finished result.
+
+Some commands of the service are ALWAYS queued: a call is answered with a job
+identity, never with the result, and the result is read through the queue's
+job status. This module is the one place the client knows how to do that. It
+carries two kinds of members:
+
+- the PRIVATE machinery every typed queued method is built on - submitting a
+  command and taking the job identity out of the answer, and waiting for a job
+  to finish and taking its result out of the job-status answer. The caller of
+  a typed method never sees a job identity, a poll or an envelope unless it
+  asks for the job identity;
+- the public typed ``messages_import_submit``, the no-wait form of the
+  ``messages_import`` command, which submits the job and returns its identity.
+  (The waiting form, ``messages_import``, is declared with the other message
+  methods.)
+
+POLLING AND ENVELOPES BELONG HERE. Everything about reading a job - the poll
+interval, the deadline, which answers are terminal, where in the job-status
+answer the command's result lives, how a failed job or a refusing result
+becomes a typed error of this client - is this module's, so a consumer of the
+client (the pipeline included) holds none of it.
+
+NETWORK LAW. This module imports nothing from the adapter framework and adds
+no transport of its own; it reaches the service only through the invocation
+seam and the job-observation surface of ``ailogger_client.invocation``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Mapping
+from typing import Any, Final
+
+from .errors import (
+    CompletionFailedError,
+    CompletionTimeoutError,
+    QueuedProtocolError,
+    ResultUnavailableError,
+    refusal_from_answer,
+)
+
+__all__ = ["QueuedMixin", "find_job_id"]
+
+#: How often a waiting caller asks the queue for the job's status, in seconds.
+_POLL_SECONDS: Final[float] = 1.0
+
+#: The longest a waiting caller waits for one job to finish, in seconds.
+_WAIT_SECONDS: Final[float] = 900.0
+
+#: Job-status values that end a job without a usable result.
+_FAILED_STATUSES: Final[frozenset[str]] = frozenset(
+    {"failed", "error", "timeout", "stopped", "cancelled"}
+)
+
+#: The key the framework's job-status tracking keeps the last queue answer under.
+_LAST_QUEUE_POLL: Final[str] = "last_queue_poll"
+
+
+#: The wrappers a job identity may sit inside in a submit answer.
+_ANSWER_WRAPPERS: Final[tuple[str, ...]] = ("data", "result")
+
+
+def find_job_id(answer: object) -> str | None:
+    """
+    The job identity a submit answer carries, if it carries one.
+
+    An always-queued command is answered with a job identity at the top of the
+    answer or inside the answer's ``data`` / ``result`` wrapper; a direct
+    command's answer carries none. Nothing deeper is looked at, so a field
+    that merely happens to be called ``job_id`` inside some result is never
+    taken for one.
+    """
+    if not isinstance(answer, Mapping):
+        return None
+    found = answer.get("job_id")
+    if isinstance(found, str) and found.strip():
+        return found.strip()
+    for wrapper in _ANSWER_WRAPPERS:
+        nested = answer.get(wrapper)
+        if isinstance(nested, Mapping):
+            found = nested.get("job_id")
+            if isinstance(found, str) and found.strip():
+                return found.strip()
+    return None
+
+
+def _find_result_array(node: object) -> list[Any] | None:
+    """
+    The array a finished job answered with: the ``data`` of the first success
+    envelope whose data is an array, searched through the job-status answer.
+    """
+    if isinstance(node, Mapping):
+        data = node.get("data")
+        if node.get("success") is True and isinstance(data, list):
+            return data
+        for value in node.values():
+            nested = _find_result_array(value)
+            if nested is not None:
+                return nested
+    elif isinstance(node, list):
+        for value in node:
+            nested = _find_result_array(value)
+            if nested is not None:
+                return nested
+    return None
+
+
+def _find_refusal(node: object, command: str) -> Exception | None:
+    """A refusing result envelope inside the job-status answer, if there is one."""
+    if isinstance(node, Mapping):
+        if node.get("success") is False:
+            refusal = refusal_from_answer(dict(node), command)
+            if refusal is not None:
+                return refusal
+        for value in node.values():
+            nested = _find_refusal(value, command)
+            if nested is not None:
+                return nested
+    elif isinstance(node, list):
+        for value in node:
+            nested = _find_refusal(value, command)
+            if nested is not None:
+                return nested
+    return None
+
+
+class QueuedMixin:
+    """
+    Mixin providing the machinery of always-queued commands and the no-wait
+    typed method of ``messages_import``.
+
+    This mixin expects to be composed with InvocationMixin, which provides
+    ``_invoke`` and the job-observation surface (``get_job_status``).
+    """
+
+    async def _invoke(
+        self,
+        command: str,
+        params: dict[str, Any] | None = None,
+        *,
+        wait_for_result: bool = True,
+    ) -> Any:
+        """Private invocation entry point, provided by InvocationMixin."""
+        raise NotImplementedError  # Provided by InvocationMixin
+
+    async def get_job_status(
+        self,
+        job_id: str,
+        *,
+        sync_from_queue: bool = False,
+    ) -> Any:
+        """Job observation, provided by InvocationMixin."""
+        raise NotImplementedError  # Provided by InvocationMixin
+
+    async def _submit_queued(self, command: str, params: dict[str, Any]) -> str:
+        """
+        Submit an always-queued command and return its job identity.
+
+        Raises:
+            QueuedProtocolError: When the service answered without a job
+                identity - an always-queued command must never be answered
+                inline.
+            ServiceRefusalError: When the whole call is refused (nothing is
+                written and no job exists).
+        """
+        answer = await self._invoke(command, params, wait_for_result=False)
+        job_id = find_job_id(answer)
+        if job_id is None:
+            raise QueuedProtocolError(
+                f"{command} was not queued: the service answered without a "
+                "job identity"
+            )
+        return job_id
+
+    async def _await_queued_result(
+        self,
+        job_id: str,
+        *,
+        command: str,
+        timeout: float | None = None,
+    ) -> list[Any]:
+        """
+        Wait for a queued job to finish and return the array it answered with.
+
+        Raises:
+            CompletionTimeoutError: When the job does not finish in time.
+            CompletionFailedError: When the job ends failed.
+            ServiceRefusalError: When the job's own result is a refusal.
+            ResultUnavailableError: When the job ended without a result array.
+        """
+        limit = _WAIT_SECONDS if timeout is None else timeout
+        deadline = time.monotonic() + limit
+        while True:
+            snapshot = await self.get_job_status(job_id, sync_from_queue=True)
+            if snapshot.is_terminal:
+                break
+            if time.monotonic() >= deadline:
+                raise CompletionTimeoutError(
+                    f"{command} job {job_id} did not finish within {limit} seconds"
+                )
+            await asyncio.sleep(_POLL_SECONDS)
+        summary = snapshot.summary
+        raw: object = summary.get(_LAST_QUEUE_POLL, summary)
+        status = str(snapshot.execution_status or "").lower()
+        refusal = _find_refusal(raw, command)
+        if refusal is not None:
+            raise refusal
+        if status in _FAILED_STATUSES:
+            raise CompletionFailedError(
+                f"{command} job {job_id} ended {status!r}: {raw!r}"
+            )
+        result = _find_result_array(raw)
+        if result is None:
+            raise ResultUnavailableError(
+                f"{command} job {job_id} ended {status!r} without a result array"
+            )
+        return result
+
+    async def messages_import_submit(self, messages: list[dict[str, Any]]) -> str:
+        """Submit a batch import without waiting and return its job identity.
+
+        ``messages_import`` is ALWAYS queued: the service answers with a job
+        identity and runs the import in a worker. This is the no-wait form:
+        it returns that identity as a plain string. The job's result - one
+        ``{message_id, success}`` entry per item - is what the waiting form,
+        ``messages_import``, returns; a caller of this method can read it
+        through ``get_job_status``.
+
+        Args:
+            messages: The items to import - exactly the ``append_message``
+                parameter set per item, with ``message_id`` and
+                ``occurred_at`` required. Passed through unchanged; the
+                service validates them.
+
+        Returns:
+            The job identity.
+
+        Raises:
+            ServiceRefusalError: When the whole call is refused (nothing is
+                written and no job is created).
+            QueuedProtocolError: When the service answered inline instead of
+                queueing.
+        """
+        return await self._submit_queued("messages_import", {"messages": messages})