use serde::{Deserialize, Serialize};
use crate::ipc::jobs::JobCategory;
use crate::wire::{RunAs, Shell, Staleness};
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct Manifest {
pub id: String,
pub version: String,
#[serde(default)]
pub description: Option<String>,
pub execute: Execute,
#[serde(default)]
pub require_approval: bool,
#[serde(default)]
pub inventory: Option<InventoryHint>,
#[serde(default)]
pub emit: Option<EmitConfig>,
#[serde(default)]
pub check: Option<CheckHint>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub collect: Option<CollectHint>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub aggregate: Option<Vec<AggregateWidget>>,
#[serde(default)]
pub staleness: Staleness,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub client: Option<ClientHint>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub tags: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub origin: Option<RepoOrigin>,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, PartialEq, Eq)]
pub struct RepoOrigin {
pub path: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub repo: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub script_file: Option<String>,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Default)]
pub struct FanoutPlan {
#[serde(default)]
pub target: Target,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub rollout: Option<Rollout>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub jitter: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub deadline_at: Option<chrono::DateTime<chrono::Utc>>,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct InventoryHint {
pub display: Vec<DisplayField>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub summary: Option<Vec<DisplayField>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub explode: Option<Vec<ExplodeSpec>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub history_scalars: Option<Vec<String>>,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct CheckHint {
pub name: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub label: Option<String>,
#[serde(default = "default_status_field")]
pub status_field: String,
#[serde(default = "default_detail_field")]
pub detail_field: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub troubleshoot: Option<String>,
#[serde(default = "default_fleet")]
pub fleet: bool,
}
fn default_status_field() -> String {
"status".to_string()
}
fn default_detail_field() -> String {
"detail".to_string()
}
fn default_fleet() -> bool {
true
}
fn default_files_field() -> String {
"files".to_string()
}
pub const DEFAULT_COLLECT_MAX_SIZE: u64 = 50 * 1_000_000;
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct CollectHint {
pub name: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_size: Option<String>,
#[serde(default = "default_files_field")]
pub files_field: String,
}
impl CollectHint {
pub fn max_size_bytes(&self) -> u64 {
match &self.max_size {
Some(s) => parse_size_bytes(s).unwrap_or(DEFAULT_COLLECT_MAX_SIZE),
None => DEFAULT_COLLECT_MAX_SIZE,
}
}
}
pub fn parse_size_bytes(s: &str) -> Result<u64, String> {
let t = s.trim();
if t.is_empty() {
return Err("size must not be empty".to_string());
}
let split = t.find(|c: char| !c.is_ascii_digit()).unwrap_or(t.len());
let (num_str, unit_raw) = t.split_at(split);
if num_str.is_empty() {
return Err(format!("size '{s}': missing leading number"));
}
let num: u64 = num_str
.parse()
.map_err(|_| format!("size '{s}': bad number '{num_str}'"))?;
let mult: u64 = match unit_raw.trim().to_ascii_lowercase().as_str() {
"" | "b" => 1,
"kb" => 1_000,
"mb" => 1_000_000,
"gb" => 1_000_000_000,
"kib" => 1024,
"mib" => 1024 * 1024,
"gib" => 1024 * 1024 * 1024,
other => {
return Err(format!(
"size '{s}': unknown unit '{other}' (use B/KB/MB/GB/KiB/MiB/GiB)"
));
}
};
num.checked_mul(mult)
.ok_or_else(|| format!("size '{s}': overflow"))
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct ClientHint {
pub name: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
pub category: JobCategory,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub icon: Option<String>,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct AggregateWidget {
pub dashboard: String,
pub title: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub order: Option<i32>,
#[serde(default)]
pub scope: AggregateScope,
pub kind: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub source: Option<String>,
pub agg: AggregateAgg,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub group_by: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub bool_path: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub value_path: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub transform: Option<AggregateTransform>,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[schemars(range(min = 1))]
pub sample_minutes: Option<u32>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub exclude: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub time_bucket: Option<AggregateTimeBucket>,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[schemars(range(min = 1))]
pub limit: Option<u32>,
pub render: AggregateRender,
}
#[derive(
Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Copy, PartialEq, Eq, Default,
)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum AggregateScope {
#[default]
Pc,
Fleet,
#[serde(other)]
Unknown,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum AggregateAgg {
Count,
Ratio,
Sum,
#[serde(other)]
Unknown,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum AggregateTransform {
Host,
#[serde(other)]
Unknown,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum AggregateTimeBucket {
Hour,
#[serde(other)]
Unknown,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum AggregateRender {
Bar,
Gauge,
Timeline,
Stat,
#[serde(other)]
Unknown,
}
fn is_valid_json_path(p: &str) -> bool {
!p.is_empty()
&& p.split('.').all(|seg| {
!seg.is_empty() && seg.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
})
}
pub fn validate_aggregate_widgets(widgets: &[AggregateWidget], field: &str) -> Result<(), String> {
if widgets.is_empty() {
return Err(format!(
"`{field}:` must list at least one widget when present"
));
}
for (i, w) in widgets.iter().enumerate() {
let at = format!("{field}[{i}]");
for (label, value) in [
("dashboard", &w.dashboard),
("title", &w.title),
("kind", &w.kind),
] {
if value.trim().is_empty() {
return Err(format!("{at}.{label} must not be empty"));
}
}
if let Some(source) = &w.source {
if source.trim().is_empty() {
return Err(format!("{at}.source must not be empty when set"));
}
}
if let Some(description) = &w.description {
if description.trim().is_empty() {
return Err(format!("{at}.description must not be empty when set"));
}
}
if w.scope == AggregateScope::Unknown {
return Err(format!("{at}.scope is not a known value (pc | fleet)"));
}
if w.agg == AggregateAgg::Unknown {
return Err(format!(
"{at}.agg is not a known value (count | ratio | sum)"
));
}
if w.render == AggregateRender::Unknown {
return Err(format!(
"{at}.render is not a known value (bar | gauge | timeline | stat)"
));
}
if w.transform == Some(AggregateTransform::Unknown) {
return Err(format!("{at}.transform is not a known value (host)"));
}
if w.time_bucket == Some(AggregateTimeBucket::Unknown) {
return Err(format!("{at}.time_bucket is not a known value (hour)"));
}
for (label, path) in [
("group_by", &w.group_by),
("bool_path", &w.bool_path),
("value_path", &w.value_path),
] {
if let Some(p) = path {
if !is_valid_json_path(p) {
return Err(format!(
"{at}.{label} '{p}' must be a dotted JSON path of [A-Za-z0-9_] segments"
));
}
}
}
match w.agg {
AggregateAgg::Count => {
for (label, path) in [("bool_path", &w.bool_path), ("value_path", &w.value_path)] {
if path.is_some() {
return Err(format!("{at}.agg=count does not use `{label}`"));
}
}
}
AggregateAgg::Ratio => {
if w.bool_path.is_none() {
return Err(format!("{at}.agg=ratio requires `bool_path`"));
}
if w.value_path.is_some() {
return Err(format!("{at}.agg=ratio does not use `value_path`"));
}
}
AggregateAgg::Sum => {
if w.value_path.is_none() {
return Err(format!("{at}.agg=sum requires `value_path`"));
}
if w.bool_path.is_some() {
return Err(format!("{at}.agg=sum does not use `bool_path`"));
}
}
AggregateAgg::Unknown => {}
}
if w.group_by.as_deref() == Some("pc_id") && w.scope != AggregateScope::Fleet {
return Err(format!(
"{at}.group_by: pc_id is only valid with scope: fleet"
));
}
if w.transform.is_some() && w.group_by.as_deref() == Some("pc_id") {
return Err(format!("{at}.transform is not valid with group_by: pc_id"));
}
if w.group_by.is_none() {
if w.limit.is_some() {
return Err(format!("{at}.limit requires `group_by`"));
}
if w.transform.is_some() {
return Err(format!("{at}.transform requires `group_by`"));
}
if !w.exclude.is_empty() {
return Err(format!("{at}.exclude requires `group_by`"));
}
}
if w.limit == Some(0) {
return Err(format!("{at}.limit must be > 0"));
}
if w.sample_minutes == Some(0) {
return Err(format!("{at}.sample_minutes must be > 0"));
}
for ex in &w.exclude {
if ex.trim().is_empty() {
return Err(format!("{at}.exclude must not contain empty entries"));
}
}
if w.render == AggregateRender::Gauge && w.agg != AggregateAgg::Ratio {
return Err(format!("{at}.render=gauge is only valid with agg: ratio"));
}
match (w.render, &w.time_bucket) {
(AggregateRender::Timeline, None) => {
return Err(format!("{at}.render=timeline requires `time_bucket`"));
}
(r, Some(_)) if r != AggregateRender::Timeline => {
return Err(format!(
"{at}.time_bucket is only valid with render: timeline"
));
}
_ => {}
}
}
Ok(())
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct View {
pub id: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
pub widgets: Vec<AggregateWidget>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub tags: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub origin: Option<RepoOrigin>,
}
pub fn is_valid_resource_id(id: &str) -> bool {
!id.is_empty()
&& id
.chars()
.all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_' || c == '-')
}
impl View {
pub fn validate(&self) -> Result<(), String> {
if !is_valid_resource_id(self.id.trim()) {
return Err(
"view.id must be non-empty and only [A-Za-z0-9._-] (it's a KV key + URL segment)"
.to_string(),
);
}
validate_aggregate_widgets(&self.widgets, "widgets")?;
for tag in &self.tags {
if tag.trim().is_empty() {
return Err("tags must not contain empty entries".to_string());
}
}
Ok(())
}
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct EmitConfig {
#[serde(rename = "type")]
pub kind: EmitKind,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub watermark_path: Option<String>,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum EmitKind {
Events,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct ExplodeSpec {
pub field: String,
pub table: String,
pub primary_key: Vec<String>,
pub columns: Vec<ExplodeColumn>,
#[serde(default)]
pub track_history: bool,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct ExplodeColumn {
pub field: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[serde(rename = "type")]
pub kind: Option<String>,
#[serde(default)]
pub index: bool,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct DisplayField {
pub field: String,
pub label: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[serde(rename = "type")]
pub kind: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub columns: Option<Vec<DisplayField>>,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct Rollout {
#[serde(default)]
pub strategy: RolloutStrategy,
pub waves: Vec<Wave>,
}
#[derive(
Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Copy, PartialEq, Eq, Default,
)]
#[serde(rename_all = "lowercase")]
pub enum RolloutStrategy {
#[default]
Wave,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct Wave {
pub group: String,
pub delay: String,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Default)]
pub struct Target {
#[serde(default)]
pub groups: Vec<String>,
#[serde(default)]
pub pcs: Vec<String>,
#[serde(default)]
pub all: bool,
}
impl Target {
pub fn is_specified(&self) -> bool {
self.all || !self.groups.is_empty() || !self.pcs.is_empty()
}
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct Execute {
pub shell: ExecuteShell,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub script: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub script_file: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub script_object: Option<String>,
pub timeout: String,
#[serde(default)]
pub run_as: RunAs,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub cwd: Option<String>,
}
impl Execute {
fn has_inline_script(&self) -> bool {
matches!(&self.script, Some(s) if !s.is_empty())
}
pub fn validate_script_source(&self) -> Result<(), String> {
let inline = self.has_inline_script();
let file = self.script_file.is_some();
let obj = self.script_object.is_some();
let set = [inline, file, obj].into_iter().filter(|b| *b).count();
match set {
1 => Ok(()),
0 => Err("execute: one of `script`, `script_file`, `script_object` must be set".into()),
_ => Err(format!(
"execute: only one of `script` / `script_file` / `script_object` may be set \
(got script={inline}, script_file={file}, script_object={obj})"
)),
}
}
}
impl Manifest {
pub fn validate(&self) -> Result<(), String> {
self.execute.validate_script_source()?;
if self.emit.is_some() && (self.inventory.is_some() || self.check.is_some()) {
return Err(
"`emit:` is incompatible with `inventory:` / `check:` — emit's stdout is NDJSON \
timeline events (and omitted from the result), while inventory/check read a \
single JSON object from stdout"
.to_string(),
);
}
if self.collect.is_some()
&& (self.inventory.is_some() || self.check.is_some() || self.emit.is_some())
{
return Err(
"`collect:` is incompatible with `inventory:` / `check:` / `emit:` — collect \
reads its own `files` JSON object from stdout. (It composes with `client:`.)"
.to_string(),
);
}
if let Some(check) = &self.check {
for (label, value) in [
("check.name", &check.name),
("check.status_field", &check.status_field),
("check.detail_field", &check.detail_field),
] {
if value.trim().is_empty() {
return Err(format!("{label} must not be empty"));
}
}
if let Some(troubleshoot) = &check.troubleshoot {
if troubleshoot.trim().is_empty() {
return Err("check.troubleshoot must not be empty when set".to_string());
}
}
if let Some(label) = &check.label {
if label.trim().is_empty() {
return Err("check.label must not be empty when set".to_string());
}
}
}
if let Some(client) = &self.client {
if client.name.trim().is_empty() {
return Err("client.name must not be empty".to_string());
}
for (label, value) in [
("client.description", &client.description),
("client.icon", &client.icon),
] {
if let Some(v) = value {
if v.trim().is_empty() {
return Err(format!("{label} must not be empty when set"));
}
}
}
}
if let Some(collect) = &self.collect {
if collect.name.trim().is_empty() {
return Err("collect.name must not be empty".to_string());
}
if collect.files_field.trim().is_empty() {
return Err("collect.files_field must not be empty".to_string());
}
if let Some(description) = &collect.description {
if description.trim().is_empty() {
return Err("collect.description must not be empty when set".to_string());
}
}
if let Some(max_size) = &collect.max_size {
parse_size_bytes(max_size).map_err(|e| format!("collect.max_size: {e}"))?;
}
}
if let Some(widgets) = &self.aggregate {
validate_aggregate_widgets(widgets, "aggregate")?;
}
for tag in &self.tags {
if tag.trim().is_empty() {
return Err("tags must not contain empty entries".to_string());
}
}
Ok(())
}
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum ExecuteShell {
Powershell,
Cmd,
}
impl From<ExecuteShell> for Shell {
fn from(s: ExecuteShell) -> Self {
match s {
ExecuteShell::Powershell => Shell::Powershell,
ExecuteShell::Cmd => Shell::Cmd,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn example_check_job_yamls_parse_and_validate() {
let jobs = [
(
"check-bitlocker",
include_str!("../../../configs/jobs/check-bitlocker.yaml"),
),
(
"check-av-signature",
include_str!("../../../configs/jobs/check-av-signature.yaml"),
),
(
"check-cert-expiry",
include_str!("../../../configs/jobs/check-cert-expiry.yaml"),
),
(
"check-disk-space",
include_str!("../../../configs/jobs/check-disk-space.yaml"),
),
(
"check-pending-reboot",
include_str!("../../../configs/jobs/check-pending-reboot.yaml"),
),
(
"check-defender-rtp",
include_str!("../../../configs/jobs/check-defender-rtp.yaml"),
),
(
"check-firewall",
include_str!("../../../configs/jobs/check-firewall.yaml"),
),
];
for (name, yaml) in jobs {
let m: Manifest =
serde_yaml::from_str(yaml).unwrap_or_else(|e| panic!("{name} parse: {e}"));
m.validate()
.unwrap_or_else(|e| panic!("{name} validate: {e}"));
let check = m
.check
.as_ref()
.unwrap_or_else(|| panic!("{name} must carry a check: hint"));
assert!(!check.name.trim().is_empty(), "{name} check.name empty");
assert_eq!(
m.execute.run_as,
RunAs::System,
"{name} should run_as system"
);
}
}
#[test]
fn example_client_job_yamls_parse_and_validate() {
let jobs = [
(
"fix-teams-cache",
JobCategory::Troubleshoot,
include_str!("../../../configs/jobs/fix-teams-cache.yaml"),
),
(
"chrome-update",
JobCategory::SoftwareUpdate,
include_str!("../../../configs/jobs/chrome-update.yaml"),
),
(
"install-slack",
JobCategory::Catalog,
include_str!("../../../configs/jobs/install-slack.yaml"),
),
(
"fix-defender-rtp",
JobCategory::Troubleshoot,
include_str!("../../../configs/jobs/fix-defender-rtp.yaml"),
),
];
for (id, category, yaml) in jobs {
let m: Manifest =
serde_yaml::from_str(yaml).unwrap_or_else(|e| panic!("{id} parse: {e}"));
m.validate()
.unwrap_or_else(|e| panic!("{id} validate: {e}"));
assert_eq!(m.id, id, "{id} id mismatch");
let client = m
.client
.as_ref()
.unwrap_or_else(|| panic!("{id} must carry a client: block"));
assert!(!client.name.trim().is_empty(), "{id} client.name empty");
assert_eq!(client.category, category, "{id} category");
}
}
#[test]
fn example_collect_job_yaml_parses_and_validates() {
let yaml = include_str!("../../../configs/jobs/collect-diagnostics.yaml");
let m: Manifest = serde_yaml::from_str(yaml).expect("collect-diagnostics parse");
m.validate().expect("collect-diagnostics validate");
assert_eq!(m.id, "collect-diagnostics");
let collect = m.collect.as_ref().expect("collect: block present");
assert!(!collect.name.trim().is_empty());
assert_eq!(collect.files_field, "files");
assert_eq!(collect.max_size_bytes(), 50_000_000);
assert!(
m.client.is_some(),
"collect-diagnostics also carries client:"
);
}
#[test]
fn example_event_collector_job_yamls_parse_and_validate() {
let jobs = [
(
"collect-winlog-events",
include_str!("../../../configs/jobs/collect-winlog-events.yaml"),
),
(
"collect-winlog-logons-all",
include_str!("../../../configs/jobs/collect-winlog-logons-all.yaml"),
),
(
"collect-wlan-events",
include_str!("../../../configs/jobs/collect-wlan-events.yaml"),
),
];
for (id, yaml) in jobs {
let m: Manifest =
crate::strict::from_yaml_str(yaml).unwrap_or_else(|e| panic!("{id} parse: {e}"));
m.validate()
.unwrap_or_else(|e| panic!("{id} validate: {e}"));
assert_eq!(m.id, id, "{id} id mismatch");
let emit = m
.emit
.as_ref()
.unwrap_or_else(|| panic!("{id} must carry an emit: block"));
assert_eq!(emit.kind, EmitKind::Events, "{id} emit.type");
assert!(
m.check.is_none() && m.inventory.is_none(),
"{id}: emit jobs must not pair with check/inventory"
);
}
}
#[test]
fn example_inventory_job_yamls_parse_and_validate() {
let jobs = [
(
"inventory-hw",
include_str!("../../../configs/jobs/inventory-hw.yaml"),
),
(
"inventory-sw",
include_str!("../../../configs/jobs/inventory-sw.yaml"),
),
(
"inventory-driver",
include_str!("../../../configs/jobs/inventory-driver.yaml"),
),
];
for (id, yaml) in jobs {
let m: Manifest =
serde_yaml::from_str(yaml).unwrap_or_else(|e| panic!("{id} parse: {e}"));
m.validate()
.unwrap_or_else(|e| panic!("{id} validate: {e}"));
assert_eq!(m.id, id, "{id} id mismatch");
assert!(m.inventory.is_some(), "{id} must carry an inventory: block");
assert!(m.emit.is_none(), "{id}: inventory jobs must not set emit:");
}
}
#[test]
fn example_check_schedule_yamls_parse_and_validate() {
let schedules = [
(
"check-bitlocker",
include_str!("../../../configs/schedules/check-bitlocker.yaml"),
),
(
"check-av-signature",
include_str!("../../../configs/schedules/check-av-signature.yaml"),
),
(
"check-cert-expiry",
include_str!("../../../configs/schedules/check-cert-expiry.yaml"),
),
(
"check-disk-space",
include_str!("../../../configs/schedules/check-disk-space.yaml"),
),
(
"check-pending-reboot",
include_str!("../../../configs/schedules/check-pending-reboot.yaml"),
),
(
"check-defender-rtp",
include_str!("../../../configs/schedules/check-defender-rtp.yaml"),
),
(
"check-firewall",
include_str!("../../../configs/schedules/check-firewall.yaml"),
),
];
for (name, yaml) in schedules {
let s: Schedule =
serde_yaml::from_str(yaml).unwrap_or_else(|e| panic!("{name} schedule parse: {e}"));
s.validate()
.unwrap_or_else(|e| panic!("{name} schedule validate: {e}"));
assert_eq!(s.job_id, name, "{name} schedule must reference its job");
}
}
#[test]
fn example_inventory_schedule_yamls_parse_and_validate() {
let schedules = [
(
"inventory-hw",
include_str!("../../../configs/schedules/inventory-hw.yaml"),
),
(
"inventory-sw",
include_str!("../../../configs/schedules/inventory-sw.yaml"),
),
(
"inventory-driver",
include_str!("../../../configs/schedules/inventory-driver.yaml"),
),
];
for (name, yaml) in schedules {
let s: Schedule =
serde_yaml::from_str(yaml).unwrap_or_else(|e| panic!("{name} schedule parse: {e}"));
s.validate()
.unwrap_or_else(|e| panic!("{name} schedule validate: {e}"));
assert_eq!(s.job_id, name, "{name} schedule must reference its job");
}
}
#[test]
fn target_is_specified_requires_at_least_one_field() {
let empty = Target::default();
assert!(!empty.is_specified());
let with_all = Target {
all: true,
..Target::default()
};
assert!(with_all.is_specified());
let with_groups = Target {
groups: vec!["canary".into()],
..Target::default()
};
assert!(with_groups.is_specified());
let with_pcs = Target {
pcs: vec!["pc-01".into()],
..Target::default()
};
assert!(with_pcs.is_specified());
}
#[test]
fn manifest_deserialises_minimal_yaml() {
let yaml = r#"
id: echo-test
version: 0.0.1
execute:
shell: powershell
script: "echo 'kanade'"
timeout: 30s
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
assert_eq!(m.id, "echo-test");
assert_eq!(m.version, "0.0.1");
assert!(matches!(m.execute.shell, ExecuteShell::Powershell));
assert_eq!(
m.execute.script.as_deref().map(str::trim),
Some("echo 'kanade'")
);
assert!(m.execute.script_file.is_none());
assert!(m.execute.script_object.is_none());
assert_eq!(m.execute.timeout, "30s");
assert!(!m.require_approval);
m.validate()
.expect("inline-script manifest passes validation");
}
#[test]
fn manifest_parses_check_job_and_validates() {
let yaml = r#"
id: check-bitlocker
version: 0.1.0
execute:
shell: powershell
run_as: system
timeout: 15s
script: |
[pscustomobject]@{ status = 'ok'; detail = 'all volumes protected' } | ConvertTo-Json -Compress
check:
name: bitlocker
troubleshoot: fix-bitlocker
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
let check = m.check.as_ref().expect("check hint present");
assert_eq!(check.name, "bitlocker");
assert_eq!(check.troubleshoot.as_deref(), Some("fix-bitlocker"));
assert_eq!(check.status_field, "status");
assert_eq!(check.detail_field, "detail");
assert!(m.inventory.is_none() && m.emit.is_none());
m.validate().expect("check-only manifest passes validation");
}
#[test]
fn manifest_check_defaults_and_custom_fields() {
let m: Manifest = serde_yaml::from_str(
r#"
id: check-disk
version: 0.1.0
execute:
shell: powershell
script: "[pscustomobject]@{ status = 'ok' } | ConvertTo-Json -Compress"
timeout: 10s
check:
name: disk_free
"#,
)
.expect("parse");
let c = m.check.as_ref().unwrap();
assert_eq!(c.name, "disk_free");
assert_eq!(c.status_field, "status");
assert_eq!(c.detail_field, "detail");
assert!(c.troubleshoot.is_none());
m.validate().expect("validates");
let m2: Manifest = serde_yaml::from_str(
r#"
id: check-custom
version: 0.1.0
execute:
shell: powershell
script: "echo x"
timeout: 10s
check:
name: patch_level
status_field: compliance
detail_field: summary
"#,
)
.expect("parse");
let c2 = m2.check.as_ref().unwrap();
assert_eq!(c2.status_field, "compliance");
assert_eq!(c2.detail_field, "summary");
}
#[test]
fn manifest_allows_check_composed_with_inventory() {
let yaml = r#"
id: check-bitlocker-detailed
version: 0.1.0
execute:
shell: powershell
script: "echo x"
timeout: 10s
check:
name: bitlocker
inventory:
display:
- { field: status, label: Status }
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
assert!(m.check.is_some() && m.inventory.is_some());
m.validate().expect("check + inventory compose");
}
#[test]
fn manifest_parses_collect_job_and_validates() {
let yaml = r#"
id: collect-diagnostics
version: 0.1.0
execute:
shell: powershell
run_as: system
timeout: 120s
script: |
@{ files = @("$env:KANADE_COLLECT_DIR/system.csv") } | ConvertTo-Json
collect:
name: "Full diagnostics"
description: "Event logs + process"
max_size: 50MB
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
let c = m.collect.as_ref().expect("collect hint present");
assert_eq!(c.name, "Full diagnostics");
assert_eq!(c.files_field, "files"); assert_eq!(c.max_size_bytes(), 50_000_000);
m.validate().expect("collect-only manifest validates");
}
#[test]
fn manifest_collect_max_size_defaults_when_unset() {
let m: Manifest = serde_yaml::from_str(
r#"
id: collect-min
version: 0.1.0
execute:
shell: powershell
script: "echo x"
timeout: 10s
collect:
name: minimal
"#,
)
.expect("parse");
let c = m.collect.as_ref().unwrap();
assert!(c.max_size.is_none());
assert_eq!(c.max_size_bytes(), DEFAULT_COLLECT_MAX_SIZE);
m.validate().expect("validates");
}
#[test]
fn manifest_allows_collect_with_client() {
let yaml = r#"
id: collect-diag-client
version: 0.1.0
execute:
shell: powershell
script: "echo x"
timeout: 10s
collect:
name: diagnostics
client:
name: "Send diagnostics"
category: troubleshoot
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
assert!(m.collect.is_some() && m.client.is_some());
m.validate().expect("collect + client compose");
}
#[test]
fn manifest_rejects_collect_combined_with_inventory() {
let yaml = r#"
id: bad-collect-mix
version: 0.1.0
execute:
shell: powershell
script: "echo x"
timeout: 10s
collect:
name: diag
inventory:
display:
- { field: status, label: Status }
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
let err = m
.validate()
.expect_err("collect + inventory must be rejected");
assert!(err.contains("collect"), "error mentions collect: {err}");
}
#[test]
fn manifest_rejects_collect_combined_with_check_or_emit() {
for extra in ["check:\n name: health\n", "emit:\n type: events\n"] {
let yaml = format!(
"id: bad-collect-mix\nversion: 0.1.0\nexecute:\n shell: powershell\n \
script: \"echo x\"\n timeout: 10s\ncollect:\n name: diag\n{extra}"
);
let m: Manifest = serde_yaml::from_str(&yaml).expect("parse");
let err = m
.validate()
.expect_err("collect + stdout-consuming hint must fail");
assert!(err.contains("collect"), "error mentions collect: {err}");
}
}
#[test]
fn manifest_rejects_collect_empty_name_and_bad_size() {
let empty_name: Manifest = serde_yaml::from_str(
r#"
id: c
version: 0.1.0
execute: { shell: powershell, script: "echo x", timeout: 10s }
collect: { name: " " }
"#,
)
.expect("parse");
assert!(
empty_name.validate().is_err(),
"blank collect.name rejected"
);
let bad_size: Manifest = serde_yaml::from_str(
r#"
id: c
version: 0.1.0
execute: { shell: powershell, script: "echo x", timeout: 10s }
collect: { name: diag, max_size: "50 quux" }
"#,
)
.expect("parse");
let err = bad_size.validate().expect_err("bad max_size rejected");
assert!(err.contains("max_size"), "error mentions max_size: {err}");
}
#[test]
fn parse_size_bytes_units() {
assert_eq!(parse_size_bytes("1024").unwrap(), 1024);
assert_eq!(parse_size_bytes("1B").unwrap(), 1);
assert_eq!(parse_size_bytes("50MB").unwrap(), 50_000_000);
assert_eq!(parse_size_bytes("500 KB").unwrap(), 500_000);
assert_eq!(parse_size_bytes("1GiB").unwrap(), 1024 * 1024 * 1024);
assert_eq!(parse_size_bytes("2mib").unwrap(), 2 * 1024 * 1024);
assert!(parse_size_bytes("").is_err());
assert!(parse_size_bytes("MB").is_err());
assert!(parse_size_bytes("12 zonks").is_err());
}
#[test]
fn manifest_rejects_check_combined_with_emit() {
let yaml = r#"
id: bad-mix
version: 0.1.0
execute:
shell: powershell
script: "echo x"
timeout: 10s
check:
name: bitlocker
emit:
type: events
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
let err = m.validate().expect_err("emit + check must fail");
assert!(err.contains("incompatible"), "err: {err}");
}
#[test]
fn manifest_rejects_emit_combined_with_inventory() {
let yaml = r#"
id: bad-mix-2
version: 0.1.0
execute:
shell: powershell
script: "echo x"
timeout: 10s
emit:
type: events
inventory:
display:
- { field: status, label: Status }
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
let err = m.validate().expect_err("emit + inventory must fail");
assert!(err.contains("incompatible"), "err: {err}");
}
#[test]
fn manifest_rejects_empty_check_field_names() {
let base = |inner: &str| {
format!(
"id: c\nversion: 0.1.0\nexecute:\n shell: powershell\n script: \"echo x\"\n timeout: 10s\ncheck:\n{inner}"
)
};
for inner in [
" name: \"\"\n",
" name: ok\n status_field: \"\"\n",
" name: ok\n detail_field: \" \"\n",
" name: ok\n troubleshoot: \" \"\n",
] {
let m: Manifest = serde_yaml::from_str(&base(inner)).expect("parse");
let err = m.validate().expect_err("empty field must fail");
assert!(err.contains("must not be empty"), "err: {err}");
}
}
#[test]
fn manifest_client_absent_by_default() {
let yaml = r#"
id: echo-test
version: 0.0.1
execute:
shell: powershell
script: "echo 'kanade'"
timeout: 30s
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
assert!(m.client.is_none());
m.validate().expect("operator-only job validates");
}
#[test]
fn manifest_client_parses_and_validates() {
let yaml = r#"
id: fix-teams-cache
version: 1.0.0
execute:
shell: powershell
script: "echo clearing"
timeout: 60s
client:
name: "Teams のキャッシュをクリア"
description: "Teams が重いときに試してください"
category: troubleshoot
icon: brush-cleaning
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
let c = m.client.as_ref().expect("client block present");
assert_eq!(c.name, "Teams のキャッシュをクリア");
assert_eq!(
c.description.as_deref(),
Some("Teams が重いときに試してください")
);
assert_eq!(c.category, JobCategory::Troubleshoot);
assert_eq!(c.icon.as_deref(), Some("brush-cleaning"));
m.validate().expect("user-invokable job validates");
}
#[test]
fn manifest_client_minimal_only_name_and_category() {
let yaml = r#"
id: install-slack
version: 1.0.0
execute:
shell: powershell
script: "echo install"
timeout: 600s
client:
name: Slack
category: catalog
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
let c = m.client.as_ref().expect("client present");
assert_eq!(c.category, JobCategory::Catalog);
assert!(c.description.is_none() && c.icon.is_none());
m.validate().expect("minimal client validates");
}
#[test]
fn manifest_client_rejects_blank_name() {
let yaml = r#"
id: j
version: 1.0.0
execute:
shell: powershell
script: "echo x"
timeout: 30s
client:
name: " "
category: catalog
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
let err = m.validate().expect_err("blank name must fail");
assert!(err.contains("client.name"), "err: {err}");
}
#[test]
fn manifest_client_rejects_blank_optional_fields() {
for (field, line) in [
("client.description", " description: \" \"\n"),
("client.icon", " icon: \"\"\n"),
] {
let yaml = format!(
"id: j\nversion: 1.0.0\nexecute:\n shell: powershell\n script: \"echo x\"\n timeout: 30s\nclient:\n name: A\n category: catalog\n{line}"
);
let m: Manifest = serde_yaml::from_str(&yaml).expect("parse");
let err = m.validate().expect_err("blank optional field must fail");
assert!(err.contains(field), "expected {field} in err: {err}");
}
}
#[test]
fn manifest_client_requires_category_at_parse() {
let yaml = r#"
id: j
version: 1.0.0
execute:
shell: powershell
script: "echo x"
timeout: 30s
client:
name: "A job"
"#;
let r: Result<Manifest, _> = serde_yaml::from_str(yaml);
assert!(
r.is_err(),
"missing category must be a parse error, got {r:?}"
);
}
#[test]
fn manifest_client_rejects_unknown_field() {
let yaml = r#"
id: j
version: 1.0.0
execute:
shell: powershell
script: "echo x"
timeout: 30s
client:
name: "A job"
category: catalog
displayname: oops
"#;
let r = crate::strict::from_yaml_str::<Manifest>(yaml);
let err = r.expect_err("unknown client field must be rejected at the write boundary");
assert!(err.contains("displayname"), "{err}");
let m: Manifest = serde_yaml::from_str(yaml).expect("tolerant read");
assert_eq!(m.client.as_ref().map(|c| c.name.as_str()), Some("A job"));
}
#[test]
fn manifest_tags_default_empty() {
let yaml = r#"
id: echo-test
version: 0.0.1
execute:
shell: powershell
script: "echo 'kanade'"
timeout: 30s
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
assert!(m.tags.is_empty());
m.validate().expect("tag-less job validates");
let json = serde_json::to_string(&m).expect("serialize");
assert!(
!json.contains("tags"),
"empty tags must not serialise: {json}"
);
}
#[test]
fn manifest_parses_and_validates_tags() {
let yaml = r#"
id: check-bitlocker
version: 0.1.0
execute:
shell: powershell
script: "echo x"
timeout: 30s
tags: [security, windows, health-check]
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
assert_eq!(m.tags, vec!["security", "windows", "health-check"]);
m.validate().expect("tagged job validates");
let json = serde_json::to_string(&m).expect("serialize");
assert!(json.contains("\"tags\""), "non-empty tags must serialise");
}
#[test]
fn manifest_rejects_blank_tag() {
let yaml = r#"
id: j
version: 0.1.0
execute:
shell: powershell
script: "echo x"
timeout: 30s
tags: [ok, " "]
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
let err = m.validate().expect_err("blank tag must fail");
assert!(err.contains("tags must not contain empty"), "err: {err}");
}
fn manifest_with_aggregate(aggregate_block: &str) -> Manifest {
let yaml = format!(
"id: t\nversion: 0.0.1\nexecute:\n shell: powershell\n script: echo hi\n timeout: 30s\n{aggregate_block}"
);
serde_yaml::from_str(&yaml).expect("parse aggregate manifest")
}
#[test]
fn aggregate_accepts_full_valid_spec() {
let m = manifest_with_aggregate(
"emit:\n type: events\naggregate:\n\
- { dashboard: Utilization, title: Top apps, kind: app_sample, agg: count, group_by: foreground.app, sample_minutes: 2, exclude: [LockApp], render: bar }\n\
- { dashboard: Utilization, title: Active ratio, kind: presence, agg: ratio, bool_path: active, sample_minutes: 5, render: gauge }\n\
- { dashboard: Utilization, title: By hour, kind: presence, agg: ratio, bool_path: active, time_bucket: hour, render: timeline }\n\
- { dashboard: Reliability, title: Crashes by PC, scope: fleet, kind: unexpected_shutdown, agg: count, group_by: pc_id, render: bar }\n\
- { dashboard: Reliability, title: Total crashes, scope: fleet, kind: unexpected_shutdown, agg: count, render: stat }\n",
);
m.validate().expect("valid aggregate spec");
}
#[test]
fn aggregate_rejects_empty_list() {
let m = manifest_with_aggregate("aggregate: []\n");
let err = m.validate().expect_err("empty list must fail");
assert!(err.contains("at least one widget"), "err: {err}");
}
#[test]
fn aggregate_rejects_ratio_without_bool_path() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: presence, agg: ratio, render: gauge }\n",
);
let err = m.validate().expect_err("ratio needs bool_path");
assert!(err.contains("agg=ratio requires `bool_path`"), "err: {err}");
}
#[test]
fn aggregate_rejects_sum_without_value_path() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: io, agg: sum, render: bar }\n",
);
let err = m.validate().expect_err("sum needs value_path");
assert!(err.contains("agg=sum requires `value_path`"), "err: {err}");
}
#[test]
fn aggregate_rejects_pc_id_group_without_fleet() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: presence, agg: count, group_by: pc_id, render: bar }\n",
);
let err = m.validate().expect_err("pc_id grouping needs fleet");
assert!(
err.contains("pc_id is only valid with scope: fleet"),
"err: {err}"
);
}
#[test]
fn aggregate_rejects_transform_with_pc_id_group() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, scope: fleet, kind: web_visit, agg: count, group_by: pc_id, transform: host, render: bar }\n",
);
let err = m
.validate()
.expect_err("transform on pc_id grouping must fail");
assert!(
err.contains("transform is not valid with group_by: pc_id"),
"err: {err}"
);
}
#[test]
fn aggregate_rejects_timeline_without_bucket() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: presence, agg: ratio, bool_path: active, render: timeline }\n",
);
let err = m.validate().expect_err("timeline needs a bucket");
assert!(
err.contains("render=timeline requires `time_bucket`"),
"err: {err}"
);
}
#[test]
fn aggregate_rejects_bucket_on_non_timeline() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: presence, agg: ratio, bool_path: active, time_bucket: hour, render: gauge }\n",
);
let err = m.validate().expect_err("bucket only on timeline");
assert!(
err.contains("time_bucket is only valid with render: timeline"),
"err: {err}"
);
}
#[test]
fn aggregate_rejects_unsafe_json_path() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: k, agg: count, group_by: \"foo'; DROP\", render: bar }\n",
);
let err = m.validate().expect_err("unsafe path must fail");
assert!(err.contains("dotted JSON path"), "err: {err}");
}
#[test]
fn aggregate_rejects_blank_title() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: \" \", kind: k, agg: count, render: stat }\n",
);
let err = m.validate().expect_err("blank title must fail");
assert!(err.contains("title must not be empty"), "err: {err}");
}
#[test]
fn aggregate_rejects_blank_kind() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: \" \", agg: count, render: stat }\n",
);
let err = m.validate().expect_err("blank kind must fail");
assert!(err.contains("kind must not be empty"), "err: {err}");
}
#[test]
fn aggregate_rejects_blank_source_when_set() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: k, source: \"\", agg: count, render: stat }\n",
);
let err = m.validate().expect_err("blank source must fail");
assert!(
err.contains("source must not be empty when set"),
"err: {err}"
);
}
#[test]
fn aggregate_accepts_description_and_rejects_blank() {
let ok = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, description: \"samples x 2 min\", kind: k, agg: count, render: stat }\n",
);
ok.validate()
.expect("description is a valid optional field");
assert_eq!(
ok.aggregate.as_ref().unwrap()[0].description.as_deref(),
Some("samples x 2 min")
);
let bad = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, description: \" \", kind: k, agg: count, render: stat }\n",
);
let err = bad.validate().expect_err("blank description must fail");
assert!(
err.contains("description must not be empty when set"),
"err: {err}"
);
}
#[test]
fn aggregate_rejects_count_with_value_path() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: k, agg: count, value_path: bytes, render: stat }\n",
);
let err = m.validate().expect_err("count must not use value_path");
assert!(
err.contains("agg=count does not use `value_path`"),
"err: {err}"
);
}
#[test]
fn aggregate_rejects_ratio_with_value_path() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: k, agg: ratio, bool_path: active, value_path: bytes, render: gauge }\n",
);
let err = m.validate().expect_err("ratio must not use value_path");
assert!(
err.contains("agg=ratio does not use `value_path`"),
"err: {err}"
);
}
#[test]
fn aggregate_rejects_gauge_without_ratio() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: k, agg: count, group_by: app, render: gauge }\n",
);
let err = m.validate().expect_err("gauge needs ratio");
assert!(
err.contains("render=gauge is only valid with agg: ratio"),
"err: {err}"
);
}
#[test]
fn aggregate_rejects_limit_without_group_by() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: k, agg: count, limit: 5, render: stat }\n",
);
let err = m.validate().expect_err("limit needs group_by");
assert!(err.contains("limit requires `group_by`"), "err: {err}");
}
#[test]
fn aggregate_rejects_exclude_without_group_by() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: k, agg: count, exclude: [x], render: stat }\n",
);
let err = m.validate().expect_err("exclude needs group_by");
assert!(err.contains("exclude requires `group_by`"), "err: {err}");
}
#[test]
fn aggregate_rejects_zero_limit_and_zero_sample_minutes() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: k, agg: count, group_by: app, limit: 0, render: bar }\n",
);
assert!(m.validate().unwrap_err().contains("limit must be > 0"));
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: k, agg: count, group_by: app, sample_minutes: 0, render: bar }\n",
);
assert!(
m.validate()
.unwrap_err()
.contains("sample_minutes must be > 0")
);
}
#[test]
fn aggregate_rejects_empty_exclude_entry() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: k, agg: count, group_by: app, exclude: [\" \"], render: bar }\n",
);
let err = m.validate().expect_err("blank exclude entry must fail");
assert!(
err.contains("exclude must not contain empty entries"),
"err: {err}"
);
}
#[test]
fn aggregate_rejects_malformed_dotted_paths() {
for bad in [".foo", "foo.", "foo..bar", "."] {
let m = manifest_with_aggregate(&format!(
"aggregate:\n- {{ dashboard: D, title: T, kind: k, agg: count, group_by: \"{bad}\", render: bar }}\n"
));
let err = m.validate().expect_err("malformed path must fail");
assert!(err.contains("dotted JSON path"), "path {bad}: {err}");
}
}
#[test]
fn aggregate_rejects_unknown_enum_value() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, kind: k, agg: count, render: heatmap }\n",
);
let err = m.validate().expect_err("unknown render must fail");
assert!(err.contains("render is not a known value"), "err: {err}");
}
#[test]
fn aggregate_accepts_order_field() {
let m = manifest_with_aggregate(
"aggregate:\n- { dashboard: D, title: T, order: -5, kind: k, agg: count, render: stat }\n",
);
m.validate().expect("order is a valid optional field");
let w = &m.aggregate.as_ref().unwrap()[0];
assert_eq!(w.order, Some(-5));
}
fn view_from(yaml_body: &str) -> View {
serde_yaml::from_str(&format!("id: v1\n{yaml_body}")).expect("parse view")
}
#[test]
fn view_accepts_valid_widgets() {
let v = view_from(
"widgets:\n\
- { dashboard: Reliability, title: Crashes by PC, scope: fleet, kind: unexpected_shutdown, agg: count, group_by: pc_id, render: bar }\n\
- { dashboard: Reliability, title: Total, scope: fleet, kind: unexpected_shutdown, agg: count, render: stat }\n",
);
v.validate().expect("valid view");
}
#[test]
fn view_rejects_empty_widgets() {
let v = view_from("widgets: []\n");
let err = v.validate().expect_err("empty widgets must fail");
assert!(err.contains("at least one widget"), "err: {err}");
}
#[test]
fn view_rejects_blank_id() {
let v: View = serde_yaml::from_str(
"id: \" \"\nwidgets:\n- { dashboard: D, title: T, kind: k, agg: count, render: stat }\n",
)
.expect("parse");
let err = v.validate().expect_err("blank id must fail");
assert!(err.contains("view.id must"), "err: {err}");
}
#[test]
fn view_rejects_unsafe_id() {
for bad in ["../etc", "a/b", "has space", "x;y"] {
let v: View = serde_yaml::from_str(&format!(
"id: \"{bad}\"\nwidgets:\n- {{ dashboard: D, title: T, kind: k, agg: count, render: stat }}\n",
))
.expect("parse");
let err = v.validate().expect_err("unsafe id must fail");
assert!(err.contains("[A-Za-z0-9._-]"), "id {bad}: {err}");
}
assert!(is_valid_resource_id("dashboards-fleet.v1_2"));
}
#[test]
fn view_reuses_shared_widget_validation() {
let v = view_from(
"widgets:\n- { dashboard: D, title: T, kind: presence, agg: ratio, render: gauge }\n",
);
let err = v.validate().expect_err("ratio without bool_path must fail");
assert!(
err.contains("widgets[0].agg=ratio requires `bool_path`"),
"err: {err}"
);
}
fn execute_with(
script: Option<&str>,
script_file: Option<&str>,
script_object: Option<&str>,
) -> Execute {
Execute {
shell: ExecuteShell::Powershell,
script: script.map(str::to_owned),
script_file: script_file.map(str::to_owned),
script_object: script_object.map(str::to_owned),
timeout: "30s".into(),
run_as: RunAs::default(),
cwd: None,
}
}
#[test]
fn validate_accepts_inline_script() {
let e = execute_with(Some("echo hi"), None, None);
assert!(e.validate_script_source().is_ok());
}
#[test]
fn validate_accepts_script_file_alone() {
let e = execute_with(None, Some("scripts/cleanup.ps1"), None);
assert!(e.validate_script_source().is_ok());
}
#[test]
fn validate_accepts_script_object_alone() {
let e = execute_with(None, None, Some("cleanup/1.0.0"));
assert!(e.validate_script_source().is_ok());
}
#[test]
fn validate_treats_empty_inline_script_as_unset() {
let e = execute_with(Some(""), None, Some("cleanup/1.0.0"));
assert!(e.validate_script_source().is_ok());
}
#[test]
fn validate_rejects_zero_sources() {
let e = execute_with(None, None, None);
let err = e.validate_script_source().unwrap_err();
assert!(err.contains("must be set"), "got: {err}");
}
#[test]
fn validate_rejects_empty_inline_only() {
let e = execute_with(Some(""), None, None);
let err = e.validate_script_source().unwrap_err();
assert!(err.contains("must be set"), "got: {err}");
}
#[test]
fn validate_rejects_inline_plus_file() {
let e = execute_with(Some("echo hi"), Some("scripts/cleanup.ps1"), None);
let err = e.validate_script_source().unwrap_err();
assert!(err.contains("only one of"), "got: {err}");
}
#[test]
fn validate_rejects_inline_plus_object() {
let e = execute_with(Some("echo hi"), None, Some("cleanup/1.0.0"));
let err = e.validate_script_source().unwrap_err();
assert!(err.contains("only one of"), "got: {err}");
}
#[test]
fn validate_rejects_file_plus_object() {
let e = execute_with(None, Some("scripts/cleanup.ps1"), Some("cleanup/1.0.0"));
let err = e.validate_script_source().unwrap_err();
assert!(err.contains("only one of"), "got: {err}");
}
#[test]
fn validate_rejects_all_three() {
let e = execute_with(
Some("echo hi"),
Some("scripts/cleanup.ps1"),
Some("cleanup/1.0.0"),
);
let err = e.validate_script_source().unwrap_err();
assert!(err.contains("only one of"), "got: {err}");
}
#[test]
fn manifest_deserialises_script_object_yaml() {
let yaml = r#"
id: cleanup-disk-temp
version: 1.0.1
execute:
shell: powershell
script_object: cleanup-disk-temp/1.0.1
timeout: 600s
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
assert_eq!(
m.execute.script_object.as_deref(),
Some("cleanup-disk-temp/1.0.1")
);
assert!(m.execute.script.is_none());
m.validate()
.expect("script_object-only manifest passes validation");
}
#[test]
fn manifest_rejects_typo_in_script_field_name() {
let yaml = r#"
id: typo
version: 1.0.0
execute:
shell: powershell
script_objectt: oops
timeout: 30s
"#;
let err = crate::strict::from_yaml_str::<Manifest>(yaml)
.expect_err("typo'd execute field must be rejected at the write boundary");
assert!(err.contains("execute.script_objectt"), "{err}");
}
#[test]
fn schedule_carries_target_and_rollout() {
let yaml = r#"
id: hourly-cleanup-canary
when:
per_pc: { every: 1h }
job_id: cleanup
enabled: true
target:
groups: [canary, wave1]
jitter: 30s
rollout:
strategy: wave
waves:
- { group: canary, delay: 0s }
- { group: wave1, delay: 5s }
"#;
let s: Schedule = serde_yaml::from_str(yaml).expect("parse");
assert_eq!(s.id, "hourly-cleanup-canary");
assert_eq!(s.job_id, "cleanup");
assert_eq!(s.plan.target.groups, vec!["canary", "wave1"]);
assert_eq!(s.plan.jitter.as_deref(), Some("30s"));
let rollout = s.plan.rollout.expect("rollout present");
assert_eq!(rollout.waves.len(), 2);
assert_eq!(rollout.waves[0].group, "canary");
assert_eq!(rollout.waves[1].delay, "5s");
assert_eq!(rollout.strategy, RolloutStrategy::Wave);
}
#[test]
fn schedule_minimal_target_all() {
let yaml = r#"
id: kitting
when:
per_pc: once
enabled: true
job_id: scheduled-echo
target: { all: true }
"#;
let s: Schedule = serde_yaml::from_str(yaml).expect("parse");
assert_eq!(s.id, "kitting");
assert_eq!(s.when, When::PerPc(PerPolicy::Once(OnceLiteral::Once)));
assert!(s.enabled);
assert_eq!(s.job_id, "scheduled-echo");
assert!(s.plan.target.all);
assert!(s.plan.rollout.is_none());
assert!(s.plan.jitter.is_none());
assert!(s.active.is_empty());
}
#[test]
fn schedule_enabled_defaults_to_true() {
let yaml = r#"
id: x
when:
per_pc: once
job_id: y
target: { all: true }
"#;
let s: Schedule = serde_yaml::from_str(yaml).expect("parse");
assert!(s.enabled);
}
#[test]
fn schedule_tags_default_empty_and_skip_serialise() {
let yaml = r#"
id: x
when:
per_pc: once
job_id: y
target: { all: true }
"#;
let s: Schedule = serde_yaml::from_str(yaml).expect("parse");
assert!(s.tags.is_empty());
s.validate().expect("tag-less schedule validates");
let json = serde_json::to_string(&s).expect("serialize");
assert!(
!json.contains("tags"),
"empty tags must not serialise: {json}"
);
}
#[test]
fn schedule_parses_and_validates_tags() {
let yaml = r#"
id: weekly-cleanup
when:
per_pc: { every: 1h }
job_id: cleanup
target: { all: true }
tags: [weekly, maintenance]
"#;
let s: Schedule = serde_yaml::from_str(yaml).expect("parse");
assert_eq!(s.tags, vec!["weekly", "maintenance"]);
s.validate().expect("tagged schedule validates");
}
#[test]
fn schedule_rejects_blank_tag() {
let yaml = r#"
id: x
when:
per_pc: once
job_id: y
target: { all: true }
tags: [ok, " "]
"#;
let s: Schedule = serde_yaml::from_str(yaml).expect("parse");
let err = s.validate().expect_err("blank tag must fail");
assert!(err.contains("tags must not contain empty"), "err: {err}");
}
fn schedule_yaml_with(when_block: &str) -> String {
format!(
r#"
id: x
when:
{when_block}
job_id: y
target: {{ all: true }}
"#
)
}
#[test]
fn when_per_pc_every_parses_unquoted_humantime() {
let s: Schedule =
serde_yaml::from_str(&schedule_yaml_with(" per_pc: { every: 6h }")).expect("parse");
assert_eq!(
s.when,
When::PerPc(PerPolicy::Every(EverySpec { every: "6h".into() }))
);
}
#[test]
fn when_per_target_every_parses() {
let s: Schedule = serde_yaml::from_str(&schedule_yaml_with(" per_target: { every: 24h }"))
.expect("parse");
assert_eq!(
s.when,
When::PerTarget(PerPolicy::Every(EverySpec {
every: "24h".into()
}))
);
}
#[test]
fn when_per_target_once_parses() {
let s: Schedule =
serde_yaml::from_str(&schedule_yaml_with(" per_target: once")).expect("parse");
assert_eq!(s.when, When::PerTarget(PerPolicy::Once(OnceLiteral::Once)));
}
#[test]
fn when_calendar_time_parses() {
let s: Schedule = serde_yaml::from_str(&schedule_yaml_with(
" calendar:\n at: \"09:00\"\n days: [mon-fri]",
))
.expect("parse");
match &s.when {
When::Calendar(c) => {
assert_eq!(c.at, "09:00");
assert_eq!(c.days, vec!["mon-fri"]);
}
other => panic!("expected calendar, got {other:?}"),
}
}
#[test]
fn when_calendar_days_default_empty() {
let s: Schedule =
serde_yaml::from_str(&schedule_yaml_with(" calendar:\n at: \"09:00\""))
.expect("parse");
match &s.when {
When::Calendar(c) => assert!(c.days.is_empty(), "days defaults to empty (= daily)"),
other => panic!("expected calendar, got {other:?}"),
}
}
#[test]
fn when_calendar_datetime_parses_all_separators() {
for at in ["2026-06-10 09:00", "2026-06-10T09:00", "2026/06/10 09:00"] {
let block = format!(" calendar:\n at: \"{at}\"");
let s: Schedule = serde_yaml::from_str(&schedule_yaml_with(&block))
.unwrap_or_else(|e| panic!("parse '{at}': {e}"));
match &s.when {
When::Calendar(c) => {
use chrono::Datelike;
let p = c.parse_at().expect("parse_at");
let d = p.date.expect("datetime at carries a date");
assert_eq!((d.year(), d.month(), d.day()), (2026, 6, 10), "for '{at}'");
}
other => panic!("expected calendar, got {other:?}"),
}
}
}
#[test]
fn when_rejects_bad_once_keyword() {
let r: Result<Schedule, _> = serde_yaml::from_str(&schedule_yaml_with(" per_pc: onec"));
assert!(r.is_err(), "expected parse error, got {r:?}");
}
#[test]
fn when_rejects_unknown_key_in_every() {
let r: Result<Schedule, _> =
serde_yaml::from_str(&schedule_yaml_with(" per_pc: { evry: 6h }"));
assert!(r.is_err(), "expected parse error, got {r:?}");
}
#[test]
fn when_rejects_unknown_variant() {
let r: Result<Schedule, _> =
serde_yaml::from_str(&schedule_yaml_with(" per_galaxy: once"));
assert!(r.is_err(), "expected parse error, got {r:?}");
}
#[test]
fn when_rejects_old_top_level_cron_field() {
let yaml = r#"
id: x
cron: "* * * * * *"
job_id: y
target: { all: true }
"#;
let r: Result<Schedule, _> = serde_yaml::from_str(yaml);
assert!(r.is_err(), "expected parse error, got {r:?}");
}
#[test]
fn when_rejects_retired_cron_escape_hatch() {
let r: Result<Schedule, _> =
serde_yaml::from_str(&schedule_yaml_with(" cron: \"0 0 9 * * mon-fri\""));
assert!(
r.is_err(),
"expected parse error for retired cron, got {r:?}"
);
}
#[test]
fn when_round_trips_json_and_yaml() {
for when in [
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
When::PerPc(PerPolicy::Every(EverySpec { every: "6h".into() })),
When::PerTarget(PerPolicy::Once(OnceLiteral::Once)),
When::PerTarget(PerPolicy::Every(EverySpec {
every: "24h".into(),
})),
calendar("09:00", &["mon-fri"]),
calendar("2026-06-10 09:00", &[]),
When::On(vec![OnTrigger::Startup]),
When::On(vec![OnTrigger::Startup, OnTrigger::Logon]),
When::On(vec![OnTrigger::Lock, OnTrigger::Unlock]),
When::On(vec![OnTrigger::NetworkChange]),
] {
let runs_on = if matches!(when, When::On(_)) {
RunsOn::Agent
} else {
RunsOn::Backend
};
let s = schedule_with(when.clone(), runs_on);
let json = serde_json::to_string(&s).expect("json serialise");
let back: Schedule = serde_json::from_str(&json).expect("json deserialise");
assert_eq!(back.when, when, "json round-trip for {when}");
let yaml = serde_yaml::to_string(&s).expect("yaml serialise");
assert!(
!yaml.contains('!'),
"yaml must use the map shape, not tags: {yaml}"
);
let back: Schedule = serde_yaml::from_str(&yaml).expect("yaml deserialise");
assert_eq!(back.when, when, "yaml round-trip for {when}");
}
}
#[test]
fn when_once_serialises_as_bare_keyword() {
let json = serde_json::to_value(When::PerPc(PerPolicy::Once(OnceLiteral::Once)))
.expect("serialise");
assert_eq!(json, serde_json::json!({ "per_pc": "once" }));
}
#[test]
fn when_displays_operator_summary() {
for (when, expected) in [
(
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
"per_pc once",
),
(
When::PerPc(PerPolicy::Every(EverySpec { every: "6h".into() })),
"per_pc every 6h",
),
(
When::PerTarget(PerPolicy::Every(EverySpec {
every: "24h".into(),
})),
"per_target every 24h",
),
(calendar("09:00", &["mon-fri"]), "at 09:00 [mon-fri]"),
(calendar("2026-06-10 09:00", &[]), "at 2026-06-10 09:00"),
(When::On(vec![OnTrigger::Startup]), "on [startup]"),
(
When::On(vec![OnTrigger::Startup, OnTrigger::Logon]),
"on [startup,logon]",
),
(
When::On(vec![OnTrigger::Lock, OnTrigger::Unlock]),
"on [lock,unlock]",
),
(
When::On(vec![OnTrigger::NetworkChange]),
"on [network_change]",
),
] {
assert_eq!(when.to_string(), expected);
}
}
fn schedule_with(when: When, runs_on: RunsOn) -> Schedule {
Schedule {
id: "x".into(),
when,
job_id: "y".into(),
plan: FanoutPlan::default(),
active: Active::default(),
constraints: Constraints::default(),
on_failure: OnFailure::default(),
tz: ScheduleTz::default(),
starting_deadline: None,
runs_on,
enabled: true,
tags: Vec::new(),
origin: None,
}
}
fn calendar(at: &str, days: &[&str]) -> When {
When::Calendar(CalendarSpec {
at: at.into(),
days: days.iter().map(|d| (*d).to_string()).collect(),
})
}
#[test]
fn next_calendar_fire_returns_next_utc_occurrence() {
use chrono::TimeZone;
let mut s = schedule_with(calendar("09:00", &[]), RunsOn::Backend);
s.tz = ScheduleTz::Utc;
let now = chrono::Utc.with_ymd_and_hms(2026, 6, 9, 8, 0, 0).unwrap();
let next = s.next_calendar_fire(now).expect("calendar has a next fire");
assert_eq!(
next,
chrono::Utc.with_ymd_and_hms(2026, 6, 9, 9, 0, 0).unwrap()
);
}
#[test]
fn next_calendar_fire_is_strictly_after_now() {
use chrono::TimeZone;
let mut s = schedule_with(calendar("09:00", &[]), RunsOn::Backend);
s.tz = ScheduleTz::Utc;
let on_fire = chrono::Utc.with_ymd_and_hms(2026, 6, 9, 9, 0, 0).unwrap();
let next = s
.next_calendar_fire(on_fire)
.expect("calendar has a next fire");
assert_eq!(
next,
chrono::Utc.with_ymd_and_hms(2026, 6, 10, 9, 0, 0).unwrap()
);
}
#[test]
fn next_calendar_fire_none_for_reconcile_shapes() {
let now = chrono::Utc::now();
for when in [
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
When::PerTarget(PerPolicy::Once(OnceLiteral::Once)),
When::PerPc(PerPolicy::Every(EverySpec { every: "6h".into() })),
When::PerTarget(PerPolicy::Every(EverySpec {
every: "24h".into(),
})),
] {
let s = schedule_with(when, RunsOn::Backend);
assert!(
s.next_calendar_fire(now).is_none(),
"reconcile shapes have no calendar fire",
);
}
}
fn cal_utc(at: &str, days: &[&str]) -> Schedule {
let mut s = schedule_with(calendar(at, days), RunsOn::Backend);
s.tz = ScheduleTz::Utc; s
}
#[test]
fn preview_lists_next_calendar_occurrences() {
use chrono::TimeZone;
let s = cal_utc("09:00", &["mon-fri"]);
let now = chrono::Utc.with_ymd_and_hms(2026, 6, 10, 0, 0, 0).unwrap();
let got = s.preview_fires(now, 5);
let want: Vec<_> = [
(2026, 6, 10), (2026, 6, 11), (2026, 6, 12), (2026, 6, 15), (2026, 6, 16), ]
.iter()
.map(|(y, m, d)| chrono::Utc.with_ymd_and_hms(*y, *m, *d, 9, 0, 0).unwrap())
.collect();
assert_eq!(got, want);
}
#[test]
fn preview_handles_nth_and_last_weekday() {
use chrono::TimeZone;
let now = chrono::Utc.with_ymd_and_hms(2026, 6, 1, 0, 0, 0).unwrap();
let nth = cal_utc("09:00", &["tue#2"]).preview_fires(now, 2);
assert_eq!(
nth,
vec![
chrono::Utc.with_ymd_and_hms(2026, 6, 9, 9, 0, 0).unwrap(),
chrono::Utc.with_ymd_and_hms(2026, 7, 14, 9, 0, 0).unwrap(),
]
);
let last = cal_utc("22:00", &["friL"]).preview_fires(now, 2);
assert_eq!(
last,
vec![
chrono::Utc.with_ymd_and_hms(2026, 6, 26, 22, 0, 0).unwrap(),
chrono::Utc.with_ymd_and_hms(2026, 7, 31, 22, 0, 0).unwrap(),
]
);
}
#[test]
fn preview_is_empty_for_reconcile_and_zero_count() {
let now = chrono::Utc::now();
let recon = schedule_with(
When::PerPc(PerPolicy::Every(EverySpec { every: "6h".into() })),
RunsOn::Backend,
);
assert!(recon.preview_fires(now, 5).is_empty());
assert!(cal_utc("09:00", &[]).preview_fires(now, 0).is_empty());
}
#[test]
fn preview_skips_outside_active_window() {
use chrono::TimeZone;
let mut s = cal_utc("09:00", &[]);
s.active = Active {
from: Some("2026-06-15".into()),
until: Some("2026-06-17".into()),
};
let now = chrono::Utc.with_ymd_and_hms(2026, 6, 10, 0, 0, 0).unwrap();
let got = s.preview_fires(now, 5);
assert_eq!(
got,
vec![
chrono::Utc.with_ymd_and_hms(2026, 6, 15, 9, 0, 0).unwrap(),
chrono::Utc.with_ymd_and_hms(2026, 6, 16, 9, 0, 0).unwrap(),
]
);
}
#[test]
fn preview_empty_when_calendar_time_outside_window() {
use chrono::TimeZone;
let mut s = cal_utc("09:00", &[]);
s.constraints = Constraints {
window: Some("22:00-05:00".into()),
..Constraints::default()
};
let now = chrono::Utc.with_ymd_and_hms(2026, 6, 10, 0, 0, 0).unwrap();
assert!(s.preview_fires(now, 5).is_empty());
assert!(s.preview_fires(now, 50).is_empty());
}
#[test]
fn preview_past_one_shot_is_empty() {
use chrono::TimeZone;
let s = cal_utc("2026-06-10 09:00", &[]);
let now = chrono::Utc.with_ymd_and_hms(2026, 6, 11, 0, 0, 0).unwrap();
assert!(s.preview_fires(now, 5).is_empty());
let before = chrono::Utc.with_ymd_and_hms(2026, 6, 1, 0, 0, 0).unwrap();
assert_eq!(
s.preview_fires(before, 5),
vec![chrono::Utc.with_ymd_and_hms(2026, 6, 10, 9, 0, 0).unwrap()]
);
}
#[test]
fn lowering_matches_the_418_table() {
let cases = [
(
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
(POLL_CRON, ExecMode::OncePerPc, None),
),
(
When::PerPc(PerPolicy::Every(EverySpec { every: "6h".into() })),
(POLL_CRON, ExecMode::OncePerPc, Some("6h")),
),
(
When::PerTarget(PerPolicy::Once(OnceLiteral::Once)),
(POLL_CRON, ExecMode::OncePerTarget, None),
),
(
When::PerTarget(PerPolicy::Every(EverySpec {
every: "24h".into(),
})),
(POLL_CRON, ExecMode::OncePerTarget, Some("24h")),
),
(
calendar("09:00", &["mon-fri"]),
("0 0 9 * * mon-fri", ExecMode::EveryTick, None),
),
(
calendar("18:30", &[]),
("0 30 18 * * *", ExecMode::EveryTick, None),
),
(
calendar("2026-06-10 09:00", &[]),
("0 0 9 10 6 * 2026", ExecMode::EveryTick, None),
),
];
for (when, (cron, mode, cooldown)) in cases {
let l = schedule_with(when.clone(), RunsOn::Backend).lowered();
assert_eq!(l.cron, cron, "cron for {when}");
assert_eq!(l.mode, mode, "mode for {when}");
assert_eq!(l.cooldown.as_deref(), cooldown, "cooldown for {when}");
}
}
#[test]
fn lowered_carries_schedule_tz() {
for (tz, want) in [
(ScheduleTz::Local, ScheduleTz::Local),
(ScheduleTz::Utc, ScheduleTz::Utc),
] {
let mut s = schedule_with(calendar("09:00", &["mon-fri"]), RunsOn::Backend);
s.tz = tz;
assert_eq!(s.lowered().tz, want, "calendar carries tz");
let mut s = schedule_with(
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
RunsOn::Backend,
);
s.tz = tz;
assert_eq!(s.lowered().tz, want, "reconcile carries tz");
}
}
#[test]
fn poll_cron_is_accepted_by_the_engine_parser() {
croner::parser::CronParser::builder()
.seconds(croner::parser::Seconds::Required)
.dom_and_dow(true)
.build()
.parse(POLL_CRON)
.expect("POLL_CRON must parse");
}
#[test]
fn validate_accepts_reconcile_shapes() {
for when in [
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
When::PerPc(PerPolicy::Every(EverySpec { every: "6h".into() })),
When::PerTarget(PerPolicy::Once(OnceLiteral::Once)),
When::PerTarget(PerPolicy::Every(EverySpec {
every: "24h".into(),
})),
] {
schedule_with(when.clone(), RunsOn::Backend)
.validate()
.unwrap_or_else(|e| panic!("{when} should validate: {e}"));
}
}
#[test]
fn validate_accepts_per_pc_on_agent() {
schedule_with(
When::PerPc(PerPolicy::Every(EverySpec { every: "1h".into() })),
RunsOn::Agent,
)
.validate()
.expect("per_pc + agent is the offline-inventory shape");
}
#[test]
fn validate_accepts_event_on_agent() {
for triggers in [
vec![OnTrigger::Startup],
vec![OnTrigger::Logon],
vec![OnTrigger::Lock],
vec![OnTrigger::Unlock],
vec![OnTrigger::NetworkChange],
vec![
OnTrigger::Startup,
OnTrigger::Logon,
OnTrigger::Lock,
OnTrigger::Unlock,
OnTrigger::NetworkChange,
],
] {
schedule_with(When::On(triggers), RunsOn::Agent)
.validate()
.expect("when.on is valid on runs_on: agent");
}
}
#[test]
fn validate_rejects_event_on_backend() {
let err = schedule_with(When::On(vec![OnTrigger::Startup]), RunsOn::Backend)
.validate()
.unwrap_err();
assert!(err.contains("when.on"), "got: {err}");
assert!(err.contains("runs_on: agent"), "got: {err}");
}
#[test]
fn validate_rejects_empty_event_list() {
let err = schedule_with(When::On(vec![]), RunsOn::Agent)
.validate()
.unwrap_err();
assert!(err.contains("when.on"), "got: {err}");
assert!(err.contains("at least one"), "got: {err}");
}
#[test]
fn event_schedule_lowers_to_event_mode_and_is_event() {
let s = schedule_with(When::On(vec![OnTrigger::Startup]), RunsOn::Agent);
assert!(s.is_event());
assert_eq!(s.lowered().mode, ExecMode::Event);
assert_eq!(s.event_triggers(), &[OnTrigger::Startup]);
let cal = schedule_with(calendar("09:00", &[]), RunsOn::Backend);
assert!(!cal.is_event());
assert!(cal.event_triggers().is_empty());
}
fn require_schedule(req: Require, runs_on: RunsOn) -> Schedule {
let mut s = schedule_with(
When::PerPc(PerPolicy::Every(EverySpec { every: "1m".into() })),
runs_on,
);
s.constraints.require = Some(req);
s
}
#[test]
fn require_met_combinations() {
use std::time::Duration;
let idle = |m: u64| Some(Duration::from_secs(m * 60));
let env = |ac, idle, cpu, net| EnvState {
ac_online: ac,
idle,
cpu_pct: cpu,
network_up: net,
};
assert!(require_met(
&Require::default(),
&env(false, None, None, false)
));
let ac = Require {
ac_power: true,
..Default::default()
};
assert!(!require_met(&ac, &env(false, None, None, true)));
assert!(require_met(&ac, &env(true, None, None, false)));
let idle10 = Require {
idle: Some("10m".into()),
..Default::default()
};
assert!(!require_met(&idle10, &env(true, None, None, true)));
assert!(!require_met(&idle10, &env(true, idle(5), None, true)));
assert!(require_met(&idle10, &env(true, idle(15), None, true)));
assert!(require_met(&idle10, &env(true, idle(10), None, true))); let cpu20 = Require {
cpu_below: Some(20.0),
..Default::default()
};
assert!(!require_met(&cpu20, &env(true, None, None, true))); assert!(!require_met(&cpu20, &env(true, None, Some(20.0), true))); assert!(!require_met(&cpu20, &env(true, None, Some(55.0), true))); assert!(require_met(&cpu20, &env(true, None, Some(5.0), true))); let net = Require {
network: true,
..Default::default()
};
assert!(!require_met(&net, &env(true, None, None, false))); assert!(require_met(&net, &env(true, None, None, true))); let all = Require {
ac_power: true,
idle: Some("10m".into()),
cpu_below: Some(20.0),
network: true,
};
assert!(!require_met(&all, &env(false, idle(20), Some(5.0), true))); assert!(!require_met(&all, &env(true, idle(1), Some(5.0), true))); assert!(!require_met(&all, &env(true, idle(20), Some(50.0), true))); assert!(!require_met(&all, &env(true, idle(20), Some(5.0), false))); assert!(require_met(&all, &env(true, idle(20), Some(5.0), true)));
let bad = Require {
ac_power: true,
idle: Some("garbage".into()),
..Default::default()
};
assert!(require_met(&bad, &env(true, None, None, true)));
assert!(!require_met(&bad, &env(false, None, None, true)));
}
#[test]
fn validate_accepts_and_rejects_cpu_below() {
require_schedule(
Require {
cpu_below: Some(20.0),
..Default::default()
},
RunsOn::Agent,
)
.validate()
.expect("cpu_below 20 is valid");
require_schedule(
Require {
cpu_below: Some(100.0),
..Default::default()
},
RunsOn::Agent,
)
.validate()
.expect("cpu_below 100 is valid");
for bad in [0.0, -5.0, 100.1] {
let err = require_schedule(
Require {
cpu_below: Some(bad),
..Default::default()
},
RunsOn::Agent,
)
.validate()
.unwrap_err();
assert!(
err.contains("constraints.require.cpu_below"),
"cpu_below {bad}: {err}"
);
}
}
#[test]
fn validate_accepts_require_on_agent() {
require_schedule(
Require {
ac_power: true,
idle: Some("10m".into()),
cpu_below: Some(20.0),
network: true,
},
RunsOn::Agent,
)
.validate()
.expect("constraints.require is valid on runs_on: agent");
}
#[test]
fn validate_rejects_require_on_backend() {
let err = require_schedule(
Require {
ac_power: true,
..Default::default()
},
RunsOn::Backend,
)
.validate()
.unwrap_err();
assert!(err.contains("constraints.require"), "got: {err}");
assert!(err.contains("runs_on: agent"), "got: {err}");
let err = require_schedule(
Require {
idle: Some("10m".into()),
..Default::default()
},
RunsOn::Backend,
)
.validate()
.unwrap_err();
assert!(
err.contains("constraints.require"),
"idle-only on backend: {err}"
);
}
#[test]
fn validate_rejects_bad_require_idle() {
let err = require_schedule(
Require {
idle: Some("not-a-duration".into()),
..Default::default()
},
RunsOn::Agent,
)
.validate()
.unwrap_err();
assert!(err.contains("constraints.require.idle"), "got: {err}");
}
#[test]
fn require_round_trips_and_skips_empty() {
let yaml = "id: s\nwhen: { per_pc: { every: 1m } }\njob_id: j\nruns_on: agent\n\
constraints: { require: { ac_power: true, idle: 10m, cpu_below: 20, \
network: true } }\n";
let s: Schedule = serde_yaml::from_str(yaml).expect("parse");
let req = s.constraints.require.as_ref().expect("require present");
assert!(req.ac_power);
assert_eq!(req.idle.as_deref(), Some("10m"));
assert_eq!(req.cpu_below, Some(20.0));
assert!(req.network);
let back = serde_json::to_string(&s.constraints).unwrap();
assert!(back.contains("\"idle\":\"10m\""), "got: {back}");
assert!(back.contains("\"cpu_below\":20"), "got: {back}");
assert!(back.contains("\"network\":true"), "got: {back}");
let mut empty = s.clone();
empty.constraints.require = Some(Require::default());
assert!(empty.constraints.is_empty());
}
#[test]
fn validate_rejects_per_target_on_agent() {
let err = schedule_with(
When::PerTarget(PerPolicy::Every(EverySpec {
every: "24h".into(),
})),
RunsOn::Agent,
)
.validate()
.unwrap_err();
assert!(err.contains("per_target"), "got: {err}");
assert!(err.contains("runs_on: agent"), "got: {err}");
let err = schedule_with(
When::PerTarget(PerPolicy::Once(OnceLiteral::Once)),
RunsOn::Agent,
)
.validate()
.unwrap_err();
assert!(err.contains("per_target"), "got (once): {err}");
assert!(err.contains("runs_on: agent"), "got (once): {err}");
}
#[test]
fn validate_rejects_bad_every_duration() {
let err = schedule_with(
When::PerPc(PerPolicy::Every(EverySpec { every: "6x".into() })),
RunsOn::Backend,
)
.validate()
.unwrap_err();
assert!(err.contains("when.every"), "got: {err}");
}
#[test]
fn validate_rejects_bad_jitter_and_starting_deadline() {
let mut s = schedule_with(
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
RunsOn::Backend,
);
s.plan.jitter = Some("5x".into());
let err = s.validate().unwrap_err();
assert!(err.contains("jitter"), "got: {err}");
let mut s = schedule_with(
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
RunsOn::Backend,
);
s.starting_deadline = Some("soon".into());
let err = s.validate().unwrap_err();
assert!(err.contains("starting_deadline"), "got: {err}");
}
#[test]
fn validate_accepts_calendar_shapes() {
for when in [
calendar("09:00", &["mon-fri"]), calendar("00:00", &["sun"]), calendar("18:30", &[]), calendar("2026-06-10 09:00", &[]), calendar("2026/12/25 00:00", &[]), ] {
schedule_with(when.clone(), RunsOn::Backend)
.validate()
.unwrap_or_else(|e| panic!("{when} should validate: {e}"));
}
}
#[test]
fn validate_rejects_bad_at() {
for bad in ["25:00", "09:60", "9", "noon", "2026-13-01 09:00"] {
let err = schedule_with(calendar(bad, &[]), RunsOn::Backend)
.validate()
.unwrap_err();
assert!(err.contains("when.at"), "for '{bad}', got: {err}");
}
}
#[test]
fn validate_rejects_datetime_at_with_days() {
let err = schedule_with(calendar("2026-06-10 09:00", &["mon"]), RunsOn::Backend)
.validate()
.unwrap_err();
assert!(
err.contains("one-shot") && err.contains("days"),
"got: {err}"
);
}
#[test]
fn validate_rejects_bad_day_name() {
let err = schedule_with(calendar("09:00", &["funday"]), RunsOn::Backend)
.validate()
.unwrap_err();
assert!(err.contains("when.days"), "got: {err}");
assert!(err.contains("funday"), "names the bad token: {err}");
let err = schedule_with(calendar("09:00", &["mon-"]), RunsOn::Backend)
.validate()
.unwrap_err();
assert!(err.contains("'mon-'"), "names the whole token: {err}");
for ok in [
calendar("09:00", &["mon-fri"]),
calendar("09:00", &["mon", "wed", "sun"]),
calendar("09:00", &["1-5"]),
] {
schedule_with(ok.clone(), RunsOn::Backend)
.validate()
.unwrap_or_else(|e| panic!("{ok} should validate: {e}"));
}
}
#[test]
fn validate_accepts_nth_weekday() {
for ok in [
calendar("09:00", &["tue#2"]), calendar("09:00", &["fri#1"]), calendar("03:00", &["sun#5"]), calendar("09:00", &["tue#2", "thu#2"]), calendar("09:00", &["2#2"]), calendar("09:00", &["TUE#2"]),
] {
schedule_with(ok.clone(), RunsOn::Backend)
.validate()
.unwrap_or_else(|e| panic!("{ok} should validate: {e}"));
}
}
#[test]
fn validate_rejects_bad_nth_weekday() {
for bad in ["tue#0", "tue#6", "tue#x", "mon-fri#2", "funday#2"] {
let err = schedule_with(calendar("09:00", &[bad]), RunsOn::Backend)
.validate()
.unwrap_err();
assert!(err.contains("when.days"), "for '{bad}', got: {err}");
}
}
#[test]
fn validate_accepts_last_weekday() {
for ok in [
calendar("09:00", &["friL"]), calendar("03:00", &["sunL"]), calendar("22:00", &["5L"]), calendar("00:00", &["0L"]), calendar("00:00", &["7L"]), calendar("09:00", &["monL", "friL"]), calendar("09:00", &["FRIL"]),
calendar("09:00", &["fril"]),
] {
schedule_with(ok.clone(), RunsOn::Backend)
.validate()
.unwrap_or_else(|e| panic!("{ok} should validate: {e}"));
}
}
#[test]
fn validate_rejects_bad_last_weekday() {
for bad in ["L", "l", "mon-friL", "fundayL", "8L", "*L", "fri L"] {
let err = schedule_with(calendar("09:00", &[bad]), RunsOn::Backend)
.validate()
.unwrap_err();
assert!(err.contains("when.days"), "for '{bad}', got: {err}");
}
}
#[test]
fn calendar_oneshot_instant_detects_past() {
use chrono::TimeZone;
let c = CalendarSpec {
at: "2024-01-01 09:00".into(),
days: vec![],
};
let t = c
.oneshot_instant(ScheduleTz::Utc)
.expect("one-shot instant");
assert_eq!(
t,
chrono::Utc.with_ymd_and_hms(2024, 1, 1, 9, 0, 0).unwrap()
);
assert!(t < chrono::Utc::now(), "2024 is in the past");
let rep = CalendarSpec {
at: "09:00".into(),
days: vec!["mon-fri".into()],
};
assert!(rep.oneshot_instant(ScheduleTz::Utc).is_none());
}
fn schedule_with_active(from: Option<&str>, until: Option<&str>) -> Schedule {
let mut s = schedule_with(
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
RunsOn::Backend,
);
s.active = Active {
from: from.map(str::to_owned),
until: until.map(str::to_owned),
};
s
}
#[test]
fn validate_accepts_active_window() {
schedule_with_active(Some("2026-07-01"), Some("2026-08-01T12:00:00+09:00"))
.validate()
.expect("date + rfc3339 bounds should validate");
}
#[test]
fn validate_rejects_unparseable_active_bound() {
let err = schedule_with_active(Some("July 1st"), None)
.validate()
.unwrap_err();
assert!(err.contains("active"), "got: {err}");
}
#[test]
fn validate_rejects_from_not_before_until() {
let err = schedule_with_active(Some("2026-08-01"), Some("2026-07-01"))
.validate()
.unwrap_err();
assert!(err.contains("strictly before"), "got: {err}");
let err = schedule_with_active(Some("2026-07-01"), Some("2026-07-01"))
.validate()
.unwrap_err();
assert!(err.contains("strictly before"), "got: {err}");
}
#[test]
fn active_window_is_half_open() {
use chrono::TimeZone;
let active = Active {
from: Some("2026-07-01".into()),
until: Some("2026-08-01".into()),
};
let at = |y, m, d, h| chrono::Utc.with_ymd_and_hms(y, m, d, h, 0, 0).unwrap();
let c = |t| active.contains(t, ScheduleTz::Utc);
assert!(!c(at(2026, 6, 30, 23)), "before from");
assert!(c(at(2026, 7, 1, 0)), "at from (inclusive)");
assert!(c(at(2026, 7, 15, 12)), "inside");
assert!(!c(at(2026, 8, 1, 0)), "at until (exclusive)");
assert!(!c(at(2026, 8, 2, 0)), "after until");
}
#[test]
fn active_empty_window_is_always_active() {
assert!(Active::default().contains(chrono::Utc::now(), ScheduleTz::Local));
}
#[test]
fn active_rfc3339_bound_honours_offset_regardless_of_tz() {
use chrono::TimeZone;
let active = Active {
from: Some("2026-07-01T09:00:00+09:00".into()),
until: None,
};
for tz in [ScheduleTz::Utc, ScheduleTz::Local] {
assert!(
!active.contains(
chrono::Utc
.with_ymd_and_hms(2026, 6, 30, 23, 59, 0)
.unwrap(),
tz
)
);
assert!(active.contains(
chrono::Utc.with_ymd_and_hms(2026, 7, 1, 0, 0, 0).unwrap(),
tz
));
}
}
#[test]
fn active_date_bound_respects_tz() {
use chrono::TimeZone;
let utc = Active::parse_bound("2026-07-01", ScheduleTz::Utc).expect("utc");
assert_eq!(
utc,
chrono::Utc.with_ymd_and_hms(2026, 7, 1, 0, 0, 0).unwrap()
);
let local = Active::parse_bound("2026-07-01", ScheduleTz::Local).expect("local");
let want = chrono::Local
.with_ymd_and_hms(2026, 7, 1, 0, 0, 0)
.single()
.expect("local midnight is unambiguous")
.with_timezone(&chrono::Utc);
assert_eq!(local, want, "date bound resolved in host-local tz");
}
#[test]
fn active_empty_is_skipped_when_serialising() {
let s = schedule_with(
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
RunsOn::Backend,
);
let json = serde_json::to_value(&s).expect("serialise");
assert!(
json.get("active").is_none(),
"empty active must not appear on the wire: {json}"
);
}
fn with_window(win: &str) -> Schedule {
let mut s = schedule_with(
When::PerPc(PerPolicy::Every(EverySpec { every: "6h".into() })),
RunsOn::Backend,
);
s.constraints.window = Some(win.into());
s
}
#[test]
fn constraints_window_parses_and_round_trips() {
let yaml = r#"
id: x
when:
per_pc: { every: 6h }
job_id: y
target: { all: true }
constraints:
window: "22:00-05:00"
"#;
let s: Schedule = serde_yaml::from_str(yaml).expect("parse");
assert_eq!(s.constraints.window.as_deref(), Some("22:00-05:00"));
let back: Schedule =
serde_json::from_str(&serde_json::to_string(&s).expect("ser")).expect("de");
assert_eq!(back.constraints.window.as_deref(), Some("22:00-05:00"));
}
#[test]
fn constraints_empty_is_skipped_when_serialising() {
let s = schedule_with(
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
RunsOn::Backend,
);
let json = serde_json::to_value(&s).expect("serialise");
assert!(
json.get("constraints").is_none(),
"empty constraints must not appear on the wire: {json}"
);
}
#[test]
fn window_no_constraint_always_allows() {
let c = Constraints::default();
assert!(c.allows(chrono::Utc::now(), ScheduleTz::Local));
}
#[test]
fn window_same_day_is_half_open() {
use chrono::TimeZone;
let s = with_window("09:00-17:00");
let at = |h, m| chrono::Utc.with_ymd_and_hms(2026, 6, 9, h, m, 0).unwrap();
let a = |t| s.constraints.allows(t, ScheduleTz::Utc);
assert!(!a(at(8, 59)), "before start");
assert!(a(at(9, 0)), "at start (inclusive)");
assert!(a(at(16, 59)), "inside");
assert!(!a(at(17, 0)), "at end (exclusive)");
assert!(!a(at(23, 0)), "after end");
}
#[test]
fn window_crossing_midnight() {
use chrono::TimeZone;
let s = with_window("22:00-05:00");
let at = |h, m| chrono::Utc.with_ymd_and_hms(2026, 6, 9, h, m, 0).unwrap();
let a = |t| s.constraints.allows(t, ScheduleTz::Utc);
assert!(a(at(22, 0)), "at start tonight");
assert!(a(at(23, 30)), "late tonight");
assert!(a(at(3, 0)), "early tomorrow");
assert!(!a(at(5, 0)), "at end (exclusive)");
assert!(!a(at(12, 0)), "midday outside");
assert!(!a(at(21, 59)), "just before start");
}
#[test]
fn window_respects_tz() {
use chrono::TimeZone;
let s = with_window("09:00-17:00");
let noon_utc = chrono::Utc.with_ymd_and_hms(2026, 6, 9, 12, 0, 0).unwrap();
assert!(s.constraints.allows(noon_utc, ScheduleTz::Utc));
let local_t = noon_utc.with_timezone(&chrono::Local).time();
let in_local = local_t >= chrono::NaiveTime::from_hms_opt(9, 0, 0).unwrap()
&& local_t < chrono::NaiveTime::from_hms_opt(17, 0, 0).unwrap();
assert_eq!(s.constraints.allows(noon_utc, ScheduleTz::Local), in_local);
}
#[test]
fn validate_accepts_good_window() {
for w in ["09:00-17:00", "22:00-05:00", "00:00-23:59"] {
with_window(w)
.validate()
.unwrap_or_else(|e| panic!("'{w}' should validate: {e}"));
}
}
#[test]
fn validate_rejects_bad_window() {
for bad in ["9-5", "22:00", "22:00-22:00", "25:00-05:00", "09:00_17:00"] {
let err = with_window(bad).validate().unwrap_err();
assert!(
err.contains("constraints.window"),
"for '{bad}', got: {err}"
);
}
}
fn with_skip_dates(dates: &[&str]) -> Schedule {
let mut s = schedule_with(calendar("09:00", &[]), RunsOn::Backend);
s.tz = ScheduleTz::Utc; s.constraints.skip_dates = dates.iter().map(|d| (*d).to_string()).collect();
s
}
#[test]
fn allows_blocks_listed_skip_date() {
use chrono::TimeZone;
let s = with_skip_dates(&["2026-06-10", "2026-12-25"]);
let on = chrono::Utc.with_ymd_and_hms(2026, 6, 10, 9, 0, 0).unwrap();
assert!(!s.constraints.allows(on, ScheduleTz::Utc));
let on_midnight = chrono::Utc.with_ymd_and_hms(2026, 12, 25, 0, 0, 0).unwrap();
assert!(!s.constraints.allows(on_midnight, ScheduleTz::Utc));
let off = chrono::Utc.with_ymd_and_hms(2026, 6, 11, 9, 0, 0).unwrap();
assert!(s.constraints.allows(off, ScheduleTz::Utc));
}
#[test]
fn allows_corrupt_skip_date_fails_closed() {
use chrono::TimeZone;
let s = with_skip_dates(&["not-a-date"]);
let any = chrono::Utc.with_ymd_and_hms(2026, 6, 11, 9, 0, 0).unwrap();
assert!(!s.constraints.allows(any, ScheduleTz::Utc));
}
#[test]
fn validate_accepts_good_skip_dates() {
with_skip_dates(&["2026-01-01", "2026-12-25", "2027-05-03"])
.validate()
.expect("well-formed skip dates should validate");
}
#[test]
fn validate_rejects_bad_skip_date() {
for bad in ["2026-13-01", "01-01-2026", "nope", "2026/01/01"] {
let err = with_skip_dates(&[bad]).validate().unwrap_err();
assert!(
err.contains("constraints.skip_dates"),
"for '{bad}', got: {err}"
);
}
}
#[test]
fn preview_skips_holidays() {
use chrono::TimeZone;
let mut s = cal_utc("09:00", &[]);
s.constraints.skip_dates = vec!["2026-06-11".into(), "2026-06-13".into()];
let now = chrono::Utc.with_ymd_and_hms(2026, 6, 10, 0, 0, 0).unwrap();
let got = s.preview_fires(now, 4);
let want: Vec<_> = [
(2026, 6, 10),
(2026, 6, 12), (2026, 6, 14), (2026, 6, 15),
]
.iter()
.map(|(y, m, d)| chrono::Utc.with_ymd_and_hms(*y, *m, *d, 9, 0, 0).unwrap())
.collect();
assert_eq!(got, want);
}
fn with_max_concurrent(max: u32, runs_on: RunsOn) -> Schedule {
let mut s = schedule_with(
When::PerPc(PerPolicy::Every(EverySpec { every: "6h".into() })),
runs_on,
);
s.constraints.max_concurrent = Some(max);
s
}
#[test]
fn validate_accepts_backend_max_concurrent() {
with_max_concurrent(5, RunsOn::Backend)
.validate()
.expect("backend max_concurrent should validate");
}
#[test]
fn validate_rejects_max_concurrent_on_agent() {
let err = with_max_concurrent(5, RunsOn::Agent)
.validate()
.unwrap_err();
assert!(err.contains("constraints.max_concurrent"), "got: {err}");
assert!(err.contains("runs_on: agent"), "got: {err}");
}
#[test]
fn validate_rejects_zero_max_concurrent() {
let err = with_max_concurrent(0, RunsOn::Backend)
.validate()
.unwrap_err();
assert!(err.contains("max_concurrent must be >= 1"), "got: {err}");
}
#[test]
fn max_concurrent_round_trips_and_skips_when_absent() {
let s = with_max_concurrent(3, RunsOn::Backend);
let json = serde_json::to_value(&s.constraints).expect("ser");
assert_eq!(json.get("max_concurrent").and_then(|v| v.as_u64()), Some(3));
let bare = schedule_with(
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
RunsOn::Backend,
);
assert!(bare.constraints.is_empty());
}
#[test]
fn window_fail_closed_on_corrupt_blob() {
let s = with_window("22:00_05:00");
assert!(
!s.constraints.allows(chrono::Utc::now(), ScheduleTz::Utc),
"corrupt window fails closed"
);
assert!(
s.bad_window().is_some(),
"bad_window reports the parse error"
);
assert!(with_window("22:00-05:00").bad_window().is_none());
}
#[test]
fn calendar_outside_window_is_flagged() {
let mut s = schedule_with(calendar("09:00", &["mon-fri"]), RunsOn::Backend);
s.constraints.window = Some("22:00-05:00".into());
assert!(s.calendar_outside_window(), "09:00 is not in 22:00-05:00");
let mut s = schedule_with(calendar("23:00", &[]), RunsOn::Backend);
s.constraints.window = Some("22:00-05:00".into());
assert!(!s.calendar_outside_window(), "23:00 is in 22:00-05:00");
let mut s = schedule_with(
When::PerPc(PerPolicy::Every(EverySpec { every: "6h".into() })),
RunsOn::Backend,
);
s.constraints.window = Some("22:00-05:00".into());
assert!(!s.calendar_outside_window(), "reconcile is unaffected");
let s = schedule_with(calendar("09:00", &[]), RunsOn::Backend);
assert!(!s.calendar_outside_window());
}
fn with_retry(max: u32, backoff: &str) -> Schedule {
let mut s = schedule_with(
When::PerPc(PerPolicy::Every(EverySpec { every: "6h".into() })),
RunsOn::Backend,
);
s.on_failure.retry = Some(Retry {
max,
backoff: backoff.into(),
});
s
}
#[test]
fn on_failure_parses_and_round_trips() {
let yaml = r#"
id: x
when:
per_pc: { every: 6h }
job_id: y
target: { all: true }
on_failure:
retry: { max: 3, backoff: 10m }
"#;
let s: Schedule = serde_yaml::from_str(yaml).expect("parse");
let r = s.on_failure.retry.as_ref().expect("retry present");
assert_eq!(r.max, 3);
assert_eq!(r.backoff, "10m");
let back: Schedule =
serde_json::from_str(&serde_json::to_string(&s).expect("ser")).expect("de");
assert_eq!(back.on_failure, s.on_failure);
}
#[test]
fn on_failure_empty_is_skipped_when_serialising() {
let s = schedule_with(
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
RunsOn::Backend,
);
let json = serde_json::to_value(&s).expect("serialise");
assert!(
json.get("on_failure").is_none(),
"empty on_failure must not appear on the wire: {json}"
);
}
#[test]
fn validate_accepts_good_retry() {
for (max, backoff) in [(1, "30s"), (3, "10m"), (10, "1h")] {
with_retry(max, backoff)
.validate()
.unwrap_or_else(|e| panic!("retry {{max:{max}, backoff:{backoff}}}: {e}"));
}
}
#[test]
fn validate_rejects_bad_backoff() {
let err = with_retry(3, "soon").validate().unwrap_err();
assert!(err.contains("on_failure.retry.backoff"), "got: {err}");
}
#[test]
fn validate_rejects_sub_second_backoff() {
for bad in ["500ms", "0s", "999ms"] {
let err = with_retry(3, bad).validate().unwrap_err();
assert!(
err.contains("on_failure.retry.backoff must be >= 1s"),
"for '{bad}', got: {err}"
);
}
}
#[test]
fn validate_rejects_out_of_range_max() {
for bad in [0u32, 11, 1000] {
let err = with_retry(bad, "10m").validate().unwrap_err();
assert!(
err.contains("on_failure.retry.max"),
"for max={bad}, got: {err}"
);
}
}
#[test]
fn lowered_retry_reduces_backoff_to_seconds() {
let s = with_retry(3, "10m");
let spec = s.on_failure.lowered_retry().expect("a retry policy");
assert_eq!(spec.max, 3);
assert_eq!(spec.backoff_secs, 600);
}
#[test]
fn lowered_retry_is_none_without_policy() {
let s = schedule_with(
When::PerPc(PerPolicy::Once(OnceLiteral::Once)),
RunsOn::Backend,
);
assert!(s.on_failure.lowered_retry().is_none());
}
#[test]
fn freeze_empty_window_is_always_active() {
let f = Freeze::default();
assert!(f.is_active(chrono::Utc::now()));
}
#[test]
fn freeze_window_is_half_open() {
use chrono::TimeZone;
let f = Freeze {
from: Some("2026-12-20T00:00:00+00:00".into()),
until: Some("2027-01-05T00:00:00+00:00".into()),
reason: Some("year-end".into()),
tz: ScheduleTz::Utc,
};
let at = |y, mo, d| chrono::Utc.with_ymd_and_hms(y, mo, d, 0, 0, 0).unwrap();
assert!(!f.is_active(at(2026, 12, 19)), "before from = not frozen");
assert!(f.is_active(at(2026, 12, 20)), "from is inclusive");
assert!(f.is_active(at(2026, 12, 31)), "inside window");
assert!(!f.is_active(at(2027, 1, 5)), "until is exclusive");
assert!(!f.is_active(at(2027, 1, 6)), "after until = not frozen");
}
#[test]
fn freeze_fails_closed_on_corrupt_bound() {
let f = Freeze {
from: Some("not-a-date".into()),
until: None,
reason: None,
tz: ScheduleTz::Utc,
};
assert!(f.is_active(chrono::Utc::now()), "corrupt bound → frozen");
}
#[test]
fn freeze_validate_accepts_good_bounds() {
Freeze {
from: Some("2026-12-20".into()),
until: Some("2027-01-05T12:00:00+09:00".into()),
reason: None,
tz: ScheduleTz::Local,
}
.validate()
.expect("date + rfc3339 bounds should validate");
Freeze::default().validate().expect("empty freeze is valid");
}
#[test]
fn freeze_validate_rejects_bad_bound_and_inverted_window() {
let err = Freeze {
from: Some("never".into()),
..Default::default()
}
.validate()
.unwrap_err();
assert!(err.contains("freeze:"), "got: {err}");
let inverted = Freeze {
from: Some("2027-01-05".into()),
until: Some("2026-12-20".into()),
..Default::default()
}
.validate()
.unwrap_err();
assert!(inverted.contains("freeze.from"), "got: {inverted}");
}
#[test]
fn freeze_round_trips_and_skips_empty_fields() {
let f = Freeze {
from: None,
until: Some("2027-01-05".into()),
reason: Some("INC-1234".into()),
tz: ScheduleTz::Utc,
};
let json = serde_json::to_value(&f).expect("serialise");
assert!(json.get("from").is_none(), "empty from omitted: {json}");
let back: Freeze = serde_json::from_value(json).expect("round-trip");
assert_eq!(back, f);
}
#[test]
fn shipped_schedule_configs_parse_and_validate() {
let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../configs/schedules");
let mut seen = 0;
for entry in std::fs::read_dir(&dir).expect("read configs/schedules") {
let path = entry.expect("dir entry").path();
if path.extension().and_then(|e| e.to_str()) != Some("yaml") {
continue;
}
let body = std::fs::read_to_string(&path).expect("read yaml");
let s: Schedule = serde_yaml::from_str(&body)
.unwrap_or_else(|e| panic!("{} failed to parse: {e}", path.display()));
s.validate()
.unwrap_or_else(|e| panic!("{} failed validate(): {e}", path.display()));
seen += 1;
}
assert!(seen > 0, "no schedule YAMLs found in {}", dir.display());
}
#[test]
fn exec_mode_serialises_snake_case() {
for (mode, expected) in [
(ExecMode::EveryTick, "every_tick"),
(ExecMode::OncePerPc, "once_per_pc"),
(ExecMode::OncePerTarget, "once_per_target"),
] {
let s = serde_json::to_value(mode).expect("serialise");
assert_eq!(s, serde_json::Value::String(expected.into()));
let back: ExecMode = serde_json::from_value(serde_json::Value::String(expected.into()))
.expect("deserialise");
assert_eq!(back, mode, "round-trip for {expected}");
}
}
#[test]
fn schedule_runs_on_defaults_to_backend() {
let yaml = r#"
id: x
when:
per_pc: once
job_id: y
target: { all: true }
"#;
let s: Schedule = serde_yaml::from_str(yaml).expect("parse");
assert_eq!(s.runs_on, RunsOn::Backend);
}
#[test]
fn schedule_runs_on_agent_parses() {
let yaml = r#"
id: offline-inv
when:
per_pc: { every: 1h }
job_id: inventory-hw
target: { all: true }
runs_on: agent
"#;
let s: Schedule = serde_yaml::from_str(yaml).expect("parse");
assert_eq!(s.runs_on, RunsOn::Agent);
assert_eq!(s.lowered().mode, ExecMode::OncePerPc);
}
#[test]
fn runs_on_serialises_snake_case() {
for (mode, expected) in [(RunsOn::Backend, "backend"), (RunsOn::Agent, "agent")] {
let s = serde_json::to_value(mode).expect("serialise");
assert_eq!(s, serde_json::Value::String(expected.into()));
let back: RunsOn = serde_json::from_value(serde_json::Value::String(expected.into()))
.expect("deserialise");
assert_eq!(back, mode);
}
}
#[test]
fn execute_shell_into_wire_shell() {
assert_eq!(Shell::from(ExecuteShell::Powershell), Shell::Powershell);
assert_eq!(Shell::from(ExecuteShell::Cmd), Shell::Cmd);
}
#[test]
fn manifest_staleness_defaults_to_cached() {
let yaml = r#"
id: x
version: 1.0.0
execute:
shell: powershell
script: "echo"
timeout: 1s
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
assert_eq!(m.staleness, Staleness::Cached);
}
#[test]
fn manifest_strict_staleness_parses() {
let yaml = r#"
id: urgent-patch
version: 2.5.1
execute:
shell: powershell
script: Install-Hotfix
timeout: 5m
staleness:
mode: strict
max_cache_age: 0s
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
match m.staleness {
Staleness::Strict { max_cache_age } => assert_eq!(max_cache_age, "0s"),
other => panic!("expected strict, got {other:?}"),
}
}
#[test]
fn manifest_unchecked_staleness_parses() {
let yaml = r#"
id: legacy
version: 0.1.0
execute:
shell: cmd
script: "echo"
timeout: 1s
staleness:
mode: unchecked
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
assert_eq!(m.staleness, Staleness::Unchecked);
}
#[test]
fn missing_required_field_errors() {
let yaml = r#"
version: 1.0.0
target: { all: true }
execute:
shell: powershell
script: "echo"
timeout: 1s
"#;
let r: Result<Manifest, _> = serde_yaml::from_str(yaml);
assert!(r.is_err(), "expected error, got {:?}", r);
}
#[test]
fn display_field_table_kind_round_trips_with_nested_columns() {
let yaml = r#"
id: inv-hw
version: 1.0.0
execute:
shell: powershell
script: "echo"
timeout: 60s
inventory:
display:
- field: hostname
label: Hostname
- field: disks
label: Disks
type: table
columns:
- field: device_id
label: Drive
- field: size_bytes
label: Size
type: bytes
- field: free_bytes
label: Free
type: bytes
- field: file_system
label: FS
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
let inv = m.inventory.as_ref().expect("inventory hint");
let disks = inv
.display
.iter()
.find(|d| d.field == "disks")
.expect("disks display row");
assert_eq!(disks.kind.as_deref(), Some("table"));
let cols = disks.columns.as_ref().expect("table needs columns");
assert_eq!(cols.len(), 4);
assert_eq!(cols[1].field, "size_bytes");
assert_eq!(cols[1].kind.as_deref(), Some("bytes"));
}
#[test]
fn display_field_scalar_kind_keeps_columns_none() {
let yaml = r#"
id: x
version: 1.0.0
execute:
shell: powershell
script: "echo"
timeout: 5s
inventory:
display:
- { field: ram_bytes, label: RAM, type: bytes }
"#;
let m: Manifest = serde_yaml::from_str(yaml).expect("parse");
let inv = m.inventory.as_ref().unwrap();
assert!(inv.display[0].columns.is_none());
}
#[test]
fn schema_files_are_current() {
assert_schema_file("schedule.schema.json", &schemars::schema_for!(Schedule));
assert_schema_file("job.schema.json", &schemars::schema_for!(Manifest));
assert_schema_file("view.schema.json", &schemars::schema_for!(View));
}
fn assert_schema_file(name: &str, schema: &schemars::Schema) {
let generated = serde_json::to_string_pretty(schema).expect("serialize schema") + "\n";
let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../docs/schemas")
.join(name);
if std::env::var_os("UPDATE_SCHEMAS").is_some() {
std::fs::create_dir_all(path.parent().unwrap()).expect("mkdir docs/schemas");
std::fs::write(&path, &generated).unwrap_or_else(|e| panic!("write {path:?}: {e}"));
return;
}
let on_disk = std::fs::read_to_string(&path)
.unwrap_or_else(|e| {
panic!(
"read {path:?}: {e}\n\
generate it with: UPDATE_SCHEMAS=1 cargo test -p kanade-shared schema_files_are_current"
)
})
.replace("\r\n", "\n");
assert_eq!(
on_disk, generated,
"{name} is stale — a Schedule/Manifest schema change isn't reflected in docs/schemas/. \
Refresh with: UPDATE_SCHEMAS=1 cargo test -p kanade-shared schema_files_are_current"
);
}
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone)]
pub struct Schedule {
pub id: String,
#[serde(with = "serde_yaml::with::singleton_map")]
#[schemars(with = "When")]
pub when: When,
pub job_id: String,
#[serde(flatten)]
pub plan: FanoutPlan,
#[serde(default, skip_serializing_if = "Active::is_empty")]
pub active: Active,
#[serde(default, skip_serializing_if = "Constraints::is_empty")]
pub constraints: Constraints,
#[serde(default, skip_serializing_if = "OnFailure::is_empty")]
pub on_failure: OnFailure,
#[serde(default)]
pub tz: ScheduleTz,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub starting_deadline: Option<String>,
#[serde(default)]
pub runs_on: RunsOn,
#[serde(default = "default_true")]
pub enabled: bool,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub tags: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub origin: Option<RepoOrigin>,
}
#[derive(
Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Copy, PartialEq, Eq, Default,
)]
#[serde(rename_all = "snake_case")]
pub enum RunsOn {
#[default]
Backend,
Agent,
}
#[derive(
Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Copy, PartialEq, Eq, Default,
)]
#[serde(rename_all = "snake_case")]
pub enum ExecMode {
#[default]
EveryTick,
OncePerPc,
OncePerTarget,
Event,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum When {
PerPc(PerPolicy),
PerTarget(PerPolicy),
Calendar(CalendarSpec),
On(Vec<OnTrigger>),
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[serde(rename_all = "snake_case")]
pub enum OnTrigger {
Startup,
Logon,
Lock,
Unlock,
NetworkChange,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, PartialEq, Eq)]
pub struct CalendarSpec {
pub at: String,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub days: Vec<String>,
}
struct ParsedAt {
minute: u32,
hour: u32,
date: Option<chrono::NaiveDate>,
}
impl CalendarSpec {
fn parse_at(&self) -> Result<ParsedAt, String> {
use chrono::Timelike;
let s = self.at.trim();
for fmt in ["%Y-%m-%d %H:%M", "%Y-%m-%dT%H:%M", "%Y/%m/%d %H:%M"] {
if let Ok(dt) = chrono::NaiveDateTime::parse_from_str(s, fmt) {
return Ok(ParsedAt {
minute: dt.minute(),
hour: dt.hour(),
date: Some(dt.date()),
});
}
}
if let Ok(t) = chrono::NaiveTime::parse_from_str(s, "%H:%M") {
return Ok(ParsedAt {
minute: t.minute(),
hour: t.hour(),
date: None,
});
}
Err(format!(
"when.at: unparseable '{}' (want HH:MM or YYYY-MM-DD HH:MM)",
self.at
))
}
fn validate_days(&self) -> Result<(), String> {
const NAMES: [&str; 7] = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"];
let is_day = |p: &str| NAMES.contains(&p) || p.parse::<u8>().is_ok_and(|n| n <= 7);
for tok in &self.days {
let invalid = |reason: &str| {
Err(format!(
"when.days: invalid day token '{tok}' ({reason}; \
want mon..sun, 0-7, a range like mon-fri, an nth-weekday \
like tue#2, a last-weekday like friL, or *)"
))
};
if let Some((day_part, nth_part)) = tok.split_once('#') {
let d = day_part.trim().to_ascii_lowercase();
if d.contains('-') || !is_day(&d) {
return invalid("the part before # must be a single weekday");
}
match nth_part.trim().parse::<u8>() {
Ok(n) if (1..=5).contains(&n) => {}
_ => return invalid("the # ordinal must be 1..5 (e.g. tue#2 = 2nd Tuesday)"),
}
continue;
}
if let Some(day_part) = tok.strip_suffix(['L', 'l']) {
let d = day_part.to_ascii_lowercase();
if d.is_empty() {
return invalid("`L` (last-weekday) needs a weekday before it, e.g. friL");
}
if d.contains('-') || !is_day(&d) {
return invalid(
"the part before L must be a single weekday (e.g. friL = last Friday)",
);
}
continue;
}
for part in tok.split('-') {
let p = part.trim().to_ascii_lowercase();
if p.is_empty() {
return invalid("empty range bound");
}
if p != "*" && !is_day(&p) {
return invalid(&format!("'{part}' is not a day"));
}
}
}
Ok(())
}
pub fn oneshot_instant(&self, tz: ScheduleTz) -> Option<chrono::DateTime<chrono::Utc>> {
let p = self.parse_at().ok()?;
let date = p.date?;
let naive = date.and_hms_opt(p.hour, p.minute, 0)?;
tz.naive_to_utc(naive)
}
pub fn fire_time(&self) -> Option<chrono::NaiveTime> {
let p = self.parse_at().ok()?;
chrono::NaiveTime::from_hms_opt(p.hour, p.minute, 0)
}
fn to_cron(&self) -> Result<String, String> {
use chrono::Datelike;
let ParsedAt { minute, hour, date } = self.parse_at()?;
match date {
Some(d) => {
if !self.days.is_empty() {
return Err(
"when.at with a date is a one-shot and cannot be combined with days".into(),
);
}
Ok(format!(
"0 {minute} {hour} {} {} * {}",
d.day(),
d.month(),
d.year()
))
}
None => {
let dow = if self.days.is_empty() {
"*".to_string()
} else {
self.validate_days()?;
self.days.join(",")
};
Ok(format!("0 {minute} {hour} * * {dow}"))
}
}
}
}
#[derive(
Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Copy, PartialEq, Eq, Default,
)]
#[serde(rename_all = "snake_case")]
pub enum ScheduleTz {
#[default]
Local,
Utc,
}
impl ScheduleTz {
fn naive_to_utc(self, naive: chrono::NaiveDateTime) -> Option<chrono::DateTime<chrono::Utc>> {
use chrono::TimeZone;
match self {
ScheduleTz::Utc => Some(chrono::DateTime::from_naive_utc_and_offset(
naive,
chrono::Utc,
)),
ScheduleTz::Local => chrono::Local
.from_local_datetime(&naive)
.earliest()
.map(|dt| dt.with_timezone(&chrono::Utc)),
}
}
fn wall_time(self, now: chrono::DateTime<chrono::Utc>) -> chrono::NaiveTime {
match self {
ScheduleTz::Utc => now.time(),
ScheduleTz::Local => now.with_timezone(&chrono::Local).time(),
}
}
fn wall_date(self, now: chrono::DateTime<chrono::Utc>) -> chrono::NaiveDate {
match self {
ScheduleTz::Utc => now.date_naive(),
ScheduleTz::Local => now.with_timezone(&chrono::Local).date_naive(),
}
}
pub fn as_str(self) -> &'static str {
match self {
ScheduleTz::Local => "local",
ScheduleTz::Utc => "utc",
}
}
}
impl std::fmt::Display for ScheduleTz {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, PartialEq, Eq)]
#[serde(untagged)]
pub enum PerPolicy {
Once(OnceLiteral),
Every(EverySpec),
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum OnceLiteral {
Once,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, PartialEq, Eq)]
pub struct EverySpec {
pub every: String,
}
impl PerPolicy {
fn cooldown(&self) -> Option<String> {
match self {
PerPolicy::Once(_) => None,
PerPolicy::Every(EverySpec { every }) => Some(every.clone()),
}
}
}
impl std::fmt::Display for When {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let policy = |p: &PerPolicy| match p {
PerPolicy::Once(_) => "once".to_string(),
PerPolicy::Every(EverySpec { every }) => format!("every {every}"),
};
match self {
When::PerPc(p) => write!(f, "per_pc {}", policy(p)),
When::PerTarget(p) => write!(f, "per_target {}", policy(p)),
When::Calendar(c) if c.days.is_empty() => write!(f, "at {}", c.at),
When::Calendar(c) => write!(f, "at {} [{}]", c.at, c.days.join(",")),
When::On(triggers) => {
let names: Vec<&str> = triggers.iter().map(|t| t.as_str()).collect();
write!(f, "on [{}]", names.join(","))
}
}
}
}
impl OnTrigger {
pub fn as_str(self) -> &'static str {
match self {
OnTrigger::Startup => "startup",
OnTrigger::Logon => "logon",
OnTrigger::Lock => "lock",
OnTrigger::Unlock => "unlock",
OnTrigger::NetworkChange => "network_change",
}
}
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Default, PartialEq, Eq)]
pub struct Active {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub from: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub until: Option<String>,
}
impl Active {
pub fn is_empty(&self) -> bool {
self.from.is_none() && self.until.is_none()
}
pub fn parse_bound(s: &str, tz: ScheduleTz) -> Result<chrono::DateTime<chrono::Utc>, String> {
if let Ok(dt) = chrono::DateTime::parse_from_rfc3339(s) {
return Ok(dt.with_timezone(&chrono::Utc));
}
if let Ok(d) = chrono::NaiveDate::parse_from_str(s, "%Y-%m-%d") {
let midnight = d.and_hms_opt(0, 0, 0).expect("00:00:00 is always valid");
return tz.naive_to_utc(midnight).ok_or_else(|| {
format!("active: bound '{s}' falls in a DST gap for the schedule's tz")
});
}
Err(format!(
"active: unparseable bound '{s}' (want YYYY-MM-DD or RFC3339)"
))
}
pub fn contains(&self, now: chrono::DateTime<chrono::Utc>, tz: ScheduleTz) -> bool {
let bound = |s: &Option<String>| s.as_deref().and_then(|s| Self::parse_bound(s, tz).ok());
if bound(&self.from).is_some_and(|from| now < from) {
return false;
}
if bound(&self.until).is_some_and(|until| now >= until) {
return false;
}
true
}
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Default, PartialEq)]
pub struct Require {
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub ac_power: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub idle: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub cpu_below: Option<f64>,
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub network: bool,
}
impl Require {
pub fn is_empty(&self) -> bool {
!self.ac_power && self.idle.is_none() && self.cpu_below.is_none() && !self.network
}
pub fn min_idle(&self) -> Option<std::time::Duration> {
self.idle
.as_deref()
.and_then(|s| humantime::parse_duration(s.trim()).ok())
}
pub fn bad_idle(&self) -> Option<String> {
self.idle.as_deref().and_then(|s| {
humantime::parse_duration(s.trim())
.err()
.map(|e| format!("constraints.require.idle: invalid duration '{s}': {e}"))
})
}
}
#[derive(Debug, Clone, Copy, Default)]
pub struct EnvState {
pub ac_online: bool,
pub idle: Option<std::time::Duration>,
pub cpu_pct: Option<f64>,
pub network_up: bool,
}
pub fn require_met(req: &Require, env: &EnvState) -> bool {
if req.ac_power && !env.ac_online {
return false;
}
if let Some(min) = req.min_idle() {
match env.idle {
Some(d) if d >= min => {}
_ => return false,
}
}
if let Some(max) = req.cpu_below {
match env.cpu_pct {
Some(p) if p < max => {}
_ => return false,
}
}
if req.network && !env.network_up {
return false;
}
true
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Default, PartialEq)]
pub struct Constraints {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub window: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_concurrent: Option<u32>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub skip_dates: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub require: Option<Require>,
}
impl Constraints {
pub fn is_empty(&self) -> bool {
self.window.is_none()
&& self.max_concurrent.is_none()
&& self.skip_dates.is_empty()
&& self.require.as_ref().is_none_or(Require::is_empty)
}
pub fn bad_skip_date(&self) -> Option<String> {
self.skip_dates.iter().find_map(|s| {
chrono::NaiveDate::parse_from_str(s.trim(), "%Y-%m-%d")
.err()
.map(|e| format!("constraints.skip_dates: invalid date '{s}': {e}"))
})
}
pub fn parse_window(s: &str) -> Result<(chrono::NaiveTime, chrono::NaiveTime), String> {
let (a, b) = s
.split_once('-')
.ok_or_else(|| format!("constraints.window: '{s}' must be 'HH:MM-HH:MM'"))?;
let parse = |part: &str| {
chrono::NaiveTime::parse_from_str(part.trim(), "%H:%M")
.map_err(|e| format!("constraints.window: invalid time '{}': {e}", part.trim()))
};
let (start, end) = (parse(a)?, parse(b)?);
if start == end {
return Err(format!(
"constraints.window: start and end are equal ('{s}'); omit window for 'always'"
));
}
Ok((start, end))
}
pub fn allows(&self, now: chrono::DateTime<chrono::Utc>, tz: ScheduleTz) -> bool {
if !self.skip_dates.is_empty() {
let today = tz.wall_date(now);
let blocked = self.skip_dates.iter().any(|s| {
match chrono::NaiveDate::parse_from_str(s.trim(), "%Y-%m-%d") {
Ok(d) => d == today,
Err(_) => true, }
});
if blocked {
return false;
}
}
match self.window.as_deref() {
None => true,
Some(_) => self.window_contains(tz.wall_time(now)).unwrap_or(false),
}
}
fn window_contains(&self, t: chrono::NaiveTime) -> Option<bool> {
let (start, end) = Self::parse_window(self.window.as_deref()?).ok()?;
Some(if start <= end {
start <= t && t < end
} else {
t >= start || t < end
})
}
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Default, PartialEq, Eq)]
pub struct OnFailure {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub retry: Option<Retry>,
}
impl OnFailure {
pub fn is_empty(&self) -> bool {
self.retry.is_none()
}
pub fn lowered_retry(&self) -> Option<crate::wire::RetrySpec> {
let r = self.retry.as_ref()?;
let backoff_secs = humantime::parse_duration(&r.backoff).ok()?.as_secs();
Some(crate::wire::RetrySpec {
max: r.max,
backoff_secs,
})
}
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, PartialEq, Eq)]
pub struct Retry {
pub max: u32,
pub backoff: String,
}
#[derive(Serialize, Deserialize, schemars::JsonSchema, Debug, Clone, Default, PartialEq, Eq)]
pub struct Freeze {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub from: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub until: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub reason: Option<String>,
#[serde(default)]
pub tz: ScheduleTz,
}
impl Freeze {
pub fn is_active(&self, now: chrono::DateTime<chrono::Utc>) -> bool {
let bound = |s: &Option<String>| -> Result<Option<chrono::DateTime<chrono::Utc>>, ()> {
match s.as_deref() {
None => Ok(None),
Some(raw) => Active::parse_bound(raw, self.tz).map(Some).map_err(|_| ()),
}
};
let (from, until) = match (bound(&self.from), bound(&self.until)) {
(Ok(f), Ok(u)) => (f, u),
_ => return true,
};
if from.is_some_and(|f| now < f) {
return false;
}
if until.is_some_and(|u| now >= u) {
return false;
}
true
}
pub fn validate(&self) -> Result<(), String> {
let from = self
.from
.as_deref()
.map(|s| Active::parse_bound(s, self.tz))
.transpose()
.map_err(|e| e.replace("active:", "freeze:"))?;
let until = self
.until
.as_deref()
.map(|s| Active::parse_bound(s, self.tz))
.transpose()
.map_err(|e| e.replace("active:", "freeze:"))?;
if let (Some(f), Some(u)) = (from, until) {
if f >= u {
return Err(format!(
"freeze.from ({}) must be strictly before freeze.until ({})",
self.from.as_deref().unwrap_or_default(),
self.until.as_deref().unwrap_or_default(),
));
}
}
Ok(())
}
}
pub const POLL_CRON: &str = "0 * * * * *";
pub struct Lowered {
pub cron: String,
pub mode: ExecMode,
pub cooldown: Option<String>,
pub tz: ScheduleTz,
}
impl Schedule {
pub fn bad_window(&self) -> Option<String> {
let w = self.constraints.window.as_deref()?;
Constraints::parse_window(w).err()
}
pub fn calendar_outside_window(&self) -> bool {
let When::Calendar(c) = &self.when else {
return false;
};
let Some(t) = c.fire_time() else {
return false;
};
matches!(self.constraints.window_contains(t), Some(false))
}
pub fn preview_fires(
&self,
now: chrono::DateTime<chrono::Utc>,
count: usize,
) -> Vec<chrono::DateTime<chrono::Utc>> {
use croner::parser::{CronParser, Seconds};
if !matches!(self.when, When::Calendar(_)) {
return Vec::new();
}
let lowered = self.lowered();
let Ok(cron) = CronParser::builder()
.seconds(Seconds::Required)
.dom_and_dow(true)
.build()
.parse(&lowered.cron)
else {
return Vec::new();
};
let accept = |utc: chrono::DateTime<chrono::Utc>| {
self.active.contains(utc, self.tz) && self.constraints.allows(utc, self.tz)
};
match self.tz {
ScheduleTz::Utc => Self::next_occurrences(&cron, now, count, accept),
ScheduleTz::Local => {
Self::next_occurrences(&cron, now.with_timezone(&chrono::Local), count, accept)
}
}
}
fn next_occurrences<Tz>(
cron: &croner::Cron,
after: chrono::DateTime<Tz>,
count: usize,
accept: impl Fn(chrono::DateTime<chrono::Utc>) -> bool,
) -> Vec<chrono::DateTime<chrono::Utc>>
where
Tz: chrono::TimeZone,
{
const SCAN_CAP: usize = 4096;
let mut out = Vec::with_capacity(count.min(SCAN_CAP));
let mut cursor = after;
let mut scanned = 0usize;
while out.len() < count && scanned < SCAN_CAP {
scanned += 1;
let Ok(next) = cron.find_next_occurrence(&cursor, false) else {
break;
};
let utc = next.with_timezone(&chrono::Utc);
if accept(utc) {
out.push(utc);
}
cursor = next;
}
out
}
pub fn lowered(&self) -> Lowered {
let tz = self.tz;
match &self.when {
When::PerPc(p) => Lowered {
cron: POLL_CRON.into(),
mode: ExecMode::OncePerPc,
cooldown: p.cooldown(),
tz,
},
When::PerTarget(p) => Lowered {
cron: POLL_CRON.into(),
mode: ExecMode::OncePerTarget,
cooldown: p.cooldown(),
tz,
},
When::Calendar(c) => Lowered {
cron: c
.to_cron()
.unwrap_or_else(|_| "# invalid calendar at".into()),
mode: ExecMode::EveryTick,
cooldown: None,
tz,
},
When::On(_) => Lowered {
cron: "# event-trigger (no cron)".into(),
mode: ExecMode::Event,
cooldown: None,
tz,
},
}
}
pub fn is_event(&self) -> bool {
matches!(self.when, When::On(_))
}
pub fn event_triggers(&self) -> &[OnTrigger] {
match &self.when {
When::On(t) => t,
_ => &[],
}
}
pub fn next_calendar_fire(
&self,
now: chrono::DateTime<chrono::Utc>,
) -> Option<chrono::DateTime<chrono::Utc>> {
if !matches!(self.when, When::Calendar(_)) {
return None;
}
let lowered = self.lowered();
let cron = croner::parser::CronParser::builder()
.seconds(croner::parser::Seconds::Required)
.dom_and_dow(true)
.build()
.parse(&lowered.cron)
.ok()?;
match lowered.tz {
ScheduleTz::Utc => cron.find_next_occurrence(&now, false).ok(),
ScheduleTz::Local => {
let now_local = now.with_timezone(&chrono::Local);
cron.find_next_occurrence(&now_local, false)
.ok()
.map(|t| t.with_timezone(&chrono::Utc))
}
}
}
pub fn validate(&self) -> Result<(), String> {
if matches!(self.runs_on, RunsOn::Agent) && matches!(self.when, When::PerTarget(_)) {
return Err(
"when.per_target needs fleet-wide completion data and is backend-only; \
it cannot be combined with runs_on: agent (each agent self-schedules, \
so per-target dedup would be deduping across a target of 1)"
.into(),
);
}
if let When::On(triggers) = &self.when {
if !matches!(self.runs_on, RunsOn::Agent) {
return Err(
"when.on (OS event trigger) is fired by the agent's own event \
source, so it requires runs_on: agent"
.into(),
);
}
if triggers.is_empty() {
return Err(
"when.on must list at least one trigger (e.g. [startup, logon])".into(),
);
}
}
if let Some(cd) = self.lowered().cooldown.as_deref() {
humantime::parse_duration(cd)
.map_err(|e| format!("when.every: invalid duration '{cd}': {e}"))?;
}
if let When::Calendar(c) = &self.when {
let cron = c.to_cron()?;
croner::parser::CronParser::builder()
.seconds(croner::parser::Seconds::Required)
.dom_and_dow(true)
.build()
.parse(&cron)
.map_err(|e| format!("when.at lowered to invalid cron '{cron}': {e}"))?;
}
if let Some(j) = &self.plan.jitter {
humantime::parse_duration(j)
.map_err(|e| format!("jitter: invalid duration '{j}': {e}"))?;
}
if let Some(sd) = &self.starting_deadline {
humantime::parse_duration(sd)
.map_err(|e| format!("starting_deadline: invalid duration '{sd}': {e}"))?;
}
let from = self
.active
.from
.as_deref()
.map(|s| Active::parse_bound(s, self.tz))
.transpose()?;
let until = self
.active
.until
.as_deref()
.map(|s| Active::parse_bound(s, self.tz))
.transpose()?;
if let (Some(f), Some(u)) = (from, until) {
if f >= u {
return Err(format!(
"active.from ({}) must be strictly before active.until ({})",
self.active.from.as_deref().unwrap_or_default(),
self.active.until.as_deref().unwrap_or_default(),
));
}
}
if let Some(w) = self.constraints.window.as_deref() {
Constraints::parse_window(w)?;
}
if let Some(err) = self.constraints.bad_skip_date() {
return Err(err);
}
if let Some(mc) = self.constraints.max_concurrent {
if matches!(self.runs_on, RunsOn::Agent) {
return Err(
"constraints.max_concurrent needs a central counter and is backend-only; \
it cannot be combined with runs_on: agent (each agent self-schedules, \
so there is no fleet-wide count to cap against)"
.into(),
);
}
if mc == 0 {
return Err(
"constraints.max_concurrent must be >= 1 (0 would never fire; \
omit it for no cap)"
.into(),
);
}
}
if let Some(req) = &self.constraints.require {
if !req.is_empty() && matches!(self.runs_on, RunsOn::Backend) {
return Err(
"constraints.require (host-state env gates: ac_power / idle / cpu_below / \
network) is sensed in-process by the agent and needs runs_on: agent; the \
backend cannot read a target host's power / idle / cpu / connectivity state"
.into(),
);
}
if let Some(err) = req.bad_idle() {
return Err(err);
}
if let Some(c) = req.cpu_below
&& !(c > 0.0 && c <= 100.0)
{
return Err(format!(
"constraints.require.cpu_below must be in (0, 100] percent (got {c}); \
omit it for no CPU requirement"
));
}
}
if let Some(r) = &self.on_failure.retry {
let backoff = humantime::parse_duration(&r.backoff).map_err(|e| {
format!(
"on_failure.retry.backoff: invalid duration '{}': {e}",
r.backoff
)
})?;
if backoff.as_secs() < 1 {
return Err(format!(
"on_failure.retry.backoff must be >= 1s (got '{}'); sub-second backoffs \
round to 0 on the wire",
r.backoff
));
}
if !(1..=10).contains(&r.max) {
return Err(format!(
"on_failure.retry.max must be 1..=10 (got {}); it counts additional \
attempts after the first run",
r.max
));
}
}
for tag in &self.tags {
if tag.trim().is_empty() {
return Err("tags must not contain empty entries".to_string());
}
}
Ok(())
}
}
fn default_true() -> bool {
true
}