Files
sigcal/src/signal_cal_bot/scheduler.py
T
kawaiipunk 68cd2895e8 License under GPL-3.0-or-later
- add verbatim GPLv3 text as LICENSE
- declare license and license-files in pyproject
- add SPDX headers to Python sources
- document licensing in README
2026-11-18 16:48:51 +00:00

483 lines
18 KiB
Python

# SPDX-License-Identifier: GPL-3.0-or-later
# Copyright (C) 2026 kawaiipunk
"""Decision logic and the main tick loop.
Flow of one tick:
1. ``_refresh_feed`` — re-fetch the iCalendar feed when it is due, expand it
into events and reconcile them with the database (``_sync``).
2. ``_dispatch`` — send everything whose outbox row is due, grouped into as
few Signal messages as possible.
3. ``_heartbeat`` — optional once-a-day "still alive" note.
All scheduling decisions are persisted (``reminder_plans`` and ``outbox``) at
discovery time, so a restart, a feed edit or a sliding window cannot reshuffle
posts that were already planned. Sending is at-least-once.
"""
from __future__ import annotations
import logging
from datetime import datetime, time, timedelta, timezone
from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
import httpx
from .config import Config, parse_duration
from .expand import Event, parse_events
from .feed import Feed
from .format import find_postcode, render_post, venue_from_description, venue_from_location
from .images import ImageService, PageScraper
from .signal_client import SignalClient, SignalError
from .store import OutboxItem, PageInfo, Store, iso
from .watchdog import Watchdog
log = logging.getLogger(__name__)
MAX_SEND_ATTEMPTS = 5
# ---------------------------------------------------------------------------
# posting windows
# ---------------------------------------------------------------------------
def in_window(moment: datetime, windows: tuple[tuple[time, time], ...]) -> bool:
"""True when the local clock time falls inside one of the preferred windows."""
clock = moment.timetz().replace(tzinfo=None)
return any(start <= clock < end for start, end in windows)
def next_window_start(
moment: datetime, windows: tuple[tuple[time, time], ...]
) -> datetime:
"""First window opening strictly after ``moment`` (same timezone)."""
for offset in range(0, 4):
day = moment.date() + timedelta(days=offset)
for start, _end in windows:
candidate = datetime.combine(day, start, tzinfo=moment.tzinfo)
if candidate > moment:
return candidate
return moment + timedelta(days=1)
def clamp_send_at(
due: datetime,
now: datetime,
deadline: datetime,
windows: tuple[tuple[time, time], ...],
guard: timedelta,
) -> datetime:
"""Defer a post to the next preferred window unless that misses the deadline.
``deadline`` is when the post stops being useful (usually the event start).
If the next window opens after ``deadline - guard``, the post goes out as
soon as it is due instead: a reminder that arrives after the event is
worse than one that arrives outside the preferred hours.
"""
base = max(due, now)
if in_window(base, windows):
return base
upcoming = next_window_start(base, windows)
if upcoming >= deadline - guard:
return base
return upcoming
def reminder_time(
event: Event,
lead: str,
first_seen: datetime,
config: Config,
local_tz: ZoneInfo,
) -> datetime | None:
"""When the reminder for this lead should go out (local time), or None.
Normally that is ``start - lead`` moved into the next posting window.
If the event was discovered *after* that moment ("added 2 days out" with a
3-day lead) the fallback is the morning of the event, so the group still
gets one heads-up rather than none. For a timed event that starts before
the configured morning time, the fallback moves earlier so it cannot land
after the event has begun.
"""
start = event.start.astimezone(local_tz)
seen = first_seen.astimezone(local_tz)
lead_delta = timedelta(seconds=parse_duration(lead))
due = start - lead_delta
if due <= seen:
if not config.reminders.fallback_to_day_of:
return None
due = datetime.combine(start.date(), config.reminders.day_of_time, tzinfo=local_tz)
if not event.all_day:
latest = start - timedelta(minutes=config.posting.urgent_guard_minutes)
if due > latest:
due = latest
deadline = start if not event.all_day else start + timedelta(hours=12)
return clamp_send_at(
due,
seen,
deadline,
config.posting.windows,
timedelta(minutes=config.posting.urgent_guard_minutes),
)
# ---------------------------------------------------------------------------
# bot
# ---------------------------------------------------------------------------
class Bot:
def __init__(
self,
config: Config,
store: Store,
feed: Feed,
sender: SignalClient,
images: ImageService,
scraper: PageScraper,
watchdog: Watchdog,
http: httpx.Client,
):
self.config = config
self.store = store
self.feed = feed
self.sender = sender
self.images = images
self.scraper = scraper
self.watchdog = watchdog
self.http = http
try:
self.local_tz = ZoneInfo(config.calendar.timezone)
except ZoneInfoNotFoundError:
self.local_tz = ZoneInfo("UTC")
# -- loop ------------------------------------------------------------
def tick(self, now: datetime | None = None) -> None:
"""One full cycle. ``now`` is injectable so tests can travel in time."""
now = now or datetime.now(timezone.utc)
self._refresh_feed(now)
self._dispatch(now)
self._heartbeat(now)
# -- feed + planning -------------------------------------------------
def _refresh_feed(self, now: datetime) -> None:
"""Fetch (when due), parse and reconcile. Never raises."""
if not self.feed.due(now):
return
try:
response = self.feed.fetch(now)
if response.content is None:
self.watchdog.feed_ok()
return
events = parse_events(
response.content,
now,
now + timedelta(days=self.config.calendar.window_days),
self.config.calendar.timezone,
)
except Exception as exc: # noqa: BLE001 - feed problems must not kill the loop
log.exception("feed refresh failed")
self.watchdog.feed_failed(str(exc), now)
return
if not events:
# Never seed from an empty feed: it is far more likely to be a
# transient publishing problem than "the calendar has no events".
if self.store.count_events() > 0:
self.watchdog.alert(
"empty-feed",
"Feed parsed to zero events while the database still has events. "
"Leaving stored events untouched.",
now,
)
else:
log.warning("feed returned no events; not seeding yet")
self.watchdog.feed_failed("feed parsed to zero events", now)
return
# Only persist validators once the payload has parsed cleanly, so a
# broken response cannot pin itself behind a 304.
self.feed.commit(response)
self.watchdog.feed_ok()
self._sync(events, now)
def _sync(self, events: list[Event], now: datetime) -> None:
"""Reconcile the feed snapshot with the database.
Only genuinely new event rows cause work: they get reminder plans, and
their series gets an announcement if this is the first occurrence we
have seen. Recurring series are pre-expanded by the feed, so keying on
the series (not the occurrence) is what stops a new weekly event from
producing thirty announcements.
"""
first_run = self.store.get_meta("seeded") is None
seeding = first_run and not self.config.announce.backfill
for event in events:
is_new = self.store.upsert_event(event, now)
if not is_new:
continue
new_series = self.store.create_series(event.series_id, now)
self._plan_reminders(event, now)
if seeding:
self.store.record_delivery("announce", event.series_id, "seed", now)
continue
if new_series:
self._plan_announcement(event, now)
self.store.mark_gone(
[event.key for event in events], now, max(event.start for event in events)
)
if first_run:
self.store.set_meta("seeded", iso(now))
log.info("first run: seeded %d events", len(events))
def _plan_announcement(self, event: Event, now: datetime) -> None:
"""Queue a "new event" post for the first occurrence of a series."""
if not self.config.announce.enabled:
return
if event.end <= now:
return
horizon = now + timedelta(days=self.config.announce.max_days_ahead)
if event.start > horizon:
return
if self.store.delivered("announce", event.series_id, "once"):
return
if self.store.queued("announce", event.series_id, "once"):
return
start_local = event.start.astimezone(self.local_tz)
deadline = (
start_local
if not event.all_day
else start_local + timedelta(hours=12)
)
send_at = clamp_send_at(
now.astimezone(self.local_tz),
now.astimezone(self.local_tz),
deadline,
self.config.posting.windows,
timedelta(minutes=self.config.posting.urgent_guard_minutes),
)
self.store.add_outbox(
"announce",
event.series_id,
"once",
event.key,
send_at.astimezone(timezone.utc),
now,
)
def _plan_reminders(self, event: Event, now: datetime) -> None:
"""Queue the T-minus reminders for a newly discovered event."""
if not self.config.reminders.enabled or event.end <= now:
return
for lead in self.config.reminders.lead_times:
if self.store.plan_exists(event.key, lead):
continue
due = reminder_time(event, lead, now, self.config, self.local_tz)
if due is None:
continue
self.store.add_plan(event.key, lead, due)
self.store.add_outbox(
"reminder",
event.key,
lead,
event.key,
due.astimezone(timezone.utc),
now,
)
# -- sending ---------------------------------------------------------
def _dispatch(self, now: datetime) -> None:
"""Send every due outbox row, grouped into one message per batch.
Rows are grouped by event so an announcement and a reminder that fall
in the same window become a single post rather than two. Items that
have become pointless (event over/started, removed from the feed) are
recorded as delivered and dropped so they are never retried.
"""
items = self.store.due_outbox(now)
if not items:
return
grouped: dict[str, list[OutboxItem]] = {}
for item in items:
grouped.setdefault(item.event_key, []).append(item)
batch: list[tuple[Event, list[OutboxItem]]] = []
for event_key, group in grouped.items():
event = self.store.get_event(event_key)
if event is None:
for item in group:
self.store.drop_outbox(item.id)
continue
valid: list[OutboxItem] = []
for item in group:
usable = (
not event.gone
and event.end > now
and (item.kind != "reminder" or event.all_day or event.start > now)
)
if usable:
valid.append(item)
else:
log.info("dropping stale %s for %s", item.kind, event.summary)
self.store.record_delivery(item.kind, item.ref, item.period, now)
self.store.drop_outbox(item.id)
if valid:
batch.append((event, valid))
if not batch:
return
try:
message, attachments = self._compose(batch)
except Exception as exc: # noqa: BLE001 - compose must not wedge the outbox
log.exception("could not compose post")
self._record_failure(batch, str(exc), now)
return
try:
self.sender.send(
message,
[self.config.signal.group_id],
attachments=attachments,
text_mode=self.config.signal.text_mode,
)
except (SignalError, httpx.HTTPError) as exc:
log.error("send failed: %s", exc)
self._record_failure(batch, str(exc), now)
return
self.watchdog.send_ok()
for event, group in batch:
for item in group:
self.store.record_delivery(item.kind, item.ref, item.period, now)
if item.kind == "announce":
self.store.mark_series_announced(item.ref, event.uid, now)
self.store.drop_outbox(item.id)
log.info("posted %d item(s) covering %d event(s)", len(items), len(batch))
def _record_failure(
self, batch: list[tuple[Event, list[OutboxItem]]], reason: str, now: datetime
) -> None:
"""Count a failed attempt; drop the post after MAX_SEND_ATTEMPTS."""
self.watchdog.send_failed(reason, now)
for _event, group in batch:
for item in group:
attempts = self.store.bump_attempts(item.id)
if attempts >= MAX_SEND_ATTEMPTS:
log.error("giving up on %s after %d attempts", item.ref, attempts)
self.watchdog.alert(
"outbox",
f"Dropping a post after {attempts} failed attempts.",
now,
)
self.store.drop_outbox(item.id)
def _compose(self, batch: list[tuple[Event, list[OutboxItem]]]) -> tuple[str, list[str]]:
"""Render the batch into one message and up to N base64 attachments.
A single event gets its own image; a multi-event batch is capped at
``images.max_images_per_post`` so the payload stays reasonable.
"""
blocks: list[str] = []
attachments: list[str] = []
limit = self.config.images.max_images_per_post if len(batch) > 1 else 1
for event, _items in batch:
block, attachment = self._compose_one(event, limit - len(attachments))
blocks.append(block)
if attachment:
attachments.append(attachment)
return "\n\n".join(blocks), attachments
def _compose_one(self, event: Event, images_left: int) -> tuple[str, str | None]:
"""Render one event; enrichment and image failures degrade to text only."""
info = PageInfo(image_url="", venue="", postcode="")
try:
info = self.scraper.details(event.url)
except Exception: # noqa: BLE001 - never block a post on scraping
log.exception("page scrape failed for %s", event.url)
venue = (
venue_from_location(event.location)
or info.venue
or venue_from_description(event.description)
)
postcode = find_postcode(event.location, event.description) or info.postcode
link = event.url
if self.config.format.shorten_links and link:
link = self._shorten(link)
text = render_post(
event,
self.config.format,
self.local_tz,
venue=venue,
postcode=postcode,
link=link,
)
attachment = None
if images_left > 0:
image_url = event.image_url or info.image_url
if image_url:
try:
attachment = self.images.data_uri(image_url)
except Exception: # noqa: BLE001 - images are best effort
log.exception("image failed for %s", image_url)
return text, attachment
def _shorten(self, url: str) -> str:
cached = self.store.get_short_link(url)
if cached:
return cached
try:
response = self.http.get(
"https://tinyurl.com/api-create.php",
params={"url": url},
timeout=8,
headers={"User-Agent": "signal-cal-bot/0.1"},
)
if response.status_code == 200 and response.text.strip().startswith("http"):
short = response.text.strip()
self.store.put_short_link(url, short, datetime.now(timezone.utc))
return short
except httpx.HTTPError as exc:
log.warning("link shortening failed: %s", exc)
return url
# -- heartbeat -------------------------------------------------------
def _heartbeat(self, now: datetime) -> None:
if not self.config.watchdog.daily_heartbeat:
return
local = now.astimezone(self.local_tz)
today = local.date().isoformat()
if local.hour < 9 or self.store.get_meta("last_heartbeat") == today:
return
try:
self.sender.send(
f"signal-cal-bot alive \u2014 {self.store.count_events()} events in the window",
[self.watchdog.recipient],
text_mode=self.config.signal.text_mode,
)
except (SignalError, httpx.HTTPError) as exc:
log.warning("heartbeat failed: %s", exc)
return
self.store.set_meta("last_heartbeat", today)