# Rust Style Guide

This guide defines Rust conventions for the MXAccess Gateway Rust client crate,
CLI, and tests.

## Baseline

- Run `cargo fmt` on every changed Rust file.
- Run `cargo clippy` for non-trivial changes when the crate is available.
- Use the current stable Rust toolchain unless the project pins a version.
- Keep generated protobuf modules isolated from handwritten API wrappers.

## Source Documentation

- Maintain the existing documentation style in the file, crate, and surrounding
  component.
- Write comments that include business-specific or domain-specific context when
  that context is available from the code, surrounding docs, or naming.
- Use `///` documentation for public APIs when behavior, parity constraints, or
  security requirements are not obvious from the type signature.
- Avoid comments that restate syntax or control flow.

## Crate Structure

- Keep the reusable client library separate from the CLI binary.
- Use small modules for `client`, `session`, `options`, `auth`, `value`, and
  `error`.
- Re-export public types intentionally from `lib.rs`.
- Keep generated modules private unless raw protobuf access is part of the API.

## Naming

- Use `snake_case` for functions, variables, modules, and fields.
- Use `UpperCamelCase` for types, traits, and enum variants.
- Use `SCREAMING_SNAKE_CASE` for constants.
- Keep protocol names aligned with the protobuf contract where exactness
  matters.

## Async And Ownership

- Use `async` APIs with `tokio` for network operations.
- Prefer explicit `close` methods for sessions. Do not rely on `Drop` for async
  cleanup.
- Avoid unbounded channels and background tasks without a shutdown path.
- Use borrowed parameters such as `&str` where ownership is not needed.

## Errors

- Use `thiserror` for library error enums.
- Preserve `tonic::Status`, transport errors, command replies, HRESULTs, and
  MXAccess status details.
- Redact API keys and secured values in `Debug`, `Display`, and tracing output.
- Avoid string-only errors for public API failures.

## Security

- Use a secret wrapper for API keys when adding a dependency is acceptable.
- Do not derive `Debug` on types that contain unredacted secrets.
- Prefer explicit redacted display implementations for options and errors.

## Tests

- Use `#[tokio::test]` for async tests.
- Use fake `tonic` services or trait-backed clients for unit tests.
- Keep live gateway tests behind `MXGATEWAY_INTEGRATION=1`.