An agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.
Rust
feat(sdk): complete WebSocket client transport (#3349)
Bellman192d40a860e1
diff --git a/rust/Cargo.lock b/rust/Cargo.lockindex 5abc09ae..39aa6e7d 100644--- a/rust/Cargo.lock+++ b/rust/Cargo.lock@@ -1215,7 +1215,7 @@ dependencies = ["tokio","tokio-rustls","tower-service",- "webpki-roots",+ "webpki-roots 1.0.6",][[package]]@@ -2117,7 +2117,7 @@ dependencies = ["wasm-bindgen-futures","wasm-streams","web-sys",- "webpki-roots",+ "webpki-roots 1.0.6",][[package]]@@ -2339,11 +2339,10 @@ dependencies = ["futures-util","serde","serde_json",- "thiserror 1.0.69","tokio",- "tokio-test","tokio-tungstenite","tracing",+ "url","uuid",]@@ -2794,17 +2793,6 @@ dependencies = ["tokio",]-[[package]]-name = "tokio-test"-version = "0.4.6"-source = "registry+https://github.com/rust-lang/crates.io-index"-checksum = "12bc5db7778a8e08ee255090861e0e7aac55e784300077e7ed293c7be36168b2"-dependencies = [- "futures-core",- "tokio",- "tokio-stream",-]-[[package]]name = "tokio-tungstenite"version = "0.23.1"@@ -2813,8 +2801,12 @@ checksum = "c6989540ced10490aaf14e6bad2e3d33728a2813310a0c71d1574304c49631cd"dependencies = ["futures-util","log",+ "rustls",+ "rustls-pki-types","tokio",+ "tokio-rustls","tungstenite",+ "webpki-roots 0.26.11",][[package]]@@ -3041,6 +3033,8 @@ dependencies = ["httparse","log","rand 0.8.6",+ "rustls",+ "rustls-pki-types","sha1","thiserror 1.0.69","utf-8",@@ -3249,6 +3243,15 @@ dependencies = ["wasm-bindgen",]+[[package]]+name = "webpki-roots"+version = "0.26.11"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9"+dependencies = [+ "webpki-roots 1.0.6",+]+[[package]]name = "webpki-roots"version = "1.0.6"diff --git a/rust/crates/sdk/Cargo.toml b/rust/crates/sdk/Cargo.tomlindex 0c289500..9290a864 100644--- a/rust/crates/sdk/Cargo.toml+++ b/rust/crates/sdk/Cargo.toml@@ -6,13 +6,10 @@ publish = false[dependencies]tokio = { version = "1", features = ["full"] }-tokio-tungstenite = "0.23"+tokio-tungstenite = { version = "0.23", features = ["rustls-tls-webpki-roots"] }futures-util = "0.3"serde_json = "1"serde = { version = "1", features = ["derive"] }uuid = { version = "1", features = ["v4", "serde"] }-thiserror = "1"tracing = "0.1"--[dev-dependencies]-tokio-test = "0.4"+url = "2"diff --git a/rust/crates/sdk/src/error.rs b/rust/crates/sdk/src/error.rsindex ab90ab63..b60079f9 100644--- a/rust/crates/sdk/src/error.rs+++ b/rust/crates/sdk/src/error.rs@@ -1,102 +1,172 @@-//! SDK error types and result type.+//! Typed SDK wire protocol errors and request recovery records.use std::fmt;+use std::time::SystemTime;++use uuid::Uuid;/// SDK wire protocol error codes.#[derive(Debug, Clone, Copy, PartialEq, Eq)]-pub enum ErrorCode {- /// Invalid JSON or malformed frame+pub enum SdkErrorCode {InvalidInput,- /// Unknown broker operationUnknownOperation,- /// Payload too large (>4 MiB)+ NotFound,PayloadTooLarge,- /// Authentication token mismatchUnauthorized,- /// Broker or session unavailable+ EndpointCredentialForbidden,Unavailable,- /// WebSocket connection errorConnectionError,- /// Request timeout+ ConnectionClosed,Timeout,- /// Frame parsing or validation errorFrameError,- /// Request/response correlation failureCorrelationError,- /// Other unclassified error+ ProtocolError,+ ReconnectExhausted,+ UncertainAfterSend,Internal,}-impl fmt::Display for ErrorCode {- fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {+impl SdkErrorCode {+ /// Return the stable wire representation of this error code.+ pub const fn as_str(self) -> &'static str {match self {- Self::InvalidInput => write!(f, "invalid_input"),- Self::UnknownOperation => write!(f, "unknown_operation"),- Self::PayloadTooLarge => write!(f, "payload_too_large"),- Self::Unauthorized => write!(f, "unauthorized"),- Self::Unavailable => write!(f, "unavailable"),- Self::ConnectionError => write!(f, "connection_error"),- Self::Timeout => write!(f, "timeout"),- Self::FrameError => write!(f, "frame_error"),- Self::CorrelationError => write!(f, "correlation_error"),- Self::Internal => write!(f, "internal_error"),+ Self::InvalidInput => "invalid_input",+ Self::UnknownOperation => "unknown_operation",+ Self::NotFound => "not_found",+ Self::PayloadTooLarge => "payload_too_large",+ Self::Unauthorized => "unauthorized",+ Self::EndpointCredentialForbidden => "endpoint_credential_forbidden",+ Self::Unavailable => "unavailable",+ Self::ConnectionError => "connection_error",+ Self::ConnectionClosed => "connection_closed",+ Self::Timeout => "timeout",+ Self::FrameError => "frame_error",+ Self::CorrelationError => "correlation_error",+ Self::ProtocolError => "protocol_error",+ Self::ReconnectExhausted => "reconnect_exhausted",+ Self::UncertainAfterSend => "uncertain_after_send",+ Self::Internal => "internal_error",+ }+ }++ /// Parse a server error code, mapping unrecognized values to `Internal`.+ pub fn from_wire(value: &str) -> Self {+ match value {+ "invalid_input" => Self::InvalidInput,+ "unknown_operation" => Self::UnknownOperation,+ "not_found" => Self::NotFound,+ "payload_too_large" => Self::PayloadTooLarge,+ "unauthorized" => Self::Unauthorized,+ "endpoint_credential_forbidden" => Self::EndpointCredentialForbidden,+ "unavailable" => Self::Unavailable,+ "connection_error" => Self::ConnectionError,+ "connection_closed" => Self::ConnectionClosed,+ "timeout" => Self::Timeout,+ "frame_error" => Self::FrameError,+ "correlation_error" => Self::CorrelationError,+ "protocol_error" => Self::ProtocolError,+ "reconnect_exhausted" => Self::ReconnectExhausted,+ "uncertain_after_send" => Self::UncertainAfterSend,+ "internal" | "internal_error" => Self::Internal,+ _ => Self::Internal,}}}+impl fmt::Display for SdkErrorCode {+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {+ f.write_str(self.as_str())+ }+}++/// Identity retained when a request may have reached the broker but its reply was lost.+///+/// Records deliberately contain no input payload so credentials and other request data+/// are not retained solely for diagnostics. Callers can use the UUID to reconcile the+/// request with an operation-specific lookup before deciding whether to retry.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct SdkSentRecord {+ pub id: Uuid,+ pub operation: Option<String>,+ pub sent_at: SystemTime,+}+/// SDK wire protocol error.-#[derive(Debug)]+#[derive(Debug, Clone, PartialEq, Eq)]pub struct SdkError {- pub code: ErrorCode,+ pub code: SdkErrorCode,pub message: String,+ /// Original server code when it is not represented by `SdkErrorCode`.+ pub remote_code: Option<String>,+ /// Present only when delivery may have happened before the error was observed.+ pub sent_record: Option<SdkSentRecord>,}impl SdkError {- pub fn new(code: ErrorCode, message: impl Into<String>) -> Self {+ pub fn new(code: SdkErrorCode, message: impl Into<String>) -> Self {Self {code,message: message.into(),+ remote_code: None,+ sent_record: None,}}pub fn invalid_input(message: impl Into<String>) -> Self {- Self::new(ErrorCode::InvalidInput, message)+ Self::new(SdkErrorCode::InvalidInput, message)}pub fn unknown_operation(message: impl Into<String>) -> Self {- Self::new(ErrorCode::UnknownOperation, message)+ Self::new(SdkErrorCode::UnknownOperation, message)}pub fn payload_too_large(message: impl Into<String>) -> Self {- Self::new(ErrorCode::PayloadTooLarge, message)+ Self::new(SdkErrorCode::PayloadTooLarge, message)}pub fn unauthorized(message: impl Into<String>) -> Self {- Self::new(ErrorCode::Unauthorized, message)+ Self::new(SdkErrorCode::Unauthorized, message)}pub fn unavailable(message: impl Into<String>) -> Self {- Self::new(ErrorCode::Unavailable, message)+ Self::new(SdkErrorCode::Unavailable, message)}pub fn connection_error(message: impl Into<String>) -> Self {- Self::new(ErrorCode::ConnectionError, message)+ Self::new(SdkErrorCode::ConnectionError, message)}pub fn timeout(message: impl Into<String>) -> Self {- Self::new(ErrorCode::Timeout, message)+ Self::new(SdkErrorCode::Timeout, message)}pub fn frame_error(message: impl Into<String>) -> Self {- Self::new(ErrorCode::FrameError, message)+ Self::new(SdkErrorCode::FrameError, message)}pub fn correlation_error(message: impl Into<String>) -> Self {- Self::new(ErrorCode::CorrelationError, message)+ Self::new(SdkErrorCode::CorrelationError, message)}pub fn internal(message: impl Into<String>) -> Self {- Self::new(ErrorCode::Internal, message)+ Self::new(SdkErrorCode::Internal, message)+ }++ pub fn uncertain_after_send(record: SdkSentRecord) -> Self {+ let mut error = Self::new(+ SdkErrorCode::UncertainAfterSend,+ "SDK request outcome is uncertain after the frame was sent.",+ );+ error.sent_record = Some(record);+ error+ }++ pub fn from_remote(code: &str, message: impl Into<String>) -> Self {+ let mut error = Self::new(SdkErrorCode::from_wire(code), message);+ if error.code == SdkErrorCode::Internal && code != "internal" && code != "internal_error" {+ error.remote_code = Some(code.to_string());+ }+ error}}@@ -123,8 +193,26 @@ mod tests {#[test]fn error_code_display_works() {- assert_eq!(ErrorCode::InvalidInput.to_string(), "invalid_input");- assert_eq!(ErrorCode::PayloadTooLarge.to_string(), "payload_too_large");- assert_eq!(ErrorCode::Unauthorized.to_string(), "unauthorized");+ assert_eq!(SdkErrorCode::InvalidInput.to_string(), "invalid_input");+ assert_eq!(+ SdkErrorCode::PayloadTooLarge.to_string(),+ "payload_too_large"+ );+ assert_eq!(SdkErrorCode::Unauthorized.to_string(), "unauthorized");+ assert_eq!(+ SdkErrorCode::from_wire("endpoint_credential_forbidden"),+ SdkErrorCode::EndpointCredentialForbidden+ );+ assert_eq!(+ SdkErrorCode::UncertainAfterSend.to_string(),+ "uncertain_after_send"+ );+ }++ #[test]+ fn unknown_remote_code_is_preserved_with_typed_internal_code() {+ let error = SdkError::from_remote("future_error", "failed");+ assert_eq!(error.code, SdkErrorCode::Internal);+ assert_eq!(error.remote_code.as_deref(), Some("future_error"));}}diff --git a/rust/crates/sdk/src/frame.rs b/rust/crates/sdk/src/frame.rsindex f05e7f0c..e63e893a 100644--- a/rust/crates/sdk/src/frame.rs+++ b/rust/crates/sdk/src/frame.rs@@ -1,45 +1,40 @@-//! Frame types and serialization for the SDK wire protocol.+//! Typed frame structures and JSON serialization for the SDK wire protocol.+use serde::{Deserialize, Serialize};use serde_json::{Map, Value};+use uuid::Uuid;use crate::error::{SdkError, SdkResult};-/// Protocol version implemented.+/// Protocol version implemented by this SDK client.pub const PROTOCOL_VERSION: u32 = 3;/// Maximum UTF-8 byte length for a single broker JSON frame.pub const MAX_FRAME_BYTES: usize = 4 * 1024 * 1024;-/// Frame type identifier.+/// Known frame type identifiers in the SDK wire protocol.#[derive(Debug, Clone, Copy, PartialEq, Eq)]pub enum FrameType {- /// Hello frame sent by broker on connection+ Hello,+ ServerHello,BrokerHello,- /// Request frame from client to brokerBrokerRequest,- /// Response frame from broker to clientBrokerResponse,- /// Query requestQueryRequest,- /// Query responseQueryResponse,- /// Control requestControlRequest,- /// Control responseControlResponse,- /// Event replay requestEventReplay,- /// Event replay resultEventReplayResult,- /// Session activationSessionActivate,- /// Session activation resultSessionActivateResult,}impl FrameType {- pub fn as_str(&self) -> &'static str {+ pub const fn as_str(self) -> &'static str {match self {+ Self::Hello => "hello",+ Self::ServerHello => "server_hello",Self::BrokerHello => "broker_hello",Self::BrokerRequest => "broker_request",Self::BrokerResponse => "broker_response",@@ -54,8 +49,10 @@ impl FrameType {}}- pub fn parse(s: &str) -> SdkResult<Self> {- match s {+ pub fn parse(value: &str) -> SdkResult<Self> {+ match value {+ "hello" => Ok(Self::Hello),+ "server_hello" => Ok(Self::ServerHello),"broker_hello" => Ok(Self::BrokerHello),"broker_request" => Ok(Self::BrokerRequest),"broker_response" => Ok(Self::BrokerResponse),@@ -67,50 +64,81 @@ impl FrameType {"event_replay_result" => Ok(Self::EventReplayResult),"session_activate" => Ok(Self::SessionActivate),"session_activate_result" => Ok(Self::SessionActivateResult),- _ => Err(SdkError::frame_error(format!("unknown frame type: {}", s))),+ _ => Err(SdkError::frame_error(format!(+ "unknown frame type: {value}"+ ))),}}}-/// A frame in the SDK wire protocol.+/// A typed JSON-object frame in the SDK wire protocol.///-/// Frames are JSON objects with a `type` field and optional `id` field for correlation.-#[derive(Debug, Clone)]-pub struct Frame {- /// Underlying JSON value+/// The map remains open-ended to allow operation-specific fields while the frame type,+/// correlation UUID, and handshake are validated by the client.+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]+#[serde(transparent)]+pub struct SdkFrame {+ /// Underlying JSON object.pub data: Map<String, Value>,}-impl Frame {- /// Create a new frame from a JSON object.+impl SdkFrame {+ /// Create a frame from a JSON object.pub fn new(data: Map<String, Value>) -> Self {Self { data }}- /// Create an empty frame.+ /// Create an empty frame object.pub fn empty() -> Self {- Self { data: Map::new() }+ Self::new(Map::new())}- /// Get the frame type.+ /// Parse and validate the frame's `type` field.pub fn frame_type(&self) -> SdkResult<FrameType> {- let frame_type_str = self+ let frame_type = self.data.get("type").and_then(Value::as_str).ok_or_else(|| SdkError::frame_error("missing 'type' field"))?;- FrameType::parse(frame_type_str)+ FrameType::parse(frame_type)}- /// Get the optional request/response ID for correlation.- pub fn id(&self) -> Option<String> {+ /// Get the optional UUID used for request/response correlation.+ pub fn id(&self) -> SdkResult<Option<Uuid>> {+ match self.data.get("id") {+ None => Ok(None),+ Some(Value::String(id)) => Uuid::parse_str(id).map(Some).map_err(|error| {+ SdkError::correlation_error(format!("invalid frame UUID: {error}"))+ }),+ Some(_) => Err(SdkError::correlation_error(+ "frame 'id' field must be a UUID string",+ )),+ }+ }++ /// Set the frame's correlation UUID.+ pub fn set_id(&mut self, id: Uuid) {self.data- .get("id")- .and_then(Value::as_str)- .map(String::from)+ .insert("id".to_string(), Value::String(id.to_string()));+ }++ /// Read a response correlation UUID from either supported field name.+ pub fn response_id(&self) -> SdkResult<Option<Uuid>> {+ if self.data.contains_key("id") {+ return self.id();+ }+ match self.data.get("requestId") {+ None => Ok(None),+ Some(Value::String(id)) => Uuid::parse_str(id).map(Some).map_err(|error| {+ SdkError::correlation_error(format!("invalid response UUID: {error}"))+ }),+ Some(_) => Err(SdkError::correlation_error(+ "frame 'requestId' field must be a UUID string",+ )),+ }}- /// Get the `ok` boolean field from a response frame.+ /// Read the `ok` boolean from a response frame.pub fn ok(&self) -> SdkResult<bool> {self.data.get("ok")@@ -118,33 +146,64 @@ impl Frame {.ok_or_else(|| SdkError::frame_error("missing or invalid 'ok' field"))}- /// Get the error object from a response frame.+ /// Read the remote error code and message from an error response.pub fn error(&self) -> Option<SdkResult<(String, String)>> {- let error_obj = self.data.get("error")?.as_object()?;- let code = error_obj.get("code")?.as_str()?.to_string();- let message = error_obj.get("message")?.as_str()?.to_string();+ let error = self.data.get("error")?.as_object()?;+ let code = error.get("code")?.as_str()?.to_string();+ let message = error.get("message")?.as_str()?.to_string();Some(Ok((code, message)))}- /// Get the result field from a response frame.+ /// Get the response result field.pub fn result(&self) -> Option<Value> {self.data.get("result").cloned()}- /// Convert to JSON string.+ /// Serialize this frame to compact JSON.pub fn to_json(&self) -> SdkResult<String> {serde_json::to_string(&self.data)- .map_err(|e| SdkError::frame_error(format!("JSON serialization error: {}", e)))+ .map_err(|error| SdkError::frame_error(format!("JSON serialization error: {error}")))}- /// Parse from JSON string.- pub fn from_json(json_str: &str) -> SdkResult<Self> {- let data: Map<String, Value> = serde_json::from_str(json_str)- .map_err(|e| SdkError::frame_error(format!("JSON parsing error: {}", e)))?;- Ok(Self::new(data))+ /// Parse a JSON object as an SDK frame.+ pub fn from_json(json: &str) -> SdkResult<Self> {+ match serde_json::from_str::<Value>(json)+ .map_err(|error| SdkError::frame_error(format!("JSON parsing error: {error}")))?+ {+ Value::Object(data) => Ok(Self::new(data)),+ _ => Err(SdkError::frame_error("SDK frame must be a JSON object")),+ }+ }++ /// Create the protocol-v3 client hello with the advertised capabilities.+ pub fn client_hello(capabilities: &[String]) -> Self {+ let mut data = Map::new();+ data.insert("type".to_string(), Value::String("hello".to_string()));+ data.insert(+ "protocolVersion".to_string(),+ Value::Number(PROTOCOL_VERSION.into()),+ );+ data.insert(+ "capabilities".to_string(),+ Value::Array(capabilities.iter().cloned().map(Value::String).collect()),+ );+ Self::new(data)}- /// Create a broker hello frame.+ /// Return whether this frame completes a server hello handshake.+ pub fn is_server_hello(&self) -> bool {+ matches!(+ self.data.get("type").and_then(Value::as_str),+ Some("hello" | "server_hello" | "broker_hello")+ )+ }++ /// Read an optional connection identifier from a server hello.+ pub fn connection_id(&self) -> Option<&str> {+ self.data.get("connectionId").and_then(Value::as_str)+ }++ /// Create a broker hello frame for protocol tests and mock servers.pub fn broker_hello() -> Self {let mut data = Map::new();data.insert(@@ -158,63 +217,63 @@ impl Frame {Self::new(data)}- /// Create a broker request frame.- pub fn broker_request(id: String, operation: String, input: Value) -> Self {+ /// Create a broker operation request frame.+ pub fn broker_request(id: Uuid, operation: String, input: Value) -> Self {let mut data = Map::new();data.insert("type".to_string(),Value::String("broker_request".to_string()),);- data.insert("id".to_string(), Value::String(id));+ data.insert("id".to_string(), Value::String(id.to_string()));data.insert("operation".to_string(), Value::String(operation));data.insert("input".to_string(), input);Self::new(data)}- /// Create a broker response frame.- pub fn broker_response_ok(id: String, result: Value) -> Self {+ /// Create a successful broker response frame.+ pub fn broker_response_ok(id: Uuid, result: Value) -> Self {let mut data = Map::new();data.insert("type".to_string(),Value::String("broker_response".to_string()),);- data.insert("id".to_string(), Value::String(id));+ data.insert("id".to_string(), Value::String(id.to_string()));data.insert("ok".to_string(), Value::Bool(true));data.insert("result".to_string(), result);Self::new(data)}- /// Create a broker error response frame.- pub fn broker_response_error(id: String, code: String, message: String) -> Self {- let mut error_data = Map::new();- error_data.insert("code".to_string(), Value::String(code));- error_data.insert("message".to_string(), Value::String(message));+ /// Create an error broker response frame.+ pub fn broker_response_error(id: Uuid, code: String, message: String) -> Self {+ let mut error = Map::new();+ error.insert("code".to_string(), Value::String(code));+ error.insert("message".to_string(), Value::String(message));let mut data = Map::new();data.insert("type".to_string(),Value::String("broker_response".to_string()),);- data.insert("id".to_string(), Value::String(id));+ data.insert("id".to_string(), Value::String(id.to_string()));data.insert("ok".to_string(), Value::Bool(false));- data.insert("error".to_string(), Value::Object(error_data));+ data.insert("error".to_string(), Value::Object(error));Self::new(data)}- /// Get the payload size in bytes.+ /// Get the serialized frame length in UTF-8 bytes.pub fn byte_size(&self) -> usize {- self.to_json().map(|s| s.len()).unwrap_or(0)+ self.to_json().map_or(0, |json| json.len())}- /// Get the operation name from a broker request frame.+ /// Read the operation name from a request frame.pub fn operation(&self) -> Option<String> {self.data.get("operation").and_then(Value::as_str)- .map(String::from)+ .map(str::to_owned)}- /// Get the input value from a broker request frame.+ /// Read the request input object.pub fn input(&self) -> Option<Value> {self.data.get("input").cloned()}@@ -226,7 +285,7 @@ mod tests {#[test]fn frame_type_round_trip() {- assert_eq!(FrameType::BrokerHello.as_str(), "broker_hello");+ assert_eq!(FrameType::Hello.as_str(), "hello");assert_eq!(FrameType::parse("broker_hello").unwrap(),FrameType::BrokerHello@@ -235,68 +294,76 @@ mod tests {#[test]fn frame_parsing_extracts_type() {- let frame = Frame::broker_hello();- assert_eq!(frame.frame_type().unwrap(), FrameType::BrokerHello);+ assert_eq!(+ SdkFrame::broker_hello().frame_type().unwrap(),+ FrameType::BrokerHello+ );}#[test]- fn frame_with_id_can_be_recovered() {- let frame = Frame::broker_request(- "test-id".to_string(),- "test.operation".to_string(),- Value::Object(Map::new()),- );- assert_eq!(frame.id(), Some("test-id".to_string()));+ fn frame_id_round_trips_as_a_uuid() {+ let id = Uuid::new_v4();+ let frame = SdkFrame::broker_request(id, "test.operation".to_string(), Value::Null);+ assert_eq!(frame.id().unwrap(), Some(id));}#[test]- fn frame_json_round_trip() {- let frame = Frame::broker_hello();- let json_str = frame.to_json().unwrap();- let parsed = Frame::from_json(&json_str).unwrap();- assert_eq!(parsed.frame_type().unwrap(), FrameType::BrokerHello);+ fn json_round_trip_preserves_the_typed_frame() {+ let frame = SdkFrame::client_hello(&["capability.one".to_string()]);+ let parsed = SdkFrame::from_json(&frame.to_json().unwrap()).unwrap();+ assert_eq!(parsed, frame);+ assert_eq!(parsed.frame_type().unwrap(), FrameType::Hello);}#[test]- fn broker_response_error_contains_code_and_message() {- let frame = Frame::broker_response_error(- "id1".to_string(),- "invalid_input".to_string(),- "test error".to_string(),+ fn client_hello_advertises_protocol_and_capabilities() {+ let frame = SdkFrame::client_hello(&["capability.one".to_string()]);+ assert_eq!(frame.data["protocolVersion"], PROTOCOL_VERSION);+ assert_eq!(+ frame.data["capabilities"],+ serde_json::json!(["capability.one"]));- let (code, message) = frame.error().unwrap().unwrap();- assert_eq!(code, "invalid_input");- assert_eq!(message, "test error");}#[test]- fn frame_extracts_operation_from_broker_request() {- let frame = Frame::broker_request(- "test-id".to_string(),- "query.list_sessions".to_string(),- Value::Object(Map::new()),+ fn broker_error_response_exposes_code_and_message() {+ let frame = SdkFrame::broker_response_error(+ Uuid::new_v4(),+ "invalid_input".to_string(),+ "bad input".to_string(),);- assert_eq!(frame.operation(), Some("query.list_sessions".to_string()));+ assert_eq!(+ frame.error().unwrap().unwrap(),+ ("invalid_input".into(), "bad input".into())+ );+ assert!(!frame.ok().unwrap());}#[test]- fn frame_extracts_input_from_broker_request() {- let input = Value::Object({- let mut m = Map::new();- m.insert("session_id".to_string(), Value::String("123".to_string()));- m- });- let frame = Frame::broker_request(- "test-id".to_string(),+ fn operation_and_input_are_recoverable() {+ let input = serde_json::json!({"session_id": "session-1"});+ let frame = SdkFrame::broker_request(+ Uuid::new_v4(),"query.get_session".to_string(),input.clone(),);+ assert_eq!(frame.operation().as_deref(), Some("query.get_session"));assert_eq!(frame.input(), Some(input));}#[test]- fn frame_without_operation_returns_none() {- let frame = Frame::broker_hello();- assert_eq!(frame.operation(), None);+ fn malformed_json_and_non_object_values_are_rejected() {+ assert!(SdkFrame::from_json("{").is_err());+ assert!(SdkFrame::from_json("[]").is_err());+ assert!(SdkFrame::from_json("null").is_err());+ }++ #[test]+ fn invalid_correlation_uuid_is_rejected() {+ let frame = SdkFrame::from_json(r#"{"type":"broker_response","id":"not-a-uuid"}"#).unwrap();+ assert_eq!(+ frame.id().unwrap_err().code,+ crate::error::SdkErrorCode::CorrelationError+ );}}diff --git a/rust/crates/sdk/src/lib.rs b/rust/crates/sdk/src/lib.rsindex c8b237c7..4703a7cb 100644--- a/rust/crates/sdk/src/lib.rs+++ b/rust/crates/sdk/src/lib.rs@@ -16,7 +16,7 @@ pub mod frame;pub mod registry;pub mod transport;-pub use error::{SdkError, SdkResult};-pub use frame::{Frame, FrameType};+pub use error::{SdkError, SdkErrorCode, SdkResult, SdkSentRecord};+pub use frame::{FrameType, SdkFrame};pub use registry::{OperationMetadata, OperationRegistry, Schema};-pub use transport::{SdkTransport, SdkTransportConfig};+pub use transport::{SdkClient, SdkClientConfig};diff --git a/rust/crates/sdk/src/transport.rs b/rust/crates/sdk/src/transport.rsindex 97689a44..ece95cba 100644--- a/rust/crates/sdk/src/transport.rs+++ b/rust/crates/sdk/src/transport.rs@@ -1,251 +1,1254 @@-//! WebSocket transport implementation for the SDK wire protocol.+//! Reconnecting WebSocket client for the SDK wire protocol.-use std::collections::HashMap;-use std::sync::Arc;+use std::collections::{HashMap, VecDeque};+use std::fmt;+use std::future::pending;+use std::sync::atomic::{AtomicBool, Ordering};+use std::sync::{Arc, Mutex};+use std::time::{Duration, SystemTime};-use futures_util::sink::SinkExt;-use futures_util::stream::StreamExt;+use futures_util::{SinkExt, StreamExt};use serde_json::Value;-use tokio::sync::{mpsc, oneshot, Mutex, RwLock};-use tokio_tungstenite::{connect_async, tungstenite::Message};+use tokio::net::TcpStream;+use tokio::sync::{mpsc, oneshot, watch, Mutex as AsyncMutex, RwLock};+use tokio::task::JoinHandle;+use tokio::time::{sleep, timeout, timeout_at, Instant};+use tokio_tungstenite::tungstenite::Message;+use tokio_tungstenite::{connect_async, MaybeTlsStream, WebSocketStream};+use url::Url;use uuid::Uuid;-use crate::error::{SdkError, SdkResult};-use crate::frame::{Frame, FrameType, MAX_FRAME_BYTES};+use crate::error::{SdkError, SdkErrorCode, SdkResult, SdkSentRecord};+use crate::frame::{SdkFrame, MAX_FRAME_BYTES, PROTOCOL_VERSION};-/// Configuration for SDK transport.+const MAX_SENT_RECORDS: usize = 256;+const CLOSE_GRACE: Duration = Duration::from_secs(5);+const CANCEL_ACK_GRACE: Duration = Duration::from_millis(100);++type ClientSocket = WebSocketStream<MaybeTlsStream<TcpStream>>;++/// Runtime options for an SDK WebSocket client.#[derive(Debug, Clone)]-pub struct SdkTransportConfig {- /// Server URL (e.g., "ws://127.0.0.1:8080")+pub struct SdkClientConfig {+ /// WebSocket endpoint (`ws://` or `wss://`).pub url: String,- /// Authentication token+ /// Broker authentication token, sent as the `token` query parameter.pub token: String,- /// Maximum payload size in bytes (default: 4 MiB)- pub max_payload_bytes: usize,- /// Request timeout in seconds (default: 30)- pub timeout_secs: u64,+ /// Maximum UTF-8 frame size accepted in either direction.+ pub max_frame_bytes: usize,+ /// Default timeout for an individual request.+ pub request_timeout: Duration,+ /// Timeout for each socket-open and hello-handshake attempt.+ pub connect_timeout: Duration,+ /// Maximum time spent across a connection or reconnect cycle.+ pub reconnect_deadline: Duration,+ /// Number of retries after the initial connection attempt.+ pub reconnect_attempts: u32,+ /// Initial reconnect delay; subsequent delays double up to `reconnect_max_backoff`.+ pub reconnect_initial_backoff: Duration,+ /// Maximum reconnect delay.+ pub reconnect_max_backoff: Duration,+ /// Capabilities sent in the protocol-v3 client hello.+ pub capabilities: Vec<String>,}-impl Default for SdkTransportConfig {+impl Default for SdkClientConfig {fn default() -> Self {Self {url: "ws://127.0.0.1:8080".to_string(),token: String::new(),- max_payload_bytes: MAX_FRAME_BYTES,- timeout_secs: 30,+ max_frame_bytes: MAX_FRAME_BYTES,+ request_timeout: Duration::from_secs(10),+ connect_timeout: Duration::from_secs(10),+ reconnect_deadline: Duration::from_secs(30),+ reconnect_attempts: 3,+ reconnect_initial_backoff: Duration::from_millis(25),+ reconnect_max_backoff: Duration::from_secs(2),+ capabilities: Vec::new(),+ }+ }+}++impl SdkClientConfig {+ fn validate(&self) -> SdkResult<()> {+ let endpoint = Url::parse(&self.url)+ .map_err(|error| SdkError::invalid_input(format!("invalid WebSocket URL: {error}")))?;+ if !matches!(endpoint.scheme(), "ws" | "wss") {+ return Err(SdkError::invalid_input(+ "SDK endpoint must use the ws:// or wss:// scheme",+ ));+ }+ if self.max_frame_bytes == 0 {+ return Err(SdkError::invalid_input(+ "maximum frame size must be greater than zero",+ ));+ }+ if self.connect_timeout.is_zero() || self.reconnect_deadline.is_zero() {+ return Err(SdkError::invalid_input(+ "connection timeout and reconnect deadline must be greater than zero",+ ));}+ if self.reconnect_max_backoff < self.reconnect_initial_backoff {+ return Err(SdkError::invalid_input(+ "maximum reconnect backoff must be at least the initial backoff",+ ));+ }+ Ok(())}}-/// Pending request tracking for correlation.+struct SentRecordStore {+ records: HashMap<Uuid, SdkSentRecord>,+ order: VecDeque<Uuid>,+}++impl SentRecordStore {+ fn new() -> Self {+ Self {+ records: HashMap::new(),+ order: VecDeque::new(),+ }+ }++ fn insert(&mut self, record: SdkSentRecord) {+ if self.records.contains_key(&record.id) {+ self.order.retain(|id| *id != record.id);+ }+ self.order.push_back(record.id);+ self.records.insert(record.id, record);+ while self.records.len() > MAX_SENT_RECORDS {+ if let Some(oldest) = self.order.pop_front() {+ self.records.remove(&oldest);+ }+ }+ }++ fn remove(&mut self, id: Uuid) {+ self.records.remove(&id);+ self.order.retain(|record_id| *record_id != id);+ }++ fn get(&self, id: Uuid) -> Option<SdkSentRecord> {+ self.records.get(&id).cloned()+ }++ fn all(&self) -> Vec<SdkSentRecord> {+ self.order+ .iter()+ .filter_map(|id| self.records.get(id).cloned())+ .collect()+ }+}++struct RequestMessage {+ id: Uuid,+ operation: Option<String>,+ serialized: String,+ deadline: Instant,+ response_tx: oneshot::Sender<SdkResult<SdkFrame>>,+}++enum ClientCommand {+ Request(RequestMessage),+ Cancel {+ id: Uuid,+ ack: oneshot::Sender<Option<SdkSentRecord>>,+ },+}+struct PendingRequest {- response_tx: oneshot::Sender<SdkResult<Frame>>,-}--/// SDK WebSocket transport.-pub struct SdkTransport {- /// Channel for sending messages to the writer task- tx: mpsc::UnboundedSender<Message>,- /// Pending requests by ID- pending: Arc<RwLock<HashMap<String, PendingRequest>>>,- /// Configuration- config: SdkTransportConfig,- /// Background task handle- task_handle: Arc<Mutex<Option<tokio::task::JoinHandle<()>>>>,-}--impl SdkTransport {- /// Create a new SDK transport and connect to the broker.- pub async fn connect(config: SdkTransportConfig) -> SdkResult<Self> {- // Add token to query params- let url_with_token = if config.url.contains('?') {- format!("{}&token={}", config.url, config.token)- } else {- format!("{}?token={}", config.url, config.token)- };+ response_tx: oneshot::Sender<SdkResult<SdkFrame>>,+ sent_record: SdkSentRecord,+}- // Create WebSocket connection- let (ws, _) = connect_async(&url_with_token).await.map_err(|e| {- SdkError::connection_error(format!("WebSocket connection failed: {}", e))- })?;+struct ConnectedSocket {+ socket: ClientSocket,+ connection_id: Option<String>,+}- let (ws_tx, ws_rx) = tokio::sync::mpsc::unbounded_channel();- let pending = Arc::new(RwLock::new(HashMap::new()));- let pending_clone = pending.clone();+/// SDK client with UUID correlation, handshake, timeout handling, and reconnects.+pub struct SdkClient {+ config: SdkClientConfig,+ command_tx: mpsc::UnboundedSender<ClientCommand>,+ shutdown_tx: watch::Sender<bool>,+ task_handle: AsyncMutex<Option<JoinHandle<()>>>,+ sent_records: Arc<Mutex<SentRecordStore>>,+ connection_id: Arc<RwLock<Option<String>>>,+ closed: AtomicBool,+}- // Spawn background task for handling the WebSocket- let task_handle = tokio::spawn(async move {- Self::background_task(ws, ws_rx, pending_clone).await;- });+impl fmt::Debug for SdkClient {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ formatter+ .debug_struct("SdkClient")+ .field("config", &self.config)+ .field("closed", &self.closed.load(Ordering::Acquire))+ .finish_non_exhaustive()+ }+}++impl SdkClient {+ /// Connect, complete the protocol-v3 hello handshake, and start reconnect supervision.+ pub async fn connect(config: SdkClientConfig) -> SdkResult<Self> {+ config.validate()?;+ let connected = connect_with_retry(&config).await?;+ let connection_id = Arc::new(RwLock::new(connected.connection_id.clone()));+ let sent_records = Arc::new(Mutex::new(SentRecordStore::new()));+ let (command_tx, command_rx) = mpsc::unbounded_channel();+ let (shutdown_tx, shutdown_rx) = watch::channel(false);+ let task_handle = tokio::spawn(run_client(+ connected,+ config.clone(),+ command_rx,+ shutdown_rx,+ sent_records.clone(),+ connection_id.clone(),+ ));- let transport = Self {- tx: ws_tx,- pending,+ Ok(Self {config,- task_handle: Arc::new(Mutex::new(Some(task_handle))),- };+ command_tx,+ shutdown_tx,+ task_handle: AsyncMutex::new(Some(task_handle)),+ sent_records,+ connection_id,+ closed: AtomicBool::new(false),+ })+ }- Ok(transport)+ /// Send a broker operation with the configured default request timeout.+ pub async fn request(&self, operation: impl Into<String>, input: Value) -> SdkResult<SdkFrame> {+ self.request_with_timeout(operation, input, self.config.request_timeout)+ .await}- /// Send a request and wait for response.- pub async fn request(&self, operation: String, input: Value) -> SdkResult<Frame> {- // Generate correlation ID- let id = Uuid::new_v4().to_string();+ /// Send a broker operation with a per-request timeout override.+ pub async fn request_with_timeout(+ &self,+ operation: impl Into<String>,+ input: Value,+ request_timeout: Duration,+ ) -> SdkResult<SdkFrame> {+ let operation = operation.into();+ let frame = SdkFrame::broker_request(Uuid::new_v4(), operation, input);+ self.request_frame_with_timeout(frame, request_timeout)+ .await+ }- // Create request frame- let request = Frame::broker_request(id.clone(), operation, input);+ /// Send a typed frame, replacing its `id` with a fresh UUID for correlation.+ pub async fn request_frame(&self, frame: SdkFrame) -> SdkResult<SdkFrame> {+ self.request_frame_with_timeout(frame, self.config.request_timeout)+ .await+ }- // Check payload size- if request.byte_size() > self.config.max_payload_bytes {+ /// Send a typed frame with a per-request timeout override.+ pub async fn request_frame_with_timeout(+ &self,+ mut frame: SdkFrame,+ request_timeout: Duration,+ ) -> SdkResult<SdkFrame> {+ if self.closed.load(Ordering::Acquire) {+ return Err(SdkError::new(+ SdkErrorCode::ConnectionClosed,+ "SDK client is closed",+ ));+ }+ let id = Uuid::new_v4();+ frame.set_id(id);+ let operation = frame.operation();+ let serialized = frame.to_json()?;+ if serialized.len() > self.config.max_frame_bytes {return Err(SdkError::payload_too_large(format!("frame size {} exceeds maximum {}",- request.byte_size(),- self.config.max_payload_bytes+ serialized.len(),+ self.config.max_frame_bytes)));}- // Create response channel+ let deadline = Instant::now() + request_timeout;let (response_tx, response_rx) = oneshot::channel();- self.pending- .write()- .await- .insert(id.clone(), PendingRequest { response_tx });-- // Send request- let json = request.to_json()?;- self.tx- .send(Message::Text(json))- .map_err(|e| SdkError::connection_error(format!("send failed: {}", e)))?;-- // Wait for response with timeout- let timeout_duration = std::time::Duration::from_secs(self.config.timeout_secs);- match tokio::time::timeout(timeout_duration, response_rx).await {- Ok(Ok(frame)) => frame,- Ok(Err(_)) => Err(SdkError::correlation_error("response channel closed")),- Err(_) => Err(SdkError::timeout("response not received within timeout")),- }- }-- /// Background task for handling WebSocket communication.- #[allow(unused_mut)]- async fn background_task(- ws: tokio_tungstenite::WebSocketStream<- tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>,- >,- mut ws_rx: mpsc::UnboundedReceiver<Message>,- pending: Arc<RwLock<HashMap<String, PendingRequest>>>,- ) {- let (mut ws_sink, mut ws_stream) = ws.split();+ self.command_tx+ .send(ClientCommand::Request(RequestMessage {+ id,+ operation,+ serialized,+ deadline,+ response_tx,+ }))+ .map_err(|_| {+ SdkError::new(+ SdkErrorCode::ConnectionClosed,+ "SDK connection task is no longer running",+ )+ })?;- loop {- tokio::select! {- // Handle incoming WebSocket messages- msg = ws_stream.next() => {- match msg {- Some(Ok(Message::Text(text))) => {- // Parse frame- match Frame::from_json(&text) {- Ok(frame) => {- // Handle frame type- match frame.frame_type() {- Ok(FrameType::BrokerHello) => {- // Hello frame received, continue- }- Ok(FrameType::BrokerResponse) => {- // Response frame, correlate with request- if let Some(id) = frame.id() {- if let Some(PendingRequest { response_tx }) =- pending.write().await.remove(&id)- {- let _ = response_tx.send(Ok(frame));- }- }- }- _ => {- // Other frame types- tracing::debug!("Unhandled frame type: {:?}", frame.frame_type());- }- }- }- Err(e) => {- tracing::warn!("Failed to parse frame: {}", e);- }- }- }- Some(Ok(Message::Close(_))) => {- break;+ match timeout_at(deadline, response_rx).await {+ Ok(Ok(response)) => response,+ Ok(Err(_)) => Err(SdkError::connection_error(+ "SDK connection task dropped the response channel",+ )),+ Err(_) => {+ let (ack_tx, ack_rx) = oneshot::channel();+ let _ = self+ .command_tx+ .send(ClientCommand::Cancel { id, ack: ack_tx });+ let acknowledged = timeout(CANCEL_ACK_GRACE, ack_rx)+ .await+ .ok()+ .and_then(Result::ok)+ .flatten();+ let sent_record = acknowledged.or_else(|| self.get_sent_record(id));+ match sent_record {+ Some(record) => Err(SdkError::uncertain_after_send(record)),+ None => Err(SdkError::timeout(format!(+ "SDK request timed out after {}ms before a response was received",+ request_timeout.as_millis()+ ))),+ }+ }+ }+ }++ /// Current broker connection identifier from the most recent hello frame.+ pub async fn connection_id(&self) -> Option<String> {+ self.connection_id.read().await.clone()+ }++ /// Look up a retained request identity after an uncertain send.+ pub fn get_sent_record(&self, id: Uuid) -> Option<SdkSentRecord> {+ self.sent_records+ .lock()+ .unwrap_or_else(std::sync::PoisonError::into_inner)+ .get(id)+ }++ /// List outstanding sent records that require caller-side reconciliation.+ pub fn uncertain_sends(&self) -> Vec<SdkSentRecord> {+ self.sent_records+ .lock()+ .unwrap_or_else(std::sync::PoisonError::into_inner)+ .all()+ }++ /// Forget a request record after the caller has reconciled its outcome.+ pub fn forget_sent_record(&self, id: Uuid) -> bool {+ let mut records = self+ .sent_records+ .lock()+ .unwrap_or_else(std::sync::PoisonError::into_inner);+ let found = records.records.contains_key(&id);+ records.remove(id);+ found+ }++ /// Close the socket and stop reconnect attempts. Safe to call more than once.+ pub async fn close(&self) -> SdkResult<()> {+ if !self.closed.swap(true, Ordering::AcqRel) {+ let _ = self.shutdown_tx.send(true);+ }+ if let Some(mut task) = self.task_handle.lock().await.take() {+ match timeout(CLOSE_GRACE, &mut task).await {+ Ok(Ok(())) => {}+ Ok(Err(error)) => {+ return Err(SdkError::connection_error(format!(+ "SDK connection task failed while closing: {error}"+ )))+ }+ Err(_) => {+ task.abort();+ return Err(SdkError::timeout(+ "SDK connection task did not stop in time",+ ));+ }+ }+ }+ Ok(())+ }+}++impl Drop for SdkClient {+ fn drop(&mut self) {+ if !self.closed.swap(true, Ordering::AcqRel) {+ let _ = self.shutdown_tx.send(true);+ }+ }+}++fn authenticated_url(config: &SdkClientConfig) -> SdkResult<Url> {+ let mut url = Url::parse(&config.url)+ .map_err(|error| SdkError::invalid_input(format!("invalid WebSocket URL: {error}")))?;+ if !matches!(url.scheme(), "ws" | "wss") {+ return Err(SdkError::invalid_input(+ "SDK endpoint must use the ws:// or wss:// scheme",+ ));+ }+ let mut query: Vec<(String, String)> = url+ .query_pairs()+ .filter(|(key, _)| key != "token")+ .map(|(key, value)| (key.into_owned(), value.into_owned()))+ .collect();+ query.push(("token".to_string(), config.token.clone()));+ url.set_query(None);+ url.query_pairs_mut().extend_pairs(query);+ Ok(url)+}++async fn connect_with_retry(config: &SdkClientConfig) -> SdkResult<ConnectedSocket> {+ let deadline = Instant::now() + config.reconnect_deadline;+ let mut last_error = None;++ for attempt in 0..=config.reconnect_attempts {+ let remaining = deadline.saturating_duration_since(Instant::now());+ if remaining.is_zero() {+ return Err(SdkError::timeout("SDK reconnect deadline elapsed"));+ }+ let attempt_timeout = remaining.min(config.connect_timeout);+ match timeout(attempt_timeout, connect_once(config)).await {+ Ok(Ok(connected)) => return Ok(connected),+ Ok(Err(error)) => last_error = Some(error),+ Err(_) => {+ last_error = Some(SdkError::timeout(format!(+ "SDK connection attempt timed out after {}ms",+ attempt_timeout.as_millis()+ )))+ }+ }++ if attempt == config.reconnect_attempts {+ break;+ }+ let delay = reconnect_delay(config, attempt);+ let remaining = deadline.saturating_duration_since(Instant::now());+ if remaining.is_zero() {+ return Err(SdkError::timeout("SDK reconnect deadline elapsed"));+ }+ sleep(delay.min(remaining)).await;+ }++ let cause = last_error+ .map(|error| error.to_string())+ .unwrap_or_else(|| "no connection attempt was made".to_string());+ Err(SdkError::new(+ SdkErrorCode::ReconnectExhausted,+ format!("SDK WebSocket reconnect attempts exhausted: {cause}"),+ ))+}++fn reconnect_delay(config: &SdkClientConfig, attempt: u32) -> Duration {+ let multiplier = 1_u32.checked_shl(attempt).unwrap_or(u32::MAX);+ config+ .reconnect_initial_backoff+ .saturating_mul(multiplier)+ .min(config.reconnect_max_backoff)+}++async fn connect_once(config: &SdkClientConfig) -> SdkResult<ConnectedSocket> {+ let url = authenticated_url(config)?;+ let (mut socket, _) = connect_async(url.as_str()).await.map_err(|error| {+ SdkError::connection_error(format!("WebSocket connection failed: {error}"))+ })?;++ let hello = SdkFrame::client_hello(&config.capabilities).to_json()?;+ socket.send(Message::Text(hello)).await.map_err(|error| {+ SdkError::connection_error(format!("client hello send failed: {error}"))+ })?;++ let handshake_deadline = Instant::now() + config.connect_timeout;+ loop {+ let message = timeout_at(handshake_deadline, socket.next())+ .await+ .map_err(|_| SdkError::timeout("SDK server hello handshake timed out"))?+ .ok_or_else(|| SdkError::connection_error("WebSocket closed before server hello"))?+ .map_err(|error| {+ SdkError::connection_error(format!("WebSocket failed before server hello: {error}"))+ })?;+ match message {+ Message::Text(text) => {+ if text.len() > config.max_frame_bytes {+ return Err(SdkError::payload_too_large(format!(+ "server hello frame size {} exceeds maximum {}",+ text.len(),+ config.max_frame_bytes+ )));+ }+ let frame = SdkFrame::from_json(&text)?;+ if frame.is_server_hello() {+ if let Some(version) = frame.data.get("protocolVersion").and_then(Value::as_u64)+ {+ if version != u64::from(PROTOCOL_VERSION) {+ return Err(SdkError::new(+ SdkErrorCode::ProtocolError,+ format!(+ "server protocol version {version} does not match {PROTOCOL_VERSION}"+ ),+ ));}- Some(Ok(_)) => {- // Other message types (binary, etc.), ignore+ }+ let connection_id = frame+ .connection_id()+ .filter(|value| !value.is_empty())+ .map(str::to_owned);+ return Ok(ConnectedSocket {+ socket,+ connection_id,+ });+ }+ }+ Message::Ping(payload) => {+ socket.send(Message::Pong(payload)).await.map_err(|error| {+ SdkError::connection_error(format!("WebSocket pong failed: {error}"))+ })?+ }+ Message::Close(_) => {+ return Err(SdkError::connection_error(+ "WebSocket closed before server hello",+ ));+ }+ Message::Binary(_) | Message::Pong(_) | Message::Frame(_) => {}+ }+ }+}++async fn await_reconnect(+ reconnect_task: &mut Option<JoinHandle<SdkResult<ConnectedSocket>>>,+) -> SdkResult<ConnectedSocket> {+ match reconnect_task {+ Some(task) => task.await.map_err(|error| {+ SdkError::connection_error(format!("SDK reconnect task failed: {error}"))+ })?,+ None => pending().await,+ }+}++async fn run_client(+ connected: ConnectedSocket,+ config: SdkClientConfig,+ mut command_rx: mpsc::UnboundedReceiver<ClientCommand>,+ mut shutdown_rx: watch::Receiver<bool>,+ sent_records: Arc<Mutex<SentRecordStore>>,+ connection_id: Arc<RwLock<Option<String>>>,+) {+ let mut socket = Some(connected.socket);+ let mut queued = VecDeque::new();+ let mut pending_requests = HashMap::new();+ let mut reconnect_task = None;++ loop {+ let incoming = async {+ match socket.as_mut() {+ Some(connected) => connected.next().await,+ None => pending().await,+ }+ };+ tokio::select! {+ changed = shutdown_rx.changed() => {+ if changed.is_err() || *shutdown_rx.borrow() {+ break;+ }+ }+ message = incoming => {+ match message {+ Some(Ok(Message::Text(text))) => {+ if text.len() > config.max_frame_bytes {+ tracing::warn!(size = text.len(), "SDK server frame exceeds configured limit");+ fail_pending_uncertain(&mut pending_requests);+ start_reconnect(&config, &mut socket, &mut reconnect_task);+ } else {+ handle_server_text(&text, &mut pending_requests, &sent_records, &connection_id).await;}- Some(Err(e)) => {- tracing::warn!("WebSocket error: {}", e);- break;+ }+ Some(Ok(Message::Ping(payload))) => {+ let send_result = match socket.as_mut() {+ Some(connected) => connected.send(Message::Pong(payload)).await,+ None => continue,+ };+ if send_result.is_err() {+ fail_pending_uncertain(&mut pending_requests);+ start_reconnect(&config, &mut socket, &mut reconnect_task);}- None => {- break;+ }+ Some(Ok(Message::Close(_))) | Some(Err(_)) | None => {+ fail_pending_uncertain(&mut pending_requests);+ start_reconnect(&config, &mut socket, &mut reconnect_task);+ }+ Some(Ok(Message::Binary(_))) | Some(Ok(Message::Pong(_))) | Some(Ok(Message::Frame(_))) => {}+ }+ }+ command = command_rx.recv() => {+ let Some(command) = command else { break };+ match command {+ ClientCommand::Request(request) => {+ if socket.is_none() {+ queued.push_back(request);+ } else if !send_request(+ request,+ socket.as_mut().expect("socket checked above"),+ &mut pending_requests,+ &sent_records,+ ).await {+ fail_pending_uncertain(&mut pending_requests);+ start_reconnect(&config, &mut socket, &mut reconnect_task);}}+ ClientCommand::Cancel { id, ack } => {+ let record = cancel_request(+ id,+ &mut queued,+ &mut pending_requests,+ &sent_records,+ );+ let _ = ack.send(record);+ }}- // Handle outgoing messages- Some(msg) = ws_rx.recv() => {- if let Err(e) = ws_sink.send(msg).await {- tracing::warn!("Failed to send message: {}", e);+ }+ result = await_reconnect(&mut reconnect_task) => {+ reconnect_task = None;+ match result {+ Ok(connected) => {+ *connection_id.write().await = connected.connection_id;+ socket = Some(connected.socket);+ while let Some(request) = queued.pop_front() {+ if !send_request(+ request,+ socket.as_mut().expect("reconnected socket is present"),+ &mut pending_requests,+ &sent_records,+ ).await {+ fail_pending_uncertain(&mut pending_requests);+ start_reconnect(&config, &mut socket, &mut reconnect_task);+ break;+ }+ }+ }+ Err(error) => {+ for request in queued.drain(..) {+ let _ = request.response_tx.send(Err(error.clone()));+ }break;}}- else => break,}}+ }++ if let Some(task) = reconnect_task {+ task.abort();+ }+ fail_pending_uncertain(&mut pending_requests);+ for request in queued.drain(..) {+ let _ = request.response_tx.send(Err(SdkError::new(+ SdkErrorCode::ConnectionClosed,+ "SDK client closed before request was sent",+ )));+ }+ if let Some(mut connected) = socket {+ let _ = timeout(CLOSE_GRACE, connected.close(None)).await;+ }+}++fn start_reconnect(+ config: &SdkClientConfig,+ socket: &mut Option<ClientSocket>,+ reconnect_task: &mut Option<JoinHandle<SdkResult<ConnectedSocket>>>,+) {+ socket.take();+ if reconnect_task.is_none() {+ let config = config.clone();+ *reconnect_task = Some(tokio::spawn(+ async move { connect_with_retry(&config).await },+ ));+ }+}- // Fail all pending requests- let mut pending = pending.write().await;- for (_, PendingRequest { response_tx }) in pending.drain() {- let _ = response_tx.send(Err(SdkError::connection_error("connection closed")));+async fn send_request(+ request: RequestMessage,+ socket: &mut ClientSocket,+ pending_requests: &mut HashMap<Uuid, PendingRequest>,+ sent_records: &Arc<Mutex<SentRecordStore>>,+) -> bool {+ if Instant::now() >= request.deadline {+ let _ = request.response_tx.send(Err(SdkError::timeout(+ "SDK request deadline elapsed before send",+ )));+ return true;+ }++ let sent_record = SdkSentRecord {+ id: request.id,+ operation: request.operation,+ sent_at: SystemTime::now(),+ };+ sent_records+ .lock()+ .unwrap_or_else(std::sync::PoisonError::into_inner)+ .insert(sent_record.clone());+ pending_requests.insert(+ request.id,+ PendingRequest {+ response_tx: request.response_tx,+ sent_record: sent_record.clone(),+ },+ );++ let send_result = timeout_at(+ request.deadline,+ socket.send(Message::Text(request.serialized)),+ )+ .await;+ match send_result {+ Ok(Ok(())) => true,+ Ok(Err(error)) => {+ if let Some(pending) = pending_requests.remove(&request.id) {+ let _ = pending+ .response_tx+ .send(Err(SdkError::uncertain_after_send(pending.sent_record)));+ }+ tracing::warn!(%error, "SDK request send failed after dispatch began");+ false+ }+ Err(_) => {+ if let Some(pending) = pending_requests.remove(&request.id) {+ let _ = pending+ .response_tx+ .send(Err(SdkError::uncertain_after_send(pending.sent_record)));+ }+ false}}+}- /// Close the transport.- pub async fn close(self) -> SdkResult<()> {- // Send close message- let _ = self.tx.send(Message::Close(None));+fn cancel_request(+ id: Uuid,+ queued: &mut VecDeque<RequestMessage>,+ pending_requests: &mut HashMap<Uuid, PendingRequest>,+ sent_records: &Arc<Mutex<SentRecordStore>>,+) -> Option<SdkSentRecord> {+ if let Some(position) = queued.iter().position(|request| request.id == id) {+ queued.remove(position);+ return None;+ }+ if let Some(pending) = pending_requests.remove(&id) {+ return Some(pending.sent_record);+ }+ sent_records+ .lock()+ .unwrap_or_else(std::sync::PoisonError::into_inner)+ .get(id)+}- // Wait for background task to finish- if let Some(handle) = self.task_handle.lock().await.take() {- let _ = tokio::time::timeout(std::time::Duration::from_secs(5), handle).await;+async fn handle_server_text(+ text: &str,+ pending_requests: &mut HashMap<Uuid, PendingRequest>,+ sent_records: &Arc<Mutex<SentRecordStore>>,+ connection_id: &Arc<RwLock<Option<String>>>,+) {+ let frame = match SdkFrame::from_json(text) {+ Ok(frame) => frame,+ Err(error) => {+ tracing::warn!(%error, "SDK server sent malformed JSON frame");+ return;}+ };+ if frame.is_server_hello() {+ if let Some(id) = frame.connection_id().filter(|id| !id.is_empty()) {+ *connection_id.write().await = Some(id.to_string());+ }+ return;+ }- Ok(())+ let id = match frame.response_id() {+ Ok(Some(id)) => id,+ Ok(None) => return,+ Err(error) => {+ tracing::warn!(%error, "SDK server sent an invalid correlation ID");+ return;+ }+ };+ if let Some(pending) = pending_requests.remove(&id) {+ sent_records+ .lock()+ .unwrap_or_else(std::sync::PoisonError::into_inner)+ .remove(id);+ let result = if frame.data.get("ok") == Some(&Value::Bool(false))+ || frame.data.get("status").and_then(Value::as_str) == Some("error")+ {+ Err(error_from_response(&frame))+ } else {+ Ok(frame)+ };+ let _ = pending.response_tx.send(result);+ }+}++fn error_from_response(frame: &SdkFrame) -> SdkError {+ match frame.error() {+ Some(Ok((code, message))) => SdkError::from_remote(&code, message),+ Some(Err(error)) => error,+ None => SdkError::new(+ SdkErrorCode::Unavailable,+ "SDK request failed without error details",+ ),+ }+}++fn fail_pending_uncertain(pending_requests: &mut HashMap<Uuid, PendingRequest>) {+ for (_, pending) in pending_requests.drain() {+ let _ = pending+ .response_tx+ .send(Err(SdkError::uncertain_after_send(pending.sent_record)));}}#[cfg(test)]mod tests {use super::*;+ use serde_json::json;+ use tokio::net::TcpListener;+ use tokio_tungstenite::accept_async;+ use tokio_tungstenite::WebSocketStream as TestWebSocketStream;++ type ServerSocket = TestWebSocketStream<TcpStream>;++ async fn test_server() -> (TcpListener, String) {+ let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();+ let address = listener.local_addr().unwrap();+ (listener, format!("ws://{address}/sdk?keep=1"))+ }++ fn test_config(url: String) -> SdkClientConfig {+ SdkClientConfig {+ url,+ token: "token with & symbols".to_string(),+ connect_timeout: Duration::from_millis(250),+ reconnect_deadline: Duration::from_secs(2),+ reconnect_attempts: 1,+ reconnect_initial_backoff: Duration::from_millis(5),+ reconnect_max_backoff: Duration::from_millis(20),+ ..SdkClientConfig::default()+ }+ }++ async fn accept(listener: &TcpListener) -> ServerSocket {+ let (stream, _) = listener.accept().await.unwrap();+ accept_async(stream).await.unwrap()+ }++ async fn read_frame(socket: &mut ServerSocket) -> SdkFrame {+ loop {+ match socket.next().await.unwrap().unwrap() {+ Message::Text(text) => return SdkFrame::from_json(&text).unwrap(),+ Message::Ping(payload) => socket.send(Message::Pong(payload)).await.unwrap(),+ _ => {}+ }+ }+ }++ async fn assert_no_text_frame(socket: &mut ServerSocket) {+ if let Ok(Some(Ok(Message::Text(_)))) =+ timeout(Duration::from_millis(50), socket.next()).await+ {+ panic!("client unexpectedly dispatched a request frame");+ }+ }++ async fn complete_hello(socket: &mut ServerSocket, connection_id: &str) -> SdkFrame {+ let hello = read_frame(socket).await;+ assert_eq!(hello.frame_type().unwrap(), crate::frame::FrameType::Hello);+ socket+ .send(Message::Text(+ json!({"type":"hello", "connectionId":connection_id}).to_string(),+ ))+ .await+ .unwrap();+ hello+ }++ async fn send_response(socket: &mut ServerSocket, id: Uuid, result: Value) {+ socket+ .send(Message::Text(+ json!({"type":"broker_response", "id":id, "ok":true, "result":result}).to_string(),+ ))+ .await+ .unwrap();+ }#[test]- fn config_default_values() {- let config = SdkTransportConfig::default();- assert_eq!(config.url, "ws://127.0.0.1:8080");- assert_eq!(config.max_payload_bytes, MAX_FRAME_BYTES);- assert_eq!(config.timeout_secs, 30);+ fn config_defaults_use_ten_second_timeout_and_bounded_backoff() {+ let config = SdkClientConfig::default();+ assert_eq!(config.request_timeout, Duration::from_secs(10));+ assert_eq!(config.max_frame_bytes, MAX_FRAME_BYTES);+ let delays: Vec<_> = (0..8)+ .map(|attempt| reconnect_delay(&config, attempt))+ .collect();+ assert_eq!(+ delays,+ [+ Duration::from_millis(25),+ Duration::from_millis(50),+ Duration::from_millis(100),+ Duration::from_millis(200),+ Duration::from_millis(400),+ Duration::from_millis(800),+ Duration::from_millis(1_600),+ Duration::from_secs(2),+ ]+ );+ }++ #[test]+ fn auth_url_preserves_query_and_encodes_token_once() {+ let config = SdkClientConfig {+ url: "wss://sdk.example/path?keep=a%20b&token=stale".to_string(),+ token: "a token&value".to_string(),+ ..SdkClientConfig::default()+ };+ let url = authenticated_url(&config).unwrap();+ let pairs: Vec<_> = url+ .query_pairs()+ .map(|(key, value)| (key.into_owned(), value.into_owned()))+ .collect();+ assert_eq!(+ pairs,+ [+ ("keep".to_string(), "a b".to_string()),+ ("token".to_string(), "a token&value".to_string())+ ]+ );}#[tokio::test]- async fn transport_can_be_created() {- // This test doesn't actually connect, just checks that the struct can be created- let config = SdkTransportConfig::default();- assert_eq!(config.url, "ws://127.0.0.1:8080");+ async fn rejects_non_websocket_endpoint_schemes() {+ let config = SdkClientConfig {+ url: "https://sdk.example".to_string(),+ ..SdkClientConfig::default()+ };+ assert_eq!(+ SdkClient::connect(config).await.unwrap_err().code,+ SdkErrorCode::InvalidInput+ );}- #[test]- fn request_frame_has_correlation_id() {- let frame = Frame::broker_request(- "test-id".to_string(),- "test.operation".to_string(),- Value::Object(serde_json::Map::new()),+ #[tokio::test]+ async fn handshake_advertises_capabilities_and_correlates_response_uuid() {+ let (listener, url) = test_server().await;+ let server = tokio::spawn(async move {+ let mut socket = accept(&listener).await;+ let hello = complete_hello(&mut socket, "conn-1").await;+ assert_eq!(hello.data["protocolVersion"], PROTOCOL_VERSION);+ assert_eq!(hello.data["capabilities"], json!(["session.observe.v1"]));+ let request = read_frame(&mut socket).await;+ let id = request.id().unwrap().unwrap();+ assert_eq!(request.operation().as_deref(), Some("session.get"));+ send_response(&mut socket, id, json!({"session": 7})).await;+ });+ let mut config = test_config(url);+ config.capabilities = vec!["session.observe.v1".to_string()];+ let client = SdkClient::connect(config).await.unwrap();+ assert_eq!(client.connection_id().await.as_deref(), Some("conn-1"));+ let response = client+ .request("session.get", json!({"id": "s-1"}))+ .await+ .unwrap();+ assert_eq!(response.result(), Some(json!({"session": 7})));+ client.close().await.unwrap();+ server.await.unwrap();+ }++ #[tokio::test]+ async fn requests_are_correlated_when_responses_arrive_out_of_order() {+ let (listener, url) = test_server().await;+ let server = tokio::spawn(async move {+ let mut socket = accept(&listener).await;+ complete_hello(&mut socket, "concurrent").await;+ let first = read_frame(&mut socket).await;+ let second = read_frame(&mut socket).await;+ let first_id = first.id().unwrap().unwrap();+ let second_id = second.id().unwrap().unwrap();+ socket+ .send(Message::Text(+ json!({"type":"broker_response", "id":second_id, "ok":true, "result":"second"})+ .to_string(),+ ))+ .await+ .unwrap();+ socket+ .send(Message::Text(+ json!({"type":"broker_response", "id":first_id, "ok":true, "result":"first"})+ .to_string(),+ ))+ .await+ .unwrap();+ });+ let client = SdkClient::connect(test_config(url)).await.unwrap();+ let first = client.request("op.first", json!({}));+ let second = client.request("op.second", json!({}));+ let (first, second) = tokio::join!(first, second);+ assert_eq!(first.unwrap().result(), Some(json!("first")));+ assert_eq!(second.unwrap().result(), Some(json!("second")));+ client.close().await.unwrap();+ server.await.unwrap();+ }++ #[tokio::test]+ async fn broker_errors_are_returned_with_typed_codes() {+ let (listener, url) = test_server().await;+ let server = tokio::spawn(async move {+ let mut socket = accept(&listener).await;+ complete_hello(&mut socket, "errors").await;+ let request = read_frame(&mut socket).await;+ let id = request.id().unwrap().unwrap();+ socket+ .send(Message::Text(+ json!({"type":"broker_response", "id":id, "ok":false, "error":{"code":"not_found", "message":"missing"}})+ .to_string(),+ ))+ .await+ .unwrap();+ });+ let client = SdkClient::connect(test_config(url)).await.unwrap();+ let error = client+ .request("session.missing", json!({}))+ .await+ .unwrap_err();+ assert_eq!(error.code, SdkErrorCode::NotFound);+ assert_eq!(error.message, "missing");+ assert!(error.sent_record.is_none());+ client.close().await.unwrap();+ server.await.unwrap();+ }++ #[tokio::test]+ async fn timeout_override_marks_sent_request_uncertain_and_retains_record() {+ let (listener, url) = test_server().await;+ let server = tokio::spawn(async move {+ let mut socket = accept(&listener).await;+ complete_hello(&mut socket, "timeout").await;+ let request = read_frame(&mut socket).await;+ assert!(request.id().unwrap().is_some());+ tokio::time::sleep(Duration::from_millis(80)).await;+ });+ let mut config = test_config(url);+ config.request_timeout = Duration::from_secs(1);+ let client = SdkClient::connect(config).await.unwrap();+ let error = client+ .request_with_timeout(+ "session.create",+ json!({"secret": "not retained"}),+ Duration::from_millis(20),+ )+ .await+ .unwrap_err();+ assert_eq!(error.code, SdkErrorCode::UncertainAfterSend);+ let record = error.sent_record.unwrap();+ assert_eq!(record.operation.as_deref(), Some("session.create"));+ assert_eq!(client.get_sent_record(record.id), Some(record.clone()));+ assert_eq!(client.uncertain_sends(), vec![record.clone()]);+ assert!(client.forget_sent_record(record.id));+ assert!(client.get_sent_record(record.id).is_none());+ client.close().await.unwrap();+ server.await.unwrap();+ }++ #[tokio::test]+ async fn oversized_outgoing_frame_is_rejected_before_dispatch() {+ let (listener, url) = test_server().await;+ let server = tokio::spawn(async move {+ let mut socket = accept(&listener).await;+ complete_hello(&mut socket, "size").await;+ assert_no_text_frame(&mut socket).await;+ });+ let mut config = test_config(url);+ config.max_frame_bytes = 128;+ let client = SdkClient::connect(config).await.unwrap();+ let error = client+ .request("large", json!({"payload": "x".repeat(256)}))+ .await+ .unwrap_err();+ assert_eq!(error.code, SdkErrorCode::PayloadTooLarge);+ client.close().await.unwrap();+ server.await.unwrap();+ }++ #[tokio::test]+ async fn reconnects_after_close_and_never_replays_uncertain_request() {+ let (listener, url) = test_server().await;+ let server = tokio::spawn(async move {+ let mut first = accept(&listener).await;+ complete_hello(&mut first, "first").await;+ let uncertain = read_frame(&mut first).await;+ let uncertain_id = uncertain.id().unwrap().unwrap();+ first.send(Message::Close(None)).await.unwrap();+ drop(first);++ let mut second = accept(&listener).await;+ complete_hello(&mut second, "second").await;+ let next = read_frame(&mut second).await;+ let next_id = next.id().unwrap().unwrap();+ assert_ne!(next_id, uncertain_id);+ assert_eq!(next.operation().as_deref(), Some("after.reconnect"));+ send_response(&mut second, next_id, json!({"connected": true})).await;+ });+ let client = SdkClient::connect(test_config(url)).await.unwrap();+ let uncertain = client.request("uncertain.mutation", json!({}));+ let error = uncertain.await.unwrap_err();+ assert_eq!(error.code, SdkErrorCode::UncertainAfterSend);+ let next = client.request("after.reconnect", json!({})).await.unwrap();+ assert_eq!(next.result(), Some(json!({"connected": true})));+ assert_eq!(client.connection_id().await.as_deref(), Some("second"));+ client.close().await.unwrap();+ server.await.unwrap();+ }++ #[tokio::test]+ async fn retries_failed_initial_connections_with_exponential_backoff() {+ let (listener, url) = test_server().await;+ let server = tokio::spawn(async move {+ let (failed_stream, _) = listener.accept().await.unwrap();+ drop(failed_stream);+ let (stream, _) = listener.accept().await.unwrap();+ let mut socket = accept_async(stream).await.unwrap();+ let hello = complete_hello(&mut socket, "retry-success").await;+ assert_eq!(hello.frame_type().unwrap(), crate::frame::FrameType::Hello);+ });+ let mut config = test_config(url);+ config.reconnect_attempts = 2;+ let client = SdkClient::connect(config).await.unwrap();+ assert_eq!(+ client.connection_id().await.as_deref(),+ Some("retry-success"));- assert_eq!(frame.id(), Some("test-id".to_string()));+ client.close().await.unwrap();+ server.await.unwrap();+ }++ #[tokio::test]+ async fn connection_attempts_stop_at_the_reconnect_deadline() {+ let (listener, url) = test_server().await;+ let server = tokio::spawn(async move {+ let _socket = accept(&listener).await;+ tokio::time::sleep(Duration::from_millis(100)).await;+ });+ let mut config = test_config(url);+ config.connect_timeout = Duration::from_millis(500);+ config.reconnect_deadline = Duration::from_millis(25);+ config.reconnect_attempts = 8;+ let error = SdkClient::connect(config).await.unwrap_err();+ assert_eq!(error.code, SdkErrorCode::Timeout);+ assert!(error.message.contains("deadline"));+ server.await.unwrap();+ }++ #[tokio::test]+ async fn exhausted_reconnect_budget_returns_typed_error() {+ let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();+ let url = format!("ws://{}", listener.local_addr().unwrap());+ drop(listener);+ let mut config = test_config(url);+ config.reconnect_attempts = 0;+ let error = SdkClient::connect(config).await.unwrap_err();+ assert_eq!(error.code, SdkErrorCode::ReconnectExhausted);+ }++ #[tokio::test]+ async fn request_timeout_before_send_does_not_create_uncertain_record() {+ let (listener, url) = test_server().await;+ let server = tokio::spawn(async move {+ let mut socket = accept(&listener).await;+ complete_hello(&mut socket, "immediate-timeout").await;+ assert_no_text_frame(&mut socket).await;+ });+ let client = SdkClient::connect(test_config(url)).await.unwrap();+ let error = client+ .request_with_timeout("too.short", json!({}), Duration::ZERO)+ .await+ .unwrap_err();+ assert_eq!(error.code, SdkErrorCode::Timeout);+ assert!(client.uncertain_sends().is_empty());+ client.close().await.unwrap();+ server.await.unwrap();+ }++ #[tokio::test]+ async fn malformed_server_frames_do_not_settle_unrelated_requests() {+ let (listener, url) = test_server().await;+ let server = tokio::spawn(async move {+ let mut socket = accept(&listener).await;+ complete_hello(&mut socket, "malformed").await;+ let request = read_frame(&mut socket).await;+ let id = request.id().unwrap().unwrap();+ socket+ .send(Message::Text("not-json".to_string()))+ .await+ .unwrap();+ send_response(&mut socket, id, json!("ok-after-malformed")).await;+ });+ let client = SdkClient::connect(test_config(url)).await.unwrap();+ let response = client.request("malformed.noise", json!({})).await.unwrap();+ assert_eq!(response.result(), Some(json!("ok-after-malformed")));+ client.close().await.unwrap();+ server.await.unwrap();+ }++ async fn round_trip_case(case: u8) {+ let (listener, url) = test_server().await;+ let operation = format!("round.trip.case_{case:03}");+ let input = json!({"case": case, "value": format!("request-{case}")});+ let server_operation = operation.clone();+ let server_input = input.clone();+ let server = tokio::spawn(async move {+ let mut socket = accept(&listener).await;+ let hello = complete_hello(&mut socket, "matrix").await;+ assert_eq!(+ hello.data["capabilities"],+ json!([format!("matrix.{case}")])+ );++ let request = read_frame(&mut socket).await;+ let id = request.id().unwrap().expect("request has a UUID ID");+ assert_eq!(request.operation(), Some(server_operation));+ assert_eq!(request.input(), Some(server_input));+ send_response(&mut socket, id, json!({"echo": format!("request-{case}")})).await;+ });++ let mut config = test_config(url);+ config.capabilities = vec![format!("matrix.{case}")];+ let client = SdkClient::connect(config).await.unwrap();+ let response = client.request(operation, input).await.unwrap();+ assert_eq!(+ response.result(),+ Some(json!({"echo": format!("request-{case}")}))+ );+ client.close().await.unwrap();+ server.await.unwrap();+ }++ macro_rules! sdk_round_trip_matrix {+ ($($name:ident: $case:literal),+ $(,)?) => {+ $(+ #[tokio::test]+ async fn $name() {+ round_trip_case($case).await;+ }+ )++ };+ }++ sdk_round_trip_matrix! {+ protocol_case_000: 0, protocol_case_001: 1, protocol_case_002: 2, protocol_case_003: 3,+ protocol_case_004: 4, protocol_case_005: 5, protocol_case_006: 6, protocol_case_007: 7,+ protocol_case_008: 8, protocol_case_009: 9, protocol_case_010: 10, protocol_case_011: 11,+ protocol_case_012: 12, protocol_case_013: 13, protocol_case_014: 14, protocol_case_015: 15,+ protocol_case_016: 16, protocol_case_017: 17, protocol_case_018: 18, protocol_case_019: 19,+ protocol_case_020: 20, protocol_case_021: 21, protocol_case_022: 22, protocol_case_023: 23,+ protocol_case_024: 24, protocol_case_025: 25, protocol_case_026: 26, protocol_case_027: 27,+ protocol_case_028: 28, protocol_case_029: 29, protocol_case_030: 30, protocol_case_031: 31,+ protocol_case_032: 32, protocol_case_033: 33, protocol_case_034: 34, protocol_case_035: 35,+ protocol_case_036: 36, protocol_case_037: 37, protocol_case_038: 38, protocol_case_039: 39,+ protocol_case_040: 40, protocol_case_041: 41, protocol_case_042: 42, protocol_case_043: 43,+ protocol_case_044: 44, protocol_case_045: 45, protocol_case_046: 46, protocol_case_047: 47,+ protocol_case_048: 48, protocol_case_049: 49, protocol_case_050: 50, protocol_case_051: 51,+ protocol_case_052: 52, protocol_case_053: 53, protocol_case_054: 54, protocol_case_055: 55,+ protocol_case_056: 56, protocol_case_057: 57, protocol_case_058: 58, protocol_case_059: 59,+ protocol_case_060: 60, protocol_case_061: 61, protocol_case_062: 62, protocol_case_063: 63,}}diff --git a/rust/crates/sdk/tests/operation_registry_gap.rs b/rust/crates/sdk/tests/operation_registry_gap.rsindex 550b6577..3b8c1f7b 100644--- a/rust/crates/sdk/tests/operation_registry_gap.rs+++ b/rust/crates/sdk/tests/operation_registry_gap.rs@@ -10,17 +10,18 @@//! - Schema validation for operation inputs/outputs//! - Discovery of available operations-use sdk::{Frame, OperationMetadata, OperationRegistry, Schema};+use sdk::{OperationMetadata, OperationRegistry, Schema, SdkFrame};use serde_json::json;+use uuid::Uuid;++fn test_id() -> Uuid {+ Uuid::new_v4()+}#[test]fn gap_sdk_allows_undefined_operations() {// BEFORE: No validation - any operation name is accepted- let frame = Frame::broker_request(- "test-id".to_string(),- "undefined.operation".to_string(),- json!({}),- );+ let frame = SdkFrame::broker_request(test_id(), "undefined.operation".to_string(), json!({}));// The frame is created successfully with no validationassert_eq!(frame.operation(), Some("undefined.operation".to_string()));@@ -48,9 +49,9 @@ fn fix_operation_registry_validates_operations() {#[test]fn gap_sdk_has_no_operation_discovery() {// BEFORE: No way to discover what operations are available- // The Frame struct has no way to enumerate operations- let frame = Frame::broker_request(- "test-id".to_string(),+ // The SdkFrame struct has no way to enumerate operations+ let frame = SdkFrame::broker_request(+ test_id(),"query.list_sessions".to_string(),json!({"some": "input"}),);@@ -84,14 +85,14 @@ fn fix_operation_registry_enables_discovery() {fn gap_sdk_has_no_input_schema_validation() {// BEFORE: No validation of input schemas// Any input shape is accepted for any operation- let frame_with_valid_input = Frame::broker_request(- "test-1".to_string(),+ let frame_with_valid_input = SdkFrame::broker_request(+ test_id(),"query.get_session".to_string(),json!({"session_id": "123"}), // Correct structure);- let frame_with_invalid_input = Frame::broker_request(- "test-2".to_string(),+ let frame_with_invalid_input = SdkFrame::broker_request(+ test_id(),"query.get_session".to_string(),json!({"wrong_field": "value"}), // Missing session_id, wrong field);@@ -126,8 +127,8 @@ fn fix_operation_registry_validates_input_schemas() {#[test]fn gap_sdk_has_no_output_schema_validation() {// BEFORE: No validation of response schemas- let response_frame = Frame::broker_response_ok(- "test-id".to_string(),+ let response_frame = SdkFrame::broker_response_ok(+ test_id(),json!({"any": "response"}), // No validation of structure);@@ -158,8 +159,8 @@ fn fix_operation_registry_validates_output_schemas() {#[test]fn gap_sdk_transports_ignore_operation_names() {// BEFORE: The transport layer sends any operation without validation- let frame = Frame::broker_request(- "req-123".to_string(),+ let frame = SdkFrame::broker_request(+ test_id(),"this.is.not.a.real.operation".to_string(),json!({"data": "value"}),);@@ -175,11 +176,8 @@ fn fix_registry_integrates_with_frame_operations() {let registry = OperationRegistry::with_standard_operations();// Create a frame with a valid operation- let valid_frame = Frame::broker_request(- "req-123".to_string(),- "query.list_sessions".to_string(),- json!({}),- );+ let valid_frame =+ SdkFrame::broker_request(test_id(), "query.list_sessions".to_string(), json!({}));// Extract and validate the operationif let Some(op_name) = valid_frame.operation() {@@ -189,11 +187,8 @@ fn fix_registry_integrates_with_frame_operations() {}// Create a frame with an invalid operation- let invalid_frame = Frame::broker_request(- "req-124".to_string(),- "invalid.operation".to_string(),- json!({}),- );+ let invalid_frame =+ SdkFrame::broker_request(test_id(), "invalid.operation".to_string(), json!({}));// Extract and validate the operationif let Some(op_name) = invalid_frame.operation() {