Rust Client Workspace

The Rust client workspace contains the MXAccess Gateway client library, a test CLI, and tests for generated contract wiring plus wrapper behavior. The library uses the shared protobuf inputs documented in ../../docs/client-proto-generation.md so the Rust bindings compile against the same public gateway and worker contracts as the server.

Layout

clients/rust/
  Cargo.toml
  build.rs
  src/
  tests/
  crates/mxgw-cli/

build.rs reads the .proto files from ../../src/MxGateway.Contracts/Protos and generates tonic/prost bindings into Cargo build output. src/generated.rs declares the Rust modules that include those generated files. src/generated remains reserved for checked-in generator output if the crate later changes to source-tree generation.

Build And Test

Run the Rust workspace checks from clients/rust:

cargo fmt --all --check
cargo test --workspace
cargo check --workspace
cargo clippy --workspace --all-targets -- -D warnings

The build script uses protoc from PATH or the Windows path recorded in ../../docs/toolchain-links.md.

Packaging

Create local release artifacts from clients/rust:

cargo build --workspace --release
cargo install --path crates/mxgw-cli --locked --force

cargo check --workspace regenerates the tonic and prost modules into Cargo build output through build.rs.

CLI

The CLI exposes version, session, command, event stream, write, and smoke commands over the same client wrapper used by tests:

cargo run -p mxgw-cli -- version --json
cargo run -p mxgw-cli -- open-session --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
cargo run -p mxgw-cli -- register --session-id <session-id> --client-name mxgw-rust-cli --json
cargo run -p mxgw-cli -- add-item --session-id <session-id> --server-handle 1 --item TestChildObject.TestInt --json
cargo run -p mxgw-cli -- advise --session-id <session-id> --server-handle 1 --item-handle 1 --json
cargo run -p mxgw-cli -- stream-events --session-id <session-id> --max-events 1 --json
cargo run -p mxgw-cli -- write --session-id <session-id> --server-handle 1 --item-handle 1 --value-type int32 --value 123 --json

Use --tls, --ca-file, and --server-name-override for TLS endpoints. The CLI reads the API key from --api-key or from --api-key-env, which defaults to MXGATEWAY_API_KEY. API keys are redacted by the library option and secret types.

cargo run -p mxgw-cli -- smoke --endpoint https://mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item TestChildObject.TestInt --json

Library Surface

ClientOptions configures endpoint, API key, plaintext or TLS transport, timeouts, custom CA files, and server name override. GatewayClient::connect creates an authenticated tonic client and attaches authorization: Bearer <api-key> metadata to unary and streaming calls.

GatewayClient exposes raw generated calls through open_session_raw, close_session_raw, invoke_raw, stream_events, and raw_client. The session helpers keep MXAccess handles visible:

let session = client.open_session(request).await?;
let server_handle = session.register("mxgw-rust").await?;
let item_handle = session.add_item(server_handle, "TestChildObject.TestInt").await?;
session.advise(server_handle, item_handle).await?;
let mut events = session.events().await?;
session.close().await?;

MxValue, MxArrayValue, and MxStatus wrap generated protobuf messages while preserving the raw message for parity diagnostics. Command replies whose protocol status is not PROTOCOL_STATUS_CODE_OK become Error::Command and retain the raw MxCommandReply.

Integration Checks

Run live checks only when a gateway and MXAccess-backed worker are available:

$env:MXGATEWAY_INTEGRATION = '1'
$env:MXGATEWAY_ENDPOINT = 'http://127.0.0.1:5000'
$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
$env:MXGATEWAY_TEST_ITEM = 'TestChildObject.TestInt'
cargo run -p mxgw-cli -- smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json

4.5 KiB Raw Blame History