@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/rust/tonic/references/service-patterns.md

@@ -0,0 +1,213 @@
+# Tonic gRPC Service Patterns
+
+## Proto Definition
+
+```protobuf
+// proto/user.proto
+syntax = "proto3";
+package user;
+
+service UserService {
+    rpc GetUser (GetUserRequest) returns (User);
+    rpc ListUsers (ListUsersRequest) returns (stream User);
+    rpc CreateUsers (stream CreateUserRequest) returns (CreateUsersResponse);
+}
+
+message User {
+    int64 id = 1;
+    string name = 2;
+    string email = 3;
+}
+
+message GetUserRequest {
+    int64 id = 1;
+}
+
+message ListUsersRequest {
+    int32 page_size = 1;
+}
+
+message CreateUserRequest {
+    string name = 1;
+    string email = 2;
+}
+
+message CreateUsersResponse {
+    int32 created_count = 1;
+}
+```
+
+## Build Configuration
+
+```rust
+// build.rs
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    tonic_build::compile_protos("proto/user.proto")?;
+    Ok(())
+}
+```
+
+## Server Implementation
+
+```rust
+use tonic::{transport::Server, Request, Response, Status};
+use user::user_service_server::{UserService, UserServiceServer};
+use user::{User, GetUserRequest, ListUsersRequest, CreateUserRequest, CreateUsersResponse};
+use tokio_stream::wrappers::ReceiverStream;
+
+pub mod user {
+    tonic::include_proto!("user");
+}
+
+#[derive(Default)]
+pub struct MyUserService {}
+
+#[tonic::async_trait]
+impl UserService for MyUserService {
+    // Unary RPC
+    async fn get_user(
+        &self,
+        request: Request<GetUserRequest>,
+    ) -> Result<Response<User>, Status> {
+        let req = request.into_inner();
+        
+        // Simulated lookup
+        let user = User {
+            id: req.id,
+            name: "John".into(),
+            email: "john@example.com".into(),
+        };
+        
+        Ok(Response::new(user))
+    }
+
+    // Server streaming
+    type ListUsersStream = ReceiverStream<Result<User, Status>>;
+
+    async fn list_users(
+        &self,
+        request: Request<ListUsersRequest>,
+    ) -> Result<Response<Self::ListUsersStream>, Status> {
+        let (tx, rx) = tokio::sync::mpsc::channel(4);
+        
+        tokio::spawn(async move {
+            for i in 0..10 {
+                let user = User {
+                    id: i,
+                    name: format!("User {}", i),
+                    email: format!("user{}@example.com", i),
+                };
+                tx.send(Ok(user)).await.unwrap();
+            }
+        });
+
+        Ok(Response::new(ReceiverStream::new(rx)))
+    }
+
+    // Client streaming
+    async fn create_users(
+        &self,
+        request: Request<tonic::Streaming<CreateUserRequest>>,
+    ) -> Result<Response<CreateUsersResponse>, Status> {
+        let mut stream = request.into_inner();
+        let mut count = 0;
+
+        while let Some(req) = stream.message().await? {
+            println!("Creating user: {}", req.name);
+            count += 1;
+        }
+
+        Ok(Response::new(CreateUsersResponse { created_count: count }))
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let addr = "[::1]:50051".parse()?;
+    let service = MyUserService::default();
+
+    Server::builder()
+        .add_service(UserServiceServer::new(service))
+        .serve(addr)
+        .await?;
+
+    Ok(())
+}
+```
+
+## Client Implementation
+
+```rust
+use user::user_service_client::UserServiceClient;
+use user::GetUserRequest;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut client = UserServiceClient::connect("http://[::1]:50051").await?;
+
+    // Unary call
+    let request = tonic::Request::new(GetUserRequest { id: 1 });
+    let response = client.get_user(request).await?;
+    println!("User: {:?}", response.into_inner());
+
+    // Server streaming
+    let request = tonic::Request::new(ListUsersRequest { page_size: 10 });
+    let mut stream = client.list_users(request).await?.into_inner();
+    
+    while let Some(user) = stream.message().await? {
+        println!("Received: {:?}", user);
+    }
+
+    Ok(())
+}
+```
+
+## Interceptors
+
+```rust
+use tonic::{Request, Status};
+
+fn auth_interceptor(mut req: Request<()>) -> Result<Request<()>, Status> {
+    let token = req.metadata()
+        .get("authorization")
+        .and_then(|t| t.to_str().ok());
+
+    match token {
+        Some(t) if validate_token(t) => Ok(req),
+        _ => Err(Status::unauthenticated("Invalid token")),
+    }
+}
+
+// Apply to server
+Server::builder()
+    .add_service(UserServiceServer::with_interceptor(service, auth_interceptor))
+    .serve(addr)
+    .await?;
+
+// Apply to client
+let channel = Channel::from_static("http://[::1]:50051").connect().await?;
+let client = UserServiceClient::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 get_user(&self, request: Request<GetUserRequest>) -> Result<Response<User>, Status> {
+    let id = request.into_inner().id;
+    
+    if id <= 0 {
+        return Err(Status::invalid_argument("ID must be positive"));
+    }
+    
+    match self.db.find_user(id).await {
+        Ok(Some(user)) => Ok(Response::new(user)),
+        Ok(None) => Err(Status::not_found(format!("User {} not found", id))),
+        Err(e) => Err(Status::internal(format!("Database error: {}", e))),
+    }
+}
+```

