flip_api.private_services.trust_tasks

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

router

PENDING_TASKS_LIMIT

Functions

_trust_identity(→ dict[str, str])

The identity block embedded in trust-facing response bodies.

_get_pending_tasks(→ dict[str, object])

Return up to PENDING_TASKS_LIMIT pending tasks for trust, marking them in-progress.

_submit_task_result(→ dict[str, object])

Record the outcome of a task that this trust owns.

_record_heartbeat(→ dict[str, object])

Stamp the trust row with the current UTC time.

get_pending_tasks(, authenticated_trust, object])

Poll for queued tasks for the authenticated trust.

submit_task_result(, db, authenticated_trust, object])

Submit the result of a previously-dispatched task.

trust_heartbeat(, authenticated_trust, object])

Record a heartbeat for the authenticated trust.

Module Contents

flip_api.private_services.trust_tasks.router
flip_api.private_services.trust_tasks.PENDING_TASKS_LIMIT = 50
flip_api.private_services.trust_tasks._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.

flip_api.private_services.trust_tasks._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.

Parameters:

  • trust (Trust) – The authenticated trust.

  • db (Session) – Database session.

Returns:

{trust_id, trust_name, tasks: [TrustTaskResponse, ...]}.

Return type:

dict[str, object]

Raises:

HTTPException – 500 on any DB error.

flip_api.private_services.trust_tasks._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.

Parameters:

  • trust (Trust) – The authenticated trust.

  • task_id (UUID) – The task whose result is being submitted.

  • task_result (TaskResultInput) – The reported outcome.

  • db (Session) – Database session.

Returns:

{trust_id, trust_name, message}.

Return type:

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.

flip_api.private_services.trust_tasks._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.

Parameters:

  • trust (Trust) – The authenticated trust.

  • db (Session) – Database session.

Returns:

{trust_id, trust_name, message}.

Return type:

dict[str, object]

Raises:

HTTPException – 500 on any error.

flip_api.private_services.trust_tasks.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.

Parameters:

  • request (Request) – The FastAPI request, used by the rate limiter.

  • db (Session) – Database session.

  • authenticated_trust (Trust) – The trust resolved from the API key.

Returns:

{trust_id, trust_name, tasks: [...]}. tasks is bounded by PENDING_TASKS_LIMIT; each task’s payload is encrypted for transport.

Return type:

dict[str, object]

flip_api.private_services.trust_tasks.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.

Parameters:

  • request (Request) – The FastAPI request, used by the rate limiter.

  • task_id (UUID) – The task whose result is being submitted.

  • task_result (TaskResultInput) – The reported outcome.

  • db (Session) – Database session.

  • authenticated_trust (Trust) – The trust resolved from the API key.

Returns:

{trust_id, trust_name, message}.

Return type:

dict[str, object]

flip_api.private_services.trust_tasks.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.

Parameters:

  • request (Request) – The FastAPI request, used by the rate limiter.

  • db (Session) – Database session.

  • authenticated_trust (Trust) – The trust resolved from the API key.

Returns:

{trust_id, trust_name, message}.

Return type:

dict[str, object]