Trait ScheduledPlugin 

pub trait ScheduledPlugin: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn schedules(&self) -> Result<Vec<Schedule>, String>;
    fn run(&self, ctx: &ScheduledRunCtx) -> Result<(), String>;

    // Provided methods
    fn priority(&self) -> u32 { ... }
    fn cleanup(&self) -> Result<(), String> { ... }
}

A plugin that declares cron-style background work.

Compile-time and WASM execution. All methods receive and return JSON-friendly or POD data for ABI compatibility with WASM guests. Runs are fire-and-forget from the request path’s point of view — the scheduler ticks on a dedicated task, so run must not block any foreground work and is allowed to take its time (subject to the fuel budget in fuel::RUN).

Concurrency: the host guarantees at most one concurrent invocation of run() per schedule_id per node. Across nodes, at-most-one is provided by the LockingHint in conjunction with a configured crate::locking::LockingPlugin — the E2 Locking capability. When no LockingPlugin is installed, multi-node deployments may double-fire RequireGlobal schedules and should be configured with a single scheduler node; the scheduler logs a warning at start when it detects this condition.

Required Methods

fn name(&self) -> &str

Unique identifier (e.g., "cron", "daily-reports"). Must be stable across restarts — used as part of the locking key and the metrics label.

fn schedules(&self) -> Result<Vec<Schedule>, String>

Declare the set of schedules this plugin owns.

Called once at plugin init (server start, or plugin hot-reload). The returned list is cached by the host and passed to crate::types::PluginManifest::provides_capabilities discovery, the dev dashboard, and the cap_conformance harness. Re-reading is cheap but not required — plugins are expected to return the same list for the lifetime of a process.

Returning an empty list is legal: a plugin may implement ScheduledPlugin just so it can be installed by configuration and then receive dynamic schedules from elsewhere (future extension point, not used in E1).

fn run(&self, ctx: &ScheduledRunCtx) -> Result<(), String>

Execute one scheduled run.

The host calls this when a declared schedule is due. Returns Ok(()) on success, Err(message) on failure; the scheduler records the failure in [bext-core::scheduler::TaskState::error_count] and logs the message. Plugins must not panic — panic inside a WASM run counts as an error and is caught by the host.

The method is synchronous in the trait to stay WASM-ABI friendly (like crate::lifecycle::LifecyclePlugin::on_request_complete). Native plugins that need async work should drive their own runtime inside run(); WASM plugins that need async I/O should use the host-function bridge documented in bext-core::host_fns::scheduled.

Provided Methods

fn priority(&self) -> u32

Execution order among scheduled plugins when more than one has a schedule firing in the same tick. Lower runs first. Default: 1000. The number matches the priority convention used by crate::lifecycle::LifecyclePlugin since scheduled jobs are conceptually in the same “background” family.

fn cleanup(&self) -> Result<(), String>

Called before the plugin is unloaded. Release resources (open files, database handles, etc.) here. Default: no-op.

Implementors