Get the app

← All engineering notes

Engineering

Hitting a 15-minute window in every time zone from one cron

· 5 min read · Cancel Cultr

A finale alert that lands at 11 am is noise. The same alert at a quarter to eight in the evening, in the user’s own time zone, is the one message of the day they act on. Here is how a scheduled job on Cloudflare Workers hits a fifteen-minute window for every user on Earth.

The constraint

Cron Triggers fire on a schedule in UTC, once per schedule regardless of how many users there are. There is no per-user timer. Whatever “7:45 pm for everyone” means, it has to come out of a job that runs at the same moments for all of them.

The approach

The nudge scan runs every fifteen minutes. On each run it loads the candidates (a tracked show whose season is complete, still marked as watching, on a paid, active subscription) and, for each one, converts the current instant into the user’s local time using the IANA zone their device reported when it registered for push. If the local time is between 7:45 and 7:59 pm, the candidate is inside the window; otherwise it waits for a later run. Across 96 runs a day, every zone gets exactly one run inside its window.

The conversion is Intl.DateTimeFormat with timeZone set and hourCycle: "h23", read back with formatToParts. No date library, no offset table to keep current; the runtime’s zone data handles daylight saving.

What an invalid zone does

A zone string the runtime doesn’t recognise would throw inside the scan loop and, unhandled, abort the run for everyone after that row. Two rules keep that from happening. The device endpoint rejects a zone that Intl can’t resolve, so bad values don’t get stored. And every time helper treats an invalid zone as a value, not an exception: it returns null, and the scan records “invalid timezone” as the skip reason for that row. Never a throw, and never a silent skip either. A scan that quietly drops a user is worse than one that fails loudly, because nobody looks for it.

The other gates

Being in the window is necessary, not sufficient. The same candidate is held back if the show was nudged in the last seven days, if the user asked to be left alone until a date, or if a “still watching” reply set a later eligibility. Each gate is a reason string in the scan’s report, so a run that sent nothing still explains itself.

Copy that can’t wedge the pipeline

The message text is generated by a language model, with the show name as the only input: never a price or an account detail. It gets one retry. If both attempts fail, a deterministic template takes over, and the alert still goes out at 7:45. The model makes the message better; it is never allowed to make the message late.