Scaffold Rust client workspace

clients/rust/src/auth.rs

@@ -0,0 +1,30 @@
+use std::fmt;
+
+/// API key wrapper that avoids exposing raw credentials in formatted output.
+#[derive(Clone, Eq, PartialEq)]
+pub struct ApiKey(String);
+
+impl ApiKey {
+    pub fn new(value: impl Into<String>) -> Self {
+        Self(value.into())
+    }
+
+    pub fn expose_secret(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Debug for ApiKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_tuple("ApiKey")
+            .field(&"<redacted>")
+            .finish()
+    }
+}
+
+impl fmt::Display for ApiKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("<redacted>")
+    }
+}

clients/rust/src/client.rs

@@ -0,0 +1,30 @@
+use tonic::transport::Channel;
+
+use crate::error::Error;
+use crate::generated::mxaccess_gateway::v1::mx_access_gateway_client::MxAccessGatewayClient;
+use crate::options::ClientOptions;
+
+/// Thin owner for the generated gateway client.
+pub struct GatewayClient {
+    inner: MxAccessGatewayClient<Channel>,
+}
+
+impl GatewayClient {
+    pub async fn connect(options: ClientOptions) -> Result<Self, Error> {
+        let endpoint = Channel::from_shared(options.endpoint().to_owned()).map_err(|source| {
+            Error::InvalidEndpoint {
+                endpoint: options.endpoint().to_owned(),
+                detail: source.to_string(),
+            }
+        })?;
+        let channel = endpoint.connect().await?;
+
+        Ok(Self {
+            inner: MxAccessGatewayClient::new(channel),
+        })
+    }
+
+    pub fn into_inner(self) -> MxAccessGatewayClient<Channel> {
+        self.inner
+    }
+}

clients/rust/src/error.rs

@@ -0,0 +1,13 @@
+use thiserror::Error as ThisError;
+
+#[derive(Debug, ThisError)]
+pub enum Error {
+    #[error("invalid gateway endpoint `{endpoint}`: {detail}")]
+    InvalidEndpoint { endpoint: String, detail: String },
+
+    #[error("gateway transport error: {0}")]
+    Transport(#[from] tonic::transport::Error),
+
+    #[error("gateway status error: {0}")]
+    Status(#[from] tonic::Status),
+}

clients/rust/src/generated.rs

@@ -0,0 +1,15 @@
+pub mod mxaccess_gateway {
+    pub mod v1 {
+        #![allow(clippy::large_enum_variant)]
+
+        tonic::include_proto!("mxaccess_gateway.v1");
+    }
+}
+
+pub mod mxaccess_worker {
+    pub mod v1 {
+        #![allow(clippy::large_enum_variant)]
+
+        tonic::include_proto!("mxaccess_worker.v1");
+    }
+}

clients/rust/src/lib.rs

@@ -0,0 +1,21 @@
+//! Rust client scaffold for MXAccess Gateway.
+//!
+//! The crate compiles generated `tonic` bindings from the shared gateway
+//! protobuf contracts and exposes a small handwritten surface for future client
+//! implementation work.
+
+pub mod auth;
+pub mod client;
+pub mod error;
+pub mod generated;
+pub mod options;
+pub mod session;
+pub mod value;
+pub mod version;
+
+pub use auth::ApiKey;
+pub use client::GatewayClient;
+pub use error::Error;
+pub use options::ClientOptions;
+pub use session::Session;
+pub use version::{CLIENT_VERSION, GATEWAY_PROTOCOL_VERSION, WORKER_PROTOCOL_VERSION};

clients/rust/src/options.rs

@@ -0,0 +1,54 @@
+use std::fmt;
+
+use crate::auth::ApiKey;
+
+#[derive(Clone)]
+pub struct ClientOptions {
+    endpoint: String,
+    api_key: Option<ApiKey>,
+    plaintext: bool,
+}
+
+impl ClientOptions {
+    pub fn new(endpoint: impl Into<String>) -> Self {
+        Self {
+            endpoint: endpoint.into(),
+            api_key: None,
+            plaintext: true,
+        }
+    }
+
+    pub fn with_api_key(mut self, api_key: ApiKey) -> Self {
+        self.api_key = Some(api_key);
+        self
+    }
+
+    pub fn endpoint(&self) -> &str {
+        &self.endpoint
+    }
+
+    pub fn api_key(&self) -> Option<&ApiKey> {
+        self.api_key.as_ref()
+    }
+
+    pub fn plaintext(&self) -> bool {
+        self.plaintext
+    }
+}
+
+impl Default for ClientOptions {
+    fn default() -> Self {
+        Self::new("http://127.0.0.1:5000")
+    }
+}
+
+impl fmt::Debug for ClientOptions {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("ClientOptions")
+            .field("endpoint", &self.endpoint)
+            .field("api_key", &self.api_key.as_ref().map(|_| "<redacted>"))
+            .field("plaintext", &self.plaintext)
+            .finish()
+    }
+}

clients/rust/src/session.rs

@@ -0,0 +1,15 @@
+/// Session identifier returned by the gateway.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct Session {
+    id: String,
+}
+
+impl Session {
+    pub fn new(id: impl Into<String>) -> Self {
+        Self { id: id.into() }
+    }
+
+    pub fn id(&self) -> &str {
+        &self.id
+    }
+}

clients/rust/src/value.rs

@@ -0,0 +1,9 @@
+use crate::generated::mxaccess_gateway::v1::MxValue;
+
+pub fn int32_value(value: i32) -> MxValue {
+    MxValue {
+        data_type: crate::generated::mxaccess_gateway::v1::MxDataType::Integer as i32,
+        kind: Some(crate::generated::mxaccess_gateway::v1::mx_value::Kind::Int32Value(value)),
+        ..MxValue::default()
+    }
+}

clients/rust/src/version.rs

@@ -0,0 +1,3 @@
+pub const CLIENT_VERSION: &str = "0.1.0-dev";
+pub const GATEWAY_PROTOCOL_VERSION: u32 = 1;
+pub const WORKER_PROTOCOL_VERSION: u32 = 1;