corvix.web.runtime_config
=========================

.. py:module:: corvix.web.runtime_config

.. autoapi-nested-parse::

   Runtime ``AppConfig`` cache and dashboard selection helpers.

   AppConfig is expensive to produce (YAML read + full parse).  We cache the
   result at module level and invalidate it only when the config file's mtime
   changes.  A plain stat() per request is orders of magnitude cheaper than a
   full YAML re-parse, so we still detect on-disk edits without re-reading
   unconditionally on every HTTP request.

   The three cache fields live in a single mutable object so they can be
   updated without ``global`` statements (which ruff PLW0603 flags).



Attributes
----------

.. autoapisummary::

   corvix.web.runtime_config.logger
   corvix.web.runtime_config._config_cache


Classes
-------

.. autoapisummary::

   corvix.web.runtime_config._ConfigCache


Functions
---------

.. autoapisummary::

   corvix.web.runtime_config._clear_config_cache
   corvix.web.runtime_config._load_runtime_config
   corvix.web.runtime_config._install_sighup_handler
   corvix.web.runtime_config._select_dashboard
   corvix.web.runtime_config._dashboard_names


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

.. py:data:: logger

.. py:class:: _ConfigCache

   Mutable container for the module-level AppConfig cache.


   .. py:attribute:: config
      :type:  corvix.config.AppConfig | None
      :value: None



   .. py:attribute:: path
      :type:  str | None
      :value: None



   .. py:attribute:: mtime
      :type:  float | None
      :value: None



.. py:data:: _config_cache

.. py:function:: _clear_config_cache() -> None

   Discard the cached AppConfig so the next request reloads from disk.


.. py:function:: _load_runtime_config() -> corvix.config.AppConfig

   Return the cached AppConfig, re-parsing from disk only when the file changes.

   Config is read from the path in the ``CORVIX_CONFIG`` environment variable
   (default: ``corvix.yaml``).  The file's mtime is checked on every call; the
   YAML is only re-parsed when either the path or the mtime differs from the
   last successful load, eliminating redundant I/O on every request.


.. py:function:: _install_sighup_handler() -> None

   Register a SIGHUP handler that clears the config cache.

   Sending ``SIGHUP`` to the server process forces the config to be reloaded
   from disk on the next request without restarting the process::

       kill -HUP <pid>

   The handler is a no-op on platforms that do not support SIGHUP (e.g. Windows).


.. py:function:: _select_dashboard(dashboards: list[corvix.config.DashboardSpec], selected_name: str | None) -> corvix.config.DashboardSpec

.. py:function:: _dashboard_names(dashboards: list[corvix.config.DashboardSpec]) -> list[str]