devstack 0.1.0

package/vendor/skills/skills/rust-async-patterns/SKILL.md

@@ -0,0 +1,519 @@
+---
+name: rust-async-patterns
+description: Master Rust async programming with Tokio, async traits, error handling, and concurrent patterns. Use when building async Rust applications, implementing concurrent systems, or debugging async code.
+---
+
+# Rust Async Patterns
+
+Production patterns for async Rust programming with Tokio runtime, including tasks, channels, streams, and error handling.
+
+## When to Use This Skill
+
+- Building async Rust applications
+- Implementing concurrent network services
+- Using Tokio for async I/O
+- Handling async errors properly
+- Debugging async code issues
+- Optimizing async performance
+
+## Core Concepts
+
+### 1. Async Execution Model
+
+```
+Future (lazy) → poll() → Ready(value) | Pending
+                ↑           ↓
+              Waker ← Runtime schedules
+```
+
+### 2. Key Abstractions
+
+| Concept    | Purpose                                  |
+| ---------- | ---------------------------------------- |
+| `Future`   | Lazy computation that may complete later |
+| `async fn` | Function returning impl Future           |
+| `await`    | Suspend until future completes           |
+| `Task`     | Spawned future running concurrently      |
+| `Runtime`  | Executor that polls futures              |
+
+## Quick Start
+
+```toml
+# Cargo.toml
+[dependencies]
+tokio = { version = "1", features = ["full"] }
+futures = "0.3"
+async-trait = "0.1"
+anyhow = "1.0"
+tracing = "0.1"
+tracing-subscriber = "0.3"
+```
+
+```rust
+use tokio::time::{sleep, Duration};
+use anyhow::Result;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Initialize tracing
+    tracing_subscriber::fmt::init();
+
+    // Async operations
+    let result = fetch_data("https://api.example.com").await?;
+    println!("Got: {}", result);
+
+    Ok(())
+}
+
+async fn fetch_data(url: &str) -> Result<String> {
+    // Simulated async operation
+    sleep(Duration::from_millis(100)).await;
+    Ok(format!("Data from {}", url))
+}
+```
+
+## Patterns
+
+### Pattern 1: Concurrent Task Execution
+
+```rust
+use tokio::task::JoinSet;
+use anyhow::Result;
+
+// Spawn multiple concurrent tasks
+async fn fetch_all_concurrent(urls: Vec<String>) -> Result<Vec<String>> {
+    let mut set = JoinSet::new();
+
+    for url in urls {
+        set.spawn(async move {
+            fetch_data(&url).await
+        });
+    }
+
+    let mut results = Vec::new();
+    while let Some(res) = set.join_next().await {
+        match res {
+            Ok(Ok(data)) => results.push(data),
+            Ok(Err(e)) => tracing::error!("Task failed: {}", e),
+            Err(e) => tracing::error!("Join error: {}", e),
+        }
+    }
+
+    Ok(results)
+}
+
+// With concurrency limit
+use futures::stream::{self, StreamExt};
+
+async fn fetch_with_limit(urls: Vec<String>, limit: usize) -> Vec<Result<String>> {
+    stream::iter(urls)
+        .map(|url| async move { fetch_data(&url).await })
+        .buffer_unordered(limit) // Max concurrent tasks
+        .collect()
+        .await
+}
+
+// Select first to complete
+use tokio::select;
+
+async fn race_requests(url1: &str, url2: &str) -> Result<String> {
+    select! {
+        result = fetch_data(url1) => result,
+        result = fetch_data(url2) => result,
+    }
+}
+```
+
+### Pattern 2: Channels for Communication
+
+```rust
+use tokio::sync::{mpsc, broadcast, oneshot, watch};
+
+// Multi-producer, single-consumer
+async fn mpsc_example() {
+    let (tx, mut rx) = mpsc::channel::<String>(100);
+
+    // Spawn producer
+    let tx2 = tx.clone();
+    tokio::spawn(async move {
+        tx2.send("Hello".to_string()).await.unwrap();
+    });
+
+    // Consume
+    while let Some(msg) = rx.recv().await {
+        println!("Got: {}", msg);
+    }
+}
+
+// Broadcast: multi-producer, multi-consumer
+async fn broadcast_example() {
+    let (tx, _) = broadcast::channel::<String>(100);
+
+    let mut rx1 = tx.subscribe();
+    let mut rx2 = tx.subscribe();
+
+    tx.send("Event".to_string()).unwrap();
+
+    // Both receivers get the message
+    let _ = rx1.recv().await;
+    let _ = rx2.recv().await;
+}
+
+// Oneshot: single value, single use
+async fn oneshot_example() -> String {
+    let (tx, rx) = oneshot::channel::<String>();
+
+    tokio::spawn(async move {
+        tx.send("Result".to_string()).unwrap();
+    });
+
+    rx.await.unwrap()
+}
+
+// Watch: single producer, multi-consumer, latest value
+async fn watch_example() {
+    let (tx, mut rx) = watch::channel("initial".to_string());
+
+    tokio::spawn(async move {
+        loop {
+            // Wait for changes
+            rx.changed().await.unwrap();
+            println!("New value: {}", *rx.borrow());
+        }
+    });
+
+    tx.send("updated".to_string()).unwrap();
+}
+```
+
+### Pattern 3: Async Error Handling
+
+```rust
+use anyhow::{Context, Result, bail};
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum ServiceError {
+    #[error("Network error: {0}")]
+    Network(#[from] reqwest::Error),
+
+    #[error("Database error: {0}")]
+    Database(#[from] sqlx::Error),
+
+    #[error("Not found: {0}")]
+    NotFound(String),
+
+    #[error("Timeout after {0:?}")]
+    Timeout(std::time::Duration),
+}
+
+// Using anyhow for application errors
+async fn process_request(id: &str) -> Result<Response> {
+    let data = fetch_data(id)
+        .await
+        .context("Failed to fetch data")?;
+
+    let parsed = parse_response(&data)
+        .context("Failed to parse response")?;
+
+    Ok(parsed)
+}
+
+// Using custom errors for library code
+async fn get_user(id: &str) -> Result<User, ServiceError> {
+    let result = db.query(id).await?;
+
+    match result {
+        Some(user) => Ok(user),
+        None => Err(ServiceError::NotFound(id.to_string())),
+    }
+}
+
+// Timeout wrapper
+use tokio::time::timeout;
+
+async fn with_timeout<T, F>(duration: Duration, future: F) -> Result<T, ServiceError>
+where
+    F: std::future::Future<Output = Result<T, ServiceError>>,
+{
+    timeout(duration, future)
+        .await
+        .map_err(|_| ServiceError::Timeout(duration))?
+}
+```
+
+### Pattern 4: Graceful Shutdown
+
+```rust
+use tokio::signal;
+use tokio::sync::broadcast;
+use tokio_util::sync::CancellationToken;
+
+async fn run_server() -> Result<()> {
+    // Method 1: CancellationToken
+    let token = CancellationToken::new();
+    let token_clone = token.clone();
+
+    // Spawn task that respects cancellation
+    tokio::spawn(async move {
+        loop {
+            tokio::select! {
+                _ = token_clone.cancelled() => {
+                    tracing::info!("Task shutting down");
+                    break;
+                }
+                _ = do_work() => {}
+            }
+        }
+    });
+
+    // Wait for shutdown signal
+    signal::ctrl_c().await?;
+    tracing::info!("Shutdown signal received");
+
+    // Cancel all tasks
+    token.cancel();
+
+    // Give tasks time to cleanup
+    tokio::time::sleep(Duration::from_secs(5)).await;
+
+    Ok(())
+}
+
+// Method 2: Broadcast channel for shutdown
+async fn run_with_broadcast() -> Result<()> {
+    let (shutdown_tx, _) = broadcast::channel::<()>(1);
+
+    let mut rx = shutdown_tx.subscribe();
+    tokio::spawn(async move {
+        tokio::select! {
+            _ = rx.recv() => {
+                tracing::info!("Received shutdown");
+            }
+            _ = async { loop { do_work().await } } => {}
+        }
+    });
+
+    signal::ctrl_c().await?;
+    let _ = shutdown_tx.send(());
+
+    Ok(())
+}
+```
+
+### Pattern 5: Async Traits
+
+```rust
+use async_trait::async_trait;
+
+#[async_trait]
+pub trait Repository {
+    async fn get(&self, id: &str) -> Result<Entity>;
+    async fn save(&self, entity: &Entity) -> Result<()>;
+    async fn delete(&self, id: &str) -> Result<()>;
+}
+
+pub struct PostgresRepository {
+    pool: sqlx::PgPool,
+}
+
+#[async_trait]
+impl Repository for PostgresRepository {
+    async fn get(&self, id: &str) -> Result<Entity> {
+        sqlx::query_as!(Entity, "SELECT * FROM entities WHERE id = $1", id)
+            .fetch_one(&self.pool)
+            .await
+            .map_err(Into::into)
+    }
+
+    async fn save(&self, entity: &Entity) -> Result<()> {
+        sqlx::query!(
+            "INSERT INTO entities (id, data) VALUES ($1, $2)
+             ON CONFLICT (id) DO UPDATE SET data = $2",
+            entity.id,
+            entity.data
+        )
+        .execute(&self.pool)
+        .await?;
+        Ok(())
+    }
+
+    async fn delete(&self, id: &str) -> Result<()> {
+        sqlx::query!("DELETE FROM entities WHERE id = $1", id)
+            .execute(&self.pool)
+            .await?;
+        Ok(())
+    }
+}
+
+// Trait object usage
+async fn process(repo: &dyn Repository, id: &str) -> Result<()> {
+    let entity = repo.get(id).await?;
+    // Process...
+    repo.save(&entity).await
+}
+```
+
+### Pattern 6: Streams and Async Iteration
+
+```rust
+use futures::stream::{self, Stream, StreamExt};
+use async_stream::stream;
+
+// Create stream from async iterator
+fn numbers_stream() -> impl Stream<Item = i32> {
+    stream! {
+        for i in 0..10 {
+            tokio::time::sleep(Duration::from_millis(100)).await;
+            yield i;
+        }
+    }
+}
+
+// Process stream
+async fn process_stream() {
+    let stream = numbers_stream();
+
+    // Map and filter
+    let processed: Vec<_> = stream
+        .filter(|n| futures::future::ready(*n % 2 == 0))
+        .map(|n| n * 2)
+        .collect()
+        .await;
+
+    println!("{:?}", processed);
+}
+
+// Chunked processing
+async fn process_in_chunks() {
+    let stream = numbers_stream();
+
+    let mut chunks = stream.chunks(3);
+
+    while let Some(chunk) = chunks.next().await {
+        println!("Processing chunk: {:?}", chunk);
+    }
+}
+
+// Merge multiple streams
+async fn merge_streams() {
+    let stream1 = numbers_stream();
+    let stream2 = numbers_stream();
+
+    let merged = stream::select(stream1, stream2);
+
+    merged
+        .for_each(|n| async move {
+            println!("Got: {}", n);
+        })
+        .await;
+}
+```
+
+### Pattern 7: Resource Management
+
+```rust
+use std::sync::Arc;
+use tokio::sync::{Mutex, RwLock, Semaphore};
+
+// Shared state with RwLock (prefer for read-heavy)
+struct Cache {
+    data: RwLock<HashMap<String, String>>,
+}
+
+impl Cache {
+    async fn get(&self, key: &str) -> Option<String> {
+        self.data.read().await.get(key).cloned()
+    }
+
+    async fn set(&self, key: String, value: String) {
+        self.data.write().await.insert(key, value);
+    }
+}
+
+// Connection pool with semaphore
+struct Pool {
+    semaphore: Semaphore,
+    connections: Mutex<Vec<Connection>>,
+}
+
+impl Pool {
+    fn new(size: usize) -> Self {
+        Self {
+            semaphore: Semaphore::new(size),
+            connections: Mutex::new((0..size).map(|_| Connection::new()).collect()),
+        }
+    }
+
+    async fn acquire(&self) -> PooledConnection<'_> {
+        let permit = self.semaphore.acquire().await.unwrap();
+        let conn = self.connections.lock().await.pop().unwrap();
+        PooledConnection { pool: self, conn: Some(conn), _permit: permit }
+    }
+}
+
+struct PooledConnection<'a> {
+    pool: &'a Pool,
+    conn: Option<Connection>,
+    _permit: tokio::sync::SemaphorePermit<'a>,
+}
+
+impl Drop for PooledConnection<'_> {
+    fn drop(&mut self) {
+        if let Some(conn) = self.conn.take() {
+            let pool = self.pool;
+            tokio::spawn(async move {
+                pool.connections.lock().await.push(conn);
+            });
+        }
+    }
+}
+```
+
+## Debugging Tips
+
+```rust
+// Enable tokio-console for runtime debugging
+// Cargo.toml: tokio = { features = ["tracing"] }
+// Run: RUSTFLAGS="--cfg tokio_unstable" cargo run
+// Then: tokio-console
+
+// Instrument async functions
+use tracing::instrument;
+
+#[instrument(skip(pool))]
+async fn fetch_user(pool: &PgPool, id: &str) -> Result<User> {
+    tracing::debug!("Fetching user");
+    // ...
+}
+
+// Track task spawning
+let span = tracing::info_span!("worker", id = %worker_id);
+tokio::spawn(async move {
+    // Enters span when polled
+}.instrument(span));
+```
+
+## Best Practices
+
+### Do's
+
+- **Use `tokio::select!`** - For racing futures
+- **Prefer channels** - Over shared state when possible
+- **Use `JoinSet`** - For managing multiple tasks
+- **Instrument with tracing** - For debugging async code
+- **Handle cancellation** - Check `CancellationToken`
+
+### Don'ts
+
+- **Don't block** - Never use `std::thread::sleep` in async
+- **Don't hold locks across awaits** - Causes deadlocks
+- **Don't spawn unboundedly** - Use semaphores for limits
+- **Don't ignore errors** - Propagate with `?` or log
+- **Don't forget Send bounds** - For spawned futures
+
+## Resources
+
+- [Tokio Tutorial](https://tokio.rs/tokio/tutorial)
+- [Async Book](https://rust-lang.github.io/async-book/)
+- [Tokio Console](https://github.com/tokio-rs/console)

package/vendor/skills/skills/rust-best-practices/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: rust-best-practices
+description: >
+  Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook. Use this skill when:
+  (1) writing new Rust code or functions,
+  (2) reviewing or refactoring existing Rust code,
+  (3) deciding between borrowing vs cloning or ownership patterns,
+  (4) implementing error handling with Result types,
+  (5) optimizing Rust code for performance,
+  (6) writing tests or documentation for Rust projects.
+license: MIT
+compatibility: Rust 1.70+, Cargo
+metadata:
+  author: apollographql
+  version: "1.1.0"
+allowed-tools: Bash(cargo:*) Bash(rustc:*) Bash(rustfmt:*) Bash(clippy:*) Read Write Edit Glob Grep
+---
+
+# Rust Best Practices
+
+Apply these guidelines when writing or reviewing Rust code. Based on Apollo GraphQL's [Rust Best Practices Handbook](https://github.com/apollographql/rust-best-practices).
+
+## Best Practices Reference
+
+Before reviewing, familiarize yourself with Apollo's Rust best practices. Read ALL relevant chapters in the same turn in parallel. Reference these files when providing feedback:
+
+- [Chapter 1 - Coding Styles and Idioms](references/chapter_01.md): Borrowing vs cloning, Copy trait, Option/Result handling, iterators, comments
+- [Chapter 2 - Clippy and Linting](references/chapter_02.md): Clippy configuration, important lints, workspace lint setup
+- [Chapter 3 - Performance Mindset](references/chapter_03.md): Profiling, avoiding redundant clones, stack vs heap, zero-cost abstractions
+- [Chapter 4 - Error Handling](references/chapter_04.md): Result vs panic, thiserror vs anyhow, error hierarchies
+- [Chapter 5 - Automated Testing](references/chapter_05.md): Test naming, one assertion per test, snapshot testing
+- [Chapter 6 - Generics and Dispatch](references/chapter_06.md): Static vs dynamic dispatch, trait objects
+- [Chapter 7 - Type State Pattern](references/chapter_07.md): Compile-time state safety, when to use it
+- [Chapter 8 - Comments vs Documentation](references/chapter_08.md): When to comment, doc comments, rustdoc
+- [Chapter 9 - Understanding Pointers](references/chapter_09.md): Thread safety, Send/Sync, pointer types
+
+## Quick Reference
+
+### Borrowing & Ownership
+
+- Prefer `&T` over `.clone()` unless ownership transfer is required
+- Use `&str` over `String`, `&[T]` over `Vec<T>` in function parameters
+- Small `Copy` types (≤24 bytes) can be passed by value
+- Use `Cow<'_, T>` when ownership is ambiguous
+
+### Error Handling
+
+- Return `Result<T, E>` for fallible operations; avoid `panic!` in production
+- Never use `unwrap()`/`expect()` outside tests
+- Use `thiserror` for library errors, `anyhow` for binaries only
+- Prefer `?` operator over match chains for error propagation
+
+### Performance
+
+- Always benchmark with `--release` flag
+- Run `cargo clippy -- -D clippy::perf` for performance hints
+- Avoid cloning in loops; use `.iter()` instead of `.into_iter()` for Copy types
+- Prefer iterators over manual loops; avoid intermediate `.collect()` calls
+
+### Linting
+
+Run regularly: `cargo clippy --all-targets --all-features --locked -- -D warnings`
+
+Key lints to watch:
+
+- `redundant_clone` - unnecessary cloning
+- `large_enum_variant` - oversized variants (consider boxing)
+- `needless_collect` - premature collection
+
+Use `#[expect(clippy::lint)]` over `#[allow(...)]` with justification comment.
+
+### Testing
+
+- Name tests descriptively: `process_should_return_error_when_input_empty()`
+- One assertion per test when possible
+- Use doc tests (`///`) for public API examples
+- Consider `cargo insta` for snapshot testing generated output
+
+### Generics & Dispatch
+
+- Prefer generics (static dispatch) for performance-critical code
+- Use `dyn Trait` only when heterogeneous collections are needed
+- Box at API boundaries, not internally
+
+### Type State Pattern
+
+Encode valid states in the type system to catch invalid operations at compile time:
+
+```rust
+struct Connection<State> { /* ... */ _state: PhantomData<State> }
+struct Disconnected;
+struct Connected;
+
+impl Connection<Connected> {
+    fn send(&self, data: &[u8]) { /* only connected can send */ }
+}
+```
+
+### Documentation
+
+- `//` comments explain _why_ (safety, workarounds, design rationale)
+- `///` doc comments explain _what_ and _how_ for public APIs
+- Every `TODO` needs a linked issue: `// TODO(#42): ...`
+- Enable `#![deny(missing_docs)]` for libraries