Skip to content
Skills Library
Programming · Building & coding

rust-backend

/rust-backend

Rust coding guidelines for the Windmill backend. MUST use when writing or modifying Rust code in the backend directory.

Repository
windmill ↗
Licence
Apache-2.0
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Rust coding guidelines for the Windmill backend. MUST use when writing or modifying Rust code in the backend directory.

Original author description

Rust coding guidelines for the Windmill backend. MUST use when writing or modifying Rust code in the backend directory.

How it works

  1. Error Handling
  2. SQLx Patterns
  3. JSON Handling
  4. Serde Optimizations
  5. Async & Concurrency
  6. Module Structure & Visibility
  7. Code Navigation
  8. Feature Telemetry
  9. Axum Handlers
Original SKILL.md headings · 111 lines, 401 words
SKILL.md preview
---
name: rust-backend
description: Rust 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>`:

```rust
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:

```rust
// 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:

```rust
// 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:

```rust
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

```rust
#[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:

```rust
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 of `pub` when 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.

## Feature Telemetry

`FEATURE_USAGE_KINDS` in `windmill-api-workspaces/src/workspaces.rs` is an allowlist: a
`(feature, kind)` pair missing from it is dropped by `valid_feature_usage_event` with a bare
`continue` — no error, and the route still returns 204. Adding a counter on the frontend without
registering it here records nothing. See `docs/feature-telemetry.md`.

## Axum Handlers

Destructure extractors directly in function signatures:

```rust
async fn process_job(
    Extension(db): Extension<DB>,
    Path((workspace, job_id)): Path<(String, Uuid)>,
    Query(pagination): Query<Pagination>,
) -> Result<Json<Job>> { ... }
```

Versions

RepositoryScoreLicence
This page · windmill-labs/windmill100Apache-2.0
Funnyhust/POC_Kaenx_Creator100GPL-3.0
zjunlp/skills100MIT

Database snapshot: 13.11.2026 · package version eb7b5141828c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100svelte-frontend
    Svelte coding guidelines for the Windmill frontend. MUST use when writing or modifying code in the frontend directory.
  • 86rust-tests-guidelines
    Guidelines for writing Rust tests. Use this when you want to write Rust tests.
  • 100rust
    Provides Rust coding best practices for structure, patterns, performance, and error handling. Use when writing or reviewing Rust code, or when the user asks for Rust style guidance.
  • 95native-trigger
    Guidance for adding native trigger services to Windmill. Use when implementing or modifying native trigger integrations across the backend and frontend.
  • 100rust-coding-style
    HASH Rust coding style. Use when writing or reviewing Rust code, choosing types, imports, function arguments, or naming.
  • 100rust
    Rust programming language coding conventions and best practices Triggers on: **/*.rs

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.