flashcron 0.1.0

A lightning-fast, ultra-efficient cron daemon written in Rust - Schedule tasks at the speed of light
Documentation

FlashCron

A lightning-fast, ultra-efficient cron daemon written in Rust

Schedule tasks at the speed of light

CI Crates.io License: MIT Rust

Features | Installation | Quick Start | Documentation | Contributing

Why FlashCron?

Traditional cron daemons get the job done, but they weren't built for speed. FlashCron is engineered from the ground up for blazing-fast performance:

Metric FlashCron Traditional cron Improvement
Scheduler Init (1000 jobs) ~400 μs 10-50 ms Up to 125x faster
Next Run Calculation ~500 ns 10-100 μs Up to 200x faster
Memory Usage 2-5 MB 10-50 MB Up to 90% less
Startup Time <10 ms 50-200 ms Up to 20x faster
CPU at Idle <0.1% 0.5-2% Up to 95% less

The Flash Philosophy

  • Priority Queue Scheduling: O(log n) operations, no polling loops
  • Zero-Copy Parsing: Minimal allocations in hot paths
  • Precise Sleep: CPU stays idle until the exact moment needed
  • Concurrent Execution: Configurable parallelism with async I/O
  • Optimized Binaries: LTO, stripped symbols, maximum optimization

Features

Core Functionality

  • Standard Cron Expressions: Full 5-field cron syntax support
  • TOML Configuration: Human-readable, version-control friendly
  • Hot Reload: Automatic config reload on file changes
  • Graceful Shutdown: Waits for running jobs to complete

Job Management

  • Timeout Handling: Kill runaway jobs automatically
  • Retry Support: Configurable retry count and delay
  • Environment Variables: Per-job environment injection
  • Working Directory: Per-job working directory
  • Concurrent Limits: Prevent resource exhaustion

Observability

  • Structured Logging: Human-readable or JSON format
  • Execution History: Track job success/failure rates
  • Prometheus Metrics: Optional metrics endpoint (feature flag)

Cross-Platform

  • Linux: Native support, systemd integration
  • macOS: Full support including Apple Silicon
  • Windows: Native Windows support

Installation

From Releases (Recommended)

Linux (x86_64)

curl -LO https://github.com/alfredo-baratta/flashcron/releases/latest/download/flashcron-linux-x86_64.tar.gz
tar xzf flashcron-linux-x86_64.tar.gz
sudo mv flashcron /usr/local/bin/

Linux (ARM64)

curl -LO https://github.com/alfredo-baratta/flashcron/releases/latest/download/flashcron-linux-aarch64.tar.gz
tar xzf flashcron-linux-aarch64.tar.gz
sudo mv flashcron /usr/local/bin/

macOS (Intel)

curl -LO https://github.com/alfredo-baratta/flashcron/releases/latest/download/flashcron-macos-x86_64.tar.gz
tar xzf flashcron-macos-x86_64.tar.gz
sudo mv flashcron /usr/local/bin/

macOS (Apple Silicon)

curl -LO https://github.com/alfredo-baratta/flashcron/releases/latest/download/flashcron-macos-aarch64.tar.gz
tar xzf flashcron-macos-aarch64.tar.gz
sudo mv flashcron /usr/local/bin/

Windows Download flashcron-windows-x86_64.zip from releases and extract to a directory in your PATH.

From Cargo

cargo install flashcron

From Source

git clone https://github.com/alfredo-baratta/flashcron
cd flashcron
cargo build --release

Docker

docker pull ghcr.io/alfredo-baratta/flashcron:latest

Quick Start

1. Generate Configuration

flashcron init -o flashcron.toml

2. Edit Configuration

[settings]
log_level = "info"
max_concurrent_jobs = 10

[jobs.backup]
schedule = "0 2 * * *"  # Daily at 2 AM
command = "/usr/local/bin/backup.sh"
description = "Daily backup"
timeout = 3600
retry_count = 3

[jobs.cleanup]
schedule = "0 */6 * * *"  # Every 6 hours
command = "find /tmp -mtime +7 -delete"
description = "Clean old temp files"
enabled = true

3. Validate Configuration

flashcron validate -c flashcron.toml

4. Start the Daemon

flashcron run -c flashcron.toml

CLI Reference

Command Description
flashcron run -c config.toml Start the daemon
flashcron validate -c config.toml Validate configuration
flashcron list -c config.toml List all jobs
flashcron schedule -c config.toml Show upcoming runs
flashcron trigger <job> -c config.toml Trigger job manually
flashcron init -o config.toml Generate default config

Options

