feat(web): expose granular RDCleanPath error details (#1117)

Add RDCleanPathDetails struct to provide detailed error information for
RDCleanPath errors, including HTTP status codes, WSA error codes, and
TLS alert codes.

Allows the web client to distinguish between different types of network
errors (say, WSAEACCES/10013) instead of showing a generic RDCleanpath
error message.

Author: gabrielbauman

crates/iron-remote-desktop/src/error.rs

@@ -1,9 +1,36 @@
+//! Error handling types and traits for iron-remote-desktop.
+//!
+//! # Example: Handling RDCleanPath errors
+//!
+//! ```no_run
+//! # use iron_remote_desktop::*;
+//! # fn handle_error(error: impl IronError) {
+//! match error.kind() {
+//!     IronErrorKind::RDCleanPath => {
+//!         if let Some(details) = error.rdcleanpath_details() {
+//!             // Check for specific HTTP errors
+//!             if details.http_status_code() == Some(403) {
+//!                 // Handle forbidden/VNET deleted case
+//!             }
+//!             // Check for WSA errors
+//!             if details.wsa_error_code() == Some(10013) {
+//!                 // Handle permission denied
+//!             }
+//!         }
+//!     }
+//!     _ => {}
+//! }
+//! # }
+//! ```
+
 use wasm_bindgen::prelude::*;
 
 pub trait IronError {
     fn backtrace(&self) -> String;
 
     fn kind(&self) -> IronErrorKind;
+
+    fn rdcleanpath_details(&self) -> Option<RDCleanPathDetails>;
 }
 
 #[derive(Clone, Copy)]
@@ -19,8 +46,83 @@ pub enum IronErrorKind {
     AccessDenied,
     /// Something wrong happened when sending or receiving the RDCleanPath message
     RDCleanPath,
-    /// Couldn’t connect to proxy
+    /// Couldn't connect to proxy
     ProxyConnect,
     /// Protocol negotiation failed
     NegotiationFailure,
 }
+
+/// Detailed error information for RDCleanPath errors.
+///
+/// When an RDCleanPath error occurs, this structure provides granular details
+/// about the underlying cause, including HTTP status codes, Windows Socket errors,
+/// and TLS alert codes.
+#[derive(Clone, Copy, Debug)]
+#[wasm_bindgen]
+pub struct RDCleanPathDetails {
+    http_status_code: Option<u16>,
+    wsa_error_code: Option<u16>,
+    tls_alert_code: Option<u8>,
+}
+
+// NOTE: multiple impl blocks required because wasm-bindgen doesn't support
+// non-exported constructors in #[wasm_bindgen] impl blocks
+#[wasm_bindgen]
+impl RDCleanPathDetails {
+    /// HTTP status code if the error originated from an HTTP response.
+    ///
+    /// Common values:
+    /// - 403: Forbidden (e.g., deleted VNET, insufficient permissions)
+    /// - 404: Not Found
+    /// - 500: Internal Server Error
+    /// - 502: Bad Gateway
+    /// - 503: Service Unavailable
+    #[wasm_bindgen(getter, js_name = httpStatusCode)]
+    pub fn http_status_code(&self) -> Option<u16> {
+        self.http_status_code
+    }
+
+    /// Windows Socket API (WSA) error code.
+    ///
+    /// Common values:
+    /// - 10013: Permission denied (WSAEACCES) - often indicates deleted/invalid VNET
+    /// - 10060: Connection timed out (WSAETIMEDOUT)
+    /// - 10061: Connection refused (WSAECONNREFUSED)
+    /// - 10051: Network is unreachable (WSAENETUNREACH)
+    /// - 10065: No route to host (WSAEHOSTUNREACH)
+    #[wasm_bindgen(getter, js_name = wsaErrorCode)]
+    pub fn wsa_error_code(&self) -> Option<u16> {
+        self.wsa_error_code
+    }
+
+    /// TLS alert code if the error occurred during TLS handshake.
+    ///
+    /// Common values:
+    /// - 40: Handshake failure
+    /// - 42: Bad certificate
+    /// - 45: Certificate expired
+    /// - 48: Unknown CA
+    /// - 112: Unrecognized name
+    #[wasm_bindgen(getter, js_name = tlsAlertCode)]
+    pub fn tls_alert_code(&self) -> Option<u8> {
+        self.tls_alert_code
+    }
+}
+
+#[expect(
+    clippy::allow_attributes,
+    reason = "Unfortunately, expect attribute doesn't work with clippy::multiple_inherent_impl lint"
+)]
+#[allow(
+    clippy::multiple_inherent_impl,
+    reason = "We don't want to expose the constructor to JS"
+)]
+impl RDCleanPathDetails {
+    pub fn new(http_status_code: Option<u16>, wsa_error_code: Option<u16>, tls_alert_code: Option<u8>) -> Self {
+        Self {
+            http_status_code,
+            wsa_error_code,
+            tls_alert_code,
+        }
+    }
+}

crates/iron-remote-desktop/src/lib.rs

