Rust Backend
Developmentrust-backendRust Backend is an Agent Skill for development published in the windmill-labs/windmill repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Rust coding guidelines for the Windmill backend. MUST use when writing or modifying Rust code in the backend directory.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/windmill-labs/windmill/blob/HEAD/.agents/skills/rust-backend/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/rust-backend, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Windmill Rust Patterns
Apply these Windmill-specific patterns when writing Rust code in backend/.
Error Handling
Use Error from windmill_common::error. Return Result<T, Error> or JsonResult<T>:
use windmill_common::error::{Error, Result};
pub async fn get_job(db: &DB, id: Uuid) -> Result<Job> {
sqlx::query_as!(Job, "SELECT id, workspace_id FROM v2_job WHERE id = $1", id)
.fetch_optional(db)
.await?
.ok_or_else(|| Error::NotFound("job not found".to_string()))?;
}
Never panic in library code. Reserve .unwrap() for compile-time guarantees.
SQLx Patterns
Never use SELECT * — always list columns explicitly. Critical for backwards compatibility when workers lag behind API version:
// Correct
sqlx::query_as!(Job, "SELECT id, workspace_id, path FROM v2_job WHERE id = $1", id)
// Wrong — breaks when columns are added
sqlx::query_as!(Job, "SELECT * FROM v2_job WHERE id = $1", id)
Use batch operations to avoid N+1:
// Preferred — single query with IN clause
sqlx::query!("SELECT ... WHERE id = ANY($1)", &ids[..]).fetch_all(db).await?
Use transactions for multi-step operations. Parameterize all queries.
JSON Handling
Prefer Box<serde_json::value::RawValue> over serde_json::Value when storing/passing JSON without inspection:
pub struct Job {
pub args: Option<Box<serde_json::value::RawValue>>,
}
Only use serde_json::Value when you need to inspect or modify the JSON.
Serde Optimizations
#[derive(Serialize, Deserialize)]
pub struct Job {
#[serde(skip_serializing_if = "Option::is_none")]
pub parent_job: Option<Uuid>,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub tags: Vec<String>,
#[serde(default)]
pub priority: i32,
}
Async & Concurrency
Never block the async runtime. Use spawn_blocking for CPU-intensive work:
let result = tokio::task::spawn_blocking(move || expensive_computation(&data)).await?;
Mutex selection: Prefer std::sync::Mutex (or parking_lot::Mutex) for data protection. Only use tokio::sync::Mutex when holding locks across .await points.
Use tokio::sync::mpsc (bounded) for channels. Avoid std::thread::sleep in async contexts.
Module Structure & Visibility
- Use
pub(crate)instead ofpubwhen possible - Place new code in the appropriate crate based on functionality
- API endpoints go in
windmill-api/src/organized by domain - Shared functionality goes in
windmill-common/src/
Code Navigation
Always use rust-analyzer LSP for go-to-definition, find-references, and type info. Do not guess at module paths.
Axum Handlers
Destructure extractors directly in function signatures:
async fn process_job(
Extension(db): Extension<DB>,
Path((workspace, job_id)): Path<(String, Uuid)>,
Query(pagination): Query<Pagination>,
) -> Result<Json<Job>> { ... }