Joseph Doherty
3.4 KiB
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.
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.
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.