wake-alarm/wake_alarm/_fallback.py

"""The PC fallback alarm: one per-minute tick, 04:00-09:59.

``wake-alarm-fallback.timer`` runs ``--tick`` every minute. Outside
``A - 5 min .. A + 45 min`` (or on a free or sick day) a tick decides from local
state alone and never touches the network. Inside, it reads every device's
``alarm.json`` once, decides (``_fallback_policy.decide``) and, when the
decision is to ring, rings *in this process* until a stop condition holds
-- the unit is a oneshot, so the timer's next minute is a no-op while it
rings and no PID file is needed. Firebase unreachable counts as "no ping,
no session, no escape": fail toward ringing.

    python -m wake_alarm._fallback --tick      # what the timer runs
    python -m wake_alarm._fallback --dry-run   # decide now, change nothing
    python -m wake_alarm._fallback --show      # latch + last decision, offline
"""

from __future__ import annotations

from dataclasses import replace
from datetime import UTC, datetime
import signal
import sys
from typing import TYPE_CHECKING

import freedays

from wake_alarm._cli_modes import mode_parser, parse_with_now
from wake_alarm._events import emit, emit_on_change, last_value
from wake_alarm._fallback_latch import Latch, mark_started, mark_stopped, read_latch
from wake_alarm._fallback_observe import (
    Observation,
    observe,
    record,
    remember_final,
    settled_reason,
)
from wake_alarm._fallback_policy import (
    Decision,
    Facts,
    alarm_instant,
    decide,
    stop_reason,
)
from wake_alarm._fallback_ring import ring
from wake_alarm._logging_setup import configure_logging
from wake_alarm._ring_wav import SYSTEM_WAV_DIR, USER_WAV_DIR, ensure_pair
from wake_alarm._sick import alarm_stands_down
from wake_alarm._sync import get_alarm

if TYPE_CHECKING:
    from types import FrameType

TERMINATED = "terminated"


def _now() -> datetime:
    """Aware local now; the seam tests patch."""
    return datetime.now(tz=UTC).astimezone()


def _close(latch: Latch, reason: str) -> None:
    """Stop an open latch and log it."""
    stopped = mark_stopped(latch, now=_now(), stop_reason=reason)
    emit(
        "fallback_ring_stop",
        reason,
        stop_reason=reason,
        started_at=stopped.started_at,
        stopped_at=stopped.stopped_at,
    )


def _poll(day: str) -> str | None:
    """Re-observe while ringing; the reason to stop, or None."""
    seen = observe(_now(), sync=True)
    record(seen)
    reason = stop_reason(replace(seen.facts, latch=read_latch(day)))
    if reason is not None:
        remember_final(day, reason)
    return reason


def ring_now(facts: Facts, reason: str) -> str:
    """Latch, ring until a stop condition, unlatch; returns the stop reason."""
    day = facts.now.date().isoformat()
    resumed = facts.latch is not None and facts.latch.started_at is not None
    latch = mark_started(facts.latch, day=day, now=facts.now, reason=reason)
    emit(
        "fallback_ring_start",
        reason,
        reason=reason,
        resumed=resumed,
        alarm=facts.alarm_at.isoformat(),
        started_at=latch.started_at,
    )
    stopped = TERMINATED
    try:
        # Inside the try: a WAV that cannot be generated must still close
        # the latch (as "terminated"), never leave it open.
        rise, loop = ensure_pair(SYSTEM_WAV_DIR, USER_WAV_DIR)
        stopped = ring(lambda: _poll(day), rise=rise, loop=loop)
    finally:
        _close(latch, stopped)
    return stopped


def tick(now: datetime) -> Decision:
    """One timer tick: observe, log a changed decision, ring if due."""
    seen = observe(now, sync=True)
    record(seen)
    facts, day = seen.facts, now.date().isoformat()
    decision = decide(facts)
    emit_on_change(
        "fallback_tick",
        f"{day}|{decision.ring}|{decision.reason}",
        f"{'ring' if decision.ring else 'quiet'}: {decision.reason}",
        ring=decision.ring,
        reason=decision.reason,
        alarm=facts.alarm_at.isoformat(),
        reachable=seen.reachable,
    )
    remember_final(day, decision.reason)
    latch = facts.latch
    if decision.ring:
        ring_now(facts, decision.reason)
    elif latch is not None and latch.started_at and not latch.stopped_at:
        _close(latch, decision.reason)
    return decision


def describe(seen: Observation, decision: Decision) -> str:
    """The ``--dry-run`` report."""
    facts = seen.facts
    verdict = "WOULD RING" if decision.ring else "quiet"
    return (
        f"{facts.now:%Y-%m-%d %H:%M} — {verdict}: {decision.reason}\n"
        f"  alarm A={facts.alarm_at:%H:%M} free_day={facts.free_day} "
        f"sick_day={facts.sick_day} "
        f"firebase={'ok' if seen.reachable else 'UNREACHABLE'}\n"
        f"  escaped={facts.escaped} session_started={facts.session_started} "
        f"ring_started={facts.ring_started} settled={facts.settled}\n"
        f"  latch={facts.latch}\n"
    )


def show(now: datetime) -> str:
    """The ``--show`` report: local state only, no network."""
    day = now.date().isoformat()
    alarm_at = alarm_instant(get_alarm(), now.date())
    return (
        f"today {day}: A={alarm_at:%H:%M} "
        f"free_day={freedays.is_free_day(now.date())} "
        f"sick_day={alarm_stands_down(now.date())}\n"
        f"  latch={read_latch(day)}\n"
        f"  last fallback_tick={last_value('fallback_tick')}\n"
        f"  settled={settled_reason(day, read_latch(day))}\n"
    )


def _terminate(signum: int, _frame: FrameType | None) -> None:
    """SIGTERM -> SystemExit, so ``finally`` silences the speakers."""
    raise SystemExit(128 + signum)


def main(argv: list[str] | None = None) -> int:
    """Entry point."""
    parser = mode_parser("PC fallback alarm tick", "tick", "decide and act")
    args, now = parse_with_now(parser, argv, _now)
    if args.show:
        sys.stdout.write(show(now))
    elif args.dry_run:
        seen = observe(now, sync=False)
        sys.stdout.write(describe(seen, decide(seen.facts)))
    else:
        configure_logging(component="fallback")
        signal.signal(signal.SIGTERM, _terminate)
        tick(now)
    return 0


if __name__ == "__main__":
    sys.exit(main())