trumpsignal-backend/app/services/scanner_state.py

"""
Scanner runtime state + control plane.

One module to answer: "what scanners are alive, when did each last fire, and
how do I turn one off without restarting the server?"

Why this exists (3 problems it solves at once):

  1. KILL SWITCH — Production safety. If a scanner is misbehaving (false
     fires, hammering an API, leaking memory) the operator needs to disable
     it WITHOUT redeploying. Per-scanner toggle + "stop all" both required.

  2. COOLDOWN PERSISTENCE — Previously each scanner kept _last_signal_at as
     a process-local dict. A backend restart wiped that dict, so a scanner
     that fired yesterday would happily re-fire today. Now cooldown is read
     from the posts table (source-of-truth) via `last_signal_at()`.

  3. OBSERVABILITY — Operator needs to see "is my RSI scanner alive?". The
     in-memory state tracker records every run (success / fire / error) so
     a GET /api/scanners endpoint can show the whole fleet at a glance.

State is intentionally process-local (no DB writes). After restart all
scanners come back ENABLED — same as the rest of the system. Cooldowns
survive restart because they're DB-derived. If you want a "permanently
disabled" scanner, comment it out of main.py instead.
"""

from __future__ import annotations

import logging
from dataclasses import dataclass, field, asdict
from datetime import datetime, timedelta, timezone
from typing import Optional

logger = logging.getLogger(__name__)


# ─── State container ────────────────────────────────────────────────────────


@dataclass
class ScannerState:
    name:               str
    enabled:            bool = True
    last_run_at:        Optional[datetime] = None
    last_status:        str = "never_ran"     # never_ran | ok | fired | error
    last_message:       Optional[str] = None
    last_fired_at:      Optional[datetime] = None
    consecutive_errors: int  = 0
    total_runs:         int  = 0
    total_fires:        int  = 0

    def to_dict(self) -> dict:
        d = asdict(self)
        for k in ("last_run_at", "last_fired_at"):
            if d[k] is not None:
                # last_run_at is tz-aware (datetime.now(timezone.utc)), so
                # isoformat() already emits "...+00:00". Appending "Z" would
                # produce the invalid "...+00:00Z" which JS Date can't parse
                # (renders as "NaNd ago" in the UI). Just use isoformat().
                d[k] = d[k].isoformat()
        return d


_STATES: dict[str, ScannerState] = {}


# ─── Registration (called once per scanner at import time) ──────────────────


def register(name: str) -> ScannerState:
    if name not in _STATES:
        _STATES[name] = ScannerState(name=name)
    return _STATES[name]


# ─── Toggle controls ────────────────────────────────────────────────────────


def is_enabled(name: str) -> bool:
    """Return False ONLY if explicitly disabled. Unknown scanners default
    to enabled — a scanner shouldn't silently refuse to run because its
    state wasn't registered (defensive)."""
    s = _STATES.get(name)
    return s.enabled if s else True


def set_enabled(name: str, enabled: bool) -> Optional[ScannerState]:
    s = _STATES.get(name)
    if s is None:
        return None
    s.enabled = enabled
    logger.info("Scanner %s %s", name, "ENABLED" if enabled else "DISABLED")
    return s


def disable_all() -> int:
    """Kill switch. Returns count of scanners that were running and got
    flipped off. Already-disabled scanners are skipped."""
    n = 0
    for s in _STATES.values():
        if s.enabled:
            s.enabled = False
            n += 1
    if n:
        logger.warning("Scanner kill switch: disabled %d scanners", n)
    return n


def enable_all() -> int:
    n = 0
    for s in _STATES.values():
        if not s.enabled:
            s.enabled = True
            n += 1
    return n


def get_all() -> list[ScannerState]:
    return list(_STATES.values())


# ─── Per-run telemetry (called by scanners after each scan) ─────────────────


def record_run(name: str, status: str, message: Optional[str] = None) -> None:
    """status: 'ok' (ran, no signal), 'fired' (emitted a signal), 'error'."""
    s = register(name)
    s.last_run_at = datetime.now(timezone.utc)
    s.last_status = status
    s.last_message = message[:240] if message else None
    s.total_runs += 1
    if status == "fired":
        s.total_fires += 1
        s.last_fired_at = s.last_run_at
        s.consecutive_errors = 0
    elif status == "error":
        s.consecutive_errors += 1
    else:
        s.consecutive_errors = 0


# ─── DB-backed cooldown (survives restart) ──────────────────────────────────


async def last_signal_at(source: str, target_asset: str) -> Optional[datetime]:
    """Most recent post with the given source+target_asset. Returns naive UTC.

    Used by scanners INSTEAD of in-memory cooldown trackers. The DB is the
    authoritative record of "did this scanner already fire?" — surviving
    restarts, multi-process deploys, and even DB migrations.
    """
    from sqlalchemy import select, func
    from app.database import AsyncSessionLocal
    from app.models import Post

    async with AsyncSessionLocal() as db:
        result = await db.execute(
            select(func.max(Post.published_at)).where(
                Post.source == source,
                Post.target_asset == target_asset.upper(),
            )
        )
        ts = result.scalar_one_or_none()
        return ts


async def in_cooldown(source: str, target_asset: str, cooldown_days: int) -> bool:
    """Convenience wrapper. True iff we fired the same {source, asset} within
    the last `cooldown_days`."""
    last = await last_signal_at(source, target_asset)
    if last is None:
        return False
    age = datetime.now(timezone.utc).replace(tzinfo=None) - last
    return age < timedelta(days=cooldown_days)