scheduler: add jitter support

- Add task jitter (random delay before execution)
- Add retry jitter (random variation in backoff delay)
- Auto-infer retry jitter as 25% of delay when not specified
- Add milliseconds (ms) support to duration parsing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: aster-void

CLAUDE.md

@@ -26,16 +26,19 @@ struct Job {
     timeout: Duration,
     concurrency: Concurrency,
     retry: Option<RetryConfig>,
+    jitter: Option<Duration>,  // Random delay before execution (0 to jitter)
 }
 
 struct RetryConfig {
     max: u32,             // Max retry attempts
     delay: Duration,      // Initial delay (exponential backoff)
+    jitter: Option<Duration>,  // Random variation added to retry delay (0 to jitter)
+                               // Auto-inferred as 25% of delay when not set
 }
 
 // Parsed from rollcron.yaml
 struct Config { jobs: HashMap<String, JobConfig> }
-struct JobConfig { name: Option<String>, schedule: ScheduleConfig, run, timeout }
+struct JobConfig { name: Option<String>, schedule: ScheduleConfig, run, timeout, jitter }
 struct ScheduleConfig { cron: String }
 ```
 
@@ -49,10 +52,13 @@ jobs:
       cron: "*/5 * * * *"
     run: echo hello
     timeout: 10s             # Optional (default: 10s)
+    jitter: 30s              # Optional: random delay 0-30s before execution
     concurrency: skip        # Optional: parallel|wait|skip|replace (default: skip)
     retry:                   # Optional
       max: 3                 # Max retry attempts
       delay: 1s              # Initial delay (default: 1s), exponential backoff
+      jitter: 500ms          # Optional: random variation 0-500ms added to retry delay
+                             # If omitted, auto-inferred as 25% of delay (e.g., 250ms for 1s delay)
 ```
 
 ## Runtime Directory Layout
@@ -92,7 +98,9 @@ jobs:
 1. Scheduler polls every 1 second
 2. Check each job's cron schedule
 3. If due: spawn task in job's directory (by ID) with timeout
-4. Log using display name
+4. Apply task jitter (random delay 0 to jitter) before first execution
+5. On failure: apply exponential backoff + retry jitter before retry
+6. Log using display name
 
 ## Constraints
 

Cargo.lock

@@ -13,6 +13,7 @@ clap = { version = "4", features = ["derive"] }
 dirs = "6"
 serde = { version = "1", features = ["derive"] }
 serde_yaml = "0.9"
+rand = "0.8"
 
 [dev-dependencies]
 tempfile = "3"

Cargo.toml

@@ -44,6 +44,7 @@ pub struct JobConfig {
     pub concurrency: Concurrency,
     pub retry: Option<RetryConfigRaw>,
     pub working_dir: Option<String>,
+    pub jitter: Option<String>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -52,6 +53,7 @@ pub struct RetryConfigRaw {
     pub max: u32,
     #[serde(default = "default_retry_delay")]
     pub delay: String,
+    pub jitter: Option<String>,
 }
 
 fn default_retry_delay() -> String {
@@ -77,12 +79,14 @@ pub struct Job {
     pub concurrency: Concurrency,
     pub retry: Option<RetryConfig>,
     pub working_dir: Option<String>,
+    pub jitter: Option<Duration>,
 }
 
 #[derive(Debug, Clone)]
 pub struct RetryConfig {
     pub max: u32,
     pub delay: Duration,
+    pub jitter: Option<Duration>,
 }
 
 pub fn parse_config(content: &str) -> Result<(RunnerConfig, Vec<Job>)> {
@@ -116,10 +120,20 @@ pub fn parse_config(content: &str) -> Result<(RunnerConfig, Vec<Job>)> {
                 .map(|r| {
                     let delay = parse_duration(&r.delay)
                         .map_err(|e| anyhow!("Invalid retry delay '{}' in job '{}': {}", r.delay, id, e))?;
-                    Ok::<_, anyhow::Error>(RetryConfig { max: r.max, delay })
+                    let jitter = r.jitter
+                        .map(|j| parse_duration(&j)
+                            .map_err(|e| anyhow!("Invalid retry jitter '{}' in job '{}': {}", j, id, e)))
+                        .transpose()?;
+                    Ok::<_, anyhow::Error>(RetryConfig { max: r.max, delay, jitter })
                 })
                 .transpose()?;
 
+            let jitter = job
+                .jitter
+                .map(|j| parse_duration(&j)
+                    .map_err(|e| anyhow!("Invalid jitter '{}' in job '{}': {}", j, id, e)))
+                .transpose()?;
+
             Ok(Job {
                 id,
                 name,
@@ -129,6 +143,7 @@ pub fn parse_config(content: &str) -> Result<(RunnerConfig, Vec<Job>)> {
                 concurrency: job.concurrency,
                 retry,
                 working_dir: job.working_dir,
+                jitter,
             })
         })
         .collect::<Result<Vec<_>>>()?;
@@ -138,7 +153,9 @@ pub fn parse_config(content: &str) -> Result<(RunnerConfig, Vec<Job>)> {
 
 fn parse_duration(s: &str) -> Result<Duration> {
     let s = s.trim();
-    if let Some(secs) = s.strip_suffix('s') {
+    if let Some(millis) = s.strip_suffix("ms") {
+        Ok(Duration::from_millis(millis.parse()?))
+    } else if let Some(secs) = s.strip_suffix('s') {
         Ok(Duration::from_secs(secs.parse()?))
     } else if let Some(mins) = s.strip_suffix('m') {
         Ok(Duration::from_secs(mins.parse::<u64>()? * 60))
@@ -370,4 +387,61 @@ jobs:
 "#;
         assert!(parse_config(yaml).is_err());
     }
+
+    #[test]
+    fn parse_jitter() {
+        let yaml = r#"
+jobs:
+  with_jitter:
+    schedule:
+      cron: "* * * * *"
+    run: echo test
+    jitter: 30s
+  no_jitter:
+    schedule:
+      cron: "* * * * *"
+    run: echo test
+"#;
+        let (_, jobs) = parse_config(yaml).unwrap();
+        let find = |id: &str| jobs.iter().find(|j| j.id == id).unwrap();
+
+        assert_eq!(find("with_jitter").jitter, Some(Duration::from_secs(30)));
+        assert!(find("no_jitter").jitter.is_none());
+    }
+
+    #[test]
+    fn parse_retry_jitter() {
+        let yaml = r#"
+jobs:
+  with_retry_jitter:
+    schedule:
+      cron: "* * * * *"
+    run: echo test
+    retry:
+      max: 3
+      delay: 1s
+      jitter: 500ms
+  retry_no_jitter:
+    schedule:
+      cron: "* * * * *"
+    run: echo test
+    retry:
+      max: 2
+      delay: 1s
+"#;
+        let (_, jobs) = parse_config(yaml).unwrap();
+        let find = |id: &str| jobs.iter().find(|j| j.id == id).unwrap();
+
+        let retry1 = find("with_retry_jitter").retry.as_ref().unwrap();
+        assert_eq!(retry1.jitter, Some(Duration::from_millis(500)));
+
+        let retry2 = find("retry_no_jitter").retry.as_ref().unwrap();
+        assert!(retry2.jitter.is_none());
+    }
+
+    #[test]
+    fn parse_duration_milliseconds() {
+        assert_eq!(parse_duration("500ms").unwrap(), Duration::from_millis(500));
+        assert_eq!(parse_duration("1000ms").unwrap(), Duration::from_millis(1000));
+    }
 }