@@ -12,7 +12,7 @@ mod session;
 pub use clipboard::{ClipboardData, ClipboardItem};
 pub use cursor::CursorStyle;
 pub use desktop_size::DesktopSize;
-pub use error::{IronError, IronErrorKind};
+pub use error::{IronError, IronErrorKind, RDCleanPathDetails};
 pub use extension::Extension;
 pub use input::{DeviceEvent, InputTransaction, RotationUnit};
 pub use session::{Session, SessionBuilder, SessionTerminationInfo};
@@ -431,6 +431,11 @@ macro_rules! make_bridge {
             pub fn kind(&self) -> $crate::IronErrorKind {
                 $crate::IronError::kind(&self.0)
             }
+
+            #[wasm_bindgen(js_name = rdcleanpathDetails)]
+            pub fn rdcleanpath_details(&self) -> Option<$crate::RDCleanPathDetails> {
+                $crate::IronError::rdcleanpath_details(&self.0)
+            }
         }
     };
 }

crates/ironrdp-web/src/error.rs

@@ -1,16 +1,26 @@
-use iron_remote_desktop::IronErrorKind;
+use iron_remote_desktop::{IronErrorKind, RDCleanPathDetails};
 use ironrdp::connector::{self, sspi, ConnectorErrorKind};
 
 pub(crate) struct IronError {
     kind: IronErrorKind,
     source: anyhow::Error,
+    rdcleanpath_details: Option<RDCleanPathDetails>,
 }
 
 impl IronError {
     pub(crate) fn with_kind(mut self, kind: IronErrorKind) -> Self {
         self.kind = kind;
         self
     }
+
+    pub(crate) fn with_rdcleanpath_details(mut self, details: RDCleanPathDetails) -> Self {
+        debug_assert!(
+            matches!(self.kind, IronErrorKind::RDCleanPath),
+            "rdcleanpath_details should only be set for RDCleanPath errors"
+        );
+        self.rdcleanpath_details = Some(details);
+        self
+    }
 }
 
 impl iron_remote_desktop::IronError for IronError {
@@ -21,6 +31,10 @@ impl iron_remote_desktop::IronError for IronError {
     fn kind(&self) -> IronErrorKind {
         self.kind
     }
+
+    fn rdcleanpath_details(&self) -> Option<RDCleanPathDetails> {
+        self.rdcleanpath_details
+    }
 }
 
 impl From<connector::ConnectorError> for IronError {
@@ -44,6 +58,7 @@ impl From<connector::ConnectorError> for IronError {
         Self {
             kind,
             source: anyhow::Error::new(e),
+            rdcleanpath_details: None,
         }
     }
 }
@@ -53,6 +68,7 @@ impl From<ironrdp::session::SessionError> for IronError {
         Self {
             kind: IronErrorKind::General,
             source: anyhow::Error::new(e),
+            rdcleanpath_details: None,
         }
     }
 }
@@ -62,6 +78,7 @@ impl From<anyhow::Error> for IronError {
         Self {
             kind: IronErrorKind::General,
             source: e,
+            rdcleanpath_details: None,
         }
     }
 }

crates/ironrdp-web/src/session.rs

@@ -1113,9 +1113,15 @@ where
                     server_addr: _,
                 } => (x224_connection_response, server_cert_chain),
                 ironrdp_rdcleanpath::RDCleanPath::GeneralErr(error) => {
+                    let details = iron_remote_desktop::RDCleanPathDetails::new(
+                        error.http_status_code,
+                        error.wsa_last_error,
+                        error.tls_alert_code,
+                    );
                     return Err(
                         IronError::from(anyhow::Error::new(error).context("received an RDCleanPath error"))
-                            .with_kind(IronErrorKind::RDCleanPath),
+                            .with_kind(IronErrorKind::RDCleanPath)
+                            .with_rdcleanpath_details(details),
                     );
                 }
                 ironrdp_rdcleanpath::RDCleanPath::NegotiationErr {

web-client/iron-remote-desktop/src/interfaces/Error.ts

@@ -8,7 +8,14 @@
     NegotiationFailure = 6,
 }
 
+export interface RDCleanPathDetails {
+    readonly httpStatusCode?: number;
+    readonly wsaErrorCode?: number;
+    readonly tlsAlertCode?: number;
+}
+
 export interface IronError {
     backtrace: () => string;
     kind: () => IronErrorKind;
+    rdcleanpathDetails: () => RDCleanPathDetails | undefined;
 }

web-client/iron-remote-desktop/src/main.ts

@@ -1,7 +1,7 @@
 export * as default from './iron-remote-desktop.svelte';
 export type { ResizeEvent } from './interfaces/ResizeEvent';
 export type { NewSessionInfo } from './interfaces/NewSessionInfo';
-export type { IronError, IronErrorKind } from './interfaces/Error';
+export type { IronError, IronErrorKind, RDCleanPathDetails } from './interfaces/Error';
 export type { SessionTerminationInfo } from './interfaces/SessionTerminationInfo';
 export type { ClipboardData } from './interfaces/ClipboardData';
 export type { ClipboardItem } from './interfaces/ClipboardItem';