Timezone-aware cron scheduler composing over infrastructure-jobs: durable beat ledger, replica-safe exactly-once beats, bounded catch-up
| Tier | infrastructure |
| Role | unclassified (baselined) |
| Path | crates/infrastructure/cron |
| Edition | 2021 |
| Targets | infrastructure_cron, beats |
| Public items | 7 across 0 modules |
| Tests | 13 |
What it is for
# infrastructure-cron
Timezone-aware cron scheduling that composes over `infrastructure-jobs` (Sprint 2.4 US-2.4.3, consensus #11). This crate owns cron syntax, timezone and DST handling, the durable beat ledger, catch-up policy, and replica-safe beat claiming; the jobs crate knows nothing about any of it.
A beat is one scheduled instant. Each beat is claimed exactly once across N replicas via a unique (schedule_id, beat_at) insert, then enqueued as an ordinary job — so cron inherits every jobs guarantee (fencing, backoff, DLQ).
The tz-aware beat calculation is harvested from rfpdb's proven due_beats_tz.
Capabilities
crate root
# infrastructure-cron
| Item |
|---|
fn to_six_field(expr : & str) -> String |
CatchupPolicy
# infrastructure-cron
| Item |
|---|
pub enum CatchupPolicy |
fn select_beats(all_due : & DateTime <Utc>, policy : CatchupPolicy, ceiling : usize,) -> Vec <DateTime <Utc>> |
CronError
# infrastructure-cron
| Item |
|---|
pub enum CronError |
fn due_beats_tz(cron_expr : & str, tz : chrono_tz::Tz, window_start : DateTime <Utc>, window_end : DateTime <Utc>,) -> Result <Vec <DateTime <Utc>>, CronError> |
Schedule
# infrastructure-cron
| Item |
|---|
pub struct Schedule |
fn uncovered_schedules(schedules : & Schedule, registered_handlers : & std::collections::HashSet <String>,) -> Vec <String> |
How to use it
No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.
Module structure
No public modules: the crate root is its whole surface.
Public surface
`crate root`
| Item | What it is |
|---|---|
pub enum CronError | Errors from cron parsing or scheduling. |
pub enum CatchupPolicy | What to do with beats missed while the scheduler was down (consensus #12) |
pub struct Schedule | A registered schedule. |
fn to_six_field(expr : & str) -> String | Normalise a 5-field cron (min hour dom mon dow) to the 6-field form the cron crate expects (sec min hour dom mon dow) by prepending 0 seconds. |
fn due_beats_tz(cron_expr : & str, tz : chrono_tz::Tz, window_start : DateTime <Utc>, window_end : DateTime <Utc>,) -> Result <Vec <DateTime <Utc>>, CronError> | All beats for cron_expr (interpreted in tz) within window_start, window_end, returned in UTC |
fn select_beats(all_due : & DateTime <Utc>, policy : CatchupPolicy, ceiling : usize,) -> Vec <DateTime <Utc>> | Apply the catch-up policy to the full set of due beats (consensus #12) |
fn uncovered_schedules(schedules : & Schedule, registered_handlers : & std::collections::HashSet <String>,) -> Vec <String> | Startup drift check (US-2.4.11): the schedule ids whose job type has no registered handler |
Re-exports. Exported here, defined elsewhere.
| Export | Defined in |
|---|---|
{claim_beat,ensure_beat_ledger,tick} | ledger::{claim_beat,ensure_beat_ledger,tick} |
Boundary
Depends on no other workspace tier.
Shares tier infrastructure with 82 other crates: infrastructure-acquire, infrastructure-adapters-google-calendar, infrastructure-adapters-google-gmail, infrastructure-adapters-google-places, infrastructure-adapters-google-trends, infrastructure-adapters-shodan, infrastructure-adapters-yelp, infrastructure-agent, … (82 total).
_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._
Where it sits
| Tier (ontology) | infrastructure |
| Architectural role (taxonomy) | unclassified (baselined) |
| Location | crates/infrastructure/cron |
| Vocabulary in force (lexicon) | current |
Dependencies
Runtime, in this workspace.
| Crate | Tier | Optional | Only on |
|---|---|---|---|
| `infrastructure-jobs` | infrastructure | no | always |
Runtime, from outside the workspace.
| Crate | Requirement | Features | Optional | Only on |
|---|---|---|---|---|
chrono | ^0.4 | serde | no | always |
chrono-tz | ^0.10 | — | no | always |
cron | ^0.15 | — | no | always |
serde | ^1 | derive | no | always |
serde_json | ^1 | — | no | always |
sqlx | ^0.8 | runtime-tokio, postgres, chrono, uuid, json | no | always |
thiserror | ^2 | — | no | always |
tokio | ^1 | full | no | always |
tracing | ^0.1 | — | no | always |
uuid | ^1 | v4, v7, serde, js | no | always |
Development, from outside the workspace.
| Crate | Requirement | Features | Optional | Only on |
|---|---|---|---|---|
tokio-test | ^0.4 | — | no | always |
Build. None.
Depended on by. 1 workspace crate.
Signal flow — what reaches this crate, and what it reaches.
flowchart LR n_application_tickets["application-tickets"] -->|uses| SELF SELF["infrastructure-cron"] SELF -->|runtime| n_infrastructure_jobs["infrastructure-jobs"] classDef self fill:#1f883d,stroke:#1f883d,color:#fff; class SELF self;
Feature flags
No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.
Targets
| Kind | Name | Source |
|---|---|---|
| lib | infrastructure_cron | `src/lib.rs` |
| test | beats | `tests/beats.rs` |
Error model
| Error type | Named by |
|---|---|
CronError | due_beats_tz |
Operational characteristics
| Property | Evidence |
|---|---|
| async public surface | none detected |
| async runtime | yes |
| database access | yes |
| network I/O | none detected |
| unsafe code | none detected |
| environment variables | none detected |
No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.
Configuration
No environment variable is read with a literal name anywhere in this crate. A variable whose key is computed at run time cannot be listed here, and is not claimed to be absent.
Related capabilities
1 workspace crate depends on this one: application-tickets.
Verification
| Kind | Count |
|---|---|
| Unit tests | 10 |
| Integration tests | 3 |
| Examples | 0 |
| Doctests | 0 |
Evidence by module. How often each public module is named by something executable.
| Module | Tests | Examples | Consumers |
|---|---|---|---|
crate root | 7 | 0 | 2 |
What the tests establish, by name:
test_a_beat_is_enqueued_exactly_once—tests/beats.rstest_the_beat_claim_is_exactly_once—tests/beats.rstest_the_enqueued_job_is_dated_at_the_beat—tests/beats.rstest_catchup_all_bounded_caps_and_keeps_the_newest—src/lib.rstest_catchup_latest_after_downtime_fires_only_the_most_recent—src/lib.rstest_catchup_skip_fires_none—src/lib.rstest_daily_beat_in_a_timezone_lands_at_local_time—src/lib.rstest_default_policy_is_latest—src/lib.rstest_dst_transition_is_handled_by_the_timezone_not_utc_math—src/lib.rstest_five_field_is_normalised_to_six—src/lib.rstest_full_coverage_yields_no_drift—src/lib.rstest_global_ceiling_overrides_policy—src/lib.rstest_uncovered_schedules_flags_a_schedule_with_no_handler—src/lib.rs
Documentation coverage
| Measure | Documented | Total |
|---|---|---|
| Public items with rustdoc | 7 | 7 |
Public modules with a //! block | 0 | 0 |
pie showData
title Public items with rustdoc
"Documented" : 7
"No rustdoc detected" : 0
Metrics
| Metric | Value |
|---|---|
| Rust source files | 2 |
| Source lines | 460 |
| Code lines | 307 |
| Public API items | 7 |
| Public modules | 0 |
| Tests | 13 |
| Examples | 0 |
| Cargo features | 0 |
| Direct runtime dependencies | 11 |
| Workspace reverse dependencies | 1 |
pie showData
title Public API by kind
"enum" : 2
"function" : 4
"struct" : 1
pie showData
title Rust source composition
"Code" : 307
"Blank or comment" : 153
Generation
Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.