Struct JobStore 

pub struct JobStore { /* private fields */ }

Persistent storage layer for scheduled jobs.

All job definitions and run history are stored in a SQLite database managed by zeph-db migrations. The scheduled_jobs table schema is defined in migration 051_scheduler_jobs.sql.

Examples

use zeph_scheduler::JobStore;

// Open from a file path.
let store = JobStore::open("sqlite:scheduler.db").await?;
store.init().await?;

// Query job list.
let jobs = store.list_jobs().await?;
for job in &jobs {
    println!("{}: {} ({}) → {}", job.name, job.kind, job.task_mode, job.next_run);
}

Implementations

impl JobStore

pub fn new(pool: DbPool) -> Self

Create a JobStore from an existing zeph_db::DbPool.

You must call JobStore::init before any other operation to ensure the schema migrations have been applied.

pub async fn open(path: &str) -> Result<Self, SchedulerError>

Open (or create) a JobStore from a SQLite file path.

Errors

Returns SchedulerError::Db if the connection cannot be established.

pub async fn init(&self) -> Result<(), SchedulerError>

Run all pending migrations on the underlying pool.

Replaces the former inline CREATE TABLE IF NOT EXISTS DDL. The scheduled_jobs schema is now managed by migration 051_scheduler_jobs.sql in zeph-db.

Errors

Returns an error if any migration fails.

pub async fn upsert_job( &self, name: &str, cron_expr: &str, kind: &str, ) -> Result<(), SchedulerError>

Upsert a job definition.

Errors

Returns an error if the SQL statement fails.

pub async fn upsert_job_with_mode( &self, name: &str, cron_expr: &str, kind: &str, task_mode: &str, run_at: Option<&str>, task_data: &str, ) -> Result<(), SchedulerError>

Upsert a job definition with explicit task_mode, optional run_at, and task_data.

Errors

Returns an error if the SQL statement fails.

pub async fn upsert_job_with_provenance( &self, name: &str, cron_expr: &str, kind: &str, task_mode: &str, run_at: Option<&str>, task_data: &str, provenance: &str, ) -> Result<(), SchedulerError>

Upsert a job definition with explicit task_mode, task_data, and RTW-A provenance.

Errors

Returns an error if the SQL statement fails.

pub async fn insert_job( &self, name: &str, cron_expr: &str, kind: &str, task_mode: &str, run_at: Option<&str>, task_data: &str, ) -> Result<(), SchedulerError>

Insert a new job. Returns SchedulerError::DuplicateJob if a job with this name exists.

This is the CLI write path (zeph schedule add, both the cron and --run-at forms), so the row is stored with crate::task::TaskProvenance::UserAdded provenance — reflecting its genuine CLI/user origin — rather than relying on the provenance column’s DB default. Scheduler::init() hydration still force-downgrades out-of-process rows to crate::task::TaskProvenance::External regardless of the stored value (#6114), so this does not change runtime trust decisions; it keeps the stored label accurate for direct inspection (e.g. a raw DB dump) — zeph schedule list/show do not currently surface provenance.

Errors

Returns SchedulerError::DuplicateJob on unique constraint violation, or SchedulerError::Database on other SQL errors.

pub async fn record_run( &self, name: &str, timestamp: &str, next_run: &str, ) -> Result<(), SchedulerError>

Record a job execution and persist the next scheduled run time.

Errors

Returns an error if the SQL statement fails.

pub async fn mark_done(&self, name: &str) -> Result<(), SchedulerError>

Mark a one-shot job as done.

Errors

Returns an error if the SQL statement fails.

pub async fn mark_error(&self, name: &str) -> Result<(), SchedulerError>

Mark a job as permanently errored (e.g. invalid cron expression on hydration).

The job remains visible in JobStore::list_jobs_full with status = "error" so operators can identify it via zeph scheduler list without reading debug logs.

Errors

Returns an error if the SQL statement fails.

pub async fn delete_job(&self, name: &str) -> Result<bool, SchedulerError>

Delete a job by name.

Errors

Returns an error if the SQL statement fails.

pub async fn job_exists(&self, name: &str) -> Result<bool, SchedulerError>

Check if a job with the given name exists.

Errors

Returns an error if the SQL query fails.

pub async fn set_next_run( &self, name: &str, next_run: &str, ) -> Result<(), SchedulerError>

Persist the next scheduled run time for a job (used during init).

Errors

Returns an error if the SQL statement fails.

pub async fn get_next_run( &self, name: &str, ) -> Result<Option<String>, SchedulerError>

Get the persisted next run timestamp for a job.

Errors

Returns an error if the SQL query fails.

pub async fn list_jobs( &self, ) -> Result<Vec<ScheduledTaskRecord>, SchedulerError>

List all active (non-done) jobs.

Returns a ScheduledTaskRecord per active job, ordered by name. One-shot jobs without a computed next_run fall back to their run_at value; if neither is set the field is an empty string.

Errors

Returns an error if the SQL query fails.

pub async fn list_jobs_full( &self, ) -> Result<Vec<ScheduledTaskInfo>, SchedulerError>

List all active (non-done) jobs with full details for display.

The cron_expr field of each returned ScheduledTaskInfo is Some for periodic tasks with a valid expression and None for one-shot tasks or rows whose stored expression failed validation. Invalid rows are not filtered out — callers can check status to distinguish error rows.

Errors

Returns an error if the SQL query fails.

pub async fn count_active_jobs(&self) -> Result<usize, SchedulerError>

Count active (non-done) jobs.

Errors

Returns an error if the SQL query fails.

pub async fn list_recent_runs( &self, n: usize, ) -> Result<Vec<RecentRunRecord>, SchedulerError>

List the n most recently run (non-done) jobs, ordered by last_run descending.

Never-run jobs (last_run IS NULL) sort last. Ordering and truncation are pushed into SQL via ORDER BY last_run IS NULL, last_run DESC LIMIT ? rather than fetched-then-sorted in Rust: last_run IS NULL evaluates to a sortable 0/1 (SQLite) or false/true (PostgreSQL) value, giving “NULLS LAST” semantics on both backends without relying on PostgreSQL-only NULLS LAST syntax, which SQLite does not support.

Errors

Returns an error if the SQL query fails.

pub fn pool(&self) -> &DbPool

Returns a reference to the underlying connection pool.

Primarily used in tests that need to execute raw SQL against the same database.

Trait Implementations

impl Debug for JobStore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.