1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
//! 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 ;
use crateOpError;
/// 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.
/// 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.
/// 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 = ;