agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/async-no-lock-await.md

@@ -0,0 +1,156 @@
+# async-no-lock-await
+
+> Never hold `Mutex`/`RwLock` across `.await`
+
+## Why It Matters
+
+Holding a lock across an `.await` point can cause deadlocks and severely hurt performance. The task may be suspended while holding the lock, blocking all other tasks waiting for it - potentially indefinitely.
+
+## Bad
+
+```rust
+use tokio::sync::Mutex;
+
+async fn bad_update(state: &Mutex<State>) {
+    let mut guard = state.lock().await;
+    
+    // BAD: Lock held across await!
+    let data = fetch_from_network().await;
+    
+    guard.value = data;
+}  // Lock finally released
+
+// This can deadlock or starve other tasks
+```
+
+## Good
+
+```rust
+use tokio::sync::Mutex;
+
+async fn good_update(state: &Mutex<State>) {
+    // Fetch data BEFORE taking the lock
+    let data = fetch_from_network().await;
+    
+    // Lock only for the quick update
+    let mut guard = state.lock().await;
+    guard.value = data;
+}  // Lock released immediately
+
+// Alternative: Clone data out, process, then update
+async fn good_update_v2(state: &Mutex<State>) {
+    // Extract what we need
+    let id = {
+        let guard = state.lock().await;
+        guard.id.clone()
+    };  // Lock released!
+    
+    // Do async work without lock
+    let data = fetch_by_id(id).await;
+    
+    // Quick update
+    state.lock().await.value = data;
+}
+```
+
+## The Problem Visualized
+
+```rust
+// Task A:
+let guard = mutex.lock().await;    // Acquires lock
+expensive_io().await;              // Suspended, still holding lock!
+// ... many milliseconds pass ...
+drop(guard);                       // Finally releases
+
+// Task B, C, D:
+let guard = mutex.lock().await;    // All blocked waiting for A!
+```
+
+## Patterns for Extraction
+
+```rust
+use tokio::sync::Mutex;
+
+// Pattern 1: Clone out, process, update
+async fn pattern_clone(state: &Mutex<State>) {
+    let config = state.lock().await.config.clone();
+    let result = process_with_io(&config).await;
+    state.lock().await.result = result;
+}
+
+// Pattern 2: Compute closure, apply
+async fn pattern_closure(state: &Mutex<State>) {
+    let update = compute_update().await;
+    
+    state.lock().await.apply(update);
+}
+
+// Pattern 3: Message passing
+async fn pattern_message(
+    state: &Mutex<State>,
+    tx: mpsc::Sender<Update>,
+) {
+    let update = compute_update().await;
+    tx.send(update).await.unwrap();
+}
+
+// Separate task handles updates
+async fn state_manager(
+    state: Arc<Mutex<State>>,
+    mut rx: mpsc::Receiver<Update>,
+) {
+    while let Some(update) = rx.recv().await {
+        state.lock().await.apply(update);
+    }
+}
+```
+
+## Using RwLock
+
+```rust
+use tokio::sync::RwLock;
+
+async fn read_heavy(state: &RwLock<State>) {
+    // Multiple readers OK, but still don't hold across await
+    let value = {
+        let guard = state.read().await;
+        guard.value.clone()
+    };
+    
+    // Process without lock
+    let result = process(value).await;
+    
+    // Write lock for update
+    state.write().await.result = result;
+}
+```
+
+## std::sync::Mutex vs tokio::sync::Mutex
+
+```rust
+// std::sync::Mutex: Blocks the entire thread
+// - Use for quick, CPU-only operations
+// - NEVER use in async code with await inside
+
+// tokio::sync::Mutex: Async-aware, yields to runtime
+// - Use in async code
+// - Still don't hold across await points!
+
+// std::sync::Mutex in async (quick operation, OK):
+async fn quick_update(state: &std::sync::Mutex<State>) {
+    state.lock().unwrap().counter += 1;  // No await, OK
+}
+
+// tokio::sync::Mutex (must use if lock scope has await):
+async fn must_await_inside(state: &tokio::sync::Mutex<State>) {
+    let mut guard = state.lock().await;
+    // Only if you REALLY need the lock during async op
+    // (usually you don't - redesign instead)
+}
+```
+
+## See Also
+
+- [async-spawn-blocking](async-spawn-blocking.md) - Use spawn_blocking for CPU work
+- [async-clone-before-await](async-clone-before-await.md) - Clone data before await
+- [anti-lock-across-await](anti-lock-across-await.md) - Anti-pattern reference

