chronon (public crate)

Public crate re-exporting split upstream crates.

Cargo features

# crates.io package is uf-chronon; Rust import stays `use chronon::…`.
chronon = { package = "uf-chronon", version = "0.1", default-features = false, features = ["mem", "axum"] }

Prelude

use chronon::prelude::*;

Configuration

Settings merge in this order (explicit builder values win over environment defaults):

Backend connection (not on ChrononBuilder)

Builder .tick_interval_ms() overrides CHRONON_TICK_INTERVAL_MS. Partition count and lease TTLs are read from the environment only — see chronon-scheduler rustdoc for the full env-var table.

How to run examples

Navigational index: examples/README.md (when-to-use ladder + success checks for every example).

Canonical teaching path (start here). Topology docs: Embedded / Coordinator–worker / Remote HTTP client.

1. Embedded — sqlite_boot (standalone)

One process, file-backed store. No external services.

cargo run -p uf-chronon --example sqlite_boot --features sqlite
# optional: CHRONON_SQLITE_PATH=:memory:  or a custom file path
# default path: /tmp/chronon-example.db

Success: stderr prints Chronon booted with SQLite store (…).

2. Coordinator–worker (multi-process — run as a set)

Coordinator and workers share one store. They are not useful alone.

Local SQLite (no Postgres/Redis) — 1 coordinator + 2 workers:

export CHRONON_SQLITE_PATH=/tmp/chronon-split.db

# Terminal 1 — coordinator
cargo run -p uf-chronon --example sqlite_coordinator_daemon --features sqlite

# Terminal 2 — worker A
CHRONON_INSTANCE_ID=worker-a cargo run -p uf-chronon --example sqlite_worker_daemon --features sqlite

# Terminal 3 — worker B
CHRONON_INSTANCE_ID=worker-b cargo run -p uf-chronon --example sqlite_worker_daemon --features sqlite

Production claim path (Postgres + Redis) — same pattern:

export CHRONON_POSTGRES_URL=postgres://user:pass@localhost/chronon
export CHRONON_REDIS_URL=redis://127.0.0.1:6379

# Terminal 1 — coordinator
cargo run -p uf-chronon --example coordinator_daemon --features postgres,redis

# Terminal 2 / 3 — workers (unique instance ids)
CHRONON_INSTANCE_ID=worker-a cargo run -p uf-chronon --example worker_daemon --features postgres,redis
CHRONON_INSTANCE_ID=worker-b cargo run -p uf-chronon --example worker_daemon --features postgres,redis

Stop with Ctrl-C on each process. Real apps link #[chronon::script] into worker binaries and use .auto_registry().

3. Remote HTTP client — remote_http_client (standalone)

App schedules via RemoteCoordinatorClient (no local Chronon loops). This demo spins a short-lived mem API host, then upserts + run_now.

cargo run -p uf-chronon --example remote_http_client --features mem,axum

Production: Chronon does not authenticate /api/chronon/*. Wrap with host auth — see axum_auth_wrap and repository SECURITY.md.

4. Combined production shape — authenticated_remote_postgres_redis (standalone)

Postgres + Redis storage, StaticTokenAdminAuth gating every route, and RemoteCoordinatorClient against the mounted API — the three earlier pieces composed into one auth-gated remote coordinator. Requires PostgreSQL and Redis:

docker run -d --name chronon-pg -e POSTGRES_USER=chronon -e POSTGRES_PASSWORD=chronon \
  -e POSTGRES_DB=chronon -p 5432:5432 postgres:16
docker run -d --name chronon-redis -p 6379:6379 redis:7

export CHRONON_POSTGRES_URL=postgres://chronon:chronon@localhost:5432/chronon
cargo run -p uf-chronon --example authenticated_remote_postgres_redis --features postgres,redis,axum

Success: missing token denied, x-chronon-admin-token allowed. RemoteCoordinatorClient has no header hook today, so the deny path uses the client as-is and the allow path attaches x-chronon-admin-token directly (reqwest in the example, curl for manual checks):

curl -i http://127.0.0.1:PORT/api/chronon/jobs                                        # 401
curl -i http://127.0.0.1:PORT/api/chronon/jobs -H 'x-chronon-admin-token: <token>'     # 200

Other examples

Documentation

API reference: cargo doc -p uf-chronon --all-features --open. See root README.md for architecture.