agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/async-bounded-channel.md

@@ -0,0 +1,175 @@
+# async-bounded-channel
+
+> Use bounded channels to apply backpressure and prevent unbounded memory growth
+
+## Why It Matters
+
+Unbounded channels grow without limit when producers outpace consumers. In production, this leads to memory exhaustion. Bounded channels apply backpressure—producers wait when the channel is full, naturally throttling the system. This prevents OOM and makes resource usage predictable.
+
+## Bad
+
+```rust
+use tokio::sync::mpsc;
+
+// Unbounded channel - can grow forever
+let (tx, mut rx) = mpsc::unbounded_channel::<Message>();
+
+// Fast producer, slow consumer = unbounded memory growth
+tokio::spawn(async move {
+    loop {
+        let msg = generate_message();
+        tx.send(msg).unwrap();  // Never blocks, never fails (until OOM)
+    }
+});
+
+tokio::spawn(async move {
+    while let Some(msg) = rx.recv().await {
+        slow_process(msg).await;  // Can't keep up
+    }
+});
+// Memory grows unboundedly until crash
+```
+
+## Good
+
+```rust
+use tokio::sync::mpsc;
+
+// Bounded channel - backpressure when full
+let (tx, mut rx) = mpsc::channel::<Message>(100);  // Max 100 items
+
+// Producer waits when channel full
+tokio::spawn(async move {
+    loop {
+        let msg = generate_message();
+        // Blocks if channel is full - natural backpressure
+        tx.send(msg).await.unwrap();
+    }
+});
+
+tokio::spawn(async move {
+    while let Some(msg) = rx.recv().await {
+        slow_process(msg).await;
+    }
+});
+// Memory usage capped at ~100 messages
+```
+
+## Choosing Buffer Size
+
+```rust
+// Too small: frequent blocking, reduced throughput
+let (tx, rx) = mpsc::channel::<Item>(1);
+
+// Too large: delayed backpressure, memory waste
+let (tx, rx) = mpsc::channel::<Item>(1_000_000);
+
+// Guidelines:
+// - Start with expected burst size
+// - Measure actual usage in production
+// - Err on the smaller side initially
+
+// Small items, high throughput
+let (tx, rx) = mpsc::channel::<u64>(1000);
+
+// Large items, moderate throughput  
+let (tx, rx) = mpsc::channel::<LargeStruct>(100);
+
+// Low latency requirement
+let (tx, rx) = mpsc::channel::<Command>(10);
+```
+
+## Handling Full Channel
+
+```rust
+use tokio::sync::mpsc;
+use tokio::time::{timeout, Duration};
+
+let (tx, mut rx) = mpsc::channel::<Message>(100);
+
+// Option 1: Wait indefinitely (default)
+tx.send(msg).await?;
+
+// Option 2: Try send, fail if full
+match tx.try_send(msg) {
+    Ok(()) => println!("Sent"),
+    Err(TrySendError::Full(msg)) => {
+        println!("Channel full, dropping message");
+    }
+    Err(TrySendError::Closed(msg)) => {
+        println!("Receiver dropped");
+    }
+}
+
+// Option 3: Timeout
+match timeout(Duration::from_secs(1), tx.send(msg)).await {
+    Ok(Ok(())) => println!("Sent"),
+    Ok(Err(_)) => println!("Channel closed"),
+    Err(_) => println!("Timeout - channel full for too long"),
+}
+
+// Option 4: send with permit reservation
+let permit = tx.reserve().await?;
+permit.send(msg);  // Guaranteed to succeed
+```
+
+## Channel Types
+
+```rust
+// mpsc: many producers, single consumer
+let (tx, rx) = mpsc::channel::<Message>(100);
+let tx2 = tx.clone();  // Can clone sender
+
+// oneshot: single value, one producer, one consumer
+let (tx, rx) = oneshot::channel::<Response>();
+tx.send(response);  // Can only send once
+
+// broadcast: multiple consumers, each gets all messages
+let (tx, _) = broadcast::channel::<Event>(100);
+let mut rx1 = tx.subscribe();
+let mut rx2 = tx.subscribe();
+
+// watch: single latest value, multiple consumers
+let (tx, rx) = watch::channel::<State>(initial);
+// Receivers see latest value, not all values
+```
+
+## Worker Pool Pattern
+
+```rust
+async fn process_with_workers(items: Vec<Item>) -> Vec<Result> {
+    let (tx, rx) = mpsc::channel(100);
+    let rx = Arc::new(Mutex::new(rx));
+    
+    // Spawn worker pool
+    let workers: Vec<_> = (0..4).map(|_| {
+        let rx = rx.clone();
+        tokio::spawn(async move {
+            loop {
+                let item = {
+                    let mut rx = rx.lock().await;
+                    rx.recv().await
+                };
+                match item {
+                    Some(item) => process(item).await,
+                    None => break,
+                }
+            }
+        })
+    }).collect();
+    
+    // Send items
+    for item in items {
+        tx.send(item).await.unwrap();
+    }
+    drop(tx);  // Signal workers to stop
+    
+    futures::future::join_all(workers).await;
+}
+```
+
+## See Also
+
+- [async-mpsc-queue](./async-mpsc-queue.md) - Multi-producer patterns
+- [async-oneshot-response](./async-oneshot-response.md) - Request-response pattern
+- [async-watch-latest](./async-watch-latest.md) - Latest-value broadcasting

