- add verbatim GPLv3 text as LICENSE - declare license and license-files in pyproject - add SPDX headers to Python sources - document licensing in README
483 lines
18 KiB
Python
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)
|