epd-server 0.9.0__py3-none-any.whl

epd_server/cache.py

@@ -0,0 +1,96 @@
+"""Shared JSON-backed disk cache with per-entry TTL."""
+from __future__ import annotations
+
+import json
+import logging
+import time
+from datetime import datetime
+from pathlib import Path
+
+DEFAULT_TTL = 3300.0  # 55 minutes
+
+log = logging.getLogger(__name__)
+
+
+def _json_default(obj):
+    if isinstance(obj, datetime):
+        return {"__dt__": obj.isoformat()}
+    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
+
+
+def _json_hook(d: dict):
+    if "__dt__" in d:
+        return datetime.fromisoformat(d["__dt__"])
+    return d
+
+
+class DiskCache:
+    """A simple JSON file-backed key/value cache with per-entry TTL.
+
+    Usage::
+
+        cache = DiskCache(Path(__file__).parent / ".cache.json", "MyService")
+
+        # TTL-based (default 55 min)
+        data = cache.get("forecast")          # None on miss/expiry
+        cache.set("forecast", payload)
+
+        # Indefinite (e.g. geocoding results)
+        coords = cache.get("coords", ttl=None)
+        cache.set("coords", {"lat": ..., "lon": ...})
+
+        # Invalidate computed results without clearing coords
+        cache.delete("forecast", "daily_summary", "hourly_forecast")
+
+    ``datetime`` values round-trip transparently.
+    """
+
+    def __init__(self, path: str | Path, service_name: str = ""):
+        self._path = Path(path)
+        self._service_name = service_name or str(self._path)
+
+    # ── Low-level I/O ─────────────────────────────────────────────────────
+
+    def load(self) -> dict:
+        try:
+            with open(self._path) as f:
+                return json.load(f, object_hook=_json_hook)
+        except (FileNotFoundError, json.JSONDecodeError):
+            return {}
+
+    def save(self, data: dict) -> None:
+        try:
+            with open(self._path, "w") as f:
+                json.dump(data, f, default=_json_default)
+        except OSError as exc:
+            log.warning("Could not write %s cache: %s", self._service_name, exc)
+
+    # ── Public API ────────────────────────────────────────────────────────
+
+    def get(self, key: str, ttl: float | None = DEFAULT_TTL):
+        """Return cached data for *key*, or ``None`` if absent or expired.
+
+        Pass ``ttl=None`` to disable expiry (cache indefinitely).
+        """
+        entry = self.load().get(key)
+        if entry is None:
+            return None
+        if ttl is not None and time.time() - entry.get("__ts__", 0) >= ttl:
+            return None
+        log.debug("%s cache hit: %s", self._service_name, key)
+        return entry["__data__"]
+
+    def set(self, key: str, data) -> None:
+        """Store *data* under *key*, recording the current timestamp."""
+        cache = self.load()
+        cache[key] = {"__ts__": time.time(), "__data__": data}
+        self.save(cache)
+
+    def delete(self, *keys: str) -> None:
+        """Remove *keys* from the cache (silently ignores missing keys)."""
+        cache = self.load()
+        if not any(k in cache for k in keys):
+            return
+        for key in keys:
+            cache.pop(key, None)
+        self.save(cache)

epd_server/compat.py

@@ -0,0 +1,51 @@
+"""Whether a board and a server can work together, judged by their versions.
+
+They match when their major numbers match, or, while the major is 0, their
+major and minor. That is semantic versioning's own rule: before 1.0.0 a minor
+release may break the contract, and after it only a major one may.
+
+The firmware applies the same rule in ``version_compat.h``, so both ends
+reach the same answer about each other.
+"""
+from __future__ import annotations
+
+import re
+
+# "v1.2.3", then anything git describe or semver adds: "-44-g2fe55a4-dirty".
+_VERSION = re.compile(r"[vV]?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?")
+# What git describe adds to a build past a tag: how many commits past it.
+_DESCRIBE = re.compile(r"-(\d+)-g[0-9a-fA-F]+(?:-dirty)?")
+
+
+def compatibility_key(version: str | None) -> tuple[int, ...] | None:
+    """The part of a version that decides compatibility, or None when it is
+    not a version that can be read, such as ``dev``."""
+    if not version:
+        return None
+    m = _VERSION.fullmatch(version.strip())
+    if m is None:
+        return None
+    major, minor = int(m[1]), int(m[2])
+    return (0, minor) if major == 0 else (major,)
+
+
+def version_order(version: str | None) -> tuple[int, int, int, int] | None:
+    """``(major, minor, patch, commits past the tag)`` for sorting versions,
+    or None when it is not a version that can be read. A build past a tag
+    sorts after the tag, and after a build fewer commits past it."""
+    if not version:
+        return None
+    version = version.strip()
+    m = _VERSION.fullmatch(version)
+    if m is None:
+        return None
+    past = _DESCRIBE.fullmatch(version[m.end(3):])
+    return int(m[1]), int(m[2]), int(m[3]), int(past[1]) if past else 0
+
+
+def compatible(a: str | None, b: str | None) -> bool | None:
+    """True or False when both can be judged; None when either cannot."""
+    ka, kb = compatibility_key(a), compatibility_key(b)
+    if ka is None or kb is None:
+        return None
+    return ka == kb

