Cursor rule

1---
2paths:
3  - "**/*.rs"
4---
5# Rust Patterns
6 
7> This file extends [common/patterns.md](../common/patterns.md) with Rust-specific content.
8 
9## Repository Pattern with Traits
10 
11Encapsulate data access behind a trait:
12 
13```rust
14pub trait OrderRepository: Send + Sync {
15    fn find_by_id(&self, id: u64) -> Result<Option<Order>, StorageError>;
16    fn find_all(&self) -> Result<Vec<Order>, StorageError>;
17    fn save(&self, order: &Order) -> Result<Order, StorageError>;
18    fn delete(&self, id: u64) -> Result<(), StorageError>;
19}
20```
21 
22Concrete implementations handle storage details (Postgres, SQLite, in-memory for tests).
23 
24## Service Layer
25 
26Business logic in service structs; inject dependencies via constructor:
27 
28```rust
29pub struct OrderService {
30    repo: Box<dyn OrderRepository>,
31    payment: Box<dyn PaymentGateway>,
32}
33 
34impl OrderService {
35    pub fn new(repo: Box<dyn OrderRepository>, payment: Box<dyn PaymentGateway>) -> Self {
36        Self { repo, payment }
37    }
38 
39    pub fn place_order(&self, request: CreateOrderRequest) -> anyhow::Result<OrderSummary> {
40        let order = Order::from(request);
41        self.payment.charge(order.total())?;
42        let saved = self.repo.save(&order)?;
43        Ok(OrderSummary::from(saved))
44    }
45}
46```
47 
48## Newtype Pattern for Type Safety
49 
50Prevent argument mix-ups with distinct wrapper types:
51 
52```rust
53struct UserId(u64);
54struct OrderId(u64);
55 
56fn get_order(user: UserId, order: OrderId) -> anyhow::Result<Order> {
57    // Can't accidentally swap user and order IDs at call sites
58    todo!()
59}
60```
61 
62## Enum State Machines
63 
64Model states as enums — make illegal states unrepresentable:
65 
66```rust
67enum ConnectionState {
68    Disconnected,
69    Connecting { attempt: u32 },
70    Connected { session_id: String },
71    Failed { reason: String, retries: u32 },
72}
73 
74fn handle(state: &ConnectionState) {
75    match state {
76        ConnectionState::Disconnected => connect(),
77        ConnectionState::Connecting { attempt } if *attempt > 3 => abort(),
78        ConnectionState::Connecting { .. } => wait(),
79        ConnectionState::Connected { session_id } => use_session(session_id),
80        ConnectionState::Failed { retries, .. } if *retries < 5 => retry(),
81        ConnectionState::Failed { reason, .. } => log_failure(reason),
82    }
83}
84```
85 
86Always match exhaustively — no wildcard `_` for business-critical enums.
87 
88## Builder Pattern
89 
90Use for structs with many optional parameters:
91 
92```rust
93pub struct ServerConfig {
94    host: String,
95    port: u16,
96    max_connections: usize,
97}
98 
99impl ServerConfig {
100    pub fn builder(host: impl Into<String>, port: u16) -> ServerConfigBuilder {
101        ServerConfigBuilder {
102            host: host.into(),
103            port,
104            max_connections: 100,
105        }
106    }
107}
108 
109pub struct ServerConfigBuilder {
110    host: String,
111    port: u16,
112    max_connections: usize,
113}
114 
115impl ServerConfigBuilder {
116    pub fn max_connections(mut self, n: usize) -> Self {
117        self.max_connections = n;
118        self
119    }
120 
121    pub fn build(self) -> ServerConfig {
122        ServerConfig {
123            host: self.host,
124            port: self.port,
125            max_connections: self.max_connections,
126        }
127    }
128}
129```
130 
131## Sealed Traits for Extensibility Control
132 
133Use a private module to seal a trait, preventing external implementations:
134 
135```rust
136mod private {
137    pub trait Sealed {}
138}
139 
140pub trait Format: private::Sealed {
141    fn encode(&self, data: &[u8]) -> Vec<u8>;
142}
143 
144pub struct Json;
145impl private::Sealed for Json {}
146impl Format for Json {
147    fn encode(&self, data: &[u8]) -> Vec<u8> { todo!() }
148}
149```
150 
151## API Response Envelope
152 
153Consistent API responses using a generic enum:
154 
155```rust
156#[derive(Debug, serde::Serialize)]
157#[serde(tag = "status")]
158pub enum ApiResponse<T: serde::Serialize> {
159    #[serde(rename = "ok")]
160    Ok { data: T },
161    #[serde(rename = "error")]
162    Error { message: String },
163}
164```
165 
166## References
167 
168See skill: `rust-patterns` for comprehensive patterns including ownership, traits, generics, concurrency, and async.
169