package/template/agent/skills/rust-developer/references/rust-rules/async-oneshot-response.md

@@ -0,0 +1,191 @@
+# async-oneshot-response
+
+> Use `oneshot` channel for request-response patterns
+
+## Why It Matters
+
+When one task needs to send a request and wait for exactly one response, `oneshot` is the perfect fit. It's a single-use channel optimized for this pattern—no buffering, no clone overhead. Combined with `mpsc`, it enables clean actor-style message passing.
+
+## Bad
+
+```rust
+// Using mpsc for single response - wasteful
+let (tx, mut rx) = mpsc::channel::<Response>(1);
+send_request().await;
+let response = rx.recv().await.unwrap();
+// Channel persists, could accidentally receive more
+
+// Using shared state - complex
+let result = Arc::new(Mutex::new(None));
+send_request(result.clone()).await;
+while result.lock().await.is_none() {
+    tokio::time::sleep(Duration::from_millis(10)).await;  // Polling!
+}
+```
+
+## Good
+
+```rust
+use tokio::sync::oneshot;
+
+let (tx, rx) = oneshot::channel::<Response>();
+
+// Send request with reply channel
+send_request(Request { data, reply: tx }).await;
+
+// Wait for response
+let response = rx.await?;
+
+// Channel is consumed - can't accidentally reuse
+```
+
+## Request-Response Pattern
+
+```rust
+use tokio::sync::{mpsc, oneshot};
+
+enum Request {
+    Get {
+        key: String,
+        reply: oneshot::Sender<Option<Value>>,
+    },
+    Set {
+        key: String,
+        value: Value,
+        reply: oneshot::Sender<bool>,
+    },
+}
+
+// Service handler
+async fn service(mut rx: mpsc::Receiver<Request>) {
+    let mut store = HashMap::new();
+    
+    while let Some(req) = rx.recv().await {
+        match req {
+            Request::Get { key, reply } => {
+                let value = store.get(&key).cloned();
+                let _ = reply.send(value);  // Ignore if receiver dropped
+            }
+            Request::Set { key, value, reply } => {
+                store.insert(key, value);
+                let _ = reply.send(true);
+            }
+        }
+    }
+}
+
+// Client
+async fn get_value(tx: &mpsc::Sender<Request>, key: &str) -> Option<Value> {
+    let (reply_tx, reply_rx) = oneshot::channel();
+    
+    tx.send(Request::Get {
+        key: key.to_string(),
+        reply: reply_tx,
+    }).await.ok()?;
+    
+    reply_rx.await.ok()?
+}
+```
+
+## With Timeout
+
+```rust
+use tokio::time::{timeout, Duration};
+
+async fn request_with_timeout(
+    tx: &mpsc::Sender<Request>,
+    key: &str,
+) -> Result<Value, Error> {
+    let (reply_tx, reply_rx) = oneshot::channel();
+    
+    tx.send(Request::Get {
+        key: key.to_string(),
+        reply: reply_tx,
+    }).await.map_err(|_| Error::ServiceDown)?;
+    
+    timeout(Duration::from_secs(5), reply_rx)
+        .await
+        .map_err(|_| Error::Timeout)?
+        .map_err(|_| Error::ServiceDown)?
+        .ok_or(Error::NotFound)
+}
+```
+
+## Error Handling
+
+```rust
+use tokio::sync::oneshot;
+
+let (tx, rx) = oneshot::channel::<String>();
+
+// Sender dropped without sending
+drop(tx);
+match rx.await {
+    Ok(value) => println!("Got: {}", value),
+    Err(oneshot::error::RecvError { .. }) => {
+        println!("Sender dropped");
+    }
+}
+
+// Receiver dropped before send
+let (tx, rx) = oneshot::channel::<String>();
+drop(rx);
+match tx.send("hello".to_string()) {
+    Ok(()) => println!("Sent"),
+    Err(value) => println!("Receiver dropped, value: {}", value),
+}
+```
+
+## Closed Detection
+
+```rust
+// Check if receiver is still waiting
+let (tx, rx) = oneshot::channel::<i32>();
+
+// In producer
+if tx.is_closed() {
+    println!("Receiver already gone, skip expensive computation");
+} else {
+    let result = expensive_computation();
+    tx.send(result).ok();
+}
+
+// Async wait for close
+let tx_clone = tx.clone();  // Note: can't actually clone, just showing concept
+tokio::select! {
+    _ = tx.closed() => println!("Receiver dropped"),
+    result = compute() => { tx.send(result).ok(); }
+}
+```
+
+## Response Type Wrapper
+
+```rust
+// Standardize request-response pattern
+struct RpcRequest<Req, Res> {
+    request: Req,
+    reply: oneshot::Sender<Res>,
+}
+
+impl<Req, Res> RpcRequest<Req, Res> {
+    fn new(request: Req) -> (Self, oneshot::Receiver<Res>) {
+        let (tx, rx) = oneshot::channel();
+        (RpcRequest { request, reply: tx }, rx)
+    }
+    
+    fn respond(self, response: Res) {
+        let _ = self.reply.send(response);
+    }
+}
+
+// Usage
+let (req, rx) = RpcRequest::new(GetUser { id: 42 });
+tx.send(req).await?;
+let user = rx.await?;
+```
+
+## See Also
+
+- [async-mpsc-queue](./async-mpsc-queue.md) - Pair with oneshot for request-response
+- [async-bounded-channel](./async-bounded-channel.md) - Channel sizing
+- [async-select-racing](./async-select-racing.md) - Timeout patterns

