Scheduled Jobs and Proactive Outreach: Time Zones, Quiet Hours, Daily Caps, a Notification Provider Abstraction

// JS has no time-zone-aware date type: a Date is just UTC milliseconds. To get the user's
// wall-clock time you have to format it into the target zone via Intl and read it back -
// the other three languages have native types and skip this detour.
function partsOf(zoneId, at) {
  const f = new Intl.DateTimeFormat('en-CA', {
    timeZone: zoneId, hour12: false,
    year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit',
  })
  const p = Object.fromEntries(f.formatToParts(at).map((x) => [x.type, x.value]))
  // en-CA with hour12:false yields 24 at midnight, so take a modulus back to 0
  return { date: `${p.year}-${p.month}-${p.day}`, hour: Number(p.hour) % 24, minute: Number(p.minute) }
}
 
function offsetMsAt(zoneId, at) {
  const p = partsOf(zoneId, at)
  const [y, m, d] = p.date.split('-').map(Number)
  return Date.UTC(y, m - 1, d, p.hour, p.minute) - Math.floor(at.getTime() / 60000) * 60000
}
 
// The reverse: a local wall-clock time back to one unique UTC instant. Use the offsets a
// day either side as candidates, which covers both offsets on a transition day; then
// convert each candidate back to wall-clock time and check.
function resolveLocal(zoneId, date, hh, mi) {
  const target = Date.UTC(...date.split('-').map(Number).map((v, i) => (i === 1 ? v - 1 : v)), hh, mi)
  const cands = [...new Set([target - 86400000, target + 86400000]
    .map((probe) => target - offsetMsAt(zoneId, new Date(probe))))].sort((a, b) => a - b)
  const valid = cands.filter((c) => {
    const p = partsOf(zoneId, new Date(c))
    return p.date === date && p.hour === hh && p.minute === mi
  })
  if (valid.length === 0) return { instant: new Date(cands.at(-1)), kind: 'gap' }
  if (valid.length > 1) return { instant: new Date(valid[0]), kind: 'ambiguous' }
  return { instant: new Date(valid[0]), kind: 'exact' }
}

from datetime import datetime, timezone
from zoneinfo import ZoneInfo
 
 
def to_user_local(zone_id: str, at: datetime) -> datetime:
    """What comes in is always an aware UTC instant; convert to the user's zone before
    judging. zoneinfo reads the system tz database, so you do not maintain DST rules."""
    return at.astimezone(ZoneInfo(zone_id))
 
 
def resolve_local(zone_id: str, wall: datetime) -> tuple[datetime, str]:
    """A local wall-clock time back to one unique instant. PEP 495 expresses DST's two
    anomalies with fold, and the order cannot be reversed: check existence first, then
    check whether it occurred twice - because inside the spring-forward gap, fold=0 and
    fold=1 also have differing offsets."""
    aware = wall.replace(tzinfo=ZoneInfo(zone_id))
    if aware.astimezone(timezone.utc).astimezone(aware.tzinfo) != aware:
        # A round trip that does not return to itself means this local time does not exist
        return aware.astimezone(timezone.utc), "gap"
    if aware.utcoffset() != aware.replace(fold=1).utcoffset():
        return aware.astimezone(timezone.utc), "ambiguous"  # fold=0 is the first occurrence
    return aware.astimezone(timezone.utc), "exact"

// Dependencies: java.time (JDK 8+). An Instant is an absolute moment and only a
// ZonedDateTime has wall-clock time; keeping the types apart is java.time's value - you
// cannot use a zoneless local time as an absolute moment.
static ZonedDateTime toUserLocal(String zoneId, Instant at) {
    return at.atZone(ZoneId.of(zoneId));
}
 
static Instant resolveLocal(String zoneId, LocalDate date, LocalTime time) {
    var zone = ZoneId.of(zoneId);
    var wall = LocalDateTime.of(date, time);
    // getValidOffsets tells you how many valid offsets exist: empty means this local time
    // does not exist (spring forward), two means it occurred twice (autumn back).
    // ZonedDateTime.of's default resolution is exactly what we want: shift past the
    // transition when absent, and take the earlier offset when doubled.
    var offsets = zone.getRules().getValidOffsets(wall);
    if (offsets.isEmpty()) log.warn("{} does not exist in {}, shifting past the transition", wall, zoneId);
    if (offsets.size() > 1) log.warn("{} occurs twice in {}, taking the first", wall, zoneId);
    return ZonedDateTime.of(wall, zone).toInstant();
}

// A Date, like an Instant, is only an absolute moment; wall-clock time comes from a
// Calendar with a timeZone set.
func calendar(_ zoneId: String) -> Calendar {
    var cal = Calendar(identifier: .gregorian)
    cal.timeZone = TimeZone(identifier: zoneId) ?? TimeZone(identifier: "UTC")!
    return cal
}
 
