flip_api.private_services.trust_tasks ===================================== .. py:module:: flip_api.private_services.trust_tasks .. autoapi-nested-parse:: Trust ↔ hub private endpoints. **Identity is the API key.** ``Depends(authenticate_trust)`` returns the resolved ``Trust`` row directly; routes use ``trust.id`` for joins and ``trust.name`` for logs without an extra DB lookup. The trust-api never has to know its own name — the hub tells it via the response body, and the trust-api self-checks against an opt-in ``EXPECTED_TRUST_ID`` from its kit file. Attributes ---------- .. autoapisummary:: flip_api.private_services.trust_tasks.router flip_api.private_services.trust_tasks.PENDING_TASKS_LIMIT Functions --------- .. autoapisummary:: flip_api.private_services.trust_tasks._trust_identity flip_api.private_services.trust_tasks._get_pending_tasks flip_api.private_services.trust_tasks._submit_task_result flip_api.private_services.trust_tasks._record_heartbeat flip_api.private_services.trust_tasks.get_pending_tasks flip_api.private_services.trust_tasks.submit_task_result flip_api.private_services.trust_tasks.trust_heartbeat Module Contents --------------- .. py:data:: router .. py:data:: PENDING_TASKS_LIMIT :value: 50 .. py:function:: _trust_identity(trust: flip_api.db.models.main_models.Trust) -> dict[str, str] The identity block embedded in trust-facing response bodies. Lets the trust-api log which trust the hub resolved it as, and verify that resolution against an opt-in ``EXPECTED_TRUST_ID`` from the kit file. .. py:function:: _get_pending_tasks(trust: flip_api.db.models.main_models.Trust, db: sqlmodel.Session) -> dict[str, object] Return up to ``PENDING_TASKS_LIMIT`` pending tasks for ``trust``, marking them in-progress. :param trust: The authenticated trust. :type trust: Trust :param db: Database session. :type db: Session :returns: ``{trust_id, trust_name, tasks: [TrustTaskResponse, ...]}``. :rtype: dict[str, object] :raises HTTPException: 500 on any DB error. .. py:function:: _submit_task_result(trust: flip_api.db.models.main_models.Trust, task_id: uuid.UUID, task_result: flip_api.domain.schemas.private.TaskResultInput, db: sqlmodel.Session) -> dict[str, object] Record the outcome of a task that this trust owns. :param trust: The authenticated trust. :type trust: Trust :param task_id: The task whose result is being submitted. :type task_id: UUID :param task_result: The reported outcome. :type task_result: TaskResultInput :param db: Database session. :type db: Session :returns: ``{trust_id, trust_name, message}``. :rtype: dict[str, object] :raises HTTPException: 404 if the task is missing, 403 if it belongs to a different trust, 409 if it is not currently ``IN_PROGRESS``, 500 on any other error. .. py:function:: _record_heartbeat(trust: flip_api.db.models.main_models.Trust, db: sqlmodel.Session) -> dict[str, object] Stamp the trust row with the current UTC time. :param trust: The authenticated trust. :type trust: Trust :param db: Database session. :type db: Session :returns: ``{trust_id, trust_name, message}``. :rtype: dict[str, object] :raises HTTPException: 500 on any error. .. py:function:: get_pending_tasks(request: fastapi.Request, db: sqlmodel.Session = Depends(get_session), authenticated_trust: flip_api.db.models.main_models.Trust = Depends(authenticate_trust)) -> dict[str, object] Poll for queued tasks for the authenticated trust. :param request: The FastAPI request, used by the rate limiter. :type request: Request :param db: Database session. :type db: Session :param authenticated_trust: The trust resolved from the API key. :type authenticated_trust: Trust :returns: ``{trust_id, trust_name, tasks: [...]}``. ``tasks`` is bounded by ``PENDING_TASKS_LIMIT``; each task's payload is encrypted for transport. :rtype: dict[str, object] .. py:function:: submit_task_result(request: fastapi.Request, task_id: uuid.UUID, task_result: flip_api.domain.schemas.private.TaskResultInput = Body(...), db: sqlmodel.Session = Depends(get_session), authenticated_trust: flip_api.db.models.main_models.Trust = Depends(authenticate_trust)) -> dict[str, object] Submit the result of a previously-dispatched task. :param request: The FastAPI request, used by the rate limiter. :type request: Request :param task_id: The task whose result is being submitted. :type task_id: UUID :param task_result: The reported outcome. :type task_result: TaskResultInput :param db: Database session. :type db: Session :param authenticated_trust: The trust resolved from the API key. :type authenticated_trust: Trust :returns: ``{trust_id, trust_name, message}``. :rtype: dict[str, object] .. py:function:: trust_heartbeat(request: fastapi.Request, db: sqlmodel.Session = Depends(get_session), authenticated_trust: flip_api.db.models.main_models.Trust = Depends(authenticate_trust)) -> dict[str, object] Record a heartbeat for the authenticated trust. :param request: The FastAPI request, used by the rate limiter. :type request: Request :param db: Database session. :type db: Session :param authenticated_trust: The trust resolved from the API key. :type authenticated_trust: Trust :returns: ``{trust_id, trust_name, message}``. :rtype: dict[str, object]