feat(web): expose granular RDCleanPath error details

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';