func toUserLocal(_ zoneId: String, _ at: Date) -> DateComponents {
    calendar(zoneId).dateComponents([.year, .month, .day, .hour, .minute], from: at)
}
 
enum Resolution { case exact(Date), gap(Date), ambiguous(Date) }
 
/// Calendar.date(from:) resolves as Java does: shift when absent, take the first when
/// doubled. It does not tell you which happened, so convert the result back to wall-clock
/// time and compare - that step is what makes the DST arithmetic add up.
func resolveLocal(_ zoneId: String, _ wall: DateComponents) -> Resolution? {
    let cal = calendar(zoneId)
    guard let date = cal.date(from: wall) else { return nil }
    let back = cal.dateComponents([.hour, .minute], from: date)
    guard back.hour == wall.hour, back.minute == wall.minute else { return .gap(date) }
    // Inside the autumn fallback hour, an instant one DST offset later yields the same
    // wall-clock time. daylightSavingTimeOffset returns a TimeInterval in seconds.
    let shift = cal.timeZone.daylightSavingTimeOffset(for: date)
    let later = date.addingTimeInterval(shift > 0 ? shift : 3600)
    let laterBack = cal.dateComponents([.hour, .minute], from: later)
    if laterBack.hour == wall.hour, laterBack.minute == wall.minute { return .ambiguous(date) }
    return .exact(date)
}

const minutesOf = (hhmm) => hhmm.split(':').reduce((h, m) => Number(h) * 60 + Number(m))
 
// Closed-open [start, end). start greater than end means it crosses midnight, and the
// condition must switch from "and" to "or"
export function isQuiet(quietStart, quietEnd, hour, minute) {
  const now = hour * 60 + minute
  const start = minutesOf(quietStart)
  const end = minutesOf(quietEnd)
  if (start === end) return false // empty interval: this user has no quiet hours
  return start < end ? now >= start && now < end : now >= start || now < end
}
 
// Which day the window ends on: local 23:30 pushes to 08:00 tomorrow, local 07:00 pushes
// to 08:00 today. For one quietEnd, which day depends on which side of midnight you are.
export function endDate(quietStart, quietEnd, localDate, hour, minute) {
  const crossesMidnight = minutesOf(quietStart) > minutesOf(quietEnd)
  const sameDay = !crossesMidnight || hour * 60 + minute < minutesOf(quietEnd)
  if (sameDay) return localDate
  const [y, m, d] = localDate.split('-').map(Number)
  return new Date(Date.UTC(y, m - 1, d + 1)).toISOString().slice(0, 10)
}

from datetime import date as Date, time as Time, timedelta
 
 
def is_quiet(quiet_start: Time, quiet_end: Time, now: Time) -> bool:
    """Closed-open. time values compare directly with no conversion to minutes - and the
    cross-midnight case still switches from and to or, no different from any language."""
    if quiet_start == quiet_end:
        return False
    if quiet_start < quiet_end:
        return quiet_start <= now < quiet_end
    return now >= quiet_start or now < quiet_end
 
 
def end_date(quiet_start: Time, quiet_end: Time, local_date: Date, now: Time) -> Date:
    """Which day the window ends on: local 23:30 to 08:00 tomorrow, local 07:00 to today."""
    same_day = quiet_start <= quiet_end or now < quiet_end
    return local_date if same_day else local_date + timedelta(days=1)

// A record keeps the configuration and the judgment together, cleaner than a static
// method taking two LocalTimes everywhere
record QuietHours(LocalTime start, LocalTime end) {
    /** Closed-open [start, end). start after end crosses midnight, so and becomes or. */
    boolean covers(LocalTime now) {
        if (start.equals(end)) return false;
        return start.isBefore(end)
            ? !now.isBefore(start) && now.isBefore(end)
            : !now.isBefore(start) || now.isBefore(end);
    }
}
 
/** Which day the window ends on: local 23:30 to 08:00 tomorrow, local 07:00 to today. */
static LocalDate endDateOf(QuietHours q, ZonedDateTime local) {
    boolean crossesMidnight = q.start().isAfter(q.end());
    boolean sameDay = !crossesMidnight || local.toLocalTime().isBefore(q.end());
    return sameDay ? local.toLocalDate() : local.toLocalDate().plusDays(1);
}

struct QuietHours {
    let start: Int // minutes from local midnight
    let end: Int
 
    /// Closed-open [start, end). start greater than end crosses midnight, so and becomes or.
    func covers(_ minutes: Int) -> Bool {
        if start == end { return false }
        return start < end ? (minutes >= start && minutes < end)
                           : (minutes >= start || minutes < end)
    }
}
 
