add cron-based schedule trigger

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

@@ -2,9 +2,17 @@
 
 from __future__ import annotations
 
+from .cron import InvalidCronError, compute_next_fire_at, validate_cron
+from .dispatch import dispatch_schedule_run
 from .params import ScheduleTriggerParams
 
-__all__ = ["ScheduleTriggerParams"]
+__all__ = [
+    "InvalidCronError",
+    "ScheduleTriggerParams",
+    "compute_next_fire_at",
+    "dispatch_schedule_run",
+    "validate_cron",
+]
 
 # Side-effect: register on the triggers store.
 from . import definition  # noqa: E402, F401

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

@@ -0,0 +1,37 @@
+"""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/schedule/dispatch.py

@@ -0,0 +1,48 @@
+"""Schedule dispatch adapter: load + guard, then call generic dispatch."""
+
+from __future__ import annotations
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.automations.dispatch import DispatchError, dispatch_run
+from app.automations.persistence.enums.automation_status import AutomationStatus
+from app.automations.persistence.models.automation import Automation
+from app.automations.persistence.models.run import AutomationRun
+from app.automations.persistence.models.trigger import AutomationTrigger
+
+
+async def dispatch_schedule_run(
+    *,
+    session: AsyncSession,
+    trigger: AutomationTrigger,
+) -> AutomationRun:
+    """Fire one scheduled run for ``trigger``.
+
+    The caller (the schedule tick) is responsible for selecting due triggers
+    and advancing ``next_fire_at`` / ``last_fired_at`` before invoking this.
+    """
+    automation = await _load_automation(session, trigger.automation_id)
+    if automation is None:
+        raise DispatchError(
+            f"automation {trigger.automation_id} not found for trigger {trigger.id}"
+        )
+
+    if automation.status != AutomationStatus.ACTIVE:
+        raise DispatchError(
+            f"automation {trigger.automation_id} is {automation.status.value}, not active"
+        )
+
+    return await dispatch_run(
+        session=session,
+        automation=automation,
+        trigger=trigger,
+        payload=None,
+    )
+
+
+async def _load_automation(
+    session: AsyncSession, automation_id: int
+) -> Automation | None:
+    stmt = select(Automation).where(Automation.id == automation_id)
+    return (await session.execute(stmt)).scalar_one_or_none()

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

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from .cron import InvalidCronError, validate_cron
 
 
 class ScheduleTriggerParams(BaseModel):
@@ -10,3 +12,11 @@ class ScheduleTriggerParams(BaseModel):
 
     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