Recurring jobs across daylight-saving changes
A recurring local-time schedule needs a timezone and explicit policies for clock gaps, repeated times, missed runs, and schedule edits. Persist the intended calendar occurrence separately from its resolved UTC instant, and make retries reuse the same occurrence identity.
Inside this article 5 sections +
“Run every day at 02:30” is incomplete until the application knows whose calendar applies and what to do when that local time does not exist or occurs twice. A fixed delay of twenty-four hours expresses a different intention. The difference appears at clock changes, but it begins in the product requirement.
Use a customer account that requests a daily inventory summary. The customer expects one summary for each local business date. That expectation is not necessarily satisfied by running at a fixed UTC hour, adding twenty-four hours to the previous execution, or accepting a scheduler library's defaults without checking them.
Store the schedule as business intent
Record the recurrence rule, an IANA timezone identifier, the intended local time, and the business policy for unusual dates. A fixed offset such as UTC+1 does not contain the zone's seasonal or historical rules. Store resolved UTC instants for execution, while preserving enough local-calendar context to explain why each instant was chosen.
Distinguish calendar recurrence from elapsed intervals. “Every six hours after activation” can reasonably use elapsed time. “At the start of each local business day” depends on calendar rules. A scheduler may support both, but the product must choose the meaning before implementation selects an API.
Execution time and reporting period are also separate. If the summary runs late, it may still need to summarize the original local date. Deriving the period from the worker's current clock can accidentally include the wrong day after a delay or replay. Persist the intended reporting period with the occurrence.
Choose a policy for missing and repeated times
| Calendar condition | Chosen product behavior | Occurrence identity |
|---|---|---|
| One valid local time | Run at its resolved instant | Schedule revision + local reporting date |
| Requested time falls in a gap | Shift to the first approved valid time after the gap | Keep the original reporting date |
| Requested time occurs twice | Choose one documented offset | One identity for the daily summary |
| Worker is unavailable at the chosen instant | Apply the separate missed-run policy | Reuse the original identity if execution remains eligible |
A timezone gap has no valid instant for some local times. Decide whether to skip the occurrence, shift it, or reject that scheduling choice. For a daily summary, shifting may preserve the customer's expectation of one report per date. For a market-sensitive operation, a shift may be unacceptable. The correct rule depends on the business consequence.
An overlap gives some local times two possible offsets and therefore two instants. Choose the earlier offset, the later offset, or both. If both executions are intentional, the identity needs to distinguish them. If the promise is one report per day, generating an identity from the execution timestamp alone can accidentally authorize two reports.
This Python 3.9+ fixture requires IANA time-zone data through the operating system or the tzdata package. A UTC round trip rejects nonexistent wall times, and a set removes the duplicate candidate on ordinary dates. The output exposes the choice instead of silently selecting a policy.
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
def candidates(local_time, zone_name):
if local_time.tzinfo is not None:
raise ValueError("a naive local wall time is required")
zone = ZoneInfo(zone_name)
result = set()
for fold in (0, 1):
utc = local_time.replace(tzinfo=zone, fold=fold).astimezone(timezone.utc)
if utc.astimezone(zone).replace(tzinfo=None) == local_time:
result.add(utc)
return sorted(result)
assert len(candidates(datetime(2024, 3, 31, 2, 30), "Europe/Berlin")) == 0
assert len(candidates(datetime(2024, 10, 27, 2, 30), "Europe/Berlin")) == 2
assert len(candidates(datetime(2024, 10, 28, 2, 30), "Europe/Berlin")) == 1
Zero candidates means the product must apply its gap rule; two means it must apply its overlap rule. Select the earlier or later UTC instant explicitly if only one execution is intended. Keep the calendar occurrence identity independent of that selection, and pin or record the time-zone database used for future schedule resolution.
Separate one occurrence from its attempts
Use a stable occurrence identity derived from the schedule revision and intended calendar occurrence. A worker attempt has a separate identifier. If the worker stops after sending a report but before acknowledging success, its retry must reconcile the same occurrence rather than create the next report because the clock has advanced.
Enforce uniqueness in durable business state, not only in the scheduler's retained jobs. Queue cleanup may remove old execution records while the application still needs to remember that a report was sent. Keep enough history to distinguish a duplicate dispatch from an authorized rerun requested by an operator.
Define missed-run behavior independently from daylight-saving behavior. After an outage, should the scheduler catch up every eligible date, send only the newest summary, or mark old occurrences skipped? Bound catch-up so recovery does not flood providers or customers. Record skipped periods explicitly when they matter to the product's completeness promise.
Version timezone and schedule changes
A customer changing the schedule from 02:30 to 03:00 should not accidentally create two summaries for the same reporting date. Specify when the new revision takes effect and what happens to already-created future occurrences. Reconcile the old and new plans using the business occurrence rule rather than relying on different cron strings to avoid collisions.
Timezone rule databases also change as governments revise calendar rules. Record the runtime or timezone-data version used in tests and regenerate future occurrences under a controlled policy when rules change. Past completed occurrences should retain their recorded local context and actual instant; rewriting history makes support investigations harder.
For user-facing previews, show several upcoming local execution times with their timezone and corresponding dates. Include an unusual date when one is relevant. A clear preview exposes mistaken assumptions earlier than an incident involving a duplicated notification or a missing report.
Test dates, downtime, and repeated delivery together
Create fixtures for an ordinary date, the spring gap, the autumn overlap, a zone without seasonal changes, a timezone edit, and downtime spanning multiple occurrences. Resolve the relevant dates using the pinned timezone data. Assert intended local dates, chosen offsets, UTC instants, and occurrence identities rather than only checking the next timer delay.
Then deliver each fixture twice and interrupt after the external effect. The reliable jobs guide explains duplicate-safe processing, while reconciliation handles uncertain completion. Scheduling implementation should preserve both calendar meaning and execution safety.