@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/rust/tokio-runtime/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: Tokio Runtime
+description: Async runtime for Rust with task scheduling, I/O, and timers.
+metadata:
+  labels: [rust, tokio, async, runtime]
+  triggers:
+    files: ['**/main.rs', '**/lib.rs']
+    keywords: [tokio, spawn, select, async, await]
+---
+
+# Tokio Runtime Standards
+
+## Runtime Setup
+
+```rust
+// Full runtime with all features
+#[tokio::main]
+async fn main() {
+    // Your async code
+}
+
+// Custom runtime configuration
+#[tokio::main(flavor = "multi_thread", worker_threads = 4)]
+async fn main() { }
+
+// Current-thread runtime (single-threaded)
+#[tokio::main(flavor = "current_thread")]
+async fn main() { }
+```
+
+## Task Spawning
+
+```rust
+use tokio::task;
+
+// Spawn async task
+let handle = tokio::spawn(async {
+    // Background work
+    expensive_computation().await
+});
+
+// Wait for result
+let result = handle.await?;
+
+// Spawn blocking task (CPU-bound work)
+let result = task::spawn_blocking(|| {
+    // Blocking/CPU-intensive code
+    compute_hash(data)
+}).await?;
+
+// Detached task (fire and forget)
+tokio::spawn(async {
+    log_event(event).await;
+});
+```
+
+## Concurrency Patterns
+
+```rust
+use tokio::{select, join, time};
+
+// Run multiple futures concurrently
+let (a, b, c) = join!(task_a(), task_b(), task_c());
+
+// Race futures, cancel losers
+select! {
+    result = fetch_primary() => handle_primary(result),
+    result = fetch_backup() => handle_backup(result),
+    _ = time::sleep(Duration::from_secs(5)) => timeout_error(),
+}
+
+// Timeout wrapper
+let result = time::timeout(
+    Duration::from_secs(30),
+    long_running_task()
+).await?;
+```
+
+## Synchronization
+
+```rust
+use tokio::sync::{Mutex, RwLock, mpsc, broadcast, oneshot};
+
+// Async mutex (allows holding across await)
+let data = Arc::new(Mutex::new(vec![]));
+{
+    let mut guard = data.lock().await;
+    guard.push(item);
+}
+
+// RwLock for read-heavy workloads
+let cache = Arc::new(RwLock::new(HashMap::new()));
+let value = cache.read().await.get(&key);
+
+// Channels
+let (tx, mut rx) = mpsc::channel(100);
+tx.send(message).await?;
+while let Some(msg) = rx.recv().await {
+    process(msg);
+}
+
+// Oneshot for single response
+let (tx, rx) = oneshot::channel();
+tokio::spawn(async move { tx.send(result) });
+let response = rx.await?;
+```
+
+## I/O Operations
+
+```rust
+use tokio::{fs, io::{AsyncReadExt, AsyncWriteExt}, net::TcpListener};
+
+// File I/O
+let content = fs::read_to_string("file.txt").await?;
+fs::write("output.txt", data).await?;
+
+// TCP server
+let listener = TcpListener::bind("127.0.0.1:8080").await?;
+loop {
+    let (socket, _) = listener.accept().await?;
+    tokio::spawn(handle_connection(socket));
+}
+
+// Buffered I/O
+use tokio::io::{BufReader, BufWriter};
+let reader = BufReader::new(file);
+let mut lines = reader.lines();
+while let Some(line) = lines.next_line().await? {
+    process(line);
+}
+```
+
+## Graceful Shutdown
+
+```rust
+use tokio::signal;
+
+async fn shutdown_signal() {
+    let ctrl_c = async {
+        signal::ctrl_c().await.expect("Failed to install Ctrl+C handler");
+    };
+
+    #[cfg(unix)]
+    let terminate = async {
+        signal::unix::signal(signal::unix::SignalKind::terminate())
+            .expect("Failed to install SIGTERM handler")
+            .recv()
+            .await;
+    };
+
+    #[cfg(not(unix))]
+    let terminate = std::future::pending::<()>();
+
+    tokio::select! {
+        _ = ctrl_c => {},
+        _ = terminate => {},
+    }
+}
+```
+
+## Best Practices
+
+1. **Never block**: Use `spawn_blocking` for CPU-bound or blocking I/O
+2. **Channel sizing**: Size mpsc channels appropriately to avoid backpressure
+3. **Error propagation**: Use `JoinHandle::await?` to propagate panics
+4. **Timeouts**: Always add timeouts to network operations
+5. **Tracing**: Use `tokio-console` for debugging async issues

package/rules/rust/tokio-runtime/references/REFERENCE.md