package/rules/rust/tracing/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: Tracing Observability
+description: Structured logging and distributed tracing for Rust.
+metadata:
+  labels: [rust, tracing, logging, observability]
+  triggers:
+    files: ['**/main.rs', '**/lib.rs']
+    keywords: [tracing, info, debug, span, instrument, subscriber]
+---
+
+# Tracing Standards
+
+## Setup
+
+```rust
+use tracing::Level;
+use tracing_subscriber::{fmt, prelude::*, EnvFilter};
+
+fn main() {
+    tracing_subscriber::registry()
+        .with(fmt::layer())
+        .with(EnvFilter::from_default_env()
+            .add_directive(Level::INFO.into()))
+        .init();
+
+    tracing::info!("Application started");
+}
+```
+
+## Log Levels
+
+```rust
+use tracing::{trace, debug, info, warn, error};
+
+fn process() {
+    trace!("Very detailed info");
+    debug!("Debug information");
+    info!("Normal operation");
+    warn!("Warning condition");
+    error!("Error occurred");
+}
+```
+
+## Structured Fields
+
+```rust
+use tracing::{info, warn};
+
+fn handle_request(user_id: u64, path: &str) {
+    info!(user_id, path, "Processing request");
+
+    // Named fields
+    info!(
+        user.id = user_id,
+        request.path = path,
+        request.method = "GET",
+        "Request received"
+    );
+
+    // Debug formatting
+    let data = vec![1, 2, 3];
+    info!(?data, "Data received");
+
+    // Display formatting
+    let error = std::io::Error::new(std::io::ErrorKind::NotFound, "missing");
+    warn!(%error, "Operation failed");
+}
+```
+
+## Spans
+
+```rust
+use tracing::{span, Level, info_span};
+
+fn process_order(order_id: u64) {
+    let span = info_span!("process_order", order_id);
+    let _guard = span.enter();
+
+    // All logs within this scope include order_id
+    tracing::info!("Starting order processing");
+    validate_order();
+    charge_payment();
+    tracing::info!("Order completed");
+}
+
+// Async spans
+async fn fetch_data() {
+    let span = info_span!("fetch_data");
+    async {
+        // async work
+    }.instrument(span).await;
+}
+```
+
+## #[instrument] Macro
+
+```rust
+use tracing::instrument;
+
+#[instrument]
+fn calculate(x: i32, y: i32) -> i32 {
+    x + y
+}
+
+// Skip sensitive fields
+#[instrument(skip(password))]
+fn login(username: &str, password: &str) -> bool {
+    true
+}
+
+// Custom span name and level
+#[instrument(name = "db_query", level = "debug")]
+async fn query_database(sql: &str) -> Result<Vec<Row>, Error> {
+    // ...
+}
+
+// Add fields
+#[instrument(fields(request_id = %uuid::Uuid::new_v4()))]
+async fn handle_request() {
+    // ...
+}
+
+// Skip all, add specific
+#[instrument(skip_all, fields(user_id))]
+fn process_user(user_id: u64, sensitive_data: &str) {
+    // ...
+}
+```
+
+## Subscribers
+
+```rust
+use tracing_subscriber::{fmt, prelude::*, EnvFilter, Layer};
+
+fn setup_tracing() {
+    // JSON output for production
+    let json_layer = fmt::layer()
+        .json()
+        .with_target(true)
+        .with_current_span(true);
+
+    // Pretty output for development
+    let pretty_layer = fmt::layer()
+        .pretty()
+        .with_file(true)
+        .with_line_number(true);
+
+    // Filter by RUST_LOG env var
+    let filter = EnvFilter::try_from_default_env()
+        .unwrap_or_else(|_| EnvFilter::new("info"));
+
+    tracing_subscriber::registry()
+        .with(filter)
+        .with(if cfg!(debug_assertions) {
+            pretty_layer.boxed()
+        } else {
+            json_layer.boxed()
+        })
+        .init();
+}
+```
+
+## OpenTelemetry Integration
+
+```rust
+use opentelemetry::sdk::trace::TracerProvider;
+use tracing_opentelemetry::OpenTelemetryLayer;
+
+fn setup_otel() {
+    let provider = TracerProvider::builder()
+        .with_simple_exporter(opentelemetry_jaeger::new_agent_pipeline())
+        .build();
+
+    let tracer = provider.tracer("my-service");
+
+    tracing_subscriber::registry()
+        .with(tracing_subscriber::fmt::layer())
+        .with(OpenTelemetryLayer::new(tracer))
+        .init();
+}
+```
+
+## Error Handling
+
+```rust
+use tracing::{error, instrument};
+
+#[instrument(err)]
+fn fallible_operation() -> Result<(), Error> {
+    // Automatically logs error if Err is returned
+    Err(Error::new("something failed"))
+}
+
+// With error level
+#[instrument(err(level = Level::WARN))]
+fn maybe_warn() -> Result<(), Error> {
+    // ...
+}
+
+// Manual error logging
+fn handle_error() {
+    if let Err(e) = operation() {
+        error!(error = %e, "Operation failed");
+    }
+}
+```
+
+## Best Practices
+
+1. **Structured logging**: Use fields, not string interpolation
+2. **Span context**: Wrap related operations in spans
+3. **Skip sensitive**: Use `skip` for passwords, tokens
+4. **Env filter**: Configure via `RUST_LOG` env var
+5. **Async**: Use `.instrument(span)` for async code

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

