steam-backlog-enforcer/steam_backlog_enforcer/_playtime_history.py

"""A durable per-day record of how much gaming time was actually spent.

``PlaytimeState`` only ever describes *today*: ``roll_over`` resets the counter
at the 06:00 boundary and the previous day is gone. The audit log in
``_playtime_log`` does retain per-day figures, but it is a rotating handler —
five 5 MB files — so a busy fortnight can push a day out of the window entirely.
Neither is a series you can plot.

So this module keeps one small file whose only job is the history: a
``day_key -> {seconds, games}`` mapping, trimmed to the last month, written
world-readable so an unprivileged reader (the web UI) can plot it. Schema 1
stored a bare seconds float per day and is still read: those days simply carry
no per-game breakdown, which the payload renders as Unattributed.

Writes are throttled rather than tied to roll-over. Upserting today's figure on a
cadence means the outgoing day is already recorded to within ``_FLUSH_DELTA``
seconds of its final value by the time the boundary arrives, which avoids
threading a "previous state" argument through the tick's hot path just to catch
one transition a day.

Like ``BudgetLog``, nothing here may raise: losing a history point is a cosmetic
failure and must never take down the enforcer.
"""

from __future__ import annotations

import json
import logging
from typing import TYPE_CHECKING, Final

from steam_backlog_enforcer._attribution_labels import labels_for
from steam_backlog_enforcer._playtime_history_parse import (
    HistoryDay,
    _parse_day,
    _parse_labels,
)
from steam_backlog_enforcer._playtime_state import STATE_MODE
from steam_backlog_enforcer.config import CONFIG_DIR, _atomic_write

if TYPE_CHECKING:
    from steam_backlog_enforcer._playtime_state import PlaytimeState

logger = logging.getLogger(__name__)

__all__ = ["HISTORY_FILE", "HistoryDay", "HistoryWriter", "load_history", "record_day"]

HISTORY_FILE: Final = CONFIG_DIR / "playtime_history.json"

_SCHEMA_VERSION: Final = 1

# Day values are polymorphic rather than versioned: a bare float is the
# original `day -> seconds` form, an object carries the per-game breakdown.
# The reader must handle both either way, so a version bump would add a
# branch that distinguishes nothing.

# Days retained. Comfortably more than the fortnight the UI plots, so a chart
# that later grows a longer window has data waiting for it.
_MAX_DAYS: Final = 30

# Rewrite only once the stored figure is this far behind. At a three-second tick
# an unthrottled upsert would rewrite the file 1200 times an hour to move a bar
# by a pixel.
_FLUSH_DELTA: Final = 60.0


def _read_file() -> tuple[dict[str, HistoryDay], dict[str, str]]:
    """Return the stored days and label map, or empties if unusable.

    Unlike the state file this one is neither root-owned nor immutable, and it
    lives in a user-owned directory — so an unprivileged process can replace it
    with anything at all, and the web server parses whatever it finds. Every
    field is therefore checked rather than trusted.

    Returns:
        The ``day -> HistoryDay`` mapping and the ``key -> label`` mapping, both
        empty when the file is missing, unreadable, corrupt or of an unknown
        schema.
    """
    try:
        raw = json.loads(HISTORY_FILE.read_text(encoding="utf-8"))
    except FileNotFoundError:
        return {}, {}
    except OSError, ValueError:
        logger.warning(
            "Playtime history at %s is unreadable; starting over.", HISTORY_FILE
        )
        return {}, {}
    if not isinstance(raw, dict) or raw.get("schema_version") != _SCHEMA_VERSION:
        logger.warning("Playtime history at %s has an unknown schema.", HISTORY_FILE)
        return {}, {}

    days = raw.get("days")
    if not isinstance(days, dict):
        return {}, {}
    parsed = {
        key: entry
        for key, value in days.items()
        if isinstance(key, str)
        for entry in [_parse_day(key, value)]
        if entry is not None
    }
    return parsed, _parse_labels(raw.get("labels"))


def load_history(limit: int = 14) -> list[HistoryDay]:
    """Return the most recent *limit* days, oldest first.

    Args:
        limit: How many days to return.

    Returns:
        Recorded days in ascending date order, at most *limit* of them.
    """
    days, _ = _read_file()
    ordered = sorted(days.items())[-limit:] if limit > 0 else []
    return [entry for _, entry in ordered]


def load_labels() -> dict[str, str]:
    """Return the stored ``key -> label`` mapping.

    Returns:
        Labels recorded alongside the history.
    """
    return _read_file()[1]


def record_day(day_key: str, seconds: float, games: dict[str, float]) -> None:
    """Upsert one day's total and breakdown, trimming to ``_MAX_DAYS``.

    Labels are merged rather than replaced so a game that stops being played
    keeps its name for as long as its days remain in the window.

    Args:
        day_key: Gaming day to record.
        seconds: Total billed for that day so far.
        games: Attribution key to seconds for that day.
    """
    days, labels = _read_file()
    days[day_key] = HistoryDay(day=day_key, seconds=seconds, games=dict(games))
    trimmed = dict(sorted(days.items())[-_MAX_DAYS:])
    labels.update(labels_for(games))
    payload = {
        "schema_version": _SCHEMA_VERSION,
        "days": {
            day: {"seconds": entry.seconds, "games": entry.games}
            for day, entry in trimmed.items()
        },
        "labels": {
            key: label
            for key, label in labels.items()
            if any(key in entry.games for entry in trimmed.values())
        },
    }
    _atomic_write(
        HISTORY_FILE,
        json.dumps(payload, indent=2) + "\n",
        mode=STATE_MODE,
    )


class HistoryWriter:
    """Throttled writer for the per-day history, held across ticks.

    Mirrors how ``TickJournal`` carries its heartbeat state on the session
    rather than in a module global, which is what keeps the throttle testable
    without reaching into module internals between cases.
    """

    def __init__(self) -> None:
        self._last_written: dict[str, float] = {}

    def observe(self, state: PlaytimeState, *, demo: bool) -> None:
        """Record *state*'s day if it is new or has moved far enough.

        Demo runs are skipped for the same reason they get their own state file
        and their own audit log: a 60-second demo must not leave a record
        describing a budget nobody was ever charged.

        Args:
            state: Current accounting state.
            demo: Whether this is a demo run.
        """
        if demo or not state.day_key:
            return
        previous = self._last_written.get(state.day_key)
        if previous is not None and abs(state.seconds - previous) < _FLUSH_DELTA:
            return
        try:
            record_day(state.day_key, state.seconds, state.per_game)
        except OSError as exc:
            # A history point is cosmetic; the enforcer keeps enforcing.
            logger.warning("Could not record playtime history: %s", exc)
            return
        self._last_written = {state.day_key: state.seconds}