99 lines
4.3 KiB
Python
99 lines
4.3 KiB
Python
"""Configuration for the NestQuest API service.
|
|
|
|
The API reads its configuration knobs from environment variables:
|
|
|
|
- ``NESTQUEST_DB_PATH`` — the SQLite database file. The API opens this
|
|
file on startup (creating it if absent) and applies migrations.
|
|
- ``NESTQUEST_PANEL_TOKEN`` — the static panel-plane service token
|
|
(D-012): the credential ``/api/v1/panel/*`` routes require via
|
|
:func:`api.dependencies.require_panel_token`. It is stored outside
|
|
the repo and handed to the service through the environment.
|
|
|
|
Unlike a dev convenience default, a missing or empty value is a
|
|
configuration ERROR, not a silent fallback: a default database path
|
|
would silently drop data at reboot, and a default (or empty) service
|
|
token would either authenticate everyone or lock the panel plane out
|
|
for good. ``ApiConfig.from_env`` therefore RAISES when either variable
|
|
is unset or empty. This mirrors the integration's "explicit settings
|
|
object" discipline (Feature 15's ``core.settings``): the API never
|
|
reads HA config; callers pass the resolved values into the wiring.
|
|
|
|
Serving: the app is built with the factory ``api.app:create_app`` — run
|
|
it with ``uvicorn --factory api.app:create_app`` so the factory reads
|
|
the environment on each worker startup rather than at import time.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import os
|
|
from dataclasses import dataclass
|
|
|
|
#: Environment variable holding the SQLite file path. The API opens
|
|
#: this file on startup (creating it if absent) and applies migrations.
|
|
#: REQUIRED — unset or empty raises :class:`ConfigError` from
|
|
#: :meth:`ApiConfig.from_env`.
|
|
DB_PATH_ENV = "NESTQUEST_DB_PATH"
|
|
|
|
#: Environment variable holding the static panel-plane service token
|
|
#: (D-012), checked by :func:`api.dependencies.require_panel_token`.
|
|
#: REQUIRED — unset or empty raises :class:`ConfigError` from
|
|
#: :meth:`ApiConfig.from_env`; there is no silent default, because an
|
|
#: empty configured token would either authenticate every caller or
|
|
#: lock the panel plane out permanently.
|
|
PANEL_TOKEN_ENV = "NESTQUEST_PANEL_TOKEN"
|
|
|
|
|
|
class ConfigError(RuntimeError):
|
|
"""Raised when required API configuration is missing or invalid."""
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ApiConfig:
|
|
"""Resolved API configuration.
|
|
|
|
Both fields are required (no defaults): ``from_env`` rejects an
|
|
unset or empty value for either, and a caller building the dataclass
|
|
directly must pass an explicit token — the token check itself fails
|
|
closed on an empty configured token, but expecting a caller to
|
|
discover that at request time is a wiring mistake, so the field is
|
|
mandatory. Kept as a dataclass so later tasks (admin plane, SSE,
|
|
settings persistence) can extend it without touching the call sites
|
|
that read ``db_path``.
|
|
"""
|
|
|
|
db_path: str
|
|
panel_token: str
|
|
|
|
@classmethod
|
|
def from_env(cls, env: dict[str, str] | None = None) -> "ApiConfig":
|
|
"""Build configuration from the process environment.
|
|
|
|
``env`` defaults to ``os.environ``; tests pass an explicit dict
|
|
so they are hermetic (no monkeypatch of the global environ).
|
|
|
|
Raises :class:`ConfigError` when ``NESTQUEST_DB_PATH`` is unset
|
|
or empty/whitespace-only — there is no silent default, because a
|
|
default in the temp directory would silently lose data at reboot
|
|
— and likewise when ``NESTQUEST_PANEL_TOKEN`` is unset or empty
|
|
(a default token is never invented: the panel plane is closed
|
|
until a real one is configured).
|
|
"""
|
|
source = env if env is not None else os.environ
|
|
raw_db_path = source.get(DB_PATH_ENV, "").strip()
|
|
if not raw_db_path:
|
|
raise ConfigError(
|
|
f"{DB_PATH_ENV} must be set to a writable SQLite file path "
|
|
f"(it is unset or empty — the API will not fall back to a "
|
|
f"temp directory and silently lose data)"
|
|
)
|
|
raw_panel_token = source.get(PANEL_TOKEN_ENV, "").strip()
|
|
if not raw_panel_token:
|
|
raise ConfigError(
|
|
f"{PANEL_TOKEN_ENV} must be set to the panel service token "
|
|
f"(it is unset or empty — the API will not start without "
|
|
f"one, and no default token is invented)"
|
|
)
|
|
return cls(db_path=raw_db_path, panel_token=raw_panel_token)
|
|
|
|
|
|
__all__ = ["ApiConfig", "ConfigError", "DB_PATH_ENV", "PANEL_TOKEN_ENV"]
|