agy-superpowers 5.1.4 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/async-joinset-structured.md

@@ -0,0 +1,195 @@
+# async-joinset-structured
+
+> Use `JoinSet` for managing dynamic collections of spawned tasks
+
+## Why It Matters
+
+When spawning a variable number of tasks, collecting `JoinHandle`s in a `Vec` and using `join_all` works but lacks flexibility. `JoinSet` provides a better abstraction: add/remove tasks dynamically, get results as they complete, and abort all on drop. It's the idiomatic way to manage task collections.
+
+## Bad
+
+```rust
+// Manual handle management
+let mut handles: Vec<JoinHandle<Result<Data>>> = Vec::new();
+
+for url in urls {
+    handles.push(tokio::spawn(fetch(url)));
+}
+
+// Wait for all, in order (not as they complete)
+let results = futures::future::join_all(handles).await;
+
+// No easy way to cancel all, handle errors progressively, or add more tasks
+```
+
+## Good
+
+```rust
+use tokio::task::JoinSet;
+
+let mut set = JoinSet::new();
+
+for url in urls {
+    set.spawn(fetch(url.clone()));
+}
+
+// Process results as they complete
+while let Some(result) = set.join_next().await {
+    match result {
+        Ok(Ok(data)) => process(data),
+        Ok(Err(e)) => log::error!("Task failed: {}", e),
+        Err(e) => log::error!("Task panicked: {}", e),
+    }
+}
+
+// All tasks done, set is empty
+```
+
+## Dynamic Task Addition
+
+```rust
+use tokio::task::JoinSet;
+
+async fn worker_pool(mut rx: mpsc::Receiver<Task>) {
+    let mut set = JoinSet::new();
+    let max_concurrent = 10;
+    
+    loop {
+        tokio::select! {
+            // Accept new tasks if under limit
+            Some(task) = rx.recv(), if set.len() < max_concurrent => {
+                set.spawn(process_task(task));
+            }
+            
+            // Process completed tasks
+            Some(result) = set.join_next() => {
+                handle_result(result);
+            }
+            
+            // Exit when no tasks and channel closed
+            else => break,
+        }
+    }
+}
+```
+
+## Abort on Drop
+
+```rust
+use tokio::task::JoinSet;
+
+{
+    let mut set = JoinSet::new();
+    set.spawn(long_running_task());
+    set.spawn(another_task());
+    
+    // Early exit
+    return;
+}  // JoinSet dropped here - all tasks are aborted!
+
+// Explicit abort
+let mut set = JoinSet::new();
+set.spawn(task());
+set.abort_all();  // Cancel all tasks
+```
+
+## Error Handling Pattern
+
+```rust
+use tokio::task::JoinSet;
+
+async fn fetch_all(urls: &[String]) -> Vec<Result<Data, Error>> {
+    let mut set = JoinSet::new();
+    let mut results = Vec::new();
+    
+    for url in urls {
+        set.spawn(fetch(url.clone()));
+    }
+    
+    while let Some(join_result) = set.join_next().await {
+        let result = match join_result {
+            Ok(task_result) => task_result,
+            Err(join_error) => {
+                if join_error.is_panic() {
+                    Err(Error::TaskPanicked)
+                } else {
+                    Err(Error::TaskCancelled)
+                }
+            }
+        };
+        results.push(result);
+    }
+    
+    results
+}
+```
+
+## With Cancellation
+
+```rust
+use tokio::task::JoinSet;
+use tokio_util::sync::CancellationToken;
+
+async fn run_workers(shutdown: CancellationToken) {
+    let mut set = JoinSet::new();
+    
+    for i in 0..4 {
+        let token = shutdown.child_token();
+        set.spawn(async move {
+            loop {
+                tokio::select! {
+                    _ = token.cancelled() => break,
+                    _ = do_work(i) => {}
+                }
+            }
+        });
+    }
+    
+    // Wait for shutdown
+    shutdown.cancelled().await;
+    
+    // Abort remaining tasks
+    set.abort_all();
+    
+    // Wait for all to finish (drain aborted tasks)
+    while set.join_next().await.is_some() {}
+}
+```
+
+## Spawning with Context
+
+```rust
+use tokio::task::JoinSet;
+
+let mut set: JoinSet<(usize, Result<Data, Error>)> = JoinSet::new();
+
+for (index, url) in urls.iter().enumerate() {
+    let url = url.clone();
+    set.spawn(async move {
+        (index, fetch(&url).await)
+    });
+}
+
+// Results include their index
+while let Some(result) = set.join_next().await {
+    if let Ok((index, data)) = result {
+        results[index] = Some(data);
+    }
+}
+```
+
+## JoinSet vs join_all
+
+| Feature | JoinSet | join_all |
+|---------|---------|----------|
+| Add tasks dynamically | Yes | No |
+| Results as-completed | Yes | No (all at once) |
+| Abort all on drop | Yes | No |
+| Cancel individual | Yes | No |
+| Memory efficient | Yes | Pre-allocates |
+
+## See Also
+
+- [async-join-parallel](./async-join-parallel.md) - Static concurrent futures
+- [async-cancellation-token](./async-cancellation-token.md) - Cancellation patterns
+- [async-try-join](./async-try-join.md) - Error handling in joins