package/template/agent/skills/rust-developer/references/rust-rules/async-select-racing.md

@@ -0,0 +1,198 @@
+# async-select-racing
+
+> Use `select!` to race futures and handle the first to complete
+
+## Why It Matters
+
+Sometimes you need the first result from multiple futures—timeout vs operation, cancellation vs work, or competing alternatives. `tokio::select!` lets you race futures and handle whichever completes first, while properly cancelling the others.
+
+## Bad
+
+```rust
+// Can't express "whichever finishes first"
+async fn fetch_with_fallback() -> Data {
+    match fetch_primary().await {
+        Ok(data) => data,
+        Err(_) => fetch_fallback().await.unwrap(),  // Sequential, not racing
+    }
+}
+
+// Manual timeout is error-prone
+async fn fetch_with_timeout() -> Option<Data> {
+    let start = Instant::now();
+    loop {
+        if start.elapsed() > Duration::from_secs(5) {
+            return None;
+        }
+        // How do we check timeout while awaiting?
+    }
+}
+```
+
+## Good
+
+```rust
+use tokio::select;
+
+async fn fetch_with_timeout() -> Result<Data, Error> {
+    select! {
+        result = fetch_data() => result,
+        _ = tokio::time::sleep(Duration::from_secs(5)) => {
+            Err(Error::Timeout)
+        }
+    }
+}
+
+async fn fetch_with_fallback() -> Data {
+    select! {
+        result = fetch_primary() => {
+            match result {
+                Ok(data) => data,
+                Err(_) => fetch_fallback().await.unwrap()
+            }
+        }
+        _ = tokio::time::sleep(Duration::from_secs(1)) => {
+            // Primary too slow, use fallback
+            fetch_fallback().await.unwrap()
+        }
+    }
+}
+```
+
+## select! Syntax
+
+```rust
+select! {
+    // Pattern = future => handler
+    result = async_operation() => {
+        // Handle result
+        println!("Got: {:?}", result);
+    }
+    
+    // Can bind with pattern matching
+    Ok(data) = fallible_operation() => {
+        process(data);
+    }
+    
+    // Conditional branches with if guards
+    msg = channel.recv(), if should_receive => {
+        handle_message(msg);
+    }
+    
+    // else branch for when all futures are disabled
+    else => {
+        println!("All branches disabled");
+    }
+}
+```
+
+## Cancellation Behavior
+
+```rust
+async fn select_example() {
+    select! {
+        _ = operation_a() => {
+            println!("A completed first");
+            // operation_b() is dropped/cancelled
+        }
+        _ = operation_b() => {
+            println!("B completed first");
+            // operation_a() is dropped/cancelled
+        }
+    }
+}
+
+// Futures are cancelled at their next .await point
+// For immediate cancellation, futures must be cancel-safe
+```
+
+## Biased Selection
+
+```rust
+// By default, select! randomly picks when multiple are ready
+// Use biased mode for deterministic priority
+select! {
+    biased;  // Check branches in order
+    
+    msg = high_priority.recv() => handle_high(msg),
+    msg = low_priority.recv() => handle_low(msg),
+}
+
+// Without biased, both channels have equal chance
+// when both have messages ready
+```
+
+## Loop with select!
+
+```rust
+async fn event_loop(
+    mut commands: mpsc::Receiver<Command>,
+    shutdown: CancellationToken,
+) {
+    loop {
+        select! {
+            _ = shutdown.cancelled() => {
+                println!("Shutting down");
+                break;
+            }
+            Some(cmd) = commands.recv() => {
+                process_command(cmd).await;
+            }
+            else => {
+                // commands channel closed
+                break;
+            }
+        }
+    }
+}
+```
+
+## Racing Multiple of Same Type
+
+```rust
+// Race multiple servers for fastest response
+async fn fastest_response(servers: &[String]) -> Result<Response> {
+    let futures = servers.iter()
+        .map(|s| fetch_from(s))
+        .collect::<Vec<_>>();
+    
+    // select! requires static branches, use select_all for dynamic
+    let (result, _index, _remaining) = 
+        futures::future::select_all(futures).await;
+    
+    result
+}
+```
+
+## Common Patterns
+
+```rust
+// Timeout
+select! {
+    result = operation() => result,
+    _ = sleep(Duration::from_secs(5)) => Err(Timeout),
+}
+
+// Cancellation
+select! {
+    result = operation() => result,
+    _ = cancel_token.cancelled() => Err(Cancelled),
+}
+
+// Interval with cancellation
+let mut interval = tokio::time::interval(Duration::from_secs(1));
+loop {
+    select! {
+        _ = shutdown.cancelled() => break,
+        _ = interval.tick() => {
+            do_periodic_work().await;
+        }
+    }
+}
+```
+
+## See Also
+
+- [async-cancellation-token](./async-cancellation-token.md) - Cancellation patterns
+- [async-join-parallel](./async-join-parallel.md) - All futures, not racing
+- [async-bounded-channel](./async-bounded-channel.md) - Channel operations in select

