mxaccessgw/docs/style-guides/RustStyleGuide.md

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.