extra_fire.py 4.7 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495
  1. """Manual runs are EXTRA fires: a run-now (``cronjob run``, ``hermes cron run``, dashboard Run,
  2. gateway-forwarded ``trigger_job``) leaves the job's pending scheduled occurrence and its
  3. ``repeat`` budget alone. Without this a test-fire of an ``in 30m`` reminder completed the
  4. one-shot and the real reminder never fired; a recurring ``repeat.times=N`` job lost one of N.
  5. The claim (``claim_job_for_fire``) decides once, under the jobs lock, and stamps the pending
  6. slot on ``fire_claim["extra_slot"]``; every later step (``claim_dispatch``, ``mark_job_run``)
  7. reads that stamp, so a crash between claim and completion leaves ``next_run_at`` on the slot.
  8. """
  9. from datetime import datetime
  10. from typing import Any, Optional
  11. RESTORE_KEY = "manual_run_restore_at" # trigger_job's overwritten next_run_at
  12. _CLAIM_KEY = "extra_slot"
  13. def queued(job: dict[str, Any]) -> bool:
  14. """A ``trigger_job`` run-now not claimed yet: ``next_run_at`` still holds its "now" stamp and
  15. the overwritten slot waits in RESTORE_KEY. This pair IS the durable manual intent, so the tick's
  16. pre-run advance leaves such a job alone (the claim restores the slot and owns the advance)."""
  17. marker = job.get("manual_run_at")
  18. return marker is not None and marker == job.get("next_run_at") and RESTORE_KEY in job
  19. def restore_target(job: dict[str, Any]) -> Optional[str]:
  20. """The slot a new ``trigger_job`` must save: a repeated trigger before the claim keeps the
  21. first trigger's saved slot, never that trigger's own "now"."""
  22. return job.get(RESTORE_KEY) if queued(job) else job.get("next_run_at")
  23. def _future_slot(value: Any, now: datetime) -> Optional[str]:
  24. from cron.jobs import _parse_aware
  25. parsed = _parse_aware(value) if isinstance(value, str) else None
  26. return value if parsed is not None and parsed > now else None
  27. def pending_slot(job: dict[str, Any], now: datetime, manual_fire: bool) -> Optional[str]:
  28. """The still-future scheduled instant an explicit run-now must leave in place, or None when
  29. this fire IS the scheduled occurrence (a tick, a provider fire, or a run-now once the slot
  30. is already due: nothing to preserve, no double fire)."""
  31. stored = job.get("next_run_at")
  32. if job.get("manual_run_at") == stored: # trigger_job replaced next_run_at with "now"
  33. return _future_slot(job.get(RESTORE_KEY), now)
  34. return _future_slot(stored, now) if manual_fire else None
  35. def stamp_claim(job: dict[str, Any], slot: str) -> None:
  36. """Mark the fresh ``fire_claim`` as an extra fire and put ``next_run_at`` back on *slot* in the
  37. same save, so the scheduled occurrence survives a crash before ``mark_job_run``."""
  38. job["fire_claim"][_CLAIM_KEY] = slot
  39. job["next_run_at"] = slot
  40. job.pop(RESTORE_KEY, None)
  41. def is_extra(job: dict[str, Any]) -> bool:
  42. claim = job.get("fire_claim")
  43. return isinstance(claim, dict) and bool(claim.get(_CLAIM_KEY))
  44. _MARKERS = ("manual_run_at", RESTORE_KEY, "manual_run_prompt")
  45. def held_markers(job: dict[str, Any]) -> dict[str, Any]:
  46. """The run-now markers of a ``trigger_job`` that landed while this extra fire was in flight: the
  47. claim popped RESTORE_KEY in its own save, so a ``queued`` job at completion was triggered
  48. after the claim (``fire_claim.at`` cannot tell: the heartbeat refreshes it). That trigger is
  49. its own run-now, so the caller puts these back after the outcome clears the markers."""
  50. return {key: job[key] for key in _MARKERS if key in job} if queued(job) else {}
  51. def reschedule(job: dict[str, Any], at: str) -> None:
  52. """Move ``next_run_at`` from a failure-path planner (the quota hold). A queued
  53. run-now's marker moves with it: the run-now is delayed, not turned into a scheduled fire that
  54. would spend a repeat run and drop the slot saved in RESTORE_KEY."""
  55. if queued(job):
  56. job["manual_run_at"] = at
  57. job["next_run_at"] = at
  58. def settle(job: dict[str, Any], now: str) -> None:
  59. """After an extra fire: ``repeat.completed`` untouched, the job keeps its pending slot, and a
  60. run-now queued during the run (``queued``) is left for its own claim. A slot that passed while
  61. the run was in flight: a one-shot fires at once; a recurring job DROPS it and takes its next
  62. natural occurrence, as on a scheduled run (the tick's pre-run advance has usually moved it
  63. already, and keeping it due would make every tick during the run log a lost-claim fire)."""
  64. from cron.jobs import compute_next_run
  65. if queued(job) or _future_slot(job.get("next_run_at"), datetime.fromisoformat(now)):
  66. return
  67. if job.get("schedule", {}).get("kind") == "once":
  68. job["next_run_at"] = now
  69. else:
  70. job["next_run_at"] = compute_next_run(
  71. job["schedule"], now, timezone=job.get("timezone")) or job.get("next_run_at")