refactor(automations): move schedule trigger into builtin package

surfsense_backend/app/automations/triggers/builtin/__init__.py

@@ -0,0 +1,5 @@
+"""Built-in trigger types — each in its own subpackage, self-registering at import."""
+
+from __future__ import annotations
+
+from . import event, schedule  # noqa: F401

surfsense_backend/app/automations/triggers/builtin/schedule/__init__.py

@@ -0,0 +1,16 @@
+"""``schedule`` trigger: fired on a cron schedule in a given timezone."""
+
+from __future__ import annotations
+
+from .cron import InvalidCronError, compute_next_fire_at, validate_cron
+from .params import ScheduleTriggerParams
+
+__all__ = [
+    "InvalidCronError",
+    "ScheduleTriggerParams",
+    "compute_next_fire_at",
+    "validate_cron",
+]
+
+# Side-effect: register on the triggers store.
+from . import definition  # noqa: F401

surfsense_backend/app/automations/triggers/builtin/schedule/cron.py

@@ -0,0 +1,41 @@
+"""Cron math for the ``schedule`` trigger: validate + advance ``next_fire_at``."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from croniter import CroniterBadCronError, croniter
+
+
+class InvalidCronError(ValueError):
+    """Raised when a cron expression or timezone fails validation."""
+
+
+def validate_cron(cron: str, timezone: str) -> None:
+    """Raise ``InvalidCronError`` if cron or timezone are unusable."""
+    try:
+        ZoneInfo(timezone)
+    except ZoneInfoNotFoundError as exc:
+        raise InvalidCronError(f"unknown timezone {timezone!r}") from exc
+
+    try:
+        croniter(cron)
+    except (CroniterBadCronError, ValueError) as exc:
+        raise InvalidCronError(f"invalid cron {cron!r}: {exc}") from exc
+
+
+def compute_next_fire_at(cron: str, timezone: str, *, after: datetime) -> datetime:
+    """Return the next moment matching ``cron`` in ``timezone`` strictly after ``after``.
+
+    The result is normalized to UTC for storage. ``after`` is converted into the
+    given timezone before evaluation so DST and IANA rules apply correctly.
+    """
+    tz = ZoneInfo(timezone)
+    base = (
+        after.astimezone(tz)
+        if after.tzinfo
+        else after.replace(tzinfo=UTC).astimezone(tz)
+    )
+    nxt: datetime = croniter(cron, base).get_next(datetime)
+    return nxt.astimezone(UTC)

surfsense_backend/app/automations/triggers/builtin/schedule/definition.py

@@ -0,0 +1,16 @@
+"""``schedule`` ``TriggerDefinition`` registration."""
+
+from __future__ import annotations
+
+from app.automations.triggers.store import register_trigger
+from app.automations.triggers.types import TriggerDefinition
+
+from .params import ScheduleTriggerParams
+
+SCHEDULE_TRIGGER = TriggerDefinition(
+    type="schedule",
+    description="Fire on a cron schedule in a given timezone.",
+    params_model=ScheduleTriggerParams,
+)
+
+register_trigger(SCHEDULE_TRIGGER)

surfsense_backend/app/automations/triggers/builtin/schedule/params.py

@@ -0,0 +1,24 @@
+"""``ScheduleTriggerParams`` — params for the ``schedule`` trigger type."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from .cron import InvalidCronError, validate_cron
+
+
+class ScheduleTriggerParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    cron: str = Field(
+        ..., description="Five-field cron expression.", examples=["0 9 * * 1-5"]
+    )
+    timezone: str = Field(..., description="IANA timezone.", examples=["Africa/Kigali"])
+
+    @model_validator(mode="after")
+    def _validate(self) -> ScheduleTriggerParams:
+        try:
+            validate_cron(self.cron, self.timezone)
+        except InvalidCronError as exc:
+            raise ValueError(str(exc)) from exc
+        return self