/// Which day the window ends on. DateComponents allows out-of-range fields and leaves the
/// carry to Calendar, so no month-end arithmetic here - far safer than hand-writing
/// "how many days does this month have".
func endDay(_ quiet: QuietHours, localMinutes: Int, today: DateComponents) -> DateComponents {
    let sameDay = quiet.start <= quiet.end || localMinutes < quiet.end
    guard !sameDay, let day = today.day else { return today }
    var next = today
    next.day = day + 1
    return next
}

// Three gates in fixed order: time zone, quiet hours, daily cap.
// The cap gate goes last, because a postponed message should not consume today's quota -
// it sends tomorrow morning, so why count it today.
// Position matters more than order: this whole function must run BEFORE the model writes the body.
export async function passGates(store, profile, candidate, at) {
  const parts = partsOf(profile.timeZone, at) // gate one: convert to the user's local time
  if (isQuiet(profile.quietStart, profile.quietEnd, parts.hour, parts.minute)) {
    const dueAt = quietEndsAt(profile, at) // gate two: quiet hours
    if (candidate.expiresAt && new Date(candidate.expiresAt) <= dueAt) {
      return { action: 'drop', reason: 'expires before the window ends', localDate: parts.date }
    }
    return { action: 'defer', dueAt, localDate: parts.date }
  }
  const used = await store.bumpDaily(profile.id, parts.date) // gate three: claim, then judge
  if (used > profile.dailyLimit) {
    await store.releaseDaily(profile.id, parts.date) // release what was not used
    return { action: 'drop', reason: 'over the daily cap', localDate: parts.date }
  }
  return { action: 'send', reason: `number ${used} today`, localDate: parts.date }
}

async def pass_gates(store, profile: Profile, candidate: Candidate,
                     at: datetime) -> Verdict:
    """Three gates in fixed order: time zone, quiet hours, daily cap.
    The cap gate goes last, because a postponed message should not consume today's quota.
    Position matters more than order: this must run BEFORE the model writes the body."""
    local = at.astimezone(ZoneInfo(profile.time_zone))  # gate one
    today = local.date()
 
    if is_quiet(profile.quiet_start, profile.quiet_end, local.time()):  # gate two
        due_at = quiet_ends_at(profile, at)
        if candidate.expires_at is not None and candidate.expires_at <= due_at:
            return Verdict("drop", "expires before the window ends", today)
        return Verdict("defer", "inside quiet hours", today, due_at=due_at)
 
    used = await store.bump_daily(profile.id, today)  # gate three: claim, then judge
    if used > profile.daily_limit:
        await store.release_daily(profile.id, today)  # release what was not used
        return Verdict("drop", "over the daily cap", today)
    return Verdict("send", f"number {used} today", today)

enum Action { SEND, DEFER, DROP }
record Verdict(Action action, String reason, LocalDate localDate, Instant dueAt) {}
 
/**
 * Three gates in fixed order: time zone, quiet hours, daily cap.
 * The cap gate goes last, because a postponed message should not consume today's quota.
 * Position matters more than order: this must run BEFORE the model writes the body.
 */
static Verdict passGates(Store store, Profile p, Candidate c, Instant at) {
    var local = at.atZone(ZoneId.of(p.zoneId()));            // gate one
    var today = local.toLocalDate();
 
    if (p.quiet().covers(local.toLocalTime())) {             // gate two
        var dueAt = quietEndsAt(p, local);
        if (c.expiresAt() != null && !c.expiresAt().isAfter(dueAt))
            return new Verdict(Action.DROP, "expires before the window ends", today, null);
        return new Verdict(Action.DEFER, "inside quiet hours", today, dueAt);
    }
 
    long used = store.bumpDaily(p.id(), today);              // gate three: claim, then judge
    if (used > p.dailyLimit()) {
        store.releaseDaily(p.id(), today);                   // release what was not used
        return new Verdict(Action.DROP, "over the daily cap", today, null);
    }
    return new Verdict(Action.SEND, "number " + used + " today", today, null);
}

// An enum with associated values: dueAt exists only for defer, pinning "no value when
// there should be none" into the type rather than a Date? checked for nil everywhere
enum Verdict {
    case send(reason: String, localDate: String)
    case postpone(dueAt: Date, localDate: String)
    case drop(reason: String, localDate: String)
}
 
