corvix.web.health
=================

.. py:module:: corvix.web.health

.. autoapi-nested-parse::

   Health endpoints and their supporting helpers.

   Serves ``GET /api/v1/health`` (the versioned health check) and ``GET
   /api/health`` (an unversioned, always-public alias kept so container health
   checks — docker-compose, e2e, Lighthouse — need not track the API version).



Attributes
----------

.. autoapisummary::

   corvix.web.health.logger


Functions
---------

.. autoapisummary::

   corvix.web.health._health_error
   corvix.web.health._health_check_staleness
   corvix.web.health._read_health_poller_status
   corvix.web.health._health_impl
   corvix.web.health.health
   corvix.web.health.health_container


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

.. py:data:: logger

.. py:function:: _health_error(poller_status: corvix.domain.PollerStatus) -> dict[str, object]

.. py:function:: _health_check_staleness(last_poll_str: str) -> dict[str, object]

.. py:function:: _read_health_poller_status() -> corvix.domain.PollerStatus | dict[str, object]

   Resolve the poller status for the health check, or a failure payload.


.. py:function:: _health_impl() -> litestar.Response[dict[str, object]]

   Compute and return the health check response.

   Both health endpoints are always public (issue #131), even when
   ``CORVIX_SECRET_TOKEN`` is set, so the response body is trimmed to a bare
   ``{"status": ...}`` — no ``reason``, ``detail``, or other internals that
   could leak service state to an unauthenticated caller. The full detail
   (``poller_status.last_error``, per-account errors, ...) remains available
   to authenticated clients via ``/api/v1/snapshot``.


.. py:function:: health() -> litestar.Response[dict[str, object]]

   Health endpoint for container checks.

   Returns 200 with {"status": "ok"} when config and storage are readable,
   the poller is running, and the poller's last poll time is not stale.
   Returns 503 with {"status": "unhealthy"} otherwise.

   This endpoint is always public, so the response carries no further
   detail; see the authenticated ``/api/v1/snapshot`` endpoint for
   poller error detail.


.. py:function:: health_container() -> litestar.Response[dict[str, object]]

   Unversioned health alias for container healthchecks; see ``/api/v1/health``.