Rename project to signal-cal-bot
- package src/signal-cal-bot -> src/signal_cal_bot - distribution and CLI entry point: signal-cal-bot - env vars CALBOT_* -> SIGNAL_CAL_BOT_* - database file, container names, user agents and logs renamed - docs and compose updated
This commit is contained in:
@@ -0,0 +1,479 @@
|
||||
"""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)
|
||||
Reference in New Issue
Block a user