jobs_invariants.py 3.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778
  1. """Execution-mode invariants every cron job definition must satisfy.
  2. ``create_job`` and ``update_job`` (``cron/jobs.py``) both run these, so an update cannot
  3. bypass a rule the create door enforces.
  4. """
  5. from typing import Optional
  6. from hermes_constants import display_hermes_home
  7. NO_AGENT_WITHOUT_SCRIPT_ERROR = (
  8. "no_agent=True requires a script — with no agent and no script "
  9. "there is nothing for the job to run."
  10. )
  11. SCRIPT_IS_COMMAND_LINE_ERROR = (
  12. "script must name a file under {scripts_dir} (e.g. 'watchdog.sh'), not a shell command line: "
  13. "{script!r} has no such file. Write the command into a script there and pass its filename."
  14. )
  15. def _validate_job_mode_invariants(
  16. monitor_script: Optional[str],
  17. monitor_url: Optional[str],
  18. no_agent: bool,
  19. script: Optional[str],
  20. ) -> None:
  21. """Execution-mode invariants shared by create_job and update_job (no bypass via the update
  22. door)."""
  23. if monitor_script and monitor_url:
  24. raise ValueError(
  25. "monitor_script and monitor_url are mutually exclusive — a job "
  26. "can only have one monitor source.")
  27. if (monitor_script or monitor_url) and no_agent:
  28. raise ValueError(
  29. "monitor_script/monitor_url cannot be combined with no_agent=True — "
  30. "the whole point of a monitor job is to suppress or wake the AGENT "
  31. "based on source changes. Use a plain no_agent script job instead.")
  32. if no_agent and not script:
  33. raise ValueError(NO_AGENT_WITHOUT_SCRIPT_ERROR)
  34. if script and _script_is_command_line(script):
  35. raise ValueError(SCRIPT_IS_COMMAND_LINE_ERROR.format(
  36. scripts_dir=display_hermes_home() + "/scripts/", script=script))
  37. def validate_schedule_knobs(
  38. schedule: dict, timezone: Optional[str], grace_minutes: Optional[int],
  39. ) -> None:
  40. """Per-job schedule knobs (``timezone``/``grace_minutes``) are validated at BOTH doors —
  41. ``create_job`` and ``update_job`` — so an update cannot store a schedule knob a create
  42. would reject.
  43. Raises ValueError for an unknown IANA zone, and for ``grace_minutes`` on a schedule that has
  44. no wall clock to be late for (``once``/``interval``): the catch-up window only means
  45. something to a recurring cron cadence, so accepting it silently would suggest an effect it
  46. cannot have.
  47. """
  48. from cron.jobs_time import normalize_grace_minutes, normalize_timezone
  49. normalize_timezone(timezone)
  50. minutes = normalize_grace_minutes(grace_minutes)
  51. if minutes is None:
  52. return
  53. kind = (schedule or {}).get("kind")
  54. if kind != "cron":
  55. raise ValueError(
  56. f"grace_minutes only applies to cron schedules (a fixed wall clock that can be "
  57. f"missed); this job's schedule kind is {kind!r}.")
  58. def _script_is_command_line(script: str) -> bool:
  59. """A ``script`` with whitespace that resolves to no file is a command line (``echo hi``),
  60. not a path; run every tick it would deliver "Script not found" as the payload. A plain
  61. missing filename stays creatable (``hermes cron doctor`` reports it)."""
  62. if not any(ch.isspace() for ch in script.strip()):
  63. return False
  64. from cron.lifecycle_guard import _resolve_script_path
  65. path = _resolve_script_path(script)
  66. return path is None or not path.is_file()