@@ -0,0 +1,14 @@
+# Tokio Runtime References
+
+## References
+
+- [**Async Patterns**](async-patterns.md) - Spawning, joining, timeouts, select
+- [**Synchronization**](synchronization.md) - Mutex, RwLock, channels, semaphores
+
+## Quick Checks
+
+- [ ] Use #[tokio::main] for async entry point
+- [ ] Spawn tasks for concurrent work
+- [ ] Use tokio::select! for racing futures
+- [ ] Prefer tokio::sync over std::sync in async code
+- [ ] Graceful shutdown with signal handling

package/rules/rust/tokio-runtime/references/async-patterns.md

@@ -0,0 +1,137 @@
+# Tokio Async Patterns
+
+## Task Spawning
+
+```rust
+use tokio::task;
+
+// Spawn background task
+let handle = tokio::spawn(async {
+    expensive_computation().await
+});
+
+// Wait for result
+let result = handle.await?;
+
+// Spawn blocking (for CPU-bound or sync code)
+let result = task::spawn_blocking(|| {
+    std::thread::sleep(Duration::from_secs(1));
+    "done"
+}).await?;
+```
+
+## Concurrent Execution
+
+```rust
+use tokio::join;
+use futures::future::join_all;
+
+// Run multiple futures concurrently
+let (user, orders, prefs) = tokio::join!(
+    fetch_user(id),
+    fetch_orders(id),
+    fetch_preferences(id),
+);
+
+// Run collection of futures
+let futures = ids.iter().map(|id| fetch_user(*id));
+let users: Vec<User> = join_all(futures).await;
+
+// Try join - fail fast on first error
+let (user, orders) = tokio::try_join!(
+    fetch_user(id),
+    fetch_orders(id),
+)?;
+```
+
+## Select and Racing
+
+```rust
+use tokio::{select, time::timeout};
+
+// Race multiple futures
+select! {
+    result = fetch_from_primary() => {
+        println!("Primary: {:?}", result);
+    }
+    result = fetch_from_backup() => {
+        println!("Backup: {:?}", result);
+    }
+}
+
+// Timeout
+match timeout(Duration::from_secs(5), long_operation()).await {
+    Ok(result) => println!("Completed: {:?}", result),
+    Err(_) => println!("Timed out"),
+}
+
+// Select with cancellation
+let mut interval = tokio::time::interval(Duration::from_secs(1));
+loop {
+    select! {
+        _ = interval.tick() => {
+            println!("tick");
+        }
+        _ = shutdown_signal() => {
+            println!("shutting down");
+            break;
+        }
+    }
+}
+```
+
+## Channels
+
+```rust
+use tokio::sync::{mpsc, oneshot, broadcast};
+
+// MPSC - multiple producers, single consumer
+let (tx, mut rx) = mpsc::channel(100);
+
+tokio::spawn(async move {
+    tx.send("hello").await.unwrap();
+});
+
+while let Some(msg) = rx.recv().await {
+    println!("Got: {}", msg);
+}
+
+// Oneshot - single value
+let (tx, rx) = oneshot::channel();
+tx.send("value").unwrap();
+let value = rx.await?;
+
+// Broadcast - multiple consumers
+let (tx, _) = broadcast::channel(16);
+let mut rx1 = tx.subscribe();
+let mut rx2 = tx.subscribe();
+tx.send("broadcast")?;
+```
+
+## Graceful Shutdown
+
+```rust
+use tokio::signal;
+
+async fn shutdown_signal() {
+    let ctrl_c = async {
+        signal::ctrl_c().await.expect("failed to listen for ctrl+c");
+    };
+
+    #[cfg(unix)]
+    let terminate = async {
+        signal::unix::signal(signal::unix::SignalKind::terminate())
+            .expect("failed to listen for terminate")
+            .recv()
+            .await;
+    };
+
+    #[cfg(not(unix))]
+    let terminate = std::future::pending::<()>();
+
+    tokio::select! {
+        _ = ctrl_c => {},
+        _ = terminate => {},
+    }
+}
+```

package/rules/rust/tokio-runtime/references/synchronization.md

