Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

4.1 KB
Raw Blame
---
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.