Option Description
-c, --config <PATH> Configuration file path
-l, --log-level <LEVEL> Log level (trace, debug, info, warn, error)
--json Output logs in JSON format
--foreground Run in foreground (don't daemonize)

Configuration Reference

Global Settings

[settings]
log_level = "info"           # trace, debug, info, warn, error
json_logs = false            # JSON format for log aggregators
max_concurrent_jobs = 10     # 0 = unlimited
shell = "/bin/sh"            # Default shell
watch_config = true          # Hot reload on config changes
history_size = 1000          # Job execution history size
shutdown_grace_period = 30   # Seconds to wait on shutdown

Job Configuration

[jobs.example]
schedule = "*/5 * * * *"     # Cron expression (required)
command = "echo 'Hello'"     # Command to execute (required)
description = "Example job"  # Optional description
enabled = true               # Enable/disable job
working_dir = "/app"         # Working directory
environment = { KEY = "value" }  # Environment variables
timeout = 300                # Timeout in seconds (0 = none)
shell = "/bin/bash"          # Override default shell
retry_count = 3              # Retry on failure
retry_delay = 60             # Seconds between retries
max_output_size = 1048576    # Max stdout/stderr capture (bytes)
run_on_startup = false       # Run immediately on daemon start

Cron Expression Format

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

Examples:

Expression Description
* * * * * Every minute
*/5 * * * * Every 5 minutes
0 * * * * Every hour
0 0 * * * Daily at midnight
0 2 * * * Daily at 2 AM
0 0 * * 7 Weekly on Sunday
0 0 1 * * Monthly on the 1st
0 9-17 * * 1-5 Weekdays 9 AM - 5 PM hourly
30 4 1,15 * * At 4:30 on 1st and 15th

Performance Benchmarks

Measured on AMD Ryzen 5 / Intel i7 equivalent:

Operation Time Notes
Cron expression parsing 1.8-4.9 μs Depending on complexity
Next occurrence calculation 400-500 ns Sub-microsecond
Scheduler init (10 jobs) ~10 μs Instant startup
Scheduler init (100 jobs) ~50 μs Scales linearly
Scheduler init (1000 jobs) ~400 μs Still under 1ms
Config parsing (50 jobs) ~566 μs TOML parsing included
Config parsing (200 jobs) ~2.9 ms Large configs handled

Memory Profile

State Memory
Idle (10 jobs) ~2 MB
Idle (100 jobs) ~3 MB
Running (10 concurrent) ~5 MB

Deployment

systemd Service

# /etc/systemd/system/flashcron.service
[Unit]
Description=FlashCron - Lightning-fast Cron Daemon
After=network.target

[Service]
Type=simple
User=flashcron
ExecStart=/usr/local/bin/flashcron run -c /etc/flashcron/config.toml
Restart=on-failure
RestartSec=5
Environment=RUST_LOG=info

[Install]
WantedBy=multi-user.target

sudo systemctl enable flashcron
sudo systemctl start flashcron

Docker Compose

version: '3.8'
services:
  flashcron:
    image: ghcr.io/alfredo-baratta/flashcron:latest
    volumes:
      - ./flashcron.toml:/app/config/flashcron.toml:ro
      - ./scripts:/scripts:ro
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: flashcron
spec:
  replicas: 1
  selector:
    matchLabels:
      app: flashcron
  template:
    metadata:
      labels:
        app: flashcron
    spec:
      containers:
      - name: flashcron
        image: ghcr.io/alfredo-baratta/flashcron:latest
        resources:
          requests:
            memory: "8Mi"
            cpu: "10m"
          limits:
            memory: "32Mi"
            cpu: "100m"
        volumeMounts:
        - name: config
          mountPath: /app/config
      volumes:
      - name: config
        configMap:
          name: flashcron-config

Comparison with Alternatives

Feature FlashCron cron fcron systemd-timer
Memory usage ~2-5 MB ~1 MB ~5 MB N/A (systemd)
Config format TOML crontab fcrontab unit files
Hot reload Yes No Yes Yes
Retry support Yes No Yes Yes
Timeout Yes No Yes Yes
Concurrent limit Yes No No No
Cross-platform Yes Unix Unix Linux
Metrics Optional No No journald
Performance Optimized Standard Standard Standard

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

# Clone the repository
git clone https://github.com/alfredo-baratta/flashcron
cd flashcron

# Run tests
cargo test

# Run benchmarks
cargo bench

# Build release
cargo build --release

License

MIT License - see LICENSE for details.

Author

Alfredo Baratta - alfredobaratta@outlook.com

Acknowledgments

  • cron - Cron expression parsing
  • tokio - Async runtime
  • clap - CLI framework
  • tracing - Structured logging

Built for speed

Because every millisecond counts