chronon/
lib.rs

1//! Chronon — cron and run-once scheduling for Rust services.
2//!
3//! Chronon provides typed script handlers, durable job/run history, and optional
4//! coordinator–worker split behind a thin [`SchedulerStore`](chronon_core::SchedulerStore) port.
5//! Feature-gated backends and HTTP adapters sit behind the public facade.
6//!
7//! # Getting started
8//!
9//! Cargo examples are **not** auto-indexed by rustdoc. Use the table below (also in
10//! [`chronon/README.md`](https://github.com/unified-field-dev/chronon/blob/main/chronon/README.md)),
11//! or `cargo run -p uf-chronon --example <name> --features …`.
12//!
13//! | Example | Shows | Features |
14//! |---------|-------|----------|
15//! | `script_macro` | `#[chronon::script]` + `Job::new` + `upsert_job` + tick | `mem` |
16//! | `script_handle_job` | Macro [`ScriptHandle`] → default job + typed params | `mem` |
17//! | `run_now` | Manual job + [`CoordinatorService::run_now`](CoordinatorService::run_now) | `mem` |
18//! | `embedded_tick` | Due job enqueue via `tick_once` | `mem` |
19//! | `store_router_boot` | Global [`StoreRouter`](chronon_core::StoreRouter) install | `mem` |
20//! | `sqlite_boot` | SQLite store boot | `sqlite` |
21//! | `postgres_boot` / `postgres_redis_boot` | Durable backends | `postgres` / `postgres,redis` |
22//! | `axum_host` | Mount HTTP router | `mem,axum` |
23//! | `coordinator_daemon` / `worker_daemon` | Split deployment shapes | `postgres,redis` |
24//!
25//! # Documentation map
26//!
27//! Full snippets live on the linked items (not repeated here).
28//!
29//! - **Boot the runtime** — [`ChrononBuilder`], [`DeploymentShape`], [`Chronon::run`]
30//! - **Define scripts** — [`script`] attribute, [`ScriptContext`](chronon_core::ScriptContext),
31//!   [`ContextFactory`](chronon_core::ContextFactory)
32//! - **Schedule a job** — [`Job`](chronon_core::Job), [`CoordinatorService::upsert_job`](CoordinatorService),
33//!   typed defaults via [`ScriptHandle`]
34//! - **Run immediately** — [`CoordinatorService::run_now`](CoordinatorService::run_now) (manual / on-demand)
35//! - **Persist jobs and runs** — [`SchedulerStore`](chronon_core::SchedulerStore),
36//!   [`Run`](chronon_core::Run)
37//! - **Manage jobs programmatically** — [`CoordinatorService`]
38//! - **Parse cron** — [`CronExpr`]
39//! - **Register storage** — `install_default_mem_store` (`mem` feature), [`StoreRouter`](chronon_core::StoreRouter)
40//! - **HTTP API** — `chronon_router` (`axum` feature)
41//! - **Metrics** — [`TelemetrySink`]
42//!
43//! # Configuration
44//!
45//! Settings merge in this order: explicit [`ChrononBuilder`] values override environment
46//! defaults where both exist.
47//!
48//! | Setting | Builder API | Environment | Default |
49//! |---------|-------------|-------------|---------|
50//! | Store | `.scheduler_store()` / `.scheduler_store_from_global()` | — | required |
51//! | Context factory | `.context_factory()` | — | `NoOpContextFactory` |
52//! | Telemetry | `.telemetry_sink()` | — | `NoOpSink` |
53//! | Script registry | `.script_registry()` / `.auto_registry()` | — | empty or inventory |
54//! | Tick interval | `.tick_interval_ms()` | `CHRONON_TICK_INTERVAL_MS` | 250 ms |
55//! | Instance id | `.instance_id()` | — | random UUID |
56//! | Partition count | — (env only) | `CHRONON_NUM_PARTITIONS` | 64 |
57//!
58//! ### Backend connection (pass to store constructors, not `ChrononBuilder`)
59//!
60//! | Backend | Configuration |
61//! |---------|---------------|
62//! | PostgreSQL | URL to `PostgresSchedulerStore::connect`; `CHRONON_POSTGRES_URL` / `CHRONON_TEST_POSTGRES_URL` for tests |
63//! | SQLite | Path or URL to `SqliteSchedulerStore` |
64//! | Redis overlay | URL to `RedisQueueLayer::connect`; optional key prefix (default `chronon`); `CHRONON_REDIS_URL` in production |
65//!
66//! Lease TTLs, tick batch limits, worker pool, and worker concurrency are environment-only.
67//! See `chronon-scheduler` crate documentation for the full environment variable table.
68//!
69//! # Cargo features
70//!
71//! No features are enabled by default. Enable explicitly:
72//!
73//! | Feature | Type | Status |
74//! |---------|------|--------|
75//! | `mem` | `InMemorySchedulerStore` | Ready — tests and local dev |
76//! | `sqlite` | `SqliteSchedulerStore` | Ready — embedded file-backed |
77//! | `postgres` | `PostgresSchedulerStore` | Ready — shared durable |
78//! | `redis` | `PostgresRedisSchedulerStore` | Ready — Postgres + Redis claim overlay (**requires `postgres` feature**) |
79//! | `axum` | `chronon_router`, HTTP DTOs | Ready — mount on host Axum server |
80//! | `telemetry-console` | Documents `ConsoleSink` usage | Optional marker (`ConsoleSink` always re-exported) |
81
82pub use chronon_macros::script;
83pub use quark::inventory;
84
85pub mod prelude {
86    //! Curated re-exports for **application developers** building Chronon worker binaries.
87    //!
88    //! One-import surface for models, runtime boot, scheduler, executor, and the [`script`] macro.
89    //! Prefer `use chronon::prelude::*;` in worker binaries and integration tests rather than
90    //! importing internal crates directly. For durable storage wiring, also enable facade features
91    //! (`sqlite`, `postgres`, `redis`) and construct the matching [`SchedulerStore`] adapter.
92
93    pub use chronon_core::{
94        ContextFactory, Job, JobRevision, JsonScriptContextFactory, NoOpContextFactory,
95        NoOpScriptContext, Run, RunStatus, ScheduleKind, SchedulerStore, Script, ScriptContext,
96        ScriptHandle, StoreRouter, ChrononError, Result, DEFAULT_STORE_NAME,
97    };
98    pub use chronon_executor::{Executor, ExecutorEvent, ScriptDescriptor, ScriptRegistry};
99    pub use chronon_runtime::{
100        builder, Chronon, ChrononBuilder, CoordinatorService, DeploymentShape, JobSummary,
101        RemoteCoordinatorClient, resolve_remote_base_url,
102    };
103    pub use chronon_scheduler::{CronExpr, Scheduler, SchedulerConfig};
104    pub use crate::script;
105}
106
107pub use chronon_core as core;
108pub use chronon_runtime::{builder, Chronon, ChrononBuilder, CoordinatorService, DeploymentShape};
109pub use chronon_core::{ChrononError, Result, ScriptHandle};
110pub use chronon_executor::{ScriptDescriptor, ScriptRegistry};
111pub use chronon_scheduler::CronExpr;
112
113#[cfg(feature = "axum")]
114pub use chronon_axum::{chronon_router, ApiResponse, ChrononState, API_PREFIX};
115
116#[cfg(feature = "mem")]
117pub use chronon_backend_mem::{install_default_mem_store, InMemorySchedulerStore};
118
119#[cfg(feature = "sqlite")]
120pub use chronon_backend_sqlite::SqliteSchedulerStore;
121
122#[cfg(feature = "postgres")]
123pub use chronon_backend_postgres::{postgres_test_url, PostgresSchedulerStore};
124
125#[cfg(feature = "redis")]
126pub use chronon_backend_redis::{PostgresRedisSchedulerStore, RedisQueueLayer};
127
128pub use chronon_telemetry::{ConsoleSink, NoOpSink, TelemetrySink};
chronon/lib.rs

chronon/
lib.rs
