trust_api.services.task_poller
==============================

.. py:module:: trust_api.services.task_poller

.. autoapi-nested-parse::

   Background polling service that periodically fetches tasks from the central hub
   and dispatches them to local handlers.

   This replaces the previous model where the hub made inbound HTTP requests to the trust.
   Now all communication is outbound from the trust to the hub.



Attributes
----------

.. autoapisummary::

   trust_api.services.task_poller.CENTRAL_HUB_API_URL
   trust_api.services.task_poller.TRUST_API_KEY
   trust_api.services.task_poller.TRUST_API_KEY_HEADER
   trust_api.services.task_poller.TRUST_NAME
   trust_api.services.task_poller.POLL_INTERVAL_SECONDS
   trust_api.services.task_poller._REPORT_MAX_RETRIES
   trust_api.services.task_poller._REPORT_RETRY_DELAY_SECONDS


Functions
---------

.. autoapisummary::

   trust_api.services.task_poller._auth_headers
   trust_api.services.task_poller._poll_for_tasks
   trust_api.services.task_poller._send_heartbeat
   trust_api.services.task_poller._report_task_result
   trust_api.services.task_poller._process_task
   trust_api.services.task_poller.run_poller


Module Contents
---------------

.. py:data:: CENTRAL_HUB_API_URL

.. py:data:: TRUST_API_KEY

.. py:data:: TRUST_API_KEY_HEADER

.. py:data:: TRUST_NAME

.. py:data:: POLL_INTERVAL_SECONDS
   :value: 5


.. py:function:: _auth_headers() -> dict[str, str]

   Return authentication headers for hub API calls.

   :returns: Single-entry mapping of the trust API key header to the configured key.
   :rtype: dict[str, str]


.. py:function:: _poll_for_tasks(client: httpx.AsyncClient) -> list[dict]
   :async:


   Poll the central hub for pending tasks.

   :param client: HTTP client for making requests.

   :returns: List of pending task dicts from the hub.


.. py:function:: _send_heartbeat(client: httpx.AsyncClient) -> None
   :async:


   Send a heartbeat to the central hub to indicate this trust is online.

   :param client: HTTP client for making requests.


.. py:data:: _REPORT_MAX_RETRIES
   :value: 3


.. py:data:: _REPORT_RETRY_DELAY_SECONDS
   :value: 2


.. py:function:: _report_task_result(client: httpx.AsyncClient, task_id: str, result: dict) -> None
   :async:


   Report the result of a completed task back to the central hub.

   Retries up to ``_REPORT_MAX_RETRIES`` times with exponential backoff on failure,
   since a lost result can leave a task permanently stuck in IN_PROGRESS on the hub.

   :param client: HTTP client for making requests.
   :param task_id: The ID of the completed task.
   :param result: The result dict containing success status and optional result data.


.. py:function:: _process_task(task: dict) -> dict
   :async:


   Process a single task by dispatching to the appropriate handler.

   :param task: Task dict with id, task_type, and payload fields.

   :returns: Result dict with success status.


.. py:function:: run_poller() -> None
   :async:


   Main polling loop. Runs indefinitely, polling the hub for tasks and processing them.

   This function is started as a background task during the FastAPI lifespan.