agy-superpowers 5.1.4 → 5.1.5

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

package/template/agent/skills/rust-developer/references/rust-rules/async-clone-before-await.md

@@ -0,0 +1,171 @@
+# async-clone-before-await
+
+> Clone Arc/Rc data before await points to avoid holding references across suspension
+
+## Why It Matters
+
+References held across `.await` points extend the future's lifetime and can cause borrow checker issues or prevent `Send` bounds. Cloning `Arc`/`Rc` before the await ensures the future only holds owned data, making it `Send` and avoiding lifetime complications.
+
+## Bad
+
+```rust
+use std::sync::Arc;
+
+async fn process(data: Arc<Data>) {
+    // Borrow extends across await - future is not Send
+    let slice = &data.items[..];  // Borrow of Arc contents
+    
+    expensive_async_operation().await;  // Await with active borrow
+    
+    use_slice(slice);  // Still using the borrow
+}
+
+// Error: future cannot be sent between threads safely
+// because `&[Item]` cannot be sent between threads safely
+tokio::spawn(process(data));
+```
+
+## Good
+
+```rust
+use std::sync::Arc;
+
+async fn process(data: Arc<Data>) {
+    // Clone what you need before await
+    let items = data.items.clone();  // Owned Vec
+    
+    expensive_async_operation().await;
+    
+    use_items(&items);  // Using owned data
+}
+
+// Or clone the Arc itself
+async fn share_data(data: Arc<Data>) {
+    let data = data.clone();  // Another Arc handle
+    
+    some_async_work().await;
+    
+    process(&data);  // Safe - we own the Arc
+}
+```
+
+## The Send Problem
+
+```rust
+// Futures must be Send to spawn on multi-threaded runtime
+async fn not_send() {
+    let rc = Rc::new(42);  // Rc is !Send
+    
+    tokio::time::sleep(Duration::from_secs(1)).await;
+    
+    println!("{}", rc);  // rc held across await
+}
+
+tokio::spawn(not_send());  // ERROR: future is not Send
+
+// Fix: use Arc or don't hold across await
+async fn is_send() {
+    let arc = Arc::new(42);  // Arc is Send
+    
+    tokio::time::sleep(Duration::from_secs(1)).await;
+    
+    println!("{}", arc);
+}
+
+tokio::spawn(is_send());  // OK
+```
+
+## Minimizing Clones
+
+```rust
+// Bad: clone everything eagerly
+async fn wasteful(data: Arc<LargeData>) {
+    let data = (*data).clone();  // Clones entire LargeData
+    async_work().await;
+    use_one_field(&data.small_field);
+}
+
+// Good: clone only what you need
+async fn efficient(data: Arc<LargeData>) {
+    let small = data.small_field.clone();  // Clone only needed field
+    async_work().await;
+    use_one_field(&small);
+}
+
+// Good: if you need the whole thing, keep the Arc
+async fn arc_efficient(data: Arc<LargeData>) {
+    let data = data.clone();  // Cheap Arc clone
+    async_work().await;
+    use_data(&data);  // Access through Arc
+}
+```
+
+## Spawn Pattern
+
+```rust
+// Common pattern: clone for spawned task
+let shared = Arc::new(SharedState::new());
+
+for i in 0..10 {
+    let shared = shared.clone();  // Clone before moving into spawn
+    tokio::spawn(async move {
+        // Task owns its Arc clone
+        shared.do_something(i).await;
+    });
+}
+```
+
+## Scope-Based Approach
+
+```rust
+// Limit borrow scope to before await
+async fn scoped(data: Arc<Data>) {
+    // Scope 1: borrow, compute, drop borrow
+    let computed = {
+        let slice = &data.items[..];  // Borrow
+        compute_something(slice)       // Use
+    };  // Borrow ends here
+    
+    // Now safe to await
+    expensive_async_operation().await;
+    
+    use_computed(computed);
+}
+```
+
+## MutexGuard Across Await
+
+```rust
+use tokio::sync::Mutex;
+
+// BAD: holding guard across await
+async fn bad(mutex: Arc<Mutex<Data>>) {
+    let mut guard = mutex.lock().await;
+    guard.value += 1;
+    
+    slow_operation().await;  // Guard held during await!
+    
+    guard.value += 1;
+}
+
+// GOOD: release before await
+async fn good(mutex: Arc<Mutex<Data>>) {
+    {
+        let mut guard = mutex.lock().await;
+        guard.value += 1;
+    }  // Guard released
+    
+    slow_operation().await;
+    
+    {
+        let mut guard = mutex.lock().await;
+        guard.value += 1;
+    }
+}
+```
+
+## See Also
+
+- [async-no-lock-await](./async-no-lock-await.md) - Lock guards across await
+- [own-arc-shared](./own-arc-shared.md) - Arc usage patterns
+- [async-spawn-blocking](./async-spawn-blocking.md) - Blocking in async

