mxaccessgw/clients/rust/RustClientDesign.md

Rust Client Detailed Design

Purpose

Provide an async Rust client crate for MXAccess Gateway, plus a test CLI and unit tests. The Rust client should use tonic and tokio.

Follow the Rust Style Guide for handwritten code and the Protobuf Style Guide for generated contract inputs.

Crate Layout

Actual layout — the mxgateway-client library crate is the workspace root, with the mxgw test CLI as a workspace member:

clients/rust/                 # `mxgateway-client` library crate (workspace root)
  Cargo.toml
  build.rs
  src/
    lib.rs
    client.rs
    session.rs
    galaxy.rs
    options.rs
    auth.rs
    value.rs
    version.rs
    error.rs
    generated.rs
  crates/
    mxgw-cli/                 # `mxgw` test CLI (workspace member)
      Cargo.toml
      src/main.rs
  tests/
    client_behavior.rs
    proto_fixtures.rs

Dependencies:

• tonic
• prost
• prost-types
• tokio
• tokio-stream
• thiserror
• clap
• serde
• serde_json

Library API

Suggested API:

pub struct GatewayClient { /* tonic channel + generated client */ }

pub struct ClientOptions {
    pub endpoint: String,
    pub api_key: String,
    pub plaintext: bool,
    pub ca_file: Option<PathBuf>,
    pub server_name_override: Option<String>,
    pub connect_timeout: Duration,
    pub call_timeout: Duration,
}

impl GatewayClient {
    pub async fn connect(options: ClientOptions) -> Result<Self, Error>;
    pub async fn open_session(&self, options: OpenSessionOptions) -> Result<Session, Error>;
    pub async fn invoke(&self, request: MxCommandRequest) -> Result<MxCommandReply, Error>;
}

Session:

pub struct Session {
    pub id: String,
}

impl Session {
    pub async fn register(&self, client_name: &str) -> Result<i32, Error>;
    pub async fn add_item(&self, server_handle: i32, item: &str) -> Result<i32, Error>;
    pub async fn add_item2(&self, server_handle: i32, item: &str, context: &str) -> Result<i32, Error>;
    pub async fn advise(&self, server_handle: i32, item_handle: i32) -> Result<(), Error>;
    pub async fn add_item_bulk(&self, server_handle: i32, tag_addresses: Vec<String>) -> Result<Vec<SubscribeResult>, Error>;
    pub async fn advise_item_bulk(&self, server_handle: i32, item_handles: Vec<i32>) -> Result<Vec<SubscribeResult>, Error>;
    pub async fn remove_item_bulk(&self, server_handle: i32, item_handles: Vec<i32>) -> Result<Vec<SubscribeResult>, Error>;
    pub async fn un_advise_item_bulk(&self, server_handle: i32, item_handles: Vec<i32>) -> Result<Vec<SubscribeResult>, Error>;
    pub async fn subscribe_bulk(&self, server_handle: i32, tag_addresses: Vec<String>) -> Result<Vec<SubscribeResult>, Error>;
    pub async fn unsubscribe_bulk(&self, server_handle: i32, item_handles: Vec<i32>) -> Result<Vec<SubscribeResult>, Error>;
    pub async fn write(&self, server_handle: i32, item_handle: i32, value: MxValue, user_id: i32) -> Result<(), Error>;
    pub async fn write_bulk(&self, server_handle: i32, entries: Vec<WriteBulkEntry>) -> Result<Vec<BulkWriteResult>, Error>;
    pub async fn write2_bulk(&self, server_handle: i32, entries: Vec<Write2BulkEntry>) -> Result<Vec<BulkWriteResult>, Error>;
    pub async fn write_secured_bulk(&self, server_handle: i32, entries: Vec<WriteSecuredBulkEntry>) -> Result<Vec<BulkWriteResult>, Error>;
    pub async fn write_secured2_bulk(&self, server_handle: i32, entries: Vec<WriteSecured2BulkEntry>) -> Result<Vec<BulkWriteResult>, Error>;
    pub async fn read_bulk<S: AsRef<str>>(&self, server_handle: i32, tag_addresses: &[S], timeout_ms: u32) -> Result<Vec<BulkReadResult>, Error>;
    pub async fn events(&self) -> Result<impl Stream<Item = Result<MxEvent, Error>>, Error>;
    pub async fn close(&self) -> Result<(), Error>;
}

