Tasks & Scripts
Relevant source files
The following files were used as context for generating this wiki page:
Tasks in Loco are operational scripts written in pure Rust that allow developers to execute business workflows with full access to the application context. They are designed for one-off operations such as resetting user passwords, sending email notifications, or performing data maintenance without needing to build a separate administrative interface.
The task system follows a linear workflow pattern, enabling developers to write business logic that can be easily tested by providing specific inputs and asserting expected outputs. Tasks are integrated into the Loco CLI, making them accessible through standard terminal commands.
Sources: docs-site/content/casts/004-creating-tasks.md:1-20, docs-site/content/casts/005-testing-tasks.md:1-20
Task Architecture
The task system is built around a registry pattern where tasks are defined by implementing a specific trait and then registered with the application.
Core Components
The system relies on three primary data structures defined in the core framework:
| Component | Description |
|---|---|
Task Trait | The interface that all tasks must implement, requiring task() and run() methods. |
TaskInfo | A struct containing the task's metadata, such as its unique name and a description. |
Vars | A collection of arguments passed to the task via the command line, stored as a key-value map. |
Tasks Registry | A collection that manages and executes registered task instances. |
Sources: src/task.rs:16-105
Task Execution Flow
When a task is invoked via the CLI, the framework resolves the task name, parses arguments into Vars, and executes the task's logic using the AppContext.
The diagram shows the sequence from user input to the final execution of the task's logic.
Sources: src/cli.rs:590-600, src/task.rs:90-100
Implementation Details
A task must implement the Task trait, which is marked with #[async_trait] to support asynchronous operations.
The Task Trait
#[async_trait]
pub trait Task: Send + Sync {
/// Get information about the task.
fn task(&self) -> TaskInfo;
/// Execute the task with the provided application context and variables.
async fn run(&self, app_context: &AppContext, vars: &Vars) -> Result<()>;
}
Sources: src/task.rs:71-77
The run method provides the AppContext, which includes access to the database connection, environment configuration, and other application-wide services. This allows tasks to interact with the same models and services used by the web controllers.
Sources: docs-site/content/casts/004-creating-tasks.md:15-18, src/task.rs:76
Variable Handling
Arguments are passed to tasks using a colon-separated syntax (e.g., key:value). These are parsed into the Vars struct.
The class diagram illustrates the relationship between the task registry, the metadata, and the input variables.
Sources: src/task.rs:16-105
CLI Integration
Loco provides a set of CLI commands for managing and executing tasks. Tasks can be generated using the scaffolding system and executed by name.
Command Reference
| Command | Usage | Description |
|---|---|---|
cargo loco generate task <NAME> | cargo loco generate task user_reset | Generates a new task template. |
cargo loco task | cargo loco task | Lists all available registered tasks. |
cargo loco task <NAME> | cargo loco task user_reset email:user@example.com | Executes a specific task with provided parameters. |
Sources: snipdoc.yml:105-115, src/cli.rs:105-115
CLI Parsing Logic
The CLI parses task parameters using a custom key-value parser. It looks for the : character to split arguments into pairs.
Sources: src/cli.rs:520-535
Scheduling Tasks
Tasks can be integrated into the Loco Scheduler to run automatically at specified intervals. The scheduler configuration allows running tasks or shell scripts using cron-like syntax or natural language descriptions.
jobs:
send_birthday:
run: "user_birthday_task"
schedule: "Run every 2 hours"
tags: ["marketing"]
Sources: docs-site/config.toml:160-175
The scheduler can filter jobs by name or by tags, allowing for group execution of related maintenance scripts.
Sources: src/cli.rs:118-135
Testing Tasks
Tasks are designed to be testable as "simple linear workflows." Because the run method is a standard asynchronous function taking Vars and AppContext, developers can programmatically invoke tasks in a test environment, provide mock or test-database inputs, and assert the results.
Sources: docs-site/content/casts/005-testing-tasks.md:15-18
The Tasks registry itself includes comprehensive tests for:
- Correct registration and name lookup.
- Parsing variables from CLI argument vectors.
- Handling task execution failures and successful runs.
- Overriding existing tasks in the registry.
Sources: src/task.rs:115-235
Summary
The Tasks & Scripts system in Loco provides a robust framework for operational automation. By leveraging the same AppContext as the main application, tasks ensure consistency in business logic while offering a simplified, CLI-driven execution model. Whether used for ad-hoc data fixes, periodic maintenance via the scheduler, or complex administrative workflows, tasks serve as the primary tool for non-request-driven logic in a Loco project.
Sources: docs-site/content/blog/hello-world.md:15-30, src/task.rs:9-15