/// Three gates in fixed order: time zone, quiet hours, daily cap.
/// The cap gate goes last, because a postponed message should not consume today's quota.
/// Position matters more than order: this must run BEFORE the model writes the body.
func passGates(_ store: Store, _ p: Profile, _ c: Candidate, at: Date) async -> Verdict {
    let cal = calendar(p.zoneId)                                      // gate one
    let parts = cal.dateComponents([.year, .month, .day, .hour, .minute], from: at)
    let today = String(format: "%04d-%02d-%02d", parts.year!, parts.month!, parts.day!)
 
    if p.quiet.covers(parts.hour! * 60 + parts.minute!) {             // gate two
        let dueAt = quietEndsAt(p, at)
        if let expiresAt = c.expiresAt, expiresAt <= dueAt {
            return .drop(reason: "expires before the window ends", localDate: today)
        }
        return .postpone(dueAt: dueAt, localDate: today)
    }
 
    let used = await store.bumpDaily(p.id, today)                     // gate three
    guard used <= p.dailyLimit else {
        await store.releaseDaily(p.id, today)                         // release what was not used
        return .drop(reason: "over the daily cap", localDate: today)
    }
    return .send(reason: "number \(used) today", localDate: today)
}

// Delivery is an asynchronous receipt, so this only expresses whether the channel accepted
// it, and the three outcomes are handled completely differently
export async function deliver(provider, notification, sleep, maxAttempts = 3) {
  for (let attempt = 1; ; attempt += 1) {
    // A retry must carry the same idempotencyKey: an extra database row you can delete,
    // an extra chime on the user's phone you cannot
    const result = await provider.send(notification)
    if (result.status === 'accepted') return { ok: true, attempts: attempt }
    if (result.status === 'rejected') return { ok: false, attempts: attempt } // bad argument, retrying will not help
    if (attempt >= maxAttempts) return { ok: false, attempts: attempt }
    await sleep(result.retryAfterMs) // wait as long as the channel says, do not improvise
  }
}

class NotificationProvider(Protocol):
    id: str
    rate_limit_per_sec: int  # the channel's own technical limit, distinct from the daily cap
 
    async def send(self, n: Notification) -> SendResult: ...  # no cancel: once sent, no recall
 
 
async def deliver(provider: NotificationProvider, n: Notification,
                  max_attempts: int = 3) -> tuple[bool, int]:
    """match dispatches by result type, and a static checker warns you to add a branch
    when a new result appears."""
    for attempt in range(1, max_attempts + 1):
        match await provider.send(n):  # a retry carries the same idempotency_key
            case Accepted():
                return True, attempt
            case Rejected():
                return False, attempt  # bad argument; ten thousand retries stay wrong
            case Throttled(retry_after_ms=ms) if attempt < max_attempts:
                await asyncio.sleep(ms / 1000)  # asyncio.sleep takes seconds
    return False, max_attempts

// A sealed interface: three outcomes are a closed set, and nobody can quietly add a
// fourth in another package
sealed interface SendResult {
    record Accepted(String providerMessageId) implements SendResult {}
    record Throttled(Duration retryAfter) implements SendResult {}
    record Rejected(String reason) implements SendResult {}
}
 
interface NotificationProvider {
    String id();
    int rateLimitPerSec();               // the channel's technical limit, not the daily cap
    SendResult send(Notification n);     // no cancel: a sent message cannot be recalled
}
 
static boolean deliver(NotificationProvider p, Notification n, int maxAttempts)
        throws InterruptedException {
    for (int attempt = 1; ; attempt++) {
        var result = p.send(n);          // a retry must carry the same idempotencyKey
        if (result instanceof SendResult.Accepted) return true;
        if (result instanceof SendResult.Rejected) return false;  // bad argument
        if (result instanceof SendResult.Throttled t) {
            if (attempt >= maxAttempts) return false;
            Thread.sleep(t.retryAfter().toMillis());  // Duration converts units for you
        }
    }
}

enum SendResult {
    case accepted(providerMessageId: String)
    case throttled(retryAfter: TimeInterval) // TimeInterval is in seconds, not milliseconds
    case rejected(reason: String)
}
 
protocol NotificationProvider {
    var id: String { get }
    var rateLimitPerSec: Int { get }        // the channel's technical limit, not the daily cap
    func send(_ n: Notification) async throws -> SendResult // no cancel: once sent, no recall
}
 
func deliver(_ provider: some NotificationProvider, _ n: Notification,
             maxAttempts: Int = 3) async throws -> Bool {
    var attempt = 0
    while true {
        attempt += 1
        // The switch covers every case, so adding an outcome forces you back here
        switch try await provider.send(n) { // a retry carries the same idempotencyKey
        case .accepted: return true
        case .rejected: return false        // bad argument; ten thousand retries stay wrong
        case .throttled(let retryAfter):
            if attempt >= maxAttempts { return false }
            try await Task.sleep(for: .seconds(retryAfter))
        }
    }
}