package/template/agent/skills/rust-developer/references/rust-rules/async-broadcast-pubsub.md

@@ -0,0 +1,185 @@
+# async-broadcast-pubsub
+
+> Use `broadcast` channel for pub/sub where all subscribers receive all messages
+
+## Why It Matters
+
+Unlike `mpsc` where one consumer receives each message, `broadcast` delivers each message to all subscribers. This is ideal for event broadcasting, real-time notifications, or when multiple components need to react to the same events independently.
+
+## Bad
+
+```rust
+use tokio::sync::mpsc;
+
+// mpsc only delivers to ONE consumer
+let (tx, mut rx) = mpsc::channel::<Event>(100);
+
+// Only one of these receives each message!
+let mut rx2 = ???;  // Can't clone receiver
+```
+
+## Good
+
+```rust
+use tokio::sync::broadcast;
+
+// broadcast delivers to ALL subscribers
+let (tx, _) = broadcast::channel::<Event>(100);
+
+// Each subscriber gets ALL messages
+let mut rx1 = tx.subscribe();
+let mut rx2 = tx.subscribe();
+
+tokio::spawn(async move {
+    while let Ok(event) = rx1.recv().await {
+        handle_in_logger(event);
+    }
+});
+
+tokio::spawn(async move {
+    while let Ok(event) = rx2.recv().await {
+        handle_in_metrics(event);
+    }
+});
+
+// Both subscribers receive this
+tx.send(Event::UserLogin { user_id: 42 })?;
+```
+
+## Broadcast Semantics
+
+```rust
+use tokio::sync::broadcast;
+
+let (tx, mut rx1) = broadcast::channel::<i32>(16);
+let mut rx2 = tx.subscribe();
+
+tx.send(1)?;
+tx.send(2)?;
+
+// Both receive all messages
+assert_eq!(rx1.recv().await?, 1);
+assert_eq!(rx1.recv().await?, 2);
+assert_eq!(rx2.recv().await?, 1);
+assert_eq!(rx2.recv().await?, 2);
+```
+
+## Handling Lagging Receivers
+
+```rust
+use tokio::sync::broadcast::{self, error::RecvError};
+
+let (tx, mut rx) = broadcast::channel::<Event>(16);
+
+loop {
+    match rx.recv().await {
+        Ok(event) => {
+            process(event);
+        }
+        Err(RecvError::Lagged(count)) => {
+            // Receiver couldn't keep up, missed `count` messages
+            log::warn!("Missed {} events", count);
+            // Continue receiving new messages
+        }
+        Err(RecvError::Closed) => {
+            break;  // All senders dropped
+        }
+    }
+}
+```
+
+## Event Bus Pattern
+
+```rust
+use tokio::sync::broadcast;
+
+#[derive(Clone, Debug)]
+enum AppEvent {
+    UserLoggedIn { user_id: u64 },
+    OrderCreated { order_id: u64 },
+    SystemShutdown,
+}
+
+struct EventBus {
+    tx: broadcast::Sender<AppEvent>,
+}
+
+impl EventBus {
+    fn new() -> Self {
+        let (tx, _) = broadcast::channel(1000);
+        EventBus { tx }
+    }
+    
+    fn publish(&self, event: AppEvent) {
+        // Ignore error if no subscribers
+        let _ = self.tx.send(event);
+    }
+    
+    fn subscribe(&self) -> broadcast::Receiver<AppEvent> {
+        self.tx.subscribe()
+    }
+}
+
+// Usage
+let bus = EventBus::new();
+
+// Logger subscribes
+let mut log_rx = bus.subscribe();
+tokio::spawn(async move {
+    while let Ok(event) = log_rx.recv().await {
+        log::info!("Event: {:?}", event);
+    }
+});
+
+// Metrics subscribes
+let mut metrics_rx = bus.subscribe();
+tokio::spawn(async move {
+    while let Ok(event) = metrics_rx.recv().await {
+        record_metric(&event);
+    }
+});
+
+// Publish events
+bus.publish(AppEvent::UserLoggedIn { user_id: 42 });
+```
+
+## Broadcast vs Watch
+
+```rust
+// broadcast: subscribers get ALL messages
+// Good for: events, logs, notifications
+let (tx, _) = broadcast::channel::<Event>(100);
+
+// watch: subscribers get LATEST value only
+// Good for: config changes, state updates
+let (tx, _) = watch::channel(initial_state);
+
+// If subscriber is slow:
+// - broadcast: they receive old messages (or lag)
+// - watch: they skip to latest (no history)
+```
+
+## Clone Requirement
+
+```rust
+// broadcast requires Clone because message is cloned to each receiver
+use tokio::sync::broadcast;
+
+#[derive(Clone)]  // Required for broadcast
+struct Event {
+    data: String,
+}
+
+let (tx, _) = broadcast::channel::<Event>(100);
+
+// For non-Clone types, wrap in Arc
+use std::sync::Arc;
+
+let (tx, _) = broadcast::channel::<Arc<LargeNonClone>>(100);
+```
+
+## See Also
+
+- [async-mpsc-queue](./async-mpsc-queue.md) - Single-consumer channels
+- [async-watch-latest](./async-watch-latest.md) - Latest-value only
+- [async-bounded-channel](./async-bounded-channel.md) - Buffer sizing

