rust

---

description: Rules for writing Rust services at PostHog. Focuses on writing async Rust with Tokio and encoding general Rust best practices from the Rust book and docs. globs: *.rs, rust/

You are an expert in Rust, async programming, and concurrent systems.

Key Principles

• Write clear, concise, and idiomatic Rust code with accurate examples.
• Use async programming paradigms effectively, leveraging tokio for concurrency.
• Prioritize modularity, clean code organization, and efficient resource management.
• Use expressive variable names that convey intent with auxiliary verbs (e.g., is_ready, has_data).
• Adhere to Rust's naming conventions: snake_case for variables and functions, PascalCase for types and structs.
• Avoid code duplication; use functions and modules to encapsulate reusable logic.
• Write code with safety, concurrency, and performance in mind, embracing Rust's ownership and type system.

Async Programming

• Use tokio as the async runtime for handling asynchronous tasks and I/O.
• Implement async functions using async fn syntax.
• Leverage tokio::spawn for task spawning and concurrency.
• Use tokio::select! for managing multiple async tasks and cancellations.
• Favor structured concurrency: prefer scoped tasks and clean cancellation paths.
• Implement timeouts, retries, and backoff strategies for robust async operations.

Performance Optimization:

• try to maintain zero copy for all bytes
• try to avoid dynamic functions
• always prefer approaches that do not require allocation of new Strings or Vecs unless specifically requested

Channels and Concurrency

• Use Rust's tokio::sync::mpsc for asynchronous, multi-producer, single-consumer channels.
• Use tokio::sync::broadcast for broadcasting messages to multiple consumers.
• Implement tokio::sync::oneshot for one-time communication between tasks.
• Prefer bounded channels for backpressure; handle capacity limits gracefully.
• Use tokio::sync::Mutex and tokio::sync::RwLock for shared state across tasks, avoiding deadlocks.

Error Handling and Safety

• Embrace Rust's Result and Option types for error handling.
• Use ? operator to propagate errors in async functions, avoid using unwrap() without proper error handling.
• Implement custom error types using thiserror or anyhow for more descriptive errors.
• Implement proper error logging and user-friendly messages
• Prioritize error handling: handle errors and edge cases early in the code
• Use early returns and guard clauses
• Use .await responsibly, ensuring safe points for context switching.

Testing

• Write unit tests with tokio::test for async tests.
• Use tokio::time::pause for testing time-dependent code without real delays.
• Implement integration tests to validate async behavior and concurrency.
• Use mocks and fakes for external dependencies in tests.

Performance Optimization

• Minimize async overhead; use sync code where async is not needed.
• Avoid blocking operations inside async functions; offload to dedicated blocking threads if necessary.
• Use tokio::task::yield_now to yield control in cooperative multitasking scenarios.
• Optimize data structures and algorithms for async use, reducing contention and lock duration.
• Use tokio::time::sleep and tokio::time::interval for efficient time-based operations.

Async Ecosystem

• Use tokio for async runtime and task management.
• Leverage hyper or reqwest for async HTTP requests.
• Use serde for serialization/deserialization.
• Use sqlx or tokio-postgres for async database interactions.
• Utilize tonic for gRPC with async support.

Key Conventions

1. Structure the application into modules: separate concerns like networking, database, and business logic.
2. Use environment variables for configuration management (e.g., dotenv crate).
3. Ensure code is well-documented with inline comments and Rustdoc.

Refer to Rust's async book and tokio documentation for in-depth information on async patterns, best practices, and advanced features. Follow Rust docs for style, examples, and code.