trust_api.services.task_poller

Background polling service: heartbeat → pull pending tasks → dispatch → report.

All communication is outbound from the trust to the hub. The hub identifies the trust by API key alone — there is no {trust_name} segment in any URL.

On the first successful heartbeat the hub returns {trust_id, trust_name, …}; we log the resolved identity (so the operator can see which trust this host came up as) and, when EXPECTED_TRUST_ID is set in the kit file, verify the hub’s answer against it. A mismatch means the wrong kit was deployed to the wrong host — we exit the process so a process-supervisor restart loop surfaces the misconfiguration loudly rather than the host silently acting as the wrong trust.

Attributes

`CENTRAL_HUB_API_URL`
`TRUST_API_KEY`
`TRUST_API_KEY_HEADER`
`EXPECTED_TRUST_ID`
`POLL_INTERVAL_SECONDS`
`_identity_logged`
`_REPORT_MAX_RETRIES`
`_REPORT_RETRY_DELAY_SECONDS`

Functions

`_auth_headers`(→ dict[str, str])	Return authentication headers for hub API calls.
`_maybe_announce_identity`(→ None)	Log resolved identity from the hub once; abort on EXPECTED_TRUST_ID mismatch.
`_poll_for_tasks`(→ list[dict])	Poll the central hub for pending tasks.
`_send_heartbeat`(→ None)	Send a heartbeat to the central hub and run the identity self-check.
`_report_task_result`(→ None)	Report the result of a completed task back to the central hub.
`_process_task`(→ dict)	Process a single task by dispatching to the appropriate handler.
`run_poller`(→ None)	Main polling loop. Runs indefinitely, polling the hub for tasks and processing them.

Module Contents

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.EXPECTED_TRUST_ID = ''

trust_api.services.task_poller.POLL_INTERVAL_SECONDS = 5

trust_api.services.task_poller._identity_logged = False

trust_api.services.task_poller._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.
Return type:: dict[str, str]

trust_api.services.task_poller._maybe_announce_identity(body: dict) → None

Log resolved identity from the hub once; abort on EXPECTED_TRUST_ID mismatch.

Called from every successful trust-facing response. The hub embeds {trust_id, trust_name} in every response body so the trust can identify itself; we only act on the first one (idempotent thanks to _identity_logged).

Parameters:: body (dict) – Parsed JSON response from the hub.
Raises:: SystemExit – If EXPECTED_TRUST_ID is set and disagrees with trust_id.

async trust_api.services.task_poller._poll_for_tasks(client: httpx.AsyncClient) → list[dict]

Poll the central hub for pending tasks.

Parameters:: client (httpx.AsyncClient) – HTTP client for making requests.
Returns:: Pending task dicts from the hub (encrypted payloads).
Return type:: list[dict]

async trust_api.services.task_poller._send_heartbeat(client: httpx.AsyncClient) → None

Send a heartbeat to the central hub and run the identity self-check.

Parameters:: client (httpx.AsyncClient) – HTTP client for making requests.

trust_api.services.task_poller._REPORT_MAX_RETRIES = 3

trust_api.services.task_poller._REPORT_RETRY_DELAY_SECONDS = 2

async trust_api.services.task_poller._report_task_result(client: httpx.AsyncClient, task_id: str, result: dict) → None

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.

Parameters:

client (httpx.AsyncClient) – HTTP client for making requests.
task_id (str) – The ID of the completed task.
result (dict) – Result dict with success and optional result / error fields.

async trust_api.services.task_poller._process_task(task: dict) → dict

Process a single task by dispatching to the appropriate handler.

Parameters:: task (dict) – Task dict with id, task_type, and payload fields.
Returns:: Result dict with success status (and optional result / error).
Return type:: dict

async trust_api.services.task_poller.run_poller() → None

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.