tokio-cron-scheduler

Version 0.6 uses a modular approach to job execution and persistence through several key traits:

Storage Traits

• MetaDataStore: Required by the scheduler to schedule jobs.
• NotificationStore: Required by the scheduler to run notifications on job start, scheduled, stop, or removals.

Code Traits

• ToCode: A generic trait that provides a PinnedGetFuture for a given UUID.
• JobCode: A trait (specializing ToCode) that provides the runnable closures for the scheduler. The default implementation is SimpleJobCode.
• NotificationCode: A trait (specializing ToCode) that provides the runnable notification closures. The default implementation is SimpleNotificationCode.

Jobs and their associated notifications are managed through specific creation and deletion workflows that ensure metadata and runnable code remain synchronized.

Creating a Job

1. A creation request is sent to a queue.
2. A JobCreator generates the next tick, saves the job metadata to MetadataStorage, and updates the list of active GUIDs.
3. The process completes once the job GUID is produced to a 'done' queue.

Deleting a Job

Deleting a job is a multi-step process to ensure no orphaned notifications remain:

1. Metadata Deletion: The job's metadata is removed from MetadataStorage.
2. Code Cleanup: The job's runnable code is removed from JobStorage.
3. Notification Cleanup: The system identifies all notifications associated with the Job ID in NotifyStorage and deletes them individually, ensuring the NotifyCode is also cleaned up.

Notifications are lifecycle hooks attached to jobs that trigger specific code when a job enters a certain state.

Creating a Notification

• A request containing the Job GUID, Notify GUID, and Job State is processed.
• The NotificationCreator retrieves existing notification data, updates the job metadata with the new notification information, and saves it to NotifyStorage.

Deleting a Notification

• A request containing the Notify GUID and Job State is processed.
• The NotificationDeleter retrieves the metadata, updates it to reflect the deletion, and saves the changes to NotifyStorage.

The JobScheduler can use custom storage implementations by implementing the MetadataStore and NotificationStore traits.

Available Storage Options:

• Volatile (Default): Uses in-memory HashMaps (SimpleMetadataStore and SimpleNotificationStore).
• Nats: Persistent storage using Nats (NatsMetadataStore and NatsNotificationStore). Requires nats_storage feature.
• PostgreSQL: Persistent storage using Postgres (PostgresMetadataStore and PostgresNotificationStore). Requires postgres_storage feature.

Add the following dependency to your Cargo.toml to use the scheduler in your Rust project:

[dependencies]
tokio-cron-scheduler = "*"

To use NATS as a persistent storage backend for tokio-cron-scheduler, you must run a NATS instance with Jetstream enabled. You can quickly spin up a compatible instance using Docker with the following command:

docker run --rm -it -p 4222:4222 -p 6222:6222 -p 7222:7222 -p 8222:8222 nats -js -DV

Version 0.6 introduced a significant architectural change. If you are upgrading from 0.4 or 0.5, the primary change for most users is that creating or removing job notifications now requires passing a reference to the scheduler as the first parameter.

Key architectural shifts include:

• The JobStore trait has been replaced by two specialized traits: MetadataStore and NotificationStore.
• JobSchedulerWithoutSync and its implementation SimpleJobScheduler have been removed.
• JobScheduler::new_with_scheduler() has been replaced by JobScheduler::new_with_storage_and_code().

For fine-grained control, such as setting specific timezones, use the JobBuilder API. This is useful when you need to work with chrono-tz timezones.

Note: chrono-tz is not a direct dependency; you must add it to your Cargo.toml to use it with JobBuilder.

async fn tz_job() {
    let job = JobBuilder::new()
        .with_timezone(chrono_tz::Africa::Johannesburg)
        .with_cron_job_type()
        .with_schedule("*/2 * * * *")
        .unwrap()
        .with_run_async(Box::new(|uuid, mut l| {
            Box::pin(async move {
                // Job logic here
            })
        }))
        .build()
        .unwrap();
}

To use PostgreSQL persistent storage, you need a running PostgreSQL instance. You can quickly spin up a local instance using Docker with the following command:

docker run --rm -it -p 5432:5432 -e POSTGRES_USER="postgres" -e POSTGRES_PASSWORD="" -e POSTGRES_HOST_AUTH_METHOD="trust" postgres:14.1