epd_server/config.py

@@ -0,0 +1,425 @@
+"""Resolve config values with environment-variable override.
+
+Precedence for every lookup: **env var > YAML value > default**.
+
+The env-var name is derived from the key path, upper-cased and joined with
+underscores: ``("server", "timezone")`` -> ``SERVER_TIMEZONE``. Env strings are
+coerced to the type of the YAML value they replace (or of the default when
+the YAML key is absent), so ``MQTT_ENABLED=true`` yields ``True`` and
+``SERVER_PORT=9090`` yields ``9090``.
+"""
+from __future__ import annotations
+
+import operator
+import os
+import re
+from functools import reduce
+from typing import Any, Callable
+
+
+def get_by_path(root, items):
+    """Access a nested object in ``root`` by a sequence of keys."""
+    return reduce(operator.getitem, items, root)
+
+
+def _env_name(keys) -> str:
+    """``("server", "timezone")`` -> ``"SERVER_TIMEZONE"``."""
+    return "_".join(str(k).upper() for k in keys)
+
+
+def _coerce_env(raw: str, reference):
+    """Coerce a string env-var value to match the type of ``reference``.
+
+    ``bool`` is checked before ``int`` because ``bool`` subclasses ``int``.
+    """
+    if isinstance(reference, bool):
+        return raw.strip().lower() in ("1", "true", "yes", "on")
+    if isinstance(reference, int):
+        return int(raw)
+    if isinstance(reference, float):
+        return float(raw)
+    if isinstance(reference, list):
+        return [s.strip() for s in raw.split(",") if s.strip()]
+    return raw
+
+
+def _resolve(keys, yaml_lookup: Callable[[], Any], default, required: bool) -> Any:
+    """Resolve one value: env var, then ``yaml_lookup()``, then ``default``.
+
+    Raises ``KeyError`` when the value is required and none of the three
+    sources provide it.
+    """
+    raw_env = os.environ.get(_env_name(keys))
+    try:
+        yaml_val = yaml_lookup()
+        yaml_present = True
+    except (KeyError, TypeError):
+        yaml_val = None
+        yaml_present = False
+
+    if raw_env is not None:
+        reference = yaml_val if yaml_present else default
+        return _coerce_env(raw_env, reference) if reference is not None else raw_env
+
+    if yaml_present:
+        return yaml_val
+
+    if default is None and required:
+        raise KeyError("{} not in config but is required".format(".".join(keys)))
+    return default
+
+
+def get_prop_by_keys(config, *keys, default=None, required=True) -> Any:
+    """Resolve a nested config value, e.g. ``get_prop_by_keys(cfg, "server", "port")``."""
+    return _resolve(keys, lambda: get_by_path(config, keys), default, required)
+
+
+def get_prop(config, prop, default=None, required=True) -> Any:
+    """Resolve a top-level config value, e.g. ``get_prop(cfg, "location")``."""
+    return _resolve((prop,), lambda: config[prop], default, required)
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Typed settings for the blocks every epd server has
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# A project validates its own keys (an API key, a broker topic, a location)
+# and calls load_core_config() for the rest. Every check raises ConfigError
+# with a message meant for the person editing config.yaml; the caller
+# decides whether that means "log and exit".
+
+from dataclasses import dataclass
+from datetime import datetime as _datetime
+from datetime import tzinfo as _tzinfo
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+import yaml
+
+from .scheduling import Pools, TimeRangesSchedule, TimesSchedule, WakeSchedule
+from .timeranges import Week
+
+
+class ConfigError(ValueError):
+    """A config value is missing or invalid. The message is user-facing."""
+
+
+def load_yaml(path) -> dict:
+    """Read a YAML file into a dict. An empty file is an empty dict."""
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path}: top level must be a mapping")
+    return data
+
+
+@dataclass(frozen=True)
+class ServerSettings:
+    port: int
+    timezone: _tzinfo
+    schedule: WakeSchedule          # from the display block: pools, and when they show
+    regen_lead_seconds: int         # regenerate this long before each wake
+    debug: bool
+
+
+@dataclass(frozen=True)
+class ImageSettings:
+    width: int
+    height: int
+    inner_width: int
+    inner_height: int
+    inner_align_x: str              # left | center | right
+    inner_align_y: str              # top | center | bottom
+
+    def page_kwargs(self) -> dict:
+        """Keyword arguments for :class:`epd_server.page.Page`."""
+        return dict(
+            width=self.width,
+            height=self.height,
+            inner_width=self.inner_width,
+            inner_height=self.inner_height,
+            inner_align_x=self.inner_align_x,
+            inner_align_y=self.inner_align_y,
+        )
+
+
+@dataclass(frozen=True)
+class MqttSettings:
+    enabled: bool
+    host: str
+    port: int
+    prefix: str   # each board logs to <prefix>/<board>
+
+
+@dataclass(frozen=True)
+class FirmwareSource:
+    """Where new images come from, when the server fetches them itself."""
+
+    github: str                     # owner/repo
+    asset: str                      # the release asset to take
+    poll_seconds: int
+    token: str                      # for a private repository
+
+
+@dataclass(frozen=True)
+class FirmwareSettings:
+    enabled: bool
+    dir: str                        # a directory of <version>.bin, or of one per product
+    product: str                    # the client name an image is for
+    offer_dev_builds: bool          # offer to boards not built from a tag
+    source: FirmwareSource | None = None
+    products: tuple[str, ...] = ()  # several products, each in dir/<product>/
+
+    def names(self) -> tuple[str, ...]:
+        """Every product this server holds images for."""
+        return self.products or ((self.product,) if self.product else ())
+
+    def dir_for(self, product: str) -> str:
+        """Where one product's images are: its own subdirectory when the
+        server holds several, the directory itself when it holds one."""
+        return os.path.join(self.dir, product) if self.products else self.dir
+
+
+@dataclass(frozen=True)
+class CoreConfig:
+    server: ServerSettings
+    image: ImageSettings
+    mqtt: MqttSettings
+    firmware: FirmwareSettings     # from the client block: client.firmware
+
+
+def _positive_int(key: str, value) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ConfigError(f"{key} must be a positive integer (got {value!r})")
+    return value
+
+
+_SCHEDULE_COMMON = {"type", "reshuffle_hours", "seed"}
+
+
+def parse_display(config: dict, tz: _tzinfo, default_display: dict | None = None) -> WakeSchedule:
+    """The ``display`` block: ``pools`` of images, and a ``schedule`` of one type.
+
+    ``times`` names a pool at each HH:MM:SS; ``timeranges`` visits the pools
+    in ``order`` at each slot of its ``week``, groups of days each with a day
+    of time ranges, each range with an interval. Either may set ``reshuffle_hours`` and ``seed`` for the
+    pools' random starts.
+    """
+    raw = get_prop_by_keys(config, "display", default=default_display, required=False)
+    if raw is None:
+        raise ConfigError("display is required: pools of images and a schedule with a type")
+    if not isinstance(raw, dict):
+        raise ConfigError("display needs pools and schedule.")
+    unknown = sorted(set(raw) - {"pools", "schedule"})
+    if unknown:
+        raise ConfigError(f"display takes pools and schedule (got {unknown})")
+
+    pools_raw = raw.get("pools")
+    if not isinstance(pools_raw, dict) or not pools_raw:
+        raise ConfigError("display.pools must be a non-empty mapping of pool name to image list")
+    pools_clean: dict[str, list[str]] = {}
+    for name, pages in pools_raw.items():
+        if isinstance(pages, str):
+            pages = [pages]
+        if (not isinstance(pages, list) or not pages
+                or not all(isinstance(p, str) and p.strip() for p in pages)):
+            raise ConfigError(f"display.pools.{name} must be a non-empty list of image filenames")
+        pools_clean[str(name)] = [p.strip() for p in pages]
+
+    sched = raw.get("schedule")
+    if not isinstance(sched, dict) or not sched:
+        raise ConfigError("display.schedule must be a mapping with a type of times or timeranges")
+    kind = sched.get("type")
+    hours = sched.get("reshuffle_hours", 3)
+    if isinstance(hours, bool) or not isinstance(hours, (int, float)) or hours <= 0:
+        raise ConfigError("display.schedule.reshuffle_hours must be a positive number of hours")
+    seed = sched.get("seed", 0)
+    if isinstance(seed, bool) or not isinstance(seed, int):
+        raise ConfigError("display.schedule.seed must be an integer")
+
+    try:
+        pools = Pools(pools_clean, reshuffle_hours=float(hours), seed=seed)
+        if kind == "times":
+            times = [(str(t), str(n).strip()) for t, n in sched.items() if t not in _SCHEDULE_COMMON]
+            if not times:
+                raise ConfigError("display.schedule of type times needs at least one HH:MM:SS: pool entry")
+            return TimesSchedule(times, pools, tz)
+        if kind == "timeranges":
+            extra = sorted(set(sched) - _SCHEDULE_COMMON - {"week", "order"})
+            if extra:
+                raise ConfigError(
+                    f"display.schedule of type timeranges takes week, order, reshuffle_hours and seed (got {extra})")
+            week = Week.from_config(sched.get("week"), tz, "display.schedule.week")
+            order = sched.get("order")
+            if order is not None and (not isinstance(order, list) or not all(isinstance(o, str) for o in order)):
+                raise ConfigError("display.schedule.order must be a list of pool names")
+            return TimeRangesSchedule(week, pools, order=order)
+    except ValueError as exc:
+        if isinstance(exc, ConfigError):
+            raise
+        msg = str(exc)
+        raise ConfigError(msg if msg.startswith("display.") else f"display.schedule: {msg}") from None
+    raise ConfigError(f"display.schedule.type must be times or timeranges (got {kind!r})")
+
+
+def parse_server(
+    config: dict,
+    *,
+    default_display: dict | None = None,
+    default_port: int = 8080,
+    default_regen_lead_seconds: int = 120,
+) -> ServerSettings:
+    port = _positive_int("server.port", get_prop_by_keys(config, "server", "port", default=default_port))
+    if port > 65535:
+        raise ConfigError(f"server.port must be 65535 or less. It is {port}.")
+
+    regen_lead = get_prop_by_keys(config, "server", "regen_lead_seconds",
+                                  default=default_regen_lead_seconds)
+    if isinstance(regen_lead, bool) or not isinstance(regen_lead, int) or regen_lead < 0:
+        raise ConfigError("server.regen_lead_seconds must be a non-negative integer (seconds)")
+
+    tz: _tzinfo = _datetime.now().astimezone().tzinfo  # type: ignore[assignment]
+    tz_name = get_prop_by_keys(config, "server", "timezone", default=None, required=False)
+    if tz_name:
+        try:
+            tz = ZoneInfo(str(tz_name))
+        except ZoneInfoNotFoundError:
+            raise ConfigError(
+                f"server.timezone '{tz_name}' is not a valid IANA zone (e.g. Europe/Dublin)"
+            ) from None
+
+    schedule = parse_display(config, tz, default_display)
+    debug = bool(get_prop(config, "debug", default=False, required=False))
+
+    return ServerSettings(
+        port=port,
+        timezone=tz,
+        schedule=schedule,
+        regen_lead_seconds=regen_lead,
+        debug=debug,
+    )
+
+
+_ALIGN_X = ("left", "center", "right")
+_ALIGN_Y = ("top", "center", "bottom")
+
+
+def parse_image(config: dict, *, default_width: int = 825, default_height: int = 1200) -> ImageSettings:
+    width = _positive_int("image.width", get_prop_by_keys(config, "image", "width", default=default_width))
+    height = _positive_int("image.height", get_prop_by_keys(config, "image", "height", default=default_height))
+    inner_w = _positive_int("image.innerWidth",
+                            get_prop_by_keys(config, "image", "innerWidth", default=width))
+    inner_h = _positive_int("image.innerHeight",
+                            get_prop_by_keys(config, "image", "innerHeight", default=height))
+    if inner_w > width:
+        raise ConfigError(f"image.innerWidth ({inner_w}) cannot be greater than image.width ({width})")
+    if inner_h > height:
+        raise ConfigError(f"image.innerHeight ({inner_h}) cannot be greater than image.height ({height})")
+
+    align_x = str(get_prop_by_keys(config, "image", "innerAlignX", default="center")).strip().lower()
+    align_y = str(get_prop_by_keys(config, "image", "innerAlignY", default="center")).strip().lower()
+    if align_x not in _ALIGN_X:
+        raise ConfigError(f"image.innerAlignX must be one of {sorted(_ALIGN_X)} (got {align_x!r})")
+    if align_y not in _ALIGN_Y:
+        raise ConfigError(f"image.innerAlignY must be one of {sorted(_ALIGN_Y)} (got {align_y!r})")
+
+    return ImageSettings(width, height, inner_w, inner_h, align_x, align_y)
+
+
+def parse_mqtt(config: dict, *, default_prefix: str = "mqtt/epd") -> MqttSettings:
+    enabled = bool(get_prop_by_keys(config, "mqtt", "enabled", default=False))
+    host = str(get_prop_by_keys(config, "mqtt", "host", default="localhost"))
+    port = _positive_int("mqtt.port", get_prop_by_keys(config, "mqtt", "port", default=1883))
+    prefix = str(get_prop_by_keys(config, "mqtt", "prefix", default=default_prefix))
+    return MqttSettings(enabled, host, port, prefix)
+
+
+_GITHUB_REPO = re.compile(r"^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$")
+
+
+def _parse_firmware_source(config: dict) -> FirmwareSource | None:
+    """The optional ``client.firmware.source`` block. Absent means images are placed by hand."""
+    github = get_prop_by_keys(config, "client", "firmware", "source", "github",
+                              default="", required=False)
+    github = str(github or "").strip()
+    if not github:
+        return None
+    if not _GITHUB_REPO.match(github):
+        raise ConfigError(f"client.firmware.source.github must be owner/repo (got {github!r})")
+    asset = str(get_prop_by_keys(config, "client", "firmware", "source", "asset",
+                                 default="firmware.bin")).strip()
+    if not asset:
+        raise ConfigError("client.firmware.source.asset must name the release asset to take")
+    poll = _positive_int("client.firmware.source.poll_seconds",
+                         get_prop_by_keys(config, "client", "firmware", "source", "poll_seconds",
+                                          default=3600))
+    token = str(get_prop_by_keys(config, "client", "firmware", "source", "token",
+                                 default="", required=False) or "")
+    return FirmwareSource(github=github, asset=asset, poll_seconds=poll, token=token)
+
+
+def parse_firmware(config: dict, *, default_product: str | None = None,
+                   base_dir: str | None = None) -> FirmwareSettings:
+    """The ``client.firmware`` block: where the images are, and who they are for.
+
+    It sits under ``client`` because every key in it describes the board, not
+    this server: the images are for the board to run, and ``product`` is the
+    name the board reports in its User-Agent. ``product`` is required once the
+    block is enabled, because offering one product's image to another
+    product's board would brick it. A relative ``dir`` is resolved against
+    ``base_dir``, which a project sets to wherever its config.yaml is.
+
+    ``products`` names several products instead, each with its images in a
+    subdirectory of its own name; ``product`` then defaults to the first.
+    """
+    enabled = bool(get_prop_by_keys(config, "client", "firmware", "enabled", default=False))
+    directory = str(get_prop_by_keys(config, "client", "firmware", "dir", default="firmware"))
+    if base_dir:
+        directory = os.path.join(base_dir, directory)
+    offer_dev = bool(get_prop_by_keys(config, "client", "firmware", "offer_dev_builds", default=False))
+    source = _parse_firmware_source(config)
+    if source and not default_product:
+        default_product = source.github.split("/")[-1]
+    products = get_prop_by_keys(config, "client", "firmware", "products", default=None,
+                                required=False) or ()
+    if isinstance(products, str) or not all(isinstance(p, str) and p.strip() for p in products):
+        raise ConfigError("client.firmware.products must be a list of client names")
+    products = tuple(p.strip() for p in products)
+    if products and not default_product:
+        default_product = products[0]
+    product = str(get_prop_by_keys(config, "client", "firmware", "product",
+                                   default=default_product or "", required=False) or "").strip()
+    if enabled and not product:
+        raise ConfigError("client.firmware.product is required when it is enabled: "
+                          "the client name the board sends, e.g. my-display")
+    return FirmwareSettings(enabled=enabled, dir=directory, product=product,
+                            offer_dev_builds=offer_dev, source=source, products=products)
+
+
+def load_core_config(
+    config: dict,
+    *,
+    default_display: dict | None = None,
+    default_firmware_product: str | None = None,
+    base_dir: str | None = None,
+    default_port: int = 8080,
+    default_regen_lead_seconds: int = 120,
+    default_width: int = 825,
+    default_height: int = 1200,
+    default_mqtt_prefix: str = "mqtt/epd",
+) -> CoreConfig:
+    """Validate the generic blocks of a config dict.
+
+    Raises :class:`ConfigError` (a ``ValueError``) on the first problem, with
+    a message for the person editing the file. A project validates its own
+    keys separately and decides how to report — typically log and exit.
+    """
+    return CoreConfig(
+        server=parse_server(config, default_display=default_display, default_port=default_port,
+                            default_regen_lead_seconds=default_regen_lead_seconds),
+        image=parse_image(config, default_width=default_width, default_height=default_height),
+        mqtt=parse_mqtt(config, default_prefix=default_mqtt_prefix),
+        firmware=parse_firmware(config, default_product=default_firmware_product,
+                                base_dir=base_dir),
+    )