.cursorrules (deprecated)

1# Rust Production — Cursor Rules
2# Production Rust: error handling, async, lifetimes, and systems programming patterns
3 
4# Project Context
5You are writing production Rust code. The project prioritizes safety, performance, and
6clear error handling. Follow Rust idioms, leverage the type system for correctness,
7and write code that the borrow checker loves. Use the 2021 edition or later.
8 
9# Error Handling (Critical)
10- Use `thiserror` for library error types, `anyhow` for application-level errors.
11- Define domain-specific error enums:
12```rust
13  use thiserror::Error;
14 
15  #[derive(Error, Debug)]
16  pub enum AppError {
17      #[error("User not found: {0}")]
18      UserNotFound(UserId),
19      #[error("Database error: {0}")]
20      Database(#[from] sqlx::Error),
21      #[error("Validation failed: {field} — {message}")]
22      Validation { field: String, message: String },
23  }
24```
25- Use `Result<T, E>` for all fallible operations. Never panic in library code.
26- Use the `?` operator for error propagation — don't call `.unwrap()` in production code.
27- Use `.expect("reason")` only when you have a provable invariant — document why.
28- Convert between error types with `From` implementations or `.map_err()`.
29- DON'T: Use `.unwrap()` — it panics. Use `?`, `.unwrap_or()`, `.unwrap_or_default()`, or match.
30- DON'T: Use `panic!()` for expected error conditions — return `Result` instead.
31 
32# Ownership and Borrowing
33- Prefer borrowing (`&T`) over owning (`T`) in function parameters when you don't need ownership.
34- Use `&str` instead of `String` for function parameters (accept both owned and borrowed).
35- Use `&[T]` instead of `Vec<T>` for function parameters (accept any contiguous slice).
36- Use `Cow<'_, str>` when you might or might not need to own the data.
37- Clone deliberately — add a comment when cloning: `// Clone needed because X takes ownership`.
38- Prefer `to_owned()` over `to_string()` for `&str -> String` conversion (more explicit).
39- Use `Arc<T>` for shared ownership across threads. Use `Rc<T>` only in single-threaded code.
40 
41# Struct and Type Design
42- Use the newtype pattern for type safety:
43```rust
44  pub struct UserId(pub i64);
45  pub struct Email(String);
46```
47- Derive common traits on all data types: `#[derive(Debug, Clone, PartialEq)]`.
48- Add `#[derive(Serialize, Deserialize)]` with serde for API types.
49- Use builder pattern for structs with many optional fields:
50```rust
51  pub struct Config {
52      host: String,
53      port: u16,
54      timeout: Duration,
55  }
56  impl Config {
57      pub fn builder() -> ConfigBuilder { ConfigBuilder::default() }
58  }
59```
60- Use `#[non_exhaustive]` on public enums and structs for future compatibility.
61 
62# Trait Patterns
63- Define traits for abstractions that have multiple implementations (repository, client).
64- Use `impl Trait` in function return position for zero-cost abstraction:
65```rust
66  fn create_handler() -> impl Fn(Request) -> Response { ... }
67```
68- Use `dyn Trait` when you need runtime polymorphism (trait objects, heterogeneous collections).
69- Use `where` clauses for complex trait bounds:
70```rust
71  fn process<T>(item: T) -> Result<Output, Error>
72  where
73      T: Serialize + Send + 'static,
74  { ... }
75```
76- Implement `Display` for user-facing output, `Debug` for developer logging.
77 
78# Async Patterns (Tokio)
79- Use `tokio` as the async runtime. Configure with `#[tokio::main]`.
80- Use `tokio::spawn` for concurrent tasks. Use `tokio::join!` for parallel execution.
81- Use `tokio::select!` for racing multiple futures.
82- For cancellation safety, prefer `tokio_util::sync::CancellationToken`.
83- Avoid holding locks across `.await` points — this causes deadlocks.
84- Use `tokio::sync::Mutex` instead of `std::sync::Mutex` in async code.
85- Prefer channels (`mpsc`, `oneshot`, `broadcast`) for inter-task communication over shared state.
86```rust
87  let (tx, mut rx) = tokio::sync::mpsc::channel::<Event>(100);
88  tokio::spawn(async move {
89      while let Some(event) = rx.recv().await {
90          process_event(event).await;
91      }
92  });
93```
94 
95# Concurrency
96- Use `rayon` for CPU-bound parallelism (data parallelism on iterators).
97- Use `tokio` for I/O-bound concurrency (network, file system).
98- Prefer message passing over shared state. If sharing state, use `Arc<Mutex<T>>`.
99- Use `RwLock` when reads vastly outnumber writes.
100- DON'T: Block the async runtime with CPU-intensive work — use `tokio::task::spawn_blocking`.
101 
102# Iterator Patterns
103- Chain iterator methods for data transformations:
104```rust
105  let active_emails: Vec<String> = users.iter()
106      .filter(|u| u.is_active)
107      .map(|u| u.email.clone())
108      .collect();
109```
110- Use `collect()` with type annotations when the target collection type isn't obvious.
111- Use `Iterator::try_fold` and `try_for_each` for fallible iterations.
112- Prefer iterators over indexed loops — they're often faster (bounds check elimination).
113 
114# API Design
115- Make invalid states unrepresentable through types:
116```rust
117  // Instead of a `status: String` field, use an enum
118  enum OrderState {
119      Pending { created_at: DateTime },
120      Shipped { tracking_number: String },
121      Delivered { delivered_at: DateTime },
122  }
123```
124- Use the typestate pattern for compile-time workflow enforcement:
125```rust
126  struct HttpRequest<S: State> { ... }
127  struct Building;
128  struct Ready;
129  impl HttpRequest<Building> { fn header(self, ...) -> Self { ... } }
130  impl HttpRequest<Building> { fn build(self) -> HttpRequest<Ready> { ... } }
131  impl HttpRequest<Ready> { async fn send(self) -> Response { ... } }
132```
133- Follow the principle: parse, don't validate. Convert raw input into typed structures at boundaries.
134 
135# Testing
136- Unit tests go in the same file: `#[cfg(test)] mod tests { ... }`.
137- Integration tests go in `tests/` directory.
138- Use `#[test]` for sync tests, `#[tokio::test]` for async tests.
139- Use `proptest` or `quickcheck` for property-based testing.
140- Use `mockall` for trait mocking in unit tests.
141- Test error paths as thoroughly as success paths.
142- Use `assert_eq!` with descriptive messages: `assert_eq!(result, expected, "user lookup failed")`.
143 
144# Cargo.toml Best Practices
145- Pin major versions: `serde = "1"`, not `serde = "1.0.160"` (Cargo resolves to latest compatible).
146- Use `[workspace]` for multi-crate projects.
147- Enable only needed features: `tokio = { version = "1", features = ["rt-multi-thread", "macros"] }`.
148- Use `cargo clippy -- -D warnings` in CI — treat clippy warnings as errors.
149- Use `cargo deny` to audit dependencies for security and licensing.
150 
151# Logging and Observability
152- Use `tracing` crate (not `log`) for structured, async-aware logging.
153- Add `#[instrument]` to key functions for automatic span creation.
154- Include context in log messages: user_id, request_id, operation.
155- Use span levels appropriately: ERROR, WARN, INFO, DEBUG, TRACE.
156 
157# Common Mistakes to Avoid
158- DON'T: Use `.unwrap()` or `.expect()` in production paths — handle errors with `?`.
159- DON'T: Clone to satisfy the borrow checker — rethink ownership structure first.
160- DON'T: Use `String` where `&str` suffices in function parameters.
161- DON'T: Hold a `MutexGuard` across an await point.
162- DON'T: Use `unsafe` without a `// SAFETY:` comment explaining the invariant.
163- DON'T: Ignore compiler warnings — fix them or understand why they're safe.
164- DON'T: Use `Box<dyn Error>` as an error type — use typed errors.
165