package/template/agent/skills/rust-developer/references/rust-rules/async-spawn-blocking.md

@@ -0,0 +1,154 @@
+# async-spawn-blocking
+
+> Use `spawn_blocking` for CPU-intensive work
+
+## Why It Matters
+
+Async runtimes like Tokio use a small number of threads to handle many tasks. CPU-intensive or blocking operations on these threads starve other tasks. `spawn_blocking` moves such work to a dedicated thread pool.
+
+## Bad
+
+```rust
+// BAD: Blocks the async runtime thread
+async fn process_image(data: &[u8]) -> ProcessedImage {
+    // CPU-intensive work on async thread!
+    let resized = resize_image(data);      // Blocks!
+    let compressed = compress(resized);     // Blocks!
+    compressed
+}
+
+// BAD: Synchronous file I/O in async context
+async fn read_large_file(path: &Path) -> Vec<u8> {
+    std::fs::read(path).unwrap()  // Blocks the runtime!
+}
+```
+
+## Good
+
+```rust
+use tokio::task;
+
+// GOOD: Offload CPU work to blocking pool
+async fn process_image(data: Vec<u8>) -> ProcessedImage {
+    task::spawn_blocking(move || {
+        let resized = resize_image(&data);
+        compress(resized)
+    })
+    .await
+    .expect("spawn_blocking failed")
+}
+
+// GOOD: Use async file I/O
+async fn read_large_file(path: &Path) -> tokio::io::Result<Vec<u8>> {
+    tokio::fs::read(path).await
+}
+
+// GOOD: Or spawn_blocking for unavoidable sync I/O
+async fn read_with_sync_lib(path: PathBuf) -> Vec<u8> {
+    task::spawn_blocking(move || {
+        sync_library::read_file(&path)
+    })
+    .await
+    .unwrap()
+}
+```
+
+## What Counts as Blocking
+
+```rust
+// CPU-intensive operations
+- Cryptographic operations (hashing, encryption)
+- Image/video processing
+- Compression/decompression
+- Complex parsing
+- Mathematical computations
+
+// Blocking I/O
+- std::fs operations
+- Synchronous database drivers
+- Synchronous HTTP clients
+- Thread::sleep
+
+// Example thresholds (rough guidelines):
+// < 10µs: OK on async thread
+// 10µs - 1ms: Consider spawn_blocking
+// > 1ms: Definitely spawn_blocking
+```
+
+## Practical Examples
+
+```rust
+// Password hashing (CPU-intensive)
+async fn hash_password(password: String) -> String {
+    task::spawn_blocking(move || {
+        bcrypt::hash(password, bcrypt::DEFAULT_COST).unwrap()
+    })
+    .await
+    .unwrap()
+}
+
+// JSON parsing of large documents
+async fn parse_large_json(data: String) -> serde_json::Value {
+    task::spawn_blocking(move || {
+        serde_json::from_str(&data).unwrap()
+    })
+    .await
+    .unwrap()
+}
+
+// Compression
+async fn compress_data(data: Vec<u8>) -> Vec<u8> {
+    task::spawn_blocking(move || {
+        let mut encoder = flate2::write::GzEncoder::new(
+            Vec::new(),
+            flate2::Compression::default(),
+        );
+        encoder.write_all(&data).unwrap();
+        encoder.finish().unwrap()
+    })
+    .await
+    .unwrap()
+}
+```
+
+## spawn_blocking vs spawn
+
+```rust
+// spawn: Runs async code on runtime threads
+tokio::spawn(async {
+    // Async code here
+    some_async_operation().await;
+});
+
+// spawn_blocking: Runs sync code on blocking thread pool
+tokio::task::spawn_blocking(|| {
+    // Synchronous, possibly CPU-intensive code
+    heavy_computation();
+});
+
+// spawn_blocking returns JoinHandle that can be awaited
+let result = tokio::task::spawn_blocking(|| {
+    expensive_sync_operation()
+}).await?;
+```
+
+## Rayon for Parallel CPU Work
+
+```rust
+// For parallel CPU work, consider Rayon inside spawn_blocking
+async fn parallel_process(items: Vec<Item>) -> Vec<Output> {
+    task::spawn_blocking(move || {
+        use rayon::prelude::*;
+        items.par_iter()
+            .map(|item| cpu_intensive_transform(item))
+            .collect()
+    })
+    .await
+    .unwrap()
+}
+```
+
+## See Also
+
+- [async-tokio-fs](async-tokio-fs.md) - Use tokio::fs for async file I/O
+- [async-no-lock-await](async-no-lock-await.md) - Don't hold locks across await