Cursor rule

1---
2description: Enforce Rust best practices and standard ecosystem choices
3globs: ["**/*.rs", "**/Cargo.toml"]
4alwaysApply: false
5---
6 
7# Rust Best Practices
8 
9## Error Handling
10 
11### Application Code (anyhow)
12 
13For application code, use **anyhow** for error handling:
14 
15```rust
16use anyhow::{Context, Result};
17 
18fn process_data(path: &str) -> Result<()> {
19    let content = std::fs::read_to_string(path)
20        .with_context(|| format!("Failed to read file: {}", path))?;
21 
22    // Process content...
23    Ok(())
24}
25```
26 
27### Library Code (thiserror)
28 
29For library code, use **thiserror** to define custom error types:
30 
31```rust
32use thiserror::Error;
33 
34#[derive(Error, Debug)]
35pub enum MyError {
36    #[error("Invalid input: {0}")]
37    InvalidInput(String),
38 
39    #[error("IO error: {0}")]
40    Io(#[from] std::io::Error),
41 
42    #[error("Parse error: {0}")]
43    Parse(#[from] serde_json::Error),
44}
45```
46 
47**Rules:**
48 
49- ✅ Use `anyhow::Result<T>` in application code
50- ✅ Use `thiserror` for library error types
51- ✅ Always use `?` operator for error propagation
52- ✅ Add context with `.with_context()` or `.context()` when appropriate
53- ❌ Do NOT use `unwrap()` or `expect()` in production code (only in tests or when absolutely certain)
54 
55## Concurrency and Synchronization
56 
57### Channels (mpsc)
58 
59**Always prefer channels** for concurrent communication:
60 
61```rust
62use std::sync::mpsc;
63use std::thread;
64 
65let (tx, rx) = mpsc::channel();
66 
67thread::spawn(move || {
68    tx.send("Hello from thread").unwrap();
69});
70 
71let received = rx.recv().unwrap();
72```
73 
74For async code, use `tokio::sync::mpsc`:
75 
76```rust
77use tokio::sync::mpsc;
78 
79let (mut tx, mut rx) = mpsc::channel(32);
80 
81tokio::spawn(async move {
82    tx.send("Hello").await.unwrap();
83});
84 
85while let Some(msg) = rx.recv().await {
86    // Process message
87}
88```
89 
90**Rules:**
91 
92- ✅ Prefer `mpsc::channel` for sync code
93- ✅ Prefer `tokio::sync::mpsc` for async code
94- ✅ Use `Arc<Mutex<T>>` only when shared mutable state is necessary
95- ✅ Consider `RwLock` for read-heavy workloads
96- ❌ Avoid `unsafe` blocks for synchronization
97 
98## Async Runtime
99 
100### Tokio
101 
102Use **Tokio** as the async runtime:
103 
104```rust
105use tokio;
106 
107#[tokio::main]
108async fn main() -> Result<()> {
109    // Async code here
110    Ok(())
111}
112```
113 
114**Cargo.toml:**
115 
116```toml
117[dependencies]
118tokio = { version = "1", features = ["full"] }
119```
120 
121**Rules:**
122 
123- ✅ Use `tokio` for async runtime
124- ✅ Use `#[tokio::main]` for async main functions
125- ✅ Prefer async/await over manual Future handling
126- ✅ Use `tokio::spawn` for concurrent tasks
127- ❌ Do NOT use other async runtimes (async-std, smol) unless specifically required
128 
129## Web and gRPC Frameworks
130 
131### Web: Axum
132 
133Use **Axum** for web applications:
134 
135```rust
136use axum::{
137    routing::get,
138    Router,
139    Json,
140};
141use serde_json::{json, Value};
142 
143async fn handler() -> Json<Value> {
144    Json(json!({ "message": "Hello, World!" }))
145}
146 
147#[tokio::main]
148async fn main() {
149    let app = Router::new()
150        .route("/", get(handler));
151 
152    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
153    axum::serve(listener, app).await.unwrap();
154}
155```
156 
157### gRPC: Tonic
158 
159Use **Tonic** for gRPC services:
160 
161```rust
162use tonic::{transport::Server, Request, Response, Status};
163 
164pub mod hello {
165    tonic::include_proto!("hello");
166}
167 
168#[tokio::main]
169async fn main() -> Result<(), Box<dyn std::error::Error>> {
170    let addr = "[::1]:50051".parse()?;
171    let greeter = MyGreeter::default();
172 
173    Server::builder()
174        .add_service(hello::greeter_server::GreeterServer::new(greeter))
175        .serve(addr)
176        .await?;
177 
178    Ok(())
179}
180```
181 
182**Rules:**
183 
184- ✅ Use `axum` for HTTP/web applications
185- ✅ Use `tonic` for gRPC services
186- ✅ Leverage Axum's type-safe routing and extractors
187- ❌ Do NOT use other web frameworks (actix-web, warp) unless specifically required
188 
189## Standard Traits
190 
191### Always Implement Standard Conversion Traits
192 
193When converting between types, **always implement** the appropriate standard traits:
194 
195### From / Into
196 
197For infallible conversions:
198 
199```rust
200use std::convert::From;
201 
202struct Point {
203    x: i32,
204    y: i32,
205}
206 
207impl From<(i32, i32)> for Point {
208    fn from((x, y): (i32, i32)) -> Self {
209        Point { x, y }
210    }
211}
212 
213// Now you can use:
214let point: Point = (10, 20).into();
215```
216 
217### TryFrom / TryInto
218 
219For fallible conversions:
220 
221```rust
222use std::convert::TryFrom;
223 
224struct PositiveNumber(i32);
225 
226impl TryFrom<i32> for PositiveNumber {
227    type Error = String;
228 
229    fn try_from(value: i32) -> Result<Self, Self::Error> {
230        if value > 0 {
231            Ok(PositiveNumber(value))
232        } else {
233            Err(format!("{} is not positive", value))
234        }
235    }
236}
237```
238 
239### FromStr
240 
241For parsing from strings:
242 
243```rust
244use std::str::FromStr;
245 
246struct Email(String);
247 
248impl FromStr for Email {
249    type Err = String;
250 
251    fn from_str(s: &str) -> Result<Self, Self::Err> {
252        if s.contains('@') {
253            Ok(Email(s.to_string()))
254        } else {
255            Err("Invalid email format".to_string())
256        }
257    }
258}
259 
260// Usage:
261let email: Email = "user@example.com".parse()?;
262```
263 
264### Display / Debug
265 
266Always implement `Display` and `Debug`:
267 
268```rust
269use std::fmt;
270 
271struct MyType {
272    value: i32,
273}
274 
275impl fmt::Display for MyType {
276    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
277        write!(f, "MyType({})", self.value)
278    }
279}
280 
281// Debug is usually derived:
282#[derive(Debug)]
283struct MyType {
284    value: i32,
285}
286```
287 
288**Rules:**
289 
290- ✅ Always implement `From` / `TryFrom` when converting between types
291- ✅ Always implement `FromStr` when parsing from strings
292- ✅ Always implement `Display` for user-facing output
293- ✅ Always derive or implement `Debug` for all types
294- ✅ Prefer `From` over manual conversion functions
295- ✅ Use `TryFrom` when conversion can fail
296- ❌ Do NOT create custom conversion functions when standard traits apply
297 
298## Safety
299 
300### No Unsafe Code
301 
302**Never use `unsafe` blocks** unless absolutely necessary and well-documented:
303 
304```rust
305// ❌ BAD - Avoid unsafe
306unsafe {
307    let ptr = raw_ptr.as_ref().unwrap();
308}
309 
310// ✅ GOOD - Use safe alternatives
311if let Some(value) = raw_ptr.as_ref() {
312    // Use value safely
313}
314```
315 
316**Rules:**
317 
318- ✅ Always prefer safe Rust code
319- ✅ Use safe abstractions from standard library
320- ✅ Use `Option` and `Result` for error handling
321- ✅ Use `Arc`, `Mutex`, `RwLock` for shared state
322- ❌ Do NOT use `unsafe` blocks
323- ❌ Do NOT use raw pointers (`*const T`, `*mut T`)
324- ❌ Do NOT use `transmute` or other unsafe operations
325- ⚠️ If `unsafe` is absolutely necessary, document why and ensure soundness
326 
327## Code Organization
328 
329### Project Structure
330 
331```
332project/
333├── Cargo.toml
334├── src/
335│   ├── main.rs              # Binary entry point
336│   ├── lib.rs               # Library entry point
337│   ├── error.rs             # Error types (thiserror)
338│   ├── config.rs            # Configuration
339│   ├── handlers/            # Request handlers
340│   │   └── mod.rs
341│   ├── models/              # Data models
342│   │   └── mod.rs
343│   ├── services/            # Business logic
344│   │   └── mod.rs
345│   └── utils/               # Utilities
346│       └── mod.rs
347└── tests/                   # Integration tests
348```
349 
350### Module Organization
351 
352```rust
353// lib.rs
354pub mod error;
355pub mod config;
356pub mod handlers;
357pub mod models;
358pub mod services;
359 
360pub use error::{Error, Result};
361```
362 
363## Testing
364 
365### Unit Tests
366 
367```rust
368#[cfg(test)]
369mod tests {
370    use super::*;
371 
372    #[test]
373    fn test_conversion() {
374        let point: Point = (10, 20).into();
375        assert_eq!(point.x, 10);
376        assert_eq!(point.y, 20);
377    }
378}
379```
380 
381### Integration Tests
382 
383```rust
384// tests/integration_test.rs
385use my_lib::*;
386 
387#[test]
388fn test_api() {
389    // Test code
390}
391```
392 
393## Dependencies
394 
395### Recommended Cargo.toml Structure
396 
397```toml
398[package]
399name = "my-project"
400version = "0.1.0"
401edition = "2021"
402
403[dependencies]
404# Error handling
405anyhow = "1.0"
406thiserror = "1.0"
407 
408# Async runtime
409tokio = { version = "1", features = ["full"] }
410 
411# Web framework
412axum = "0.8"
413 
414# gRPC
415tonic = "0.11"
416prost = "0.13"
417 
418# Serialization
419serde = { version = "1.0", features = ["derive"] }
420serde_json = "1.0"
421 
422# Logging
423tracing = "0.1"
424tracing-subscriber = "0.3"
425
426[dev-dependencies]
427# Testing
428tokio-test = "0.4"
429```
430 
431## Summary Checklist
432 
433When writing Rust code, ensure:
434 
435- ✅ Error handling: `anyhow` for apps, `thiserror` for libraries
436- ✅ Concurrency: Prefer channels (`mpsc`) over shared state
437- ✅ Async: Use `tokio` runtime
438- ✅ Web: Use `axum` for HTTP services
439- ✅ gRPC: Use `tonic` for gRPC services
440- ✅ Traits: Implement `From`, `TryFrom`, `FromStr` for conversions
441- ✅ Safety: Never use `unsafe` blocks
442- ✅ Testing: Write unit and integration tests
443- ✅ Documentation: Document public APIs with doc comments
444