kma-core/windmill / .agents/skills/rust-backend
rust-backend
UnverifiedRust coding guidelines for the Windmill backend. MUST use when writing or modifying Rust code in the backend directory.
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>> { ... }
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |