a3s-cron

Cron scheduling library for A3S with natural language support.

Features

• Standard Cron Syntax: 5-field cron expressions (minute hour day month weekday)
• Natural Language: Parse schedules from English and Chinese
• Persistence: JSON file-based storage with pluggable backends
• CRUD Operations: Create, pause, resume, update, and remove jobs
• Execution History: Track job runs with output and status
• 71 Unit Tests: Comprehensive test coverage

Installation

[dependencies]
a3s-cron = "0.1"

Library Usage

use a3s_cron::{CronManager, FileCronStore, parse_natural};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Parse natural language to cron expression
    let cron = parse_natural("every day at 2am")?;  // Returns "0 2 * * *"
    let cron = parse_natural("每天凌晨2点")?;        // Returns "0 2 * * *"

    // Create a manager with file-based storage
    let store = FileCronStore::new("/path/to/storage").await?;
    let manager = CronManager::new(store);

    // Add a job
    let job = manager.add_job("backup", "0 2 * * *", "backup.sh").await?;

    // List jobs
    let jobs = manager.list_jobs().await?;

    // Pause/resume
    manager.pause_job(&job.id).await?;
    manager.resume_job(&job.id).await?;

    // Manual execution
    let execution = manager.run_job(&job.id).await?;
    println!("Exit code: {}", execution.exit_code.unwrap_or(-1));

    // Get execution history
    let history = manager.get_history(&job.id, 10).await?;

    Ok(())
}

CLI Usage (via a3s-tools)

# Parse natural language to cron expression
TOOL_ARGS='{"action":"parse","input":"every day at 2am"}' a3s-tools cron
# Output: Cron expression: 0 2 * * *

TOOL_ARGS='{"action":"parse","input":"每周一上午9点"}' a3s-tools cron
# Output: Cron expression: 0 9 * * 1

# Create a job with natural language schedule
TOOL_ARGS='{"action":"add","name":"backup","schedule":"every day at 3am","command":"./backup.sh"}' a3s-tools cron

# List all jobs
TOOL_ARGS='{"action":"list"}' a3s-tools cron

# Get job details
TOOL_ARGS='{"action":"get","id":"<job-id>"}' a3s-tools cron

# Manually run a job
TOOL_ARGS='{"action":"run","id":"<job-id>"}' a3s-tools cron

# View execution history
TOOL_ARGS='{"action":"history","id":"<job-id>"}' a3s-tools cron

# Pause a job
TOOL_ARGS='{"action":"pause","id":"<job-id>"}' a3s-tools cron

# Resume a job
TOOL_ARGS='{"action":"resume","id":"<job-id>"}' a3s-tools cron

# Update job schedule
TOOL_ARGS='{"action":"update","id":"<job-id>","schedule":"every monday at 9am"}' a3s-tools cron

# Remove a job
TOOL_ARGS='{"action":"remove","id":"<job-id>"}' a3s-tools cron

Natural Language Support

English

Chinese (中文)

Cron Expression Format

Standard 5-field cron format:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Special characters:

• * - any value
• , - value list (e.g., 1,3,5)
• - - range (e.g., 1-5)
• / - step (e.g., */5)

Architecture

a3s-cron/
├── src/
│   ├── lib.rs        # Public API
│   ├── types.rs      # CronJob, JobStatus, JobExecution
│   ├── parser.rs     # Cron expression parser
│   ├── natural.rs    # Natural language parser
│   ├── store.rs      # CronStore trait, FileCronStore, MemoryCronStore
│   └── scheduler.rs  # CronManager with CRUD operations
└── Cargo.toml

License

MIT