salamandr-plugin-sdk 0.3.0

Write Salamandr helpdesk extensions in Rust: safe typed wrappers for every host capability, the fetch_context wire contract, and an in-process mock host for testing.
Documentation
//! The wire contract of `scheduled_run` — unattended, periodic execution.
//!
//! A field-for-field mirror of internal/extwasm/schedule.go's
//! `ScheduledRunInput`/`ScheduledRunResult`.
//!
//! # Why this exists
//!
//! Every other entrypoint runs because somebody did something: an agent
//! opened a ticket, an agent clicked an action, a vendor delivered a
//! webhook. Nothing ran a plugin on a clock, which rules out a whole class
//! of connector — reconciling an ERP's customer list nightly, polling a
//! vendor that offers no webhooks at all, expiring stale links, sweeping a
//! queue the plugin keeps in [`crate::kv_set`]. Each of those would
//! otherwise need a runner written in Go inside Salamandr, per vendor.
//!
//! # How to use it
//!
//! Declare `schedule = true` under `[scopes]`, set
//! `schedule_every_minutes` (five minutes is the floor), and list
//! `"scheduled_run"` in `entrypoints`. The manifest is refused at install
//! if any of those disagree. Register the handler in the **`context_ops`**
//! block — its wire shape is `context_ops`' exactly.
//!
//! ```no_run
//! use salamandr_plugin_sdk::{ScheduledRunInput, ScheduledRunResult, ScheduledRunOutcome};
//!
//! fn scheduled_run(input: ScheduledRunInput) -> ScheduledRunResult {
//!     // `occurred_at` is the only clock a freestanding wasm guest has.
//!     let since = salamandr_plugin_sdk::kv_get("last_sync")?;
//!     // ... reconcile through http_fetch / core ...
//!     salamandr_plugin_sdk::kv_set("last_sync", input.occurred_at.as_bytes())?;
//!     let _ = since;
//!     Ok(ScheduledRunOutcome { message: "synced".into() })
//! }
//! ```
//!
//! # What a run is, and is not
//!
//! It is **claimed before it runs**, so a failure waits for the next
//! interval rather than being retried immediately — under-acting once
//! beats acting on every tick forever. Two worker replicas can never run
//! the same schedule for the same tenant in the same tick. And the call is
//! bounded by a host timeout: a plugin that never returns is stopped, not
//! waited on.
//!
//! There is no catch-up. If a deployment was down for a day, the next tick
//! runs the plugin once, not once per missed interval — which is why a
//! plugin that cares about the window should record its own high-water
//! mark in `host_kv` rather than assuming `every_minutes` elapsed.

use serde::{Deserialize, Serialize};

use crate::error::OpError;

/// ScheduledRunInput is what `scheduled_run` receives.
///
/// Deliberately thin: a scheduled run has no ticket, no actor and no
/// payload, and inventing context for it would be inventing a lie.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct ScheduledRunInput {
    /// RFC3339 UTC. The only clock a freestanding wasm guest has — there
    /// is no WASI and no host time function, so anything time-dependent
    /// starts here.
    #[serde(default)]
    pub occurred_at: String,
    /// The plugin's own declared interval, echoed back so a plugin
    /// reconciling "everything since last time" can compute a window
    /// without storing one itself. Note the no-catch-up caveat above.
    #[serde(default)]
    pub every_minutes: i32,
}

/// ScheduledRunOutcome is what the run reports. `message` is surfaced in
/// the admin panel as the last run's result; a plugin with nothing to say
/// returns the default.
#[derive(Debug, Clone, Default, Serialize)]
pub struct ScheduledRunOutcome {
    #[serde(skip_serializing_if = "String::is_empty")]
    pub message: String,
}

/// ScheduledRunResult is `scheduled_run`'s return type. An `Err` is
/// recorded against the schedule and shown to the admin; the next run
/// still happens on the ordinary interval.
pub type ScheduledRunResult = Result<ScheduledRunOutcome, OpError>;