@@ -0,0 +1,152 @@
+# Tokio Synchronization
+
+## Mutex
+
+```rust
+use tokio::sync::Mutex;
+use std::sync::Arc;
+
+async fn shared_state() {
+    let counter = Arc::new(Mutex::new(0));
+    
+    let mut handles = vec![];
+    
+    for _ in 0..10 {
+        let counter = Arc::clone(&counter);
+        let handle = tokio::spawn(async move {
+            let mut lock = counter.lock().await;
+            *lock += 1;
+        });
+        handles.push(handle);
+    }
+    
+    for handle in handles {
+        handle.await.unwrap();
+    }
+    
+    println!("Counter: {}", *counter.lock().await);
+}
+```
+
+## RwLock
+
+```rust
+use tokio::sync::RwLock;
+use std::sync::Arc;
+
+struct Cache {
+    data: Arc<RwLock<HashMap<String, String>>>,
+}
+
+impl Cache {
+    async fn get(&self, key: &str) -> Option<String> {
+        let read_lock = self.data.read().await;
+        read_lock.get(key).cloned()
+    }
+    
+    async fn set(&self, key: String, value: String) {
+        let mut write_lock = self.data.write().await;
+        write_lock.insert(key, value);
+    }
+}
+```
+
+## Semaphore
+
+```rust
+use tokio::sync::Semaphore;
+use std::sync::Arc;
+
+async fn limited_concurrency() {
+    let semaphore = Arc::new(Semaphore::new(3)); // Max 3 concurrent
+    
+    let mut handles = vec![];
+    
+    for i in 0..10 {
+        let permit = semaphore.clone().acquire_owned().await.unwrap();
+        let handle = tokio::spawn(async move {
+            println!("Task {} started", i);
+            tokio::time::sleep(Duration::from_secs(1)).await;
+            println!("Task {} done", i);
+            drop(permit); // Release when done
+        });
+        handles.push(handle);
+    }
+    
+    for handle in handles {
+        handle.await.unwrap();
+    }
+}
+```
+
+## Notify
+
+```rust
+use tokio::sync::Notify;
+use std::sync::Arc;
+
+async fn wait_for_signal() {
+    let notify = Arc::new(Notify::new());
+    
+    let notify_clone = notify.clone();
+    tokio::spawn(async move {
+        tokio::time::sleep(Duration::from_secs(1)).await;
+        notify_clone.notify_one(); // Wake one waiter
+    });
+    
+    notify.notified().await; // Wait for notification
+    println!("Received signal!");
+}
+```
+
+## Watch Channel
+
+```rust
+use tokio::sync::watch;
+
+async fn config_updates() {
+    let (tx, mut rx) = watch::channel(Config::default());
+    
+    // Watcher task
+    tokio::spawn(async move {
+        while rx.changed().await.is_ok() {
+            let config = rx.borrow();
+            println!("Config updated: {:?}", *config);
+        }
+    });
+    
+    // Update config
+    tx.send(Config { debug: true }).unwrap();
+}
+```
+
+## Barrier
+
+```rust
+use tokio::sync::Barrier;
+use std::sync::Arc;
+
+async fn sync_tasks() {
+    let barrier = Arc::new(Barrier::new(5));
+    
+    let mut handles = vec![];
+    
+    for i in 0..5 {
+        let barrier = barrier.clone();
+        let handle = tokio::spawn(async move {
+            println!("Task {} preparing", i);
+            tokio::time::sleep(Duration::from_millis(i as u64 * 100)).await;
+            
+            // Wait for all tasks
+            barrier.wait().await;
+            
+            println!("Task {} proceeding", i);
+        });
+        handles.push(handle);
+    }
+    
+    for handle in handles {
+        handle.await.unwrap();
+    }
+}
+```