@@ -0,0 +1,13 @@
+# Rust Tracing References
+
+## References
+
+- [**Instrumentation**](instrumentation.md) - Spans, events, subscribers
+
+## Quick Checks
+
+- [ ] Use #[instrument] for automatic spans
+- [ ] Structured fields for context
+- [ ] Appropriate log levels
+- [ ] Subscriber configuration
+- [ ] Span relationships for request tracing

package/rules/rust/tracing/references/instrumentation.md

@@ -0,0 +1,187 @@
+# Tracing Instrumentation
+
+## Basic Setup
+
+```rust
+use tracing::{info, warn, error, debug, trace, span, Level};
+use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
+
+fn main() {
+    // Simple setup
+    tracing_subscriber::fmt::init();
+
+    // Or with layers
+    tracing_subscriber::registry()
+        .with(tracing_subscriber::fmt::layer())
+        .with(tracing_subscriber::EnvFilter::from_default_env())
+        .init();
+
+    info!("Application started");
+}
+```
+
+## Events (Logs)
+
+```rust
+use tracing::{info, warn, error, debug, trace};
+
+fn process_request(request_id: &str, user_id: u64) {
+    // Simple message
+    info!("Processing request");
+
+    // With structured fields
+    info!(request_id, user_id, "Processing request");
+
+    // Named fields
+    info!(
+        request_id = %request_id,
+        user_id = user_id,
+        action = "process",
+        "Handling user request"
+    );
+
+    // Display vs Debug formatting
+    info!(user = %user, "Using Display");  // %
+    info!(user = ?user, "Using Debug");    // ?
+    
+    // Error with source
+    if let Err(e) = do_something() {
+        error!(error = ?e, "Operation failed");
+    }
+}
+```
+
+## Spans
+
+```rust
+use tracing::{span, Level, Instrument};
+
+async fn handle_request(request_id: String) {
+    // Create span
+    let span = span!(Level::INFO, "handle_request", %request_id);
+    let _guard = span.enter(); // Auto-exits when dropped
+
+    info!("Starting request processing");
+    
+    // Nested span
+    {
+        let db_span = span!(Level::DEBUG, "database_query");
+        let _guard = db_span.enter();
+        query_database().await;
+    }
+
+    info!("Request completed");
+}
+
+// Async with instrument
+async fn process() {
+    do_work()
+        .instrument(span!(Level::INFO, "do_work"))
+        .await;
+}
+```
+
+## Instrument Attribute
+
+```rust
+use tracing::instrument;
+
+#[instrument]
+fn simple_function(x: i32) -> i32 {
+    x * 2
+}
+
+#[instrument(
+    name = "process_user",
+    level = "info",
+    skip(password),  // Don't log sensitive data
+    fields(user_id = %user.id),
+    err,  // Log errors
+    ret,  // Log return value
+)]
+async fn process_user(user: &User, password: &str) -> Result<(), Error> {
+    info!("Processing user");
+    Ok(())
+}
+
+#[instrument(skip_all, fields(request_id = %request.id))]
+async fn handle(request: Request) -> Response {
+    // Implementation
+}
+```
+
+## Custom Subscriber
+
+```rust
+use tracing_subscriber::{
+    fmt,
+    layer::SubscriberExt,
+    util::SubscriberInitExt,
+    EnvFilter,
+};
+
+fn setup_tracing() {
+    let fmt_layer = fmt::layer()
+        .with_target(true)
+        .with_thread_ids(true)
+        .with_file(true)
+        .with_line_number(true)
+        .json();  // JSON output
+
+    let filter_layer = EnvFilter::try_from_default_env()
+        .unwrap_or_else(|_| EnvFilter::new("info"));
+
+    tracing_subscriber::registry()
+        .with(filter_layer)
+        .with(fmt_layer)
+        .init();
+}
+
+// Set level via RUST_LOG env var:
+// RUST_LOG=debug
+// RUST_LOG=my_crate=debug,other_crate=warn
+```
+
+## Integration with Axum
+
+```rust
+use axum::{Router, routing::get};
+use tower_http::trace::TraceLayer;
+use tracing::info_span;
+
+fn app() -> Router {
+    Router::new()
+        .route("/", get(handler))
+        .layer(
+            TraceLayer::new_for_http()
+                .make_span_with(|request: &Request<_>| {
+                    info_span!(
+                        "http_request",
+                        method = %request.method(),
+                        uri = %request.uri(),
+                        request_id = %uuid::Uuid::new_v4(),
+                    )
+                })
+        )
+}
+```
+
+## OpenTelemetry Integration
+
+```rust
+use tracing_subscriber::layer::SubscriberExt;
+use tracing_opentelemetry::OpenTelemetryLayer;
+use opentelemetry::sdk::trace::TracerProvider;
+
+fn setup_otel() {
+    let tracer = TracerProvider::builder()
+        .with_simple_exporter(opentelemetry_jaeger::new_agent_pipeline().build_simple()?)
+        .build()
+        .tracer("my-service");
+
+    tracing_subscriber::registry()
+        .with(tracing_subscriber::fmt::layer())
+        .with(OpenTelemetryLayer::new(tracer))
+        .init();
+}
+```