Locci Scheduler - Rust Client

A powerful and easy-to-use Rust client library for the Locci Scheduler platform. Schedule webhook executions with flexible timing options including one-time, recurring (cron), and interval-based schedules.

Features

• ✅ Multiple HTTP methods (GET, POST, PUT, PATCH, DELETE)
• ✅ Custom headers and JSON payloads
• ✅ Webhook authentication (API Key, Bearer Token, Basic Auth)
• ✅ HMAC signature verification for webhook security
• ✅ Flexible scheduling (one-time, cron, intervals)
• ✅ Task lifecycle management (pause, resume, cancel, delete)
• ✅ Execution history tracking
• ✅ Async/await support with Tokio
• ✅ Type-safe API with comprehensive error handling

Installation

Add this to your Cargo.toml:

[dependencies]
locci-scheduler = "0.1.0"
tokio = { version = "1", features = ["full"] }

Quick Start

use locci_scheduler::{LocciScheduler, SchedulerConfig, WebhookConfig, HttpMethod};
use std::collections::HashMap;

#[tokio::main]
async fn main() -> locci_scheduler::Result<()> {
    // Initialize the scheduler client
    let config = SchedulerConfig {
        base_url: "https://api.scheduler.locci.cloud".to_string(),
        api_token: "your-api-token-here".to_string(),
        timeout: 30000,
        retries: 3,
    };

    let scheduler = LocciScheduler::new(config)?;

    // Create a simple webhook task
    let webhook = WebhookConfig {
        url: "https://example.com/webhook".to_string(),
        method: Some(HttpMethod::Post),
        headers: Some(HashMap::new()),
        payload: Some(serde_json::json!({
            "message": "Hello from Locci Scheduler!"
        })),
        timeout_seconds: Some(30),
        retry_config: None,
        authentication: None,
        webhook_secret: None,
    };

    // Schedule to run every minute
    let task = scheduler
        .schedule_every_minute(
            "My First Task".to_string(),
            webhook,
            Some("A simple scheduled task".to_string()),
            None,
        )
        .await?;

    println!("Task created: {}", task.id);

    Ok(())
}

Usage Examples

Create a One-Time Task

use chrono::Utc;

let execute_at = Utc::now() + chrono::Duration::hours(1);
let task = scheduler
    .schedule_once(
        "One-time task".to_string(),
        webhook,
        execute_at,
        Some("Executes once in 1 hour".to_string()),
        None,
    )
    .await?;

Create a Daily Recurring Task

let task = scheduler
    .schedule_daily(
        "Daily report".to_string(),
        webhook,
        "09:00",  // Time in HH:MM format
        Some("Africa/Nairobi".to_string()),
        Some("Runs every day at 9 AM".to_string()),
        None,
    )
    .await?;

Create an Interval Task

let task = scheduler
    .schedule_interval(
        "Health check".to_string(),
        webhook,
        300,  // Every 5 minutes
        None,
        None,
        Some("Runs every 5 minutes".to_string()),
        None,
    )
    .await?;

Create Task with Authentication

use locci_scheduler::{AuthConfig, BearerTokenAuth};

let webhook = WebhookConfig {
    url: "https://api.example.com/webhook".to_string(),
    method: Some(HttpMethod::Post),
    headers: Some(HashMap::new()),
    payload: Some(serde_json::json!({"event": "notification"})),
    timeout_seconds: Some(30),
    retry_config: None,
    authentication: Some(AuthConfig::BearerToken {
        bearer_token: BearerTokenAuth {
            token: "your-token".to_string(),
        },
    }),
    webhook_secret: None,
};

Create Task with HMAC Signature

let webhook = WebhookConfig {
    url: "https://api.example.com/secure".to_string(),
    method: Some(HttpMethod::Post),
    headers: Some(HashMap::new()),
    payload: Some(serde_json::json!({"data": "sensitive"})),
    timeout_seconds: Some(30),
    retry_config: None,
    authentication: None,
    webhook_secret: Some("my-secret-key".to_string()),
};

List Tasks

use locci_scheduler::PaginationOptions;

let tasks = scheduler
    .list_tasks(PaginationOptions {
        page: Some(1),
        per_page: Some(20),
    })
    .await?;

for task in tasks.tasks {
    println!("Task: {} ({})", task.name, task.id);
}

Pause, Resume, and Delete Tasks

// Pause a task
let paused = scheduler.pause_task(&task_id).await?;

// Resume a task
let resumed = scheduler.resume_task(&task_id).await?;

// Delete a task
scheduler.delete_task(&task_id).await?;

Trigger Task Manually

scheduler.trigger_task(&task_id).await?;

Get Task Execution History

let history = scheduler.get_task_history(&task_id).await?;

for execution in history.executions {
    println!("Executed at: {}", execution.executed_at);
    println!("Status: {:?}", execution.status);
}

Authentication Types

API Key Authentication

use locci_scheduler::{AuthConfig, ApiKeyAuth};

let auth = AuthConfig::ApiKey {
    api_key: ApiKeyAuth {
        header_name: "X-API-Key".to_string(),
        key: "your-api-key".to_string(),
    },
};

Bearer Token Authentication

use locci_scheduler::{AuthConfig, BearerTokenAuth};

let auth = AuthConfig::BearerToken {
    bearer_token: BearerTokenAuth {
        token: "your-bearer-token".to_string(),
    },
};

Basic Authentication

use locci_scheduler::{AuthConfig, BasicAuthConfig};

let auth = AuthConfig::BasicAuth {
    basic_auth: BasicAuthConfig {
        username: "admin".to_string(),
        password: "secret".to_string(),
    },
};

Error Handling

The library uses a comprehensive error type:

use locci_scheduler::SchedulerError;

match scheduler.create_task(options).await {
    Ok(task) => println!("Task created: {}", task.id),
    Err(SchedulerError::AuthenticationError(msg)) => {
        eprintln!("Auth failed: {}", msg);
    }
    Err(SchedulerError::ValidationError(msg)) => {
        eprintln!("Validation failed: {}", msg);
    }
    Err(SchedulerError::NotFoundError(msg)) => {
        eprintln!("Not found: {}", msg);
    }
    Err(e) => eprintln!("Error: {}", e),
}

Examples

Check the examples/ directory for complete working examples:

• basic_usage.rs - Comprehensive example covering all features
• webhook_auth.rs - Examples of different authentication methods

Run an example:

cargo run --example basic_usage
cargo run --example webhook_auth

License

MIT

Support

For issues and questions, please visit: https://github.com/MikeTeddyOmondi/locci-scheduler/issues