From ce87d6bf0de07d5f69931383ce5ba3979c535e50 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Thu, 15 Oct 2026 23:59:50 +0000 Subject: [PATCH] feat(automations): schedule, at and relative triggers as timers timers.schedule_automation sets one timer per schedule trigger (its next time, re-armed as it fires, DST as schedule.py has it) and per at trigger still to come, leaves timers a trigger still wants alone so they can catch up, calls off the rest, and cancels everything when the automation is off. timers.relative sets a relative trigger's timer per automation, trigger and object, so a moved calendar event moves its timer; past times are skipped with a note. When they fire, automations.fire gets a clock.tick activity (a new kind, never stored) or the activity that set the timer. timers.upcoming lists what an automation has waiting, in words, and schedule.describe reads weekdays, single days and days of the month. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01KfD6cia42GiEZakbs74jxY --- docs/automations.md | 42 ++- fastapi_backend/app/domain/schedule.py | 33 +- fastapi_backend/app/domain/timers.py | 335 ++++++++++++++++++ .../tests/domain/test_timer_triggers.py | 192 ++++++++++ 4 files changed, 598 insertions(+), 4 deletions(-) create mode 100644 fastapi_backend/tests/domain/test_timer_triggers.py diff --git a/docs/automations.md b/docs/automations.md index a67d696be..842fbf4c3 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -29,7 +29,8 @@ merged is called built. | Settings → Automations: how often followers look, how long the event log is kept, and how late a timer may fire | built | | A webhook address per automation trigger, and calls to it as `webhook.received` ([Webhook trigger](#webhook-trigger)) | built | | Timers that outlast a restart and fire once across the API and the worker (`app/domain/timers.py`, [Time](#time)) | built | -| Schedule, `at` and `relative` triggers, and actions that wait ([Time](#time)) | planned | +| The timers behind schedule, `at` and `relative` triggers, the `clock.tick` kind and what's coming ([Time](#time)); automations set them once they are stored | built | +| Actions that wait (`delay`, `when`) ([Time](#time)) | planned | | The Timeline page with filters, grouping, review keys and new items, and Home's Latest card ([Timeline](timeline.md)) | built | | Storing and running automations, joins, approvals, variables, the studio | planned | @@ -104,6 +105,7 @@ and the paths holding outside text are in `GET /api/v1/activities/kinds` (`event | `comment.added` | | `comments` | a `Note`: `content`, `inReplyTo` (the comment it answers), `quote` (the passage), `t0`, `t1` (the moment, ms); `target` is the asset | Sam commented on “Call with the school” | | `note.created` | | `note_pages` | a `Page`: `summary`, `about` (what it's the page of), `place`, `author` (person or assistant) | Assistant wrote the note “St Mary's School” | | `note.saved` | | `note_versions` | as `note.created`, with `version` (the page as it was before) and `why` | Sam edited the note “School trip plans” | +| `clock.tick` | | `clock` (never stored) | an `Event`: `at` (the moment, UTC), `cron`, `timezone`, `local` (the time there, in words), `description` (the schedule in words, or once), `late`; actor `Lens clock` | Lens clock: Fri 16 Oct at 07:00 (every weekday at 07:00, Europe/London) | | `entity.changed` | | `graph` | `op` (created, renamed, merged, split, linked, unlinked, deleted, rolled back, changed), `change` (the graph's own op), `entityType`, `before` (a renamed entity's name), `version`, `count`; tagged with its entities | Sam renamed “St Marys” to “St Mary's School” | | `sensor.reading` | | `sensor_readings` | `{type: Note, id: lens:sensor_reading/, name: ": ", url: /sensors/}`, `stream`, `value`, `text`, `fields` (a JSON reading's numbers), `level` (syslog), `pattern`, `label` (the line's pattern and its label); noisy | Kitchen sensor temperature: 31.2 | | `sensor.alert` | | `log` | `{type: Note, id: lens:sensor_pattern/}`, `label` (alert or notable), `pattern`, `example` (a line it fits), `count` (lines in all), `lines` (in the batch that raised it), `hour` | 192.168.1.1 logged an alert: wlan: authentication failed for | @@ -518,6 +520,39 @@ def _(db, cfg, payload): ... # payload + late (true checks once a minute, and at once when this process sets one. A timer set by the other process (the API, when the worker fires them) can so fire up to a minute late. +### Schedule, at and relative triggers + +Built as timers; automations set them once they are stored. Each trigger checks as +[Automations: triggers and joins](#automations-triggers-and-joins) says. + +```python +timers.schedule_automation(db, automation) # {id, enabled, spaces, triggers}: on save, switch on, switch off +timers.relative(db, automation, alias, activity, field, offset) # a matching activity came: {key, at, set, note} +timers.upcoming(db, automation, n=10) # what it has waiting, soonest first, in words +timers.clock_state(db, automation) # each schedule and at trigger: waiting, done, missed, failed or off +``` + +- **Schedule** (`on: schedule`, `cron`, `timezone`): one timer, `sched--`, at the schedule's next + time (`schedule.py`: five-field cron, the shorthands, time zones; a time daylight saving skips runs when the clock + gets past the gap, a time it repeats runs once). When it fires, the automation fires with a `clock.tick` activity + for that moment, and the timer is re-armed for the next time in the same update. +- **At** (`on: at`, `at`, `timezone`): one timer, `at--`, if the time is still to come; afterwards + the trigger reads done, and saving the automation again doesn't set it again. +- **Relative** (`on: relative`, `kinds`, `where`, `field`, `offset`): when a matching activity comes, a timer at the + time in its `field` plus `offset` (`-30m`: half an hour before; a date alone is its midnight in UTC), keyed by the + automation, the trigger and the activity's object (`rel---`). So when a calendar event + moves (`calendar_event.changed`, about the same object) its timer moves with it rather than adding a second. A time + more than 5 minutes in the past is skipped, with a note for the automation's log, and a timer it had is called + off. When it fires, the automation fires with the activity that set it. +- **Saving again** leaves a timer a trigger still wants as it is, so one that came due while Lens was off can still + catch up. A changed schedule or time sets it anew, a trigger that's gone has its timer called off, and waiting + relative timers follow a changed `field` or `offset`. Switching an automation off calls off every timer it has. +- **What's coming** (`upcoming`): `{key, at, kind, trigger, node, description, untrusted}`, such as "Every weekday at + 07:00: next on Fri 16 Oct at 07:00 (Europe/London)" or "30 minutes before “Parents' evening” starts: on Tue 20 Oct + at 16:30 (UTC)"; `untrusted` says the description quotes outside text (the event's title). The builder previews a + schedule with `GET /api/v1/routines/schedule`, which now reads weekdays, single days and days of the month in + words too ("every weekday at 07:00", "at 09:00 on the 20th of every month"). + ## Refine later - More operators: `in`, `matches` (bounded regular expressions), `between`, times against now, `changed`. @@ -554,7 +589,10 @@ def _(db, cfg, payload): ... # payload + late (true - Calling a web address: secrets in the address itself (a Slack or Discord webhook URL) sealed like headers; PATCH and DELETE (DELETE would count as deleting); OAuth sign-in for an API; form-encoded bodies; retries with backoff; networks allowed for automations apart from notifications. -- Time: sub-second timers woken by `events.wake()` alone; telling the other process (the worker) at once when the +- Time: calendar-aware schedules ("first workday of the month", holidays); sunrise and sunset triggers; an all-day + event's date in the person's time zone rather than UTC; upcoming relative timers in the person's time zone; an + event that's cancelled calling off its relative timers; the timeline's kind filter leaving out `clock.tick`, which + is never stored; sub-second timers woken by `events.wake()` alone; telling the other process (the worker) at once when the API sets a timer, rather than within a minute. - Running Lens work: a routine run's id passed on (today the scheduler starts it later); waiting for the job and passing on its outputs; roles on collections counting for `process`; running a pipeline on every asset a join collected. diff --git a/fastapi_backend/app/domain/schedule.py b/fastapi_backend/app/domain/schedule.py index fa5a8bc0f..4fc968bca 100644 --- a/fastapi_backend/app/domain/schedule.py +++ b/fastapi_backend/app/domain/schedule.py @@ -133,12 +133,41 @@ def next_after(expr, tz="UTC", after=None): return None +DAYS = ("Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday") +WEEKDAYS = ("1-5", "mon-fri") +WEEKENDS = ("0,6", "6,0", "6,7", "6-7", "sat,sun", "sun,sat", "sat-sun") + + +def _ordinal(n): + return f"{n}{'th' if 10 <= n % 100 <= 20 else {1: 'st', 2: 'nd', 3: 'rd'}.get(n % 10, 'th')}" + + +def _one_day(text): + """The name of a single day of the week, or None.""" + try: + d = _value(text, 4) + except ValueError: + return None + return DAYS[d % 7] if 0 <= d <= 7 else None + + def describe(expr): """A short reading of common schedules; the expression itself otherwise.""" e = SHORTHANDS.get((expr or "").strip().lower(), (expr or "").strip()) p = e.split() - if len(p) == 5 and p[0].isdigit() and p[1].isdigit() and p[2:] == ["*", "*", "*"]: - return f"every day at {int(p[1]):02d}:{int(p[0]):02d}" + if len(p) == 5 and p[0].isdigit() and p[1].isdigit() and p[3] == "*" and int(p[0]) < 60 and int(p[1]) < 24: + at = f"{int(p[1]):02d}:{int(p[0]):02d}" + dom, dow = p[2], p[4].lower() + if dom == "*" and dow == "*": + return f"every day at {at}" + if dom == "*" and dow in WEEKDAYS: + return f"every weekday at {at}" + if dom == "*" and dow in WEEKENDS: + return f"every Saturday and Sunday at {at}" + if dom == "*" and _one_day(dow): + return f"every {_one_day(dow)} at {at}" + if dow == "*" and dom.isdigit() and 1 <= int(dom) <= 31: + return f"at {at} on the {_ordinal(int(dom))} of every month" if len(p) == 5 and p[0].isdigit() and p[1:] == ["*", "*", "*", "*"]: return f"every hour at :{int(p[0]):02d}" if len(p) == 5 and p[0].startswith("*/") and p[1:] == ["*", "*", "*", "*"]: diff --git a/fastapi_backend/app/domain/timers.py b/fastapi_backend/app/domain/timers.py index 3c8b6f75e..5c060b6dd 100644 --- a/fastapi_backend/app/domain/timers.py +++ b/fastapi_backend/app/domain/timers.py @@ -10,6 +10,10 @@ that repeats (`again`: a schedule's next time) is re-armed in that same update, so a repeating timer is never lost; a process that dies while a handler runs leaves that one firing done (at most once, never twice). +What sets them: `schedule_automation` (an automation's schedule and at triggers; they fire it with a `clock.tick` +activity), `relative` (a relative trigger's time for one activity, moved when the activity's object moves), and +`upcoming` lists what an automation has waiting, in words. + While Lens was off: a timer due within automations.catch_up (1 hour by default) fires late, with `late: true` in its payload; an older one is missed (counted on its automation). A repeating one fires once, for its latest time in the window, and then waits for its next. Fired, failed, cancelled and missed rows are dropped after KEEP_DAYS (`tidy`, @@ -364,3 +368,334 @@ def tidy(db, cfg=None, now=None): cut = _iso(_now(now) - dt.timedelta(days=KEEP_DAYS)) db.q("DELETE timer WHERE status IN $s AND done_at < $c", s=list(ENDED), c=cut) return cut + + +# ---------- what an automation's clock triggers set ---------- +SCHEDULE = "schedule.next" # a schedule or at trigger: a clock.tick for its automation (re-armed for a schedule) +FIRE = "automation.fire" # fire an automation with the activity in the payload (relative triggers, joins) +CLOCK = {"type": "Application", "id": "lens:clock", "name": "Lens clock"} +PAST_SECONDS = 300 # a relative time further in the past than this is skipped +WEEK = ("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun") +MONTHS = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec") +UNIT_WORDS = {"s": "second", "m": "minute", "h": "hour", "d": "day"} + + +def _provided(module, fn): + """`fn` of a studio module built in its own step (automations, approvals), or None while it isn't there yet.""" + import importlib + + try: + m = importlib.import_module(f"{__package__}.{module}") + except ModuleNotFoundError as e: + if e.name != f"{__package__}.{module}": + raise + return None + return getattr(m, fn, None) + + +def _aid(automation): + aid = automation.get("id") if isinstance(automation, dict) else automation + if not isinstance(aid, int) or isinstance(aid, bool): + raise ValueError("name the automation by its id") + return aid + + +def _zone(name): + from . import schedule + + try: + return schedule.zone(name or "UTC") + except ValueError: + return dt.timezone.utc + + +def local(t, tz="UTC", now=None): + """A time in words in a time zone: "Fri 16 Oct at 07:00" (with the year when it isn't this year's).""" + d = _utc(t).astimezone(_zone(tz)) + year = f" {d.year}" if d.year != _now(now).astimezone(_zone(tz)).year else "" + return f"{WEEK[d.weekday()]} {d.day} {MONTHS[d.month - 1]}{year} at {d:%H:%M}" + + +def _at_of(t): + """An at trigger's moment, in UTC: its time, in its time zone when it names none.""" + d = dt.datetime.fromisoformat(str(t["at"]).replace("Z", "+00:00")) + return (d if d.tzinfo else d.replace(tzinfo=_zone(t.get("timezone")))).astimezone(dt.timezone.utc) + + +def _what(p): + """A schedule or at trigger's payload, in words: "every weekday at 07:00", "once".""" + from . import schedule + + return schedule.describe(p["cron"]) if p.get("cron") else "once" + + +def tick(automation, alias, at, timezone="UTC", cron=None, spaces=None, late=False): + """The activity a clock trigger fires its automation with (kind clock.tick, never stored): the moment it is for + (`at`), in its time zone, with the schedule (`cron`) when it repeats.""" + aid = _aid(automation) + when = _utc(at) + desc = _what({"cron": cron}) + spaces = sorted({int(s) for s in spaces or []}) + obj = store.clean( + { + "type": "Event", + "name": desc[:1].upper() + desc[1:], + "cron": cron, + "at": events.stamp(when), + "timezone": timezone or "UTC", + "local": local(when, timezone, when), + "description": desc, + "late": bool(late), + } + ) + return events.build( + f"tick-{aid}-{alias}-{int(when.timestamp())}", + "clock.tick", + actor=dict(CLOCK), + obj=obj, + summary=f"Lens clock: {obj['local']} ({desc}, {obj['timezone']})", + space=spaces[0] if len(spaces) == 1 else None, + spaces=spaces if len(spaces) > 1 else None, + source="clock", + pos=[events.stamp(when), f"tick-{aid}-{alias}"], + published=when, + ) + + +def _next_time(p, after): + from . import schedule + + return schedule.next_after(p["cron"], p.get("timezone") or "UTC", after) if p.get("cron") else None + + +@handler(SCHEDULE, again=_next_time) +def _tick(db, cfg, p): + act = tick(p["automation"], p["alias"], p["timer"]["at"], p.get("timezone"), p.get("cron"), p.get("spaces"), p.get("late")) + fire = _provided("automations", "fire") + if fire is None: + raise RuntimeError("automations aren't stored yet, so there is nothing to fire") + fire(db, cfg, int(p["automation"]), p["alias"], act) + + +@handler(FIRE) +def _fire_automation(db, cfg, p): + fire = _provided("automations", "fire") + if fire is None: + raise RuntimeError("automations aren't stored yet, so there is nothing to fire") + fire(db, cfg, int(p["automation"]), p["alias"], p.get("activity")) + + +def _waiting(db, aid): + return db.rows(f"SELECT {FIELDS} FROM timer WHERE automation = $a AND status = 'waiting' ORDER BY at", a=aid) + + +def schedule_automation(db, automation, now=None): + """Set an automation's clock timers from its triggers ({id, enabled, spaces, triggers}; M6 calls it when one is + saved, switched on or switched off): one per schedule trigger, at its next time, and one per at trigger still to + come. A timer a trigger still wants is left as it is (so one Lens missed can still catch up); one no trigger wants + any more is called off; waiting relative timers follow a changed field or offset. Switched off, every timer it has + is called off. The keys of its clock timers waiting.""" + aid = _aid(automation) + if not automation.get("enabled", True): + cancel_for(db, aid) + return [] + t0 = _now(now) + spaces = sorted({int(s) for s in automation.get("spaces") or []}) + triggers = [automation_spec.check_trigger(t, n) for n, t in enumerate(automation.get("triggers") or [], 1)] + have = {r["key"]: r for r in _waiting(db, aid)} + keep: dict[str, dict] = {} + rel = {} + for t in triggers: + if t["on"] == "relative": + rel[t["as"]] = t + continue + if t["on"] not in ("schedule", "at"): + continue + key = f"{'sched' if t['on'] == 'schedule' else 'at'}-{aid}-{t['as']}" + payload = {"automation": aid, "alias": t["as"], "timezone": t["timezone"], "spaces": spaces} + if t["on"] == "schedule": + from . import schedule + + payload["cron"] = t["cron"] + when = schedule.next_after(t["cron"], t["timezone"], t0) + else: + payload["at"] = t["at"] + when = _at_of(t) + old = have.get(key) + if old and old.get("kind") == SCHEDULE and old.get("payload") == payload and (t["on"] == "schedule" or old["at"] == _iso(when)): + keep[key] = _view(old) + elif when is not None and (t["on"] == "schedule" or when > t0): + keep[key] = set(db, key, when, SCHEDULE, payload, aid) + for key, r in have.items(): + p = r.get("payload") or {} + if r.get("kind") == SCHEDULE and key not in keep: + _end(db, r, "cancelled", "its trigger changed") + elif r.get("kind") == FIRE and key.startswith(f"rel-{aid}-") and p.get("alias") is not None: + t = rel.get(p["alias"]) + if t is None: + _end(db, r, "cancelled", "its trigger changed") + elif (t["field"], t["offset"]) != (p.get("field"), p.get("offset")) and isinstance(p.get("activity"), dict): + relative(db, aid, p["alias"], p["activity"], t["field"], t["offset"], now=t0) + return sorted(keep) + + +def _field(a, path): + v = a + for k in str(path).split("."): + if isinstance(v, dict): + v = v.get(k) + elif isinstance(v, list) and k.isdigit() and int(k) < len(v): + v = v[int(k)] + else: + return None + return v + + +def _time_of(v): + """A time an activity holds (ISO 8601, a date meaning its midnight in UTC), in UTC; None when it isn't one.""" + if isinstance(v, str) and re.match(r"^\d{4}-\d{2}-\d{2}$", v.strip()): + v = v.strip() + "T00:00:00+00:00" + try: + return _utc(v) + except (TypeError, ValueError): + return None + + +def _offset_words(offset): + n = automation_spec.check_duration(offset, back=True) + if n == 0: + return "when" + unit = next(u for u in ("d", "h", "m", "s") if abs(n) % automation_spec.UNITS[u] == 0) + k = abs(n) // automation_spec.UNITS[unit] + return f"{k} {UNIT_WORDS[unit]}{'' if k == 1 else 's'} {'before' if n < 0 else 'after'}" + + +def relative(db, automation, alias, activity, field, offset="0s", now=None): + """Set the timer of a relative trigger for one activity (M6 calls it when a matching activity comes): due at the + time in its `field` plus `offset` (-30m: half an hour before), to fire the automation with that activity. One + timer per automation, trigger and object (`rel---`), so an event that moves + (calendar_event.changed, about the same object) moves its timer rather than adding one. A time more than + PAST_SECONDS in the past is skipped (and a timer it had is called off). {key, at, set, note}.""" + aid = _aid(automation) + if not isinstance(activity, dict) or not isinstance(activity.get("id"), str): + raise ValueError("a relative trigger counts from an activity") + ref = (activity.get("object") or {}).get("id") or activity["id"] + key = f"rel-{aid}-{alias}-{ref}" + _check_key(key) + seconds = automation_spec.check_duration(offset or "0s", back=True, what=f"trigger {alias}'s offset") + base = _time_of(_field(activity, field)) + if base is None: + note = f"trigger {alias}: {activity['id']} has no time at {field}, so nothing was set" + log.info("automation %s: %s", aid, note) + return {"key": key, "at": None, "set": False, "note": note} + when = base + dt.timedelta(seconds=seconds) + t0 = _now(now) + if when < t0 - dt.timedelta(seconds=PAST_SECONDS): + cancel(db, key, why="its time had passed") + note = f"trigger {alias}: {_iso(when)} for {activity['id']} had already passed, so it was skipped" + log.info("automation %s: %s", aid, note) + return {"key": key, "at": _iso(when), "set": False, "note": note} + payload = {"automation": aid, "alias": alias, "activity": activity, "field": field, "offset": offset or "0s"} + set(db, key, when, FIRE, payload, aid) + return {"key": key, "at": _iso(when), "set": True, "note": None} + + +# ---------- what is coming ---------- +def _describe(r, now): + p = r.get("payload") or {} + alias = p.get("alias") + if r["kind"] == SCHEDULE: + tz = p.get("timezone") or "UTC" + return f"{_what(p)[:1].upper()}{_what(p)[1:]}: next on {local(r['at'], tz, now)} ({tz})", False + if r["kind"] == FIRE and isinstance(p.get("activity"), dict) and p.get("field"): + a = p["activity"] + try: + title = (events.field_at(a.get("kind"), p["field"]) or {}).get("title") + except (KeyError, ValueError): + title = None + name = (a.get("object") or {}).get("name") or a.get("summary") or a["id"] + what = f"{_offset_words(p.get('offset') or '0s')} “{str(name)[:120]}” {(title or p['field']).lower()}" + return f"{what[:1].upper()}{what[1:]}: on {local(r['at'], 'UTC', now)} (UTC)", True + alias_text = f" of trigger {alias}" if alias else "" + return f"{r['kind']}{alias_text}: on {local(r['at'], 'UTC', now)} (UTC)", False + + +def upcoming(db, automation, n=10, now=None): + """An automation's waiting timers, soonest first (M6 serves them at GET /api/v1/automations/{id}/upcoming): + [{key, at, kind, trigger, node, description, untrusted}]. `untrusted` says the description quotes outside text + (an event's title).""" + t0 = _now(now) + rows = db.rows( + f"SELECT {FIELDS} FROM timer WHERE automation = $a AND status = 'waiting' ORDER BY at LIMIT $n", + a=_aid(automation), + n=max(1, min(int(n), 100)), + ) + out = [] + for r in rows: + p = r.get("payload") or {} + text, outside = _describe(r, t0) + out.append( + { + "key": r["key"], + "at": r["at"], + "kind": r["kind"], + "trigger": p.get("alias"), + "node": (p.get("intent") or {}).get("node") if isinstance(p.get("intent"), dict) else None, + "description": text, + "untrusted": outside, + } + ) + return out + + +def clock_state(db, automation, now=None): + """How each schedule and at trigger of an automation ({id, enabled, triggers}) stands, for its page: {alias: + {status, at, description}}, status waiting (at: when next), done (an at trigger whose time came), failed or + missed (its last time), or off (switched off, or not set).""" + aid = _aid(automation) + t0 = _now(now) + out = {} + for n, t in enumerate(automation.get("triggers") or [], 1): + t = automation_spec.check_trigger(t, n) + if t["on"] not in ("schedule", "at"): + continue + r = get(db, f"{'sched' if t['on'] == 'schedule' else 'at'}-{aid}-{t['as']}") + status = (r or {}).get("status") + if not automation.get("enabled", True): + state = "off" + elif status == "waiting": + state = "waiting" + elif status in ("missed", "failed"): + state = status + elif t["on"] == "at" and _at_of(t) <= t0: + state = "done" + else: + state = "off" + at = r["at"] if state == "waiting" and r else (_iso(_at_of(t)) if t["on"] == "at" else None) + out[t["as"]] = {"status": state, "at": at, "description": _what({"cron": t.get("cron")})} + return out + + +CLOCK_KIND = { + "label": "Time came", + "source": "clock", + "as_type": "Arrive", + "object_type": "Event", + "fields": { + "actor": {"type": "object", "properties": {"name": {"type": "string", "title": "Clock"}}}, + "object": { + "type": "object", + "properties": { + "at": {"type": "string", "title": "Time", "format": "date-time"}, + "cron": {"type": "string", "title": "Schedule"}, + "timezone": {"type": "string", "title": "Time zone"}, + "local": {"type": "string", "title": "Time there"}, + "description": {"type": "string", "title": "When"}, + "late": {"type": "boolean", "title": "Late (Lens was off)"}, + }, + }, + }, + "noisy": True, +} +events.kind("clock.tick", **CLOCK_KIND) # first without its sample, which is built with the kind +events.kind("clock.tick", **CLOCK_KIND, sample=tick(4, "morning", "2026-10-16T06:00:00Z", "Europe/London", "0 7 * * 1-5", [3])) diff --git a/fastapi_backend/tests/domain/test_timer_triggers.py b/fastapi_backend/tests/domain/test_timer_triggers.py new file mode 100644 index 000000000..086ba9471 --- /dev/null +++ b/fastapi_backend/tests/domain/test_timer_triggers.py @@ -0,0 +1,192 @@ +"""The clock as a trigger: schedule triggers fire at their next time and re-arm (DST as schedule.py has it), at +triggers fire once, relative timers move with their event and skip past times, and upcoming says what's coming.""" + +from __future__ import annotations + +import datetime as dt + +import pytest + +from app.domain import events, schedule, store, timers + +UTC = dt.UTC + + +def t(s): + return dt.datetime.fromisoformat(s).replace(tzinfo=UTC) + + +@pytest.fixture +def fired(monkeypatch): + """automations.fire, as M6 provides it: records each (automation, alias, activity).""" + got = [] + timers._idle["until"] = 0.0 + real = timers._provided + + def provided(module, fn): + if (module, fn) == ("automations", "fire"): + return lambda db, cfg, aid, alias, activity, **kw: got.append((aid, alias, activity)) + return real(module, fn) + + monkeypatch.setattr(timers, "_provided", provided) + return got + + +def auto(*triggers, aid=4, enabled=True, spaces=(3,)): + return {"id": aid, "enabled": enabled, "spaces": list(spaces), "triggers": list(triggers)} + + +MORNING = {"as": "morning", "on": "schedule", "cron": "0 7 * * 1-5", "timezone": "Europe/London"} +SOON = {"as": "soon", "on": "relative", "kinds": ["calendar_event.added"], "field": "object.startTime", "offset": "-30m"} + + +def event(start, kind="calendar_event.added", aid="create-recording-9"): + a = events.kind_info(kind)["sample"] + return {**a, "id": aid, "object": {**a["object"], "id": "lens:recording/9", "startTime": start}} + + +def test_a_schedule_trigger_fires_at_its_next_time_and_re_arms(db, cfg, fired): + assert timers.schedule_automation(db, auto(MORNING), now=t("2026-10-15T12:00:00")) == ["sched-4-morning"] + assert timers.get(db, "sched-4-morning")["at"] == "2026-10-16T06:00:00+00:00" # 07:00 in London is 06:00 UTC + assert timers.due(db, cfg, now=t("2026-10-16T05:59:00")) == 0 + assert timers.due(db, cfg, now=t("2026-10-16T06:00:03")) == 1 + [(aid, alias, act)] = fired + assert (aid, alias) == (4, "morning") and events.check_activity(act) + assert act["kind"] == "clock.tick" and act["actor"] == timers.CLOCK and act["space"] == 3 + assert act["object"]["at"] == "2026-10-16T06:00:00.000Z" and act["object"]["local"] == "Fri 16 Oct at 07:00" + assert act["object"]["description"] == "every weekday at 07:00" and act["object"]["late"] is False + assert act["published"] == act["object"]["at"] and act["id"] == "tick-4-morning-1792130400" + assert timers.get(db, "sched-4-morning")["at"] == "2026-10-19T06:00:00+00:00" # Friday, then Monday + assert timers.due(db, cfg, now=t("2026-10-17T06:00:00")) == 0 + + +def test_schedules_follow_dst_as_schedule_py_does(db, cfg, fired): + gap = {"as": "early", "on": "schedule", "cron": "30 2 * * *", "timezone": "Europe/Stockholm"} + repeat = {"as": "night", "on": "schedule", "cron": "30 1 * * *", "timezone": "America/New_York"} + timers.schedule_automation(db, auto(gap, aid=5), now=t("2027-03-27T12:00:00")) + timers.schedule_automation(db, auto(repeat, aid=6), now=t("2026-10-31T12:00:00")) + # 02:30 doesn't happen in Stockholm that night: it runs when the clock gets past the gap (03:00 = 01:00 UTC) + assert timers.get(db, "sched-5-early")["at"] == "2027-03-28T01:00:00+00:00" + # 01:30 happens twice in New York on 1 November: it runs once, at the first + assert timers.get(db, "sched-6-night")["at"] == "2026-11-01T05:30:00+00:00" + assert timers.due(db, cfg, now=t("2026-11-01T05:30:01")) == 1 + assert timers.due(db, cfg, now=t("2026-11-01T06:30:01")) == 0 + assert timers.get(db, "sched-6-night")["at"] == _iso(schedule.next_after("30 1 * * *", "America/New_York", t("2026-11-01T05:31:00"))) + + +def _iso(d): + return d.isoformat(timespec="seconds") + + +def test_saving_again_keeps_changes_and_calls_off(db, cfg, fired): + at = {"as": "once", "on": "at", "at": "2026-10-20T09:00", "timezone": "Europe/London"} + a = auto(MORNING, at, SOON) + noon = t("2026-10-15T12:00:00") + assert timers.schedule_automation(db, a, now=noon) == ["at-4-once", "sched-4-morning"] + assert timers.get(db, "at-4-once")["at"] == "2026-10-20T08:00:00+00:00" + timers.relative(db, 4, "soon", event("2026-10-20T18:00:00+01:00"), "object.startTime", "-30m", now=noon) + # Lens off past 07:00 Friday: saving again then leaves the timer due, so it can still catch up + timers.schedule_automation(db, a, now=t("2026-10-16T06:30:00")) + assert timers.get(db, "sched-4-morning")["at"] == "2026-10-16T06:00:00+00:00" + assert timers.due(db, cfg, now=t("2026-10-16T06:30:00")) == 1 and fired[0][2]["object"]["late"] is True + # a new schedule, the at trigger dropped, the relative offset changed: the timers follow + later = {**MORNING, "cron": "0 8 * * *"} + timers.schedule_automation(db, auto(later, {**SOON, "offset": "-1h"}), now=t("2026-10-16T06:45:00")) + assert timers.get(db, "sched-4-morning")["at"] == "2026-10-16T07:00:00+00:00" # 08:00 London + assert timers.get(db, "at-4-once")["status"] == "cancelled" + assert timers.get(db, "rel-4-soon-lens:recording/9")["at"] == "2026-10-20T16:00:00+00:00" + # the relative trigger removed: its timers go; switched off: every timer goes + timers.schedule_automation(db, auto(later), now=t("2026-10-16T07:00:00")) + assert timers.get(db, "rel-4-soon-lens:recording/9")["status"] == "cancelled" + assert timers.schedule_automation(db, auto(later, enabled=False)) == [] + assert timers.get(db, "sched-4-morning")["status"] == "cancelled" and timers.upcoming(db, 4) == [] + + +def test_an_at_trigger_fires_once_then_reads_done(db, cfg, fired): + at = {"as": "once", "on": "at", "at": "2026-10-20T09:00", "timezone": "Europe/London"} + a = auto(at) + timers.schedule_automation(db, a, now=t("2026-10-15T12:00:00")) + assert timers.clock_state(db, a, now=t("2026-10-15T12:00:00"))["once"] == { + "status": "waiting", + "at": "2026-10-20T08:00:00+00:00", + "description": "once", + } + assert timers.due(db, cfg, now=t("2026-10-20T08:00:01")) == 1 and fired[0][2]["object"]["description"] == "once" + assert timers.get(db, "at-4-once")["status"] == "fired" + assert timers.schedule_automation(db, a, now=t("2026-10-20T09:00:00")) == [] # saved again afterwards: not re-armed + assert timers.get(db, "at-4-once")["status"] == "fired" + assert timers.clock_state(db, a, now=t("2026-10-20T09:00:00"))["once"]["status"] == "done" + assert timers.clock_state(db, {**a, "enabled": False})["once"]["status"] == "off" + # one already past when it's saved is never set, and reads done + past = auto({**at, "as": "gone", "at": "2026-10-01T09:00:00+00:00"}, aid=9) + assert timers.schedule_automation(db, past, now=t("2026-10-15T12:00:00")) == [] + assert timers.clock_state(db, past, now=t("2026-10-15T12:00:00"))["gone"]["status"] == "done" + + +def test_a_relative_timer_moves_when_its_event_moves(db, cfg, fired): + noon = t("2026-10-15T12:00:00") + got = timers.relative(db, 4, "soon", event("2026-10-20T18:00:00+01:00"), "object.startTime", "-30m", now=noon) + assert got == {"key": "rel-4-soon-lens:recording/9", "at": "2026-10-20T16:30:00+00:00", "set": True, "note": None} + moved = event("2026-10-21T18:00:00+01:00", kind="calendar_event.changed", aid="log-13") + timers.relative(db, 4, "soon", moved, "object.startTime", "-30m", now=noon) + assert db.one("SELECT count() AS n FROM timer GROUP ALL")["n"] == 1 # one timer per event, at its new time + assert timers.due(db, cfg, now=t("2026-10-20T16:31:00")) == 0 + assert timers.due(db, cfg, now=t("2026-10-21T16:30:02")) == 1 + [(aid, alias, act)] = fired + assert (aid, alias, act["id"]) == (4, "soon", "log-13") # fired with the activity that set it + # a date is its midnight in UTC; a time a few minutes past is due now; further past is skipped, with a note + assert timers.relative(db, 4, "soon", event("2026-11-02"), "object.startTime", "0s", now=noon)["at"] == "2026-11-02T00:00:00+00:00" + assert timers.relative(db, 4, "soon", event("2026-10-15T12:28:00+00:00"), "object.startTime", "-30m", now=noon)["set"] + skipped = timers.relative(db, 4, "soon", event("2026-10-15T12:20:00+00:00"), "object.startTime", "-30m", now=noon) + assert skipped["set"] is False and "had already passed" in skipped["note"] + assert timers.get(db, "rel-4-soon-lens:recording/9")["status"] == "cancelled" # the timer it had is called off + none = timers.relative(db, 4, "soon", event(None), "object.startTime", "-30m", now=noon) + assert none["set"] is False and "has no time at object.startTime" in none["note"] + with pytest.raises(ValueError, match="offset"): + timers.relative(db, 4, "soon", event("2026-10-20T18:00:00Z"), "object.startTime", "soon", now=noon) + + +def test_upcoming_says_what_is_coming(db, cfg, fired): + noon = t("2026-10-15T12:00:00") + timers.schedule_automation(db, auto(MORNING, {"as": "once", "on": "at", "at": "2027-01-04T09:00:00Z"}), now=noon) + timers.relative(db, 4, "soon", event("2026-10-20T18:00:00+01:00"), "object.startTime", "-30m", now=noon) + got = timers.upcoming(db, 4, now=noon) + assert [(u["key"], u["trigger"], u["untrusted"]) for u in got] == [ + ("sched-4-morning", "morning", False), + ("rel-4-soon-lens:recording/9", "soon", True), + ("at-4-once", "once", False), + ] + assert [u["description"] for u in got] == [ + "Every weekday at 07:00: next on Fri 16 Oct at 07:00 (Europe/London)", + "30 minutes before “Parents' evening” starts: on Tue 20 Oct at 16:30 (UTC)", + "Once: next on Mon 4 Jan 2027 at 09:00 (UTC)", + ] + assert len(timers.upcoming(db, 4, n=1, now=noon)) == 1 and timers.upcoming(db, 5) == [] + + +def test_before_automations_are_stored_a_schedule_still_re_arms(db, cfg): + timers._idle["until"] = 0.0 + timers.schedule_automation(db, auto(MORNING), now=t("2026-10-15T12:00:00")) + assert timers.due(db, cfg, now=t("2026-10-16T06:00:00")) == 1 + row = timers.get(db, "sched-4-morning") + assert row["status"] == "waiting" and "aren't stored yet" in row["last"]["error"] + + +def test_the_clock_is_a_kind_that_is_never_stored(db): + k = events.kind_info("clock.tick") + assert k["source"] == "clock" and k["noisy"] and k["type"] == "Arrive" + assert events.field_at("clock.tick", "object.at")["title"] == "Time" + assert "clock" not in {s.name for s in events.sources()} # nothing reads it from the database + assert store.R("timer", "x") # the table is in the schema + assert db.rows("INFO FOR TABLE timer") + + +def test_schedules_in_words(): + assert schedule.describe("0 7 * * 1-5") == "every weekday at 07:00" + assert schedule.describe("30 8 * * sat,sun") == "every Saturday and Sunday at 08:30" + assert schedule.describe("0 9 * * mon") == "every Monday at 09:00" + assert schedule.describe("0 9 * * 7") == "every Sunday at 09:00" + assert schedule.describe("0 9 20 * *") == "at 09:00 on the 20th of every month" + assert schedule.describe("0 9 22 * *") == "at 09:00 on the 22nd of every month" + assert schedule.describe("0 9 11 * *") == "at 09:00 on the 11th of every month" + assert schedule.describe("0 9 * * 1,3") == "0 9 * * 1,3"