package/template/agent/skills/rust-developer/references/rust-rules/async-join-parallel.md

@@ -0,0 +1,158 @@
+# async-join-parallel
+
+> Use `join!` or `try_join!` for concurrent independent futures
+
+## Why It Matters
+
+Awaiting futures sequentially takes the sum of their durations. `join!` runs futures concurrently, taking only as long as the slowest one. For independent operations like multiple API calls or parallel file reads, this can dramatically reduce latency.
+
+## Bad
+
+```rust
+async fn fetch_data() -> (User, Posts, Comments) {
+    // Sequential: 300ms total (100 + 100 + 100)
+    let user = fetch_user().await;        // 100ms
+    let posts = fetch_posts().await;      // 100ms  
+    let comments = fetch_comments().await; // 100ms
+    
+    (user, posts, comments)
+}
+
+async fn read_configs() -> Result<(Config, Settings)> {
+    // Sequential: 20ms + 20ms = 40ms
+    let config = fs::read_to_string("config.toml").await?;
+    let settings = fs::read_to_string("settings.json").await?;
+    
+    Ok((parse_config(&config)?, parse_settings(&settings)?))
+}
+```
+
+## Good
+
+```rust
+use tokio::join;
+
+async fn fetch_data() -> (User, Posts, Comments) {
+    // Concurrent: ~100ms total (max of all three)
+    let (user, posts, comments) = join!(
+        fetch_user(),
+        fetch_posts(),
+        fetch_comments(),
+    );
+    
+    (user, posts, comments)
+}
+
+use tokio::try_join;
+
+async fn read_configs() -> Result<(Config, Settings)> {
+    // Concurrent: ~20ms total
+    let (config_str, settings_str) = try_join!(
+        fs::read_to_string("config.toml"),
+        fs::read_to_string("settings.json"),
+    )?;
+    
+    Ok((parse_config(&config_str)?, parse_settings(&settings_str)?))
+}
+```
+
+## join! vs try_join!
+
+```rust
+// join! - all futures run to completion, returns tuple
+let (a, b, c) = join!(future_a, future_b, future_c);
+
+// try_join! - short-circuits on first error
+let (a, b, c) = try_join!(fallible_a, fallible_b, fallible_c)?;
+// If fallible_b fails, returns Err immediately
+// Other futures may still be running (cancellation is async)
+```
+
+## futures::join_all for Dynamic Collections
+
+```rust
+use futures::future::join_all;
+
+async fn fetch_all_users(ids: &[u64]) -> Vec<User> {
+    let futures: Vec<_> = ids.iter()
+        .map(|id| fetch_user(*id))
+        .collect();
+    
+    join_all(futures).await
+}
+
+// With fallible futures
+use futures::future::try_join_all;
+
+async fn fetch_all_users(ids: &[u64]) -> Result<Vec<User>> {
+    let futures: Vec<_> = ids.iter()
+        .map(|id| fetch_user(*id))
+        .collect();
+    
+    try_join_all(futures).await
+}
+```
+
+## Limiting Concurrency
+
+```rust
+use futures::stream::{self, StreamExt};
+
+async fn fetch_with_limit(ids: &[u64]) -> Vec<Result<User>> {
+    stream::iter(ids)
+        .map(|id| fetch_user(*id))
+        .buffer_unordered(10)  // Max 10 concurrent requests
+        .collect()
+        .await
+}
+
+// Or with tokio::sync::Semaphore
+use tokio::sync::Semaphore;
+
+async fn fetch_with_semaphore(ids: &[u64]) -> Vec<User> {
+    let semaphore = Arc::new(Semaphore::new(10));
+    
+    let futures: Vec<_> = ids.iter().map(|id| {
+        let semaphore = semaphore.clone();
+        async move {
+            let _permit = semaphore.acquire().await.unwrap();
+            fetch_user(*id).await
+        }
+    }).collect();
+    
+    join_all(futures).await
+}
+```
+
+## When NOT to Use join!
+
+```rust
+// ❌ Dependent futures - must be sequential
+async fn create_and_populate() -> Result<()> {
+    let db = create_database().await?;   // Must complete first
+    populate_tables(&db).await?;          // Depends on db
+    Ok(())
+}
+
+// ❌ Short-circuiting logic
+async fn find_first() -> Option<Data> {
+    // Want to stop when one succeeds
+    // Use select! instead
+}
+
+// ❌ Shared mutable state
+async fn bad_shared_state() {
+    let counter = Arc::new(Mutex::new(0));
+    // This might work but can cause contention
+    join!(
+        increment(counter.clone()),
+        increment(counter.clone()),
+    );
+}
+```
+
+## See Also
+
+- [async-try-join](./async-try-join.md) - Error handling in concurrent futures
+- [async-select-racing](./async-select-racing.md) - Racing futures
+- [async-joinset-structured](./async-joinset-structured.md) - Dynamic task sets