package/template/agent/skills/rust-developer/references/rust-rules/async-cancellation-token.md

@@ -0,0 +1,203 @@
+# async-cancellation-token
+
+> Use `CancellationToken` for graceful shutdown and task cancellation
+
+## Why It Matters
+
+Dropping a `JoinHandle` doesn't cancel the task—it just detaches it. For graceful shutdown, you need explicit cancellation. `tokio_util::sync::CancellationToken` provides a cooperative cancellation mechanism that tasks can check and respond to, enabling clean resource cleanup.
+
+## Bad
+
+```rust
+// Dropping handle doesn't stop the task
+let handle = tokio::spawn(async {
+    loop {
+        do_work().await;
+    }
+});
+
+drop(handle);  // Task continues running in background!
+
+// Using bool flag - not async-aware
+let running = Arc::new(AtomicBool::new(true));
+
+tokio::spawn({
+    let running = running.clone();
+    async move {
+        while running.load(Ordering::Relaxed) {
+            do_work().await;  // Can't wake up if blocked here
+        }
+    }
+});
+
+running.store(false, Ordering::Relaxed);
+// Task won't stop until current do_work() completes
+```
+
+## Good
+
+```rust
+use tokio_util::sync::CancellationToken;
+
+let token = CancellationToken::new();
+
+let handle = tokio::spawn({
+    let token = token.clone();
+    async move {
+        loop {
+            tokio::select! {
+                _ = token.cancelled() => {
+                    println!("Shutting down gracefully");
+                    cleanup().await;
+                    break;
+                }
+                _ = do_work() => {
+                    // Work completed
+                }
+            }
+        }
+    }
+});
+
+// Later: trigger cancellation
+token.cancel();
+handle.await?;  // Task completes cleanly
+```
+
+## CancellationToken API
+
+```rust
+use tokio_util::sync::CancellationToken;
+
+// Create token
+let token = CancellationToken::new();
+
+// Clone for sharing (cheap Arc-based clone)
+let token2 = token.clone();
+
+// Check if cancelled (non-blocking)
+if token.is_cancelled() {
+    return;
+}
+
+// Wait for cancellation (async)
+token.cancelled().await;
+
+// Trigger cancellation
+token.cancel();
+
+// Child tokens - cancelled when parent is cancelled
+let child = token.child_token();
+```
+
+## Hierarchical Cancellation
+
+```rust
+async fn run_server(shutdown: CancellationToken) {
+    let listener = TcpListener::bind("0.0.0.0:8080").await?;
+    
+    loop {
+        tokio::select! {
+            _ = shutdown.cancelled() => {
+                println!("Server shutting down");
+                break;
+            }
+            result = listener.accept() => {
+                let (socket, _) = result?;
+                // Each connection gets child token
+                let conn_token = shutdown.child_token();
+                tokio::spawn(handle_connection(socket, conn_token));
+            }
+        }
+    }
+    
+    // Child tokens auto-cancelled when we exit
+}
+
+async fn handle_connection(socket: TcpStream, token: CancellationToken) {
+    loop {
+        tokio::select! {
+            _ = token.cancelled() => {
+                // Connection cleanup
+                break;
+            }
+            data = socket.read() => {
+                // Handle data
+            }
+        }
+    }
+}
+```
+
+## Graceful Shutdown Pattern
+
+```rust
+use tokio::signal;
+
+async fn main() -> Result<()> {
+    let shutdown = CancellationToken::new();
+    
+    // Spawn signal handler
+    let shutdown_trigger = shutdown.clone();
+    tokio::spawn(async move {
+        signal::ctrl_c().await.expect("failed to listen for Ctrl+C");
+        println!("Received Ctrl+C, initiating shutdown...");
+        shutdown_trigger.cancel();
+    });
+    
+    // Run application with shutdown token
+    run_app(shutdown).await
+}
+
+async fn run_app(shutdown: CancellationToken) -> Result<()> {
+    let mut tasks = JoinSet::new();
+    
+    tasks.spawn(worker_task(shutdown.child_token()));
+    tasks.spawn(server_task(shutdown.child_token()));
+    
+    // Wait for shutdown or task completion
+    tokio::select! {
+        _ = shutdown.cancelled() => {
+            println!("Shutdown requested, waiting for tasks...");
+        }
+        Some(result) = tasks.join_next() => {
+            // A task completed/failed
+            result??;
+        }
+    }
+    
+    // Wait for remaining tasks with timeout
+    tokio::time::timeout(
+        Duration::from_secs(30),
+        async { while tasks.join_next().await.is_some() {} }
+    ).await.ok();
+    
+    Ok(())
+}
+```
+
+## DropGuard Pattern
+
+```rust
+use tokio_util::sync::CancellationToken;
+
+// Auto-cancel on drop
+let token = CancellationToken::new();
+let guard = token.clone().drop_guard();
+
+tokio::spawn({
+    let token = token.clone();
+    async move {
+        token.cancelled().await;
+        println!("Cancelled!");
+    }
+});
+
+drop(guard);  // Automatically calls token.cancel()
+```
+
+## See Also
+
+- [async-joinset-structured](./async-joinset-structured.md) - Managing multiple tasks
+- [async-select-racing](./async-select-racing.md) - select! for cancellation
+- [async-tokio-runtime](./async-tokio-runtime.md) - Runtime shutdown