tokio-cron-scheduler

tokio-cron-scheduler is a Rust library for scheduling asynchronous tasks on the Tokio runtime using cron-like expressions. It lets you run jobs on a recurring cron schedule, at a specific instant, or repeatedly at a fixed duration, all as async closures driven by Tokio’s timers.

Beyond basic scheduling it supports job lifecycle notifications (start, stop, removed), plain-English schedule parsing, timezone-aware cron via chrono-tz, and optional persistence of jobs to PostgreSQL or NATS so schedules survive restarts. With millions of downloads, it is a widely used building block for background work in async Rust services.

What You Get

• A JobScheduler that runs cron-expression and interval jobs as async Tokio tasks
• One-shot, repeating, and instant job types with per-job UUID identity
• Lifecycle notifications for job start, stop, and removal
• Optional PostgreSQL and NATS persistence for durable schedules
• Timezone-aware cron via chrono-tz and optional English-to-cron parsing

Common Use Cases

• Running periodic background jobs in an async Rust service
• Scheduling one-off tasks to fire at a specific instant
• Persisting job schedules across restarts using Postgres or NATS
• Triggering timezone-aware recurring work with cron expressions

Under The Hood

Architecture - The crate centers on a JobScheduler (job_scheduler.rs) that owns a scheduler loop (scheduler.rs) and a pluggable job store (store/, simple/) plus a context (context.rs) for coordination. Job definitions live under src/job/ split into cron and non-cron jobs, builders/creators, a runner, and deleter, with a to_code layer bridging to protobuf-encoded job data (job_data_prost.rs) when persistence is enabled. Notification dispatch (notification/) fires lifecycle callbacks, and backend modules (postgres/, nats/) implement durable storage behind Cargo features, with a build.rs compiling prost protobuf definitions.

Tech Stack - Rust edition 2024 built on tokio (time, rt, sync), using croner for cron parsing, chrono/chrono-tz for time and timezones, and uuid for job identity. Optional features layer in async-nats, tokio-postgres with TLS, prost/prost-build for serialization, english-to-cron for natural-language schedules, and tracing-subscriber for logging. The dependency surface is minimal by default and grows only as you opt into persistence.

Code Quality - The codebase is cleanly modularized by concern (job, scheduler, store, notification, backends) with a dedicated error module. It ships runnable examples for simple, threaded, Postgres, and NATS usage plus design.adoc and per-backend docs (postgres.md, nats.md, migration.md), giving strong reference material. Recent commit activity is low, consistent with a mature, stable library in maintenance mode.

API Design - The API is builder-oriented and ergonomic: create a JobScheduler, construct a Job from a cron string and an async closure, add it, and call start(). Jobs return UUIDs for later removal, and notification hooks attach cleanly. The main learning curve comes from wiring optional persistence backends and understanding async closure lifetimes, but the core scheduling API stays approachable for common recurring-task needs.