package/template/agent/skills/rust-developer/references/rust-rules/async-mpsc-queue.md

@@ -0,0 +1,171 @@
+# async-mpsc-queue
+
+> Use `mpsc` channels for async message queues between tasks
+
+## Why It Matters
+
+`tokio::sync::mpsc` (multi-producer, single-consumer) is the workhorse channel for async Rust. It provides async send/receive, backpressure via bounded capacity, and efficient cloning of senders. It's the default choice for task-to-task communication.
+
+## Bad
+
+```rust
+use std::sync::mpsc;  // Wrong! Blocks the async runtime
+
+let (tx, rx) = std::sync::mpsc::channel();
+
+tokio::spawn(async move {
+    tx.send("hello").unwrap();  // Might block
+});
+
+tokio::spawn(async move {
+    let msg = rx.recv().unwrap();  // BLOCKS the executor thread!
+});
+```
+
+## Good
+
+```rust
+use tokio::sync::mpsc;
+
+let (tx, mut rx) = mpsc::channel::<String>(100);
+
+tokio::spawn(async move {
+    tx.send("hello".to_string()).await.unwrap();
+});
+
+tokio::spawn(async move {
+    while let Some(msg) = rx.recv().await {
+        println!("Received: {}", msg);
+    }
+});
+```
+
+## Sender Cloning
+
+```rust
+use tokio::sync::mpsc;
+
+let (tx, mut rx) = mpsc::channel::<Event>(100);
+
+// Multiple producers
+for i in 0..10 {
+    let tx = tx.clone();  // Cheap clone
+    tokio::spawn(async move {
+        tx.send(Event { source: i }).await.unwrap();
+    });
+}
+
+// Drop original sender so channel closes when all clones dropped
+drop(tx);
+
+// Consumer
+while let Some(event) = rx.recv().await {
+    process(event);
+}
+// Loop exits when all senders dropped
+```
+
+## Message Handler Pattern
+
+```rust
+use tokio::sync::mpsc;
+
+enum Command {
+    Get { key: String, reply: oneshot::Sender<Option<Value>> },
+    Set { key: String, value: Value },
+    Delete { key: String },
+}
+
+async fn run_store(mut commands: mpsc::Receiver<Command>) {
+    let mut store = HashMap::new();
+    
+    while let Some(cmd) = commands.recv().await {
+        match cmd {
+            Command::Get { key, reply } => {
+                let _ = reply.send(store.get(&key).cloned());
+            }
+            Command::Set { key, value } => {
+                store.insert(key, value);
+            }
+            Command::Delete { key } => {
+                store.remove(&key);
+            }
+        }
+    }
+}
+
+// Usage
+async fn client(tx: mpsc::Sender<Command>) -> Option<Value> {
+    let (reply_tx, reply_rx) = oneshot::channel();
+    
+    tx.send(Command::Get { 
+        key: "foo".to_string(), 
+        reply: reply_tx 
+    }).await.unwrap();
+    
+    reply_rx.await.unwrap()
+}
+```
+
+## Graceful Shutdown
+
+```rust
+async fn worker(mut rx: mpsc::Receiver<Task>, shutdown: CancellationToken) {
+    loop {
+        tokio::select! {
+            _ = shutdown.cancelled() => {
+                // Drain remaining messages
+                while let Ok(task) = rx.try_recv() {
+                    process(task).await;
+                }
+                break;
+            }
+            Some(task) = rx.recv() => {
+                process(task).await;
+            }
+            else => break,  // Channel closed
+        }
+    }
+}
+```
+
+## WeakSender for Optional Producers
+
+```rust
+use tokio::sync::mpsc;
+
+let (tx, mut rx) = mpsc::channel::<Message>(100);
+let weak = tx.downgrade();  // Doesn't keep channel alive
+
+tokio::spawn(async move {
+    // Strong sender - keeps channel alive
+    tx.send("from strong".into()).await.unwrap();
+});
+
+tokio::spawn(async move {
+    // Weak sender - may fail if strong senders dropped
+    if let Some(tx) = weak.upgrade() {
+        tx.send("from weak".into()).await.unwrap();
+    }
+});
+```
+
+## Permit Pattern
+
+```rust
+// Reserve slot before preparing message
+let permit = tx.reserve().await?;
+
+// Now we have guaranteed capacity
+let message = expensive_to_create_message();
+permit.send(message);  // Never fails
+
+// Useful when message creation is expensive
+// and you don't want to create it if channel is full
+```
+
+## See Also
+
+- [async-bounded-channel](./async-bounded-channel.md) - Why bounded channels
+- [async-oneshot-response](./async-oneshot-response.md) - Request-response with oneshot
+- [async-broadcast-pubsub](./async-broadcast-pubsub.md) - Multiple consumers

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