.cursorrules (deprecated)

1# Rust + Actix Web — Cursor Rules
2# Comprehensive rules for building web APIs with Rust and Actix Web
3 
4## Project Context
5You are working on a Rust web API built with the Actix Web framework. The codebase
6follows Rust idioms, emphasizes type safety and zero-cost abstractions, and uses the
7Rust ownership model for memory safety without a garbage collector. The project uses
8Cargo for dependency management and follows the Rust 2021 edition.
9 
10## Tech Stack
11- Rust 2021 edition (stable toolchain)
12- Actix Web 4.x for HTTP framework
13- SQLx for async database access (compile-time checked queries)
14- Serde for serialization/deserialization
15- Tokio as async runtime (via Actix)
16- Tracing + tracing-subscriber for structured logging
17- Cargo for build and dependency management
18- Docker for deployment
19 
20## Coding Style
21 
22### Naming Conventions
23- Types/structs/enums: PascalCase (e.g., `UserService`, `OrderStatus`)
24- Functions/methods: snake_case (e.g., `create_user`, `get_order_by_id`)
25- Modules: snake_case (e.g., `user_handler`, `order_service`)
26- Constants: UPPER_SNAKE_CASE (e.g., `MAX_PAGE_SIZE`, `DEFAULT_TIMEOUT`)
27- Traits: PascalCase, descriptive of behavior (e.g., `UserRepository`, `Authenticator`)
28- Crate names: kebab-case in Cargo.toml, snake_case in code
29- Error types: PascalCase with `Error` suffix (e.g., `AppError`, `AuthError`)
30- Lifetimes: short, descriptive if multiple (`'a`, `'req`, `'conn`)
31 
32### Project Structure
33```
34src/
35  main.rs                # Entry point, server setup
36  config.rs              # Configuration loading (env vars, files)
37  lib.rs                 # Library root (re-exports)
38  errors.rs              # Error types and conversions
39  handlers/              # HTTP handlers (thin — extract, delegate, respond)
40    mod.rs
41    user.rs
42    order.rs
43  services/              # Business logic
44    mod.rs
45    user.rs
46    order.rs
47  models/                # Domain types and database models
48    mod.rs
49    user.rs
50    order.rs
51  repositories/          # Data access layer
52    mod.rs
53    user.rs
54    order.rs
55  middleware/             # Actix middleware
56    mod.rs
57    auth.rs
58    logging.rs
59  extractors/            # Custom Actix extractors
60    mod.rs
61    auth.rs
62migrations/              # SQLx migrations
63tests/                   # Integration tests
64  common/mod.rs          # Shared test utilities
65  api/                   # API integration tests
66```
67 
68## Rust/Actix Patterns
69 
70### Handler Pattern
71```rust
72use actix_web::{web, HttpResponse, Result};
73 
74pub async fn get_user(
75    path: web::Path<i64>,
76    service: web::Data<UserService>,
77) -> Result<HttpResponse, AppError> {
78    let user_id = path.into_inner();
79    let user = service.find_by_id(user_id).await?;
80 
81    match user {
82        Some(user) => Ok(HttpResponse::Ok().json(UserResponse::from(user))),
83        None => Err(AppError::NotFound(format!("User {} not found", user_id))),
84    }
85}
86 
87pub async fn create_user(
88    body: web::Json<CreateUserRequest>,
89    service: web::Data<UserService>,
90) -> Result<HttpResponse, AppError> {
91    let input = body.into_inner();
92    let user = service.create(input).await?;
93    Ok(HttpResponse::Created().json(UserResponse::from(user)))
94}
95 
96pub fn configure(cfg: &mut web::ServiceConfig) {
97    cfg.service(
98        web::scope("/users")
99            .route("", web::post().to(create_user))
100            .route("/{id}", web::get().to(get_user))
101            .route("/{id}", web::put().to(update_user))
102            .route("/{id}", web::delete().to(delete_user)),
103    );
104}
105```
106 
107### Error Handling
108```rust
109use actix_web::{HttpResponse, ResponseError};
110use std::fmt;
111 
112#[derive(Debug)]
113pub enum AppError {
114    NotFound(String),
115    BadRequest(String),
116    Unauthorized(String),
117    Internal(String),
118    Database(sqlx::Error),
119}
120 
121impl fmt::Display for AppError {
122    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
123        match self {
124            Self::NotFound(msg) => write!(f, "Not found: {msg}"),
125            Self::BadRequest(msg) => write!(f, "Bad request: {msg}"),
126            Self::Unauthorized(msg) => write!(f, "Unauthorized: {msg}"),
127            Self::Internal(msg) => write!(f, "Internal error: {msg}"),
128            Self::Database(e) => write!(f, "Database error: {e}"),
129        }
130    }
131}
132 
133impl ResponseError for AppError {
134    fn error_response(&self) -> HttpResponse {
135        let (status, message) = match self {
136            Self::NotFound(msg) => (StatusCode::NOT_FOUND, msg.clone()),
137            Self::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg.clone()),
138            Self::Unauthorized(msg) => (StatusCode::UNAUTHORIZED, msg.clone()),
139            Self::Internal(_) | Self::Database(_) => {
140                tracing::error!("Internal error: {self}");
141                (StatusCode::INTERNAL_SERVER_ERROR, "Internal server error".into())
142            }
143        };
144        HttpResponse::build(status).json(serde_json::json!({"error": message}))
145    }
146}
147 
148impl From<sqlx::Error> for AppError {
149    fn from(e: sqlx::Error) -> Self {
150        Self::Database(e)
151    }
152}
153```
154 
155### Serde Models
156```rust
157use serde::{Deserialize, Serialize};
158use chrono::{DateTime, Utc};
159 
160#[derive(Debug, Serialize, sqlx::FromRow)]
161pub struct User {
162    pub id: i64,
163    pub email: String,
164    pub name: String,
165    pub created_at: DateTime<Utc>,
166    pub updated_at: DateTime<Utc>,
167}
168 
169#[derive(Debug, Deserialize)]
170pub struct CreateUserRequest {
171    #[serde(deserialize_with = "validate_email")]
172    pub email: String,
173    pub name: String,
174    pub password: String,
175}
176 
177#[derive(Debug, Serialize)]
178pub struct UserResponse {
179    pub id: i64,
180    pub email: String,
181    pub name: String,
182    pub created_at: DateTime<Utc>,
183}
184 
185impl From<User> for UserResponse {
186    fn from(u: User) -> Self {
187        Self {
188            id: u.id,
189            email: u.email,
190            name: u.name,
191            created_at: u.created_at,
192        }
193    }
194}
195```
196 
197### Service Pattern
198```rust
199pub struct UserService {
200    pool: PgPool,
201}
202 
203impl UserService {
204    pub fn new(pool: PgPool) -> Self {
205        Self { pool }
206    }
207 
208    pub async fn find_by_id(&self, id: i64) -> Result<Option<User>, AppError> {
209        let user = sqlx::query_as!(User, "SELECT * FROM users WHERE id = $1", id)
210            .fetch_optional(&self.pool)
211            .await?;
212        Ok(user)
213    }
214 
215    pub async fn create(&self, input: CreateUserRequest) -> Result<User, AppError> {
216        let password_hash = hash_password(&input.password)?;
217        let user = sqlx::query_as!(
218            User,
219            "INSERT INTO users (email, name, password_hash) VALUES ($1, $2, $3) RETURNING *",
220            input.email, input.name, password_hash,
221        )
222        .fetch_one(&self.pool)
223        .await
224        .map_err(|e| match e {
225            sqlx::Error::Database(ref db_err) if db_err.constraint() == Some("users_email_key") => {
226                AppError::BadRequest("Email already registered".into())
227            }
228            e => AppError::Database(e),
229        })?;
230        Ok(user)
231    }
232}
233```
234 
235## Ownership and Borrowing
236- Use `&str` for function parameters when you only need to read a string
237- Use `String` in structs that own their data
238- Use `Arc<T>` for shared ownership across threads/tasks (via `web::Data`)
239- Prefer cloning over complex lifetime annotations in web handlers
240- Use `Cow<'_, str>` when a function might or might not allocate
241 
242## Testing
243```rust
244#[cfg(test)]
245mod tests {
246    use super::*;
247    use actix_web::{test, App};
248 
249    #[actix_web::test]
250    async fn test_get_user_not_found() {
251        let pool = setup_test_db().await;
252        let service = web::Data::new(UserService::new(pool));
253        let app = test::init_service(
254            App::new().app_data(service.clone()).configure(configure),
255        ).await;
256 
257        let req = test::TestRequest::get().uri("/users/999").to_request();
258        let resp = test::call_service(&app, req).await;
259        assert_eq!(resp.status(), StatusCode::NOT_FOUND);
260    }
261}
262```
263 
264## Performance Guidelines
265- Use `web::Data<T>` (wraps `Arc`) for shared application state
266- Use connection pooling with SQLx `PgPool`
267- Prefer `query_as!` macro for compile-time checked SQL
268- Use streaming responses for large payloads (`HttpResponse::Ok().streaming(...)`)
269- Avoid unnecessary allocations — use references and slices where possible
270- Use `tokio::spawn` for CPU-intensive work to avoid blocking the runtime
271- Profile with `cargo flamegraph` or `perf`
272 
273## Security
274- Validate all input with serde and custom validators
275- Use parameterized queries (SQLx prevents SQL injection by default)
276- Hash passwords with `argon2` or `bcrypt` crate
277- Set security headers in middleware
278- Use `actix-cors` with explicit origins
279- Never expose internal errors to clients
280- Rate limit with `actix-governor`
281 
282## Common Pitfalls
283- Forgetting to call `.await` on async functions (Rust won't warn if result is unused)
284- Holding a `MutexGuard` across `.await` points (causes deadlocks)
285- Not implementing `From` conversions for error types (verbose `map_err` everywhere)
286- Using `unwrap()` in production code — use `?` operator or handle explicitly
287- Blocking the async runtime with synchronous I/O (use `tokio::task::spawn_blocking`)
288- Circular module dependencies — restructure with traits
289- Forgetting `#[derive(Serialize)]` or `#[derive(Deserialize)]` on types used in JSON
290- Not running `cargo clippy` — it catches many subtle issues
291