The four bulk-write helpers (write_bulk, write2_bulk, write_secured_bulk, write_secured2_bulk) and read_bulk mirror the worker's bulk command shapes in mxaccess_gateway.proto and use the same correlation-id discipline as the unary helpers — next_correlation_id is part of the public SDK surface, re-exported at the crate root (mxgateway_client::next_correlation_id), so that consumers constructing raw MxCommandRequest/CloseSessionRequest payloads outside the Session helpers (notably the mxgw test CLI's ping and close-session subcommands) share the same id generation. The returned id is documented as an opaque token with three guaranteed properties (embeds the caller's label, unique within a process, carries no secret); its textual format is intentionally not part of the contract.

The per-entry fields that the matching MXAccess COM calls accept once per batch — user_id (WriteBulkEntry/Write2BulkEntry), timestamp_value (Write2BulkEntry/WriteSecured2BulkEntry), and current_user_id / verifier_user_id (WriteSecuredBulkEntry/WriteSecured2BulkEntry) — live on the entry structs themselves rather than as trailing positional arguments on the helper, matching the protobuf shapes in mxaccess_gateway.proto (WriteBulkCommand / Write2BulkCommand / WriteSecuredBulkCommand / WriteSecured2BulkCommand). read_bulk is generic over AsRef<str> so callers can pass &[String] or &[&str] without cloning at the call site.

Authentication

Use a tonic interceptor or request extension layer to add:

authorization: Bearer <api key>

Use SecretString or equivalent if a dependency is acceptable. Always redact API keys in Debug output.

TLS

Support:

• plaintext channel for local development,
• native or rustls TLS depending on project preference,
• custom CA file,
• domain override.

Streaming

Expose event streams as a Stream<Item = Result<MxEvent, Error>>. Dropping the stream should cancel the underlying gRPC stream.

Do not buffer unboundedly in the client. If a helper channel is used, make it bounded.

Error Handling

Use thiserror:

pub enum Error {
    InvalidEndpoint { endpoint: String, detail: String },
    InvalidArgument { name: String, detail: String },
    Transport(tonic::transport::Error),
    Authentication { message: String, status: Box<tonic::Status> },
    Authorization { message: String, status: Box<tonic::Status> },
    Timeout { message: String, status: Box<tonic::Status> },
    Cancelled { message: String, status: Box<tonic::Status> },
    Unavailable { message: String, status: Box<tonic::Status> },
    Status(Box<tonic::Status>),
    Command(Box<CommandError>),
    ProtocolStatus { operation: &'static str, code: ProtocolStatusCode, message: String },
    MalformedReply { detail: String },
}

Unavailable classifies the transient Code::Unavailable / Code::ResourceExhausted statuses so callers can decide whether to retry without unwrapping the raw status. MalformedReply surfaces OK replies whose payload does not carry the data the command contract requires (for example, an AddItem reply missing the item handle, or a WriteBulk reply carrying the wrong payload arm). InvalidEndpoint is returned when the endpoint URL fails to parse or its TLS material cannot be loaded.

Preserve raw command replies in CommandError where applicable.

Test CLI

Binary: mxgw.

Use clap derive.

Commands (see clients/rust/README.md for full argument lists):

mxgw version
mxgw ping
mxgw open-session
mxgw close-session --session-id <id>
mxgw register --session-id <id> --client-name <name>
mxgw add-item --session-id <id> --server-handle <h> --item <tag>
mxgw advise --session-id <id> --server-handle <h> --item-handle <h>
mxgw subscribe-bulk --session-id <id> --server-handle <h> --items <a,b,c>
mxgw unsubscribe-bulk --session-id <id> --server-handle <h> --item-handles <1,2,3>
mxgw read-bulk --session-id <id> --server-handle <h> --items <a,b,c> --timeout-ms 1500
mxgw write --session-id <id> --server-handle 1 --item-handle 1 --value-type int32 --value 123
mxgw write2 --session-id <id> --server-handle 1 --item-handle 1 --value-type int32 --value 123 --timestamp <rfc3339>
mxgw write-bulk --session-id <id> --server-handle <h> --item-handles <1,2> --value-type int32 --values <1,2>
mxgw write2-bulk --session-id <id> --server-handle <h> --item-handles <1,2> --value-type int32 --values <1,2> --timestamp <rfc3339>
mxgw write-secured-bulk --session-id <id> --server-handle <h> --item-handles <1,2> --value-type int32 --values <1,2>
mxgw write-secured2-bulk --session-id <id> --server-handle <h> --item-handles <1,2> --value-type int32 --values <1,2> --timestamp <rfc3339>
mxgw stream-events --session-id <id> --json
mxgw bench-read-bulk --duration-seconds 30 --bulk-size 6 --json
mxgw smoke --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --item TestChildObject.TestInt
mxgw galaxy test-connection
mxgw galaxy last-deploy-time
mxgw galaxy discover-hierarchy
mxgw galaxy watch [--last-seen-deploy-time <rfc3339>] [--max-events N]

JSON output should use serde_json.

Unit Tests

Use a fake tonic server started on a local ephemeral port, or abstract the generated client behind a trait for unit tests.

Required tests:

• generated client compiles from proto,
• auth metadata injection,
• TLS/plaintext endpoint construction,
• value conversion,
• command request construction,
• error mapping from tonic::Status,
• event stream order,
• stream cancellation,
• CLI parsing,
• JSON redaction.

Integration Tests

Skip unless:

MXGATEWAY_INTEGRATION=1

Use tokio::test. Run bounded smoke flow and ensure CloseSession is attempted with drop fallback docs, but do not rely on Drop for async close.

Related Documentation

• Client Libraries Detailed Design
• Client Proto Generation
• Client Packaging
• Rust Style Guide