# 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)