rust-coding-standards.mdc

---
description: Rust style, imports, derives, error handling, and Cargo.toml dependency ordering for this workspace
globs:
  - "**/*.rs"
  - "**/Cargo.toml"
alwaysApply: false
---

# Rust coding standards

- Prefer **Rust 2024 edition** idioms and language features where they fit the codebase.
- Prefer the **current Rust version’s std**; use https://doc.rust-lang.org/std/ as the canonical std reference.

## Symbol visibility

Prioritize symbol visibility in this order, from most restrictive to least restrictive:

1. Private (default). If a symbol does not need to be referenced outside of its (sub)module hierarchy, keep it private.
2. `pub(crate)`. If a symbol needs to be referenced in another module tree within the crate, scope its visibility to `pub(crate)` only.
3. `pub`. Only if a symbol must be referenced by another crate entirely—whether within this workspace or by a third-party user—scope its visibility to `pub`.

## `#[derive(...)]`

List proc-macro attributes in **alphabetical order**.

```rust
// ✅ GOOD
#[derive(Clone, Debug, Eq, Hash, PartialEq)]

// ❌ BAD (arbitrary order)
#[derive(Debug, PartialEq, Clone)]
```

## `use` imports

1. **Three blocks** separated by **one blank line**: `std` / `core` / `alloc` first, then **third-party crates**, then **`crate` / `super` / `self`** (internal).
2. Within each block, group by **top-level crate or second-level std module** and use **brace lists** `{}` for multiple items from the same path.
3. Inside each section, ensure listings are in strict alphabetical order. `cargo fmt` will enforce this.

✅ GOOD
```rust
use std::collections::{BTreeMap, HashMap};
use std::fmt;
use std::sync::{atomic::{AtomicU64, Ordering}, Arc};

use anyhow::Context;
use serde::{de::Deserialize, ser::Serialize};

use crate::{foo::{Bar, Baz}, fud::Dud};
```

❌ BAD
```rust
use anyhow::Context;
use crate::foo::{Bar, Baz};
use crate::fud::Dud;
use serde::de::Deserialize;
use serde::ser::Serialize;
use std::collections::{BTreeMap, HashMap};
use std::fmt;
use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};
```

## `Cargo.toml` dependencies

In every manifest, keep dependency **keys** in **strict alphabetical order** within each table you touch:

- `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]`
- `[workspace.dependencies]` (workspace roots)
- Target-specific tables such as `[target.'cfg(...)'.dependencies]` — sort **within that table only**

Do not reorder unrelated keys or tables for their own sake; when adding or editing dependencies, preserve **alphabetical order** in the affected table.

```toml
# ✅ GOOD
[dependencies]
anyhow = "1"
serde = { version = "1", features = ["derive"] }
thiserror = "2"

# ❌ BAD (crate names not alphabetical)
[dependencies]
thiserror = "2"
anyhow = "1"
```

## Error handling

- **Do not** use `unwrap()` on `Option` or `Result` outside **tests**; propagate, match, or use `?` / contextual helpers instead.
- **Do not** use `expect()` when a **clearer** option exists (e.g. `?`, `map_err`, `context`, or an explicit branch).

## Import depth and symbol paths

- **Types**: do not spell out long paths at every use site (for example `crate::module1::module2::MyType`). Import `MyType` (or its parent module, per local style) at the top of the file or module.
- **Functions and constants**: do not call through long paths like `crate::module1::module2::function()`. Import the **leaf module** you need (for example `use crate::module1::module2`) and call **`module2::function()`** so references stay shallow (typically **two path segments** after the import).

When in doubt, match patterns already used in neighboring modules in this repository.

## Checks and actions to perform after iterating on code

- `cargo fmt --all` to ensure all code is formatted according to our rustfmt rules.
- `cargo check --workspace` to ensure the whole workspace has valid syntax and type checks pass.
- `cargo clippy --workspace -- -D warnings` to check all lints and treat warnings as errors. Only #[allow(dead_code)] may be used on code that is intended to be used in future work. Otherwise, all warnings should be fixed, not allowed.
- `cargo test --workspace` to run all Rust host tests to ensure they pass.
- `cargo pgrx test pg17 -p pgwasm` to run all PostgreSQL/pgrx tests and ensure they pass on at least PostgreSQL 17.