Joseph Doherty
66 lines
2.4 KiB
Markdown
66 lines
2.4 KiB
Markdown
# 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`.
|