Crate runledger_runtime 

Async runtime loops for executing Runledger jobs against a persistence backend.

Use this crate to wire the operational pieces around runledger-core handlers and runledger-postgres storage:

• Supervisor starts and joins the worker, intent promoter, scheduler, and reaper loops for a typical worker process
• catalog::JobCatalog is the preferred startup API for handler registration, definition sync, and catalog-validated enqueue helpers
• registry::JobRegistry stores concrete handlers directly for advanced setups that manage definitions separately
• config::JobsConfig centralizes poll, lease, and concurrency settings
• observer::JobLifecycleObserver receives best-effort post-commit running, success, continuation, failure, lease-loss, and reaper outcomes

A typical service builds a shared PostgreSQL pool, registers handlers in a catalog::JobCatalog, syncs definitions during startup, and starts a Supervisor with SupervisorBuilder::with_catalog. Worker processes should call Supervisor::run_until_shutdown to observe task failures while still applying a bounded shutdown deadline. Use Supervisor::shutdown_with_timeout when shutdown is signaled externally, or Supervisor::shutdown when the caller already has an external shutdown budget or knows all loops will exit promptly.

The lower-level worker::run_worker_loop, intent_promoter::run_intent_promoter_loop, scheduler::run_scheduler_loop, and reaper::run_reaper_loop functions remain public for custom process orchestration, but Supervisor is the preferred runtime facade. Custom orchestration that uses durable enqueue intents must run both the worker and intent promoter loops.

Copy-Paste Examples

• Run a worker binary
• Enqueue one job
• Enqueue a workflow DAG
• Use an external workflow gate
• Create a scheduled job entrypoint
• Adopt continuation, retry timing, coordination, and recovery

Prelude

use runledger_runtime::prelude::*;

The runtime prelude exports the worker-process facade and configuration types. Import runledger_core::prelude::* for handler contracts and runledger_postgres::prelude::* for persistence APIs.

Run A Worker Process

use std::time::Duration;

use runledger_core::prelude::*;
use runledger_runtime::prelude::*;

struct MyHandler;

let catalog = JobCatalog::new().handler(MyHandler);
catalog.sync_definitions(&pool).await?;
let supervisor = Supervisor::builder_from_env(&pool)?
    .with_catalog(&catalog)
    .build()?;

supervisor
    .run_until_shutdown(std::future::pending::<()>(), Duration::from_secs(30))
    .await?;

Use Supervisor::run_until_shutdown for ordinary worker binaries so the process observes internal runtime task failures while still applying a bounded shutdown deadline. Use the lower-level loop functions only for custom process orchestration.

Re-exports

pub use error::Error;

pub use error::ReaperError;

pub use error::Result;

pub use error::RuntimeError;

pub use error::SchedulerError;

pub use error::WorkerError;

pub use observer::JobCompletionPersistFailedEvent;

pub use observer::JobCompletionPersistenceOperation;

pub use observer::JobContinuedEvent;

pub use observer::JobFailedEvent;

pub use observer::JobFailureDisposition;

pub use observer::JobLeaseLostEvent;

pub use observer::JobLeaseReapedDisposition;

pub use observer::JobLeaseReapedEvent;

pub use observer::JobLifecycleObserver;

pub use observer::JobLifecycleObservers;

pub use observer::JobRunningEvent;

pub use observer::JobSucceededEvent;

pub use observer::ObservedJob;

pub use supervisor::Supervisor;

pub use supervisor::SupervisorBuilder;

pub use supervisor::SupervisorShutdown;

Modules

catalog

Catalog-backed startup API for keeping handlers, job definitions, schedules, and workflow steps aligned.

config

error

intent_promoter

observer

prelude

Common runledger-runtime imports for worker-process integration.

reaper

registry

scheduler

supervisor

worker

Enums

RuntimeLoopExit

Reason a low-level runtime loop exited.