package/rules/rust/tonic/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: Tonic gRPC
+description: gRPC framework for Rust built on Tokio and Tower.
+metadata:
+  labels: [rust, tonic, grpc, protobuf, rpc]
+  triggers:
+    files: ['**/*.proto', 'build.rs']
+    keywords: [tonic, prost, Request, Response, Server, Channel]
+---
+
+# Tonic gRPC Standards
+
+## Proto Definition
+
+```protobuf
+// proto/hello.proto
+syntax = "proto3";
+package hello;
+
+service Greeter {
+    rpc SayHello (HelloRequest) returns (HelloReply);
+    rpc SayHelloStream (HelloRequest) returns (stream HelloReply);
+}
+
+message HelloRequest {
+    string name = 1;
+}
+
+message HelloReply {
+    string message = 1;
+}
+```
+
+## Build Configuration
+
+```rust
+// build.rs
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    tonic_build::compile_protos("proto/hello.proto")?;
+    Ok(())
+}
+```
+
+```toml
+# Cargo.toml
+[dependencies]
+tonic = "0.10"
+prost = "0.12"
+tokio = { version = "1", features = ["full"] }
+
+[build-dependencies]
+tonic-build = "0.10"
+```
+
+## Server Implementation
+
+```rust
+use tonic::{transport::Server, Request, Response, Status};
+use hello::greeter_server::{Greeter, GreeterServer};
+use hello::{HelloReply, HelloRequest};
+
+pub mod hello {
+    tonic::include_proto!("hello");
+}
+
+#[derive(Default)]
+pub struct MyGreeter {}
+
+#[tonic::async_trait]
+impl Greeter for MyGreeter {
+    async fn say_hello(
+        &self,
+        request: Request<HelloRequest>,
+    ) -> Result<Response<HelloReply>, Status> {
+        let name = request.into_inner().name;
+        let reply = HelloReply {
+            message: format!("Hello, {}!", name),
+        };
+        Ok(Response::new(reply))
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let addr = "[::1]:50051".parse()?;
+    let greeter = MyGreeter::default();
+
+    Server::builder()
+        .add_service(GreeterServer::new(greeter))
+        .serve(addr)
+        .await?;
+
+    Ok(())
+}
+```
+
+## Client
+
+```rust
+use hello::greeter_client::GreeterClient;
+use hello::HelloRequest;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut client = GreeterClient::connect("http://[::1]:50051").await?;
+
+    let request = tonic::Request::new(HelloRequest {
+        name: "World".into(),
+    });
+
+    let response = client.say_hello(request).await?;
+    println!("Response: {:?}", response);
+
+    Ok(())
+}
+```
+
+## Streaming
+
+```rust
+use tokio_stream::wrappers::ReceiverStream;
+use futures_util::StreamExt;
+
+#[tonic::async_trait]
+impl Greeter for MyGreeter {
+    // Server streaming
+    type SayHelloStreamStream = ReceiverStream<Result<HelloReply, Status>>;
+
+    async fn say_hello_stream(
+        &self,
+        request: Request<HelloRequest>,
+    ) -> Result<Response<Self::SayHelloStreamStream>, Status> {
+        let (tx, rx) = tokio::sync::mpsc::channel(4);
+        let name = request.into_inner().name;
+
+        tokio::spawn(async move {
+            for i in 0..5 {
+                tx.send(Ok(HelloReply {
+                    message: format!("Hello #{}, {}!", i, name),
+                })).await.unwrap();
+                tokio::time::sleep(Duration::from_secs(1)).await;
+            }
+        });
+
+        Ok(Response::new(ReceiverStream::new(rx)))
+    }
+}
+
+// Client receiving stream
+let mut stream = client.say_hello_stream(request).await?.into_inner();
+while let Some(reply) = stream.next().await {
+    println!("Reply: {:?}", reply?);
+}
+```
+
+## Interceptors
+
+```rust
+use tonic::{Request, Status};
+
+fn auth_interceptor(req: Request<()>) -> Result<Request<()>, Status> {
+    let token = req.metadata()
+        .get("authorization")
+        .ok_or_else(|| Status::unauthenticated("No token"))?
+        .to_str()
+        .map_err(|_| Status::unauthenticated("Invalid token"))?;
+
+    if !validate_token(token) {
+        return Err(Status::unauthenticated("Invalid token"));
+    }
+
+    Ok(req)
+}
+
+// Apply interceptor
+let greeter = GreeterServer::with_interceptor(MyGreeter::default(), auth_interceptor);
+
+// Client with interceptor
+let channel = Channel::from_static("http://[::1]:50051").connect().await?;
+let client = GreeterClient::with_interceptor(channel, |mut req: Request<()>| {
+    req.metadata_mut().insert("authorization", "Bearer token".parse().unwrap());
+    Ok(req)
+});
+```
+
+## Error Handling
+
+```rust
+use tonic::Status;
+
+async fn my_method(&self, request: Request<Req>) -> Result<Response<Resp>, Status> {
+    let data = fetch_data()
+        .await
+        .map_err(|e| Status::internal(format!("DB error: {}", e)))?;
+
+    if data.is_empty() {
+        return Err(Status::not_found("Resource not found"));
+    }
+
+    // Status codes: ok, cancelled, unknown, invalid_argument,
+    // deadline_exceeded, not_found, already_exists, permission_denied,
+    // resource_exhausted, failed_precondition, aborted, out_of_range,
+    // unimplemented, internal, unavailable, data_loss, unauthenticated
+
+    Ok(Response::new(resp))
+}
+```
+
+## TLS
+
+```rust
+use tonic::transport::{Certificate, Identity, ServerTlsConfig};
+
+let cert = std::fs::read_to_string("server.crt")?;
+let key = std::fs::read_to_string("server.key")?;
+let identity = Identity::from_pem(cert, key);
+
+Server::builder()
+    .tls_config(ServerTlsConfig::new().identity(identity))?
+    .add_service(service)
+    .serve(addr)
+    .await?;
+```
+
+## Best Practices
+
+1. **Proto first**: Design API in proto files
+2. **Error codes**: Use appropriate Status codes
+3. **Streaming**: Use for large data or real-time
+4. **Interceptors**: Auth, logging, metrics
+5. **Deadlines**: Set timeouts on client calls

package/rules/rust/tonic/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Tonic gRPC References
+
+## References
+
+- [**Service Patterns**](service-patterns.md) - Proto, server, client implementation
+
+## Quick Checks
+
+- [ ] Use tonic-build for code generation
+- [ ] Implement generated service traits
+- [ ] Streaming support (server, client, bidirectional)
+- [ ] Interceptors for middleware
+- [ ] Proper error handling with tonic::Status