feat(sdk): complete WebSocket client transport (#3349)

Co-authored-by: clawdbot <clawdbot@ultraworkers.dev>
This commit is contained in:
Bellmanandclawdbot authored and GitHub committed 2026-10-13 03:40:03 +01:00
1 parent a35caea528
commit 192d40a860
7 files changed
+1541 -388

No files matched your search

+128 -40
View File
@@ -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 operation
UnknownOperation,
/// Payload too large (>4 MiB)
NotFound,
PayloadTooLarge,
/// Authentication token mismatch
Unauthorized,
/// Broker or session unavailable
EndpointCredentialForbidden,
Unavailable,
/// WebSocket connection error
ConnectionError,
/// Request timeout
ConnectionClosed,
Timeout,
/// Frame parsing or validation error
FrameError,
/// Request/response correlation failure
CorrelationError,
/// 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"));
}
}