Add Error::is_connection_lost() predicate for reconnect loops (#685) (#690)

* Add Error::is_connection_lost() predicate for reconnect loops (#685)

Public predicate so reconnect consumers branch on connection loss without
matching internal Error variants. Matches ConnectionReset/ConnectionFailed
and connection-kind Io errors; excludes Shutdown (intentional teardown) and
ConnectionRejected (unrecoverable handshake refusal).

Internal is_connection_error() now delegates to the public method. README,
stream_retry example, and api-patterns docs adopt the new idiom.

* Break on terminal ConnectionFailed in stream-retry idiom

is_connection_lost() also matches ConnectionFailed, which the transport
returns only after reconnection permanently fails and the client shuts
down. Resubscribing then loops on a dead client (panicking via .expect).
Add a terminal ConnectionFailed arm before the is_connection_lost guard
in the stream_retry example and the README idiom.

* Scope is_connection_lost to recoverable loss; drop ConnectionFailed

Distillation pass (SRP/composability): is_connection_lost lumped terminal
ConnectionFailed (reconnect exhausted) in with recoverable mid-stream loss,
forcing every correct consumer to de-lump it with a preceding match arm.
ConnectionFailed is produced only by reconnect() exhaustion and never reaches
the transport read-error branch that calls is_connection_error, so dropping it
from the predicate leaves reconnect behavior unchanged.

Predicate now matches ConnectionReset + connection-kind Io only; doc reworded
to match. README/example drop the now-redundant terminal arm (ConnectionFailed
falls through to the generic give-up arm), restoring the clean two-arm idiom.

* Update is_connection_error test: ConnectionFailed is terminal

The predicate now treats ConnectionFailed (reconnect exhausted) as terminal,
not a recoverable mid-stream loss. Flip the stale test case expectation from
true to false to match the new contract. This test lives under the
client::error_handler path, which the 'cargo test errors' filter never ran.

Author: wboayue

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `ConnectivityStatus` enum with `ConnectivityStatus::from_code()` and `Notice::connectivity_status()` to expose data-farm connectivity sub-states (Ok / Broken / Inactive / Connecting) within the 2100–2169 warning band (#684).
+- `Error::is_connection_lost()` predicate so reconnect loops can branch on connection loss without matching internal error variants (#685).
 
 ## [3.1.0] - 2026-06-19
 

README.md

@@ -809,10 +809,12 @@ fn main() {
             match item {
                 Ok(SubscriptionItem::Data(bar)) => println!("bar: {bar:?}"),
                 Ok(SubscriptionItem::Notice(note)) => eprintln!("notice: {note}"),
-                Err(Error::ConnectionReset) => {
-                    eprintln!("Connection reset. Retrying stream...");
+                Err(e) if e.is_connection_lost() => {
+                    eprintln!("Connection lost. Retrying stream...");
                     continue 'outer;
                 }
+                // Everything else — including terminal ConnectionFailed (reconnect
+                // exhausted) — is not recoverable here, so stop.
                 Err(e) => {
                     eprintln!("error: {e}");
                     break 'outer;

docs/api-patterns.md

@@ -511,7 +511,7 @@ match client.market_data(contract).subscribe() {
 for result in subscription {
     match result {
         Ok(data) => process(data),
-        Err(Error::ConnectionReset) => {
+        Err(e) if e.is_connection_lost() => {
             // Resubscribe after reconnection
             break;
         },

examples/sync/stream_retry.rs

@@ -8,7 +8,7 @@
 
 use ibapi::client::blocking::Client;
 use ibapi::contracts::Contract;
-use ibapi::{market_data::TradingHours, Error};
+use ibapi::market_data::TradingHours;
 
 fn main() {
     env_logger::init();
@@ -29,10 +29,12 @@ fn main() {
         for bar in subscription.iter_data() {
             match bar {
                 Ok(bar) => println!("bar: {bar:?}"),
-                Err(Error::ConnectionReset) => {
-                    eprintln!("Connection reset. Retrying stream...");
+                Err(e) if e.is_connection_lost() => {
+                    eprintln!("Connection lost. Retrying stream...");
                     continue 'retry;
                 }
+                // Everything else — including terminal ConnectionFailed (reconnect
+                // exhausted, client shut down) — is not recoverable here, so give up.
                 Err(e) => {
                     eprintln!("error: {e}");
                     break 'retry;

src/client/error_handler/mod.rs

@@ -14,16 +14,12 @@ use crate::errors::Error;
 /// Maximum number of retries for transient errors
 pub(crate) const MAX_RETRIES: u32 = 3;
 
-/// Checks if the error is a connection-related IO error that should trigger reconnection
+/// Checks if the error is a connection-related error that should trigger reconnection.
+///
+/// Delegates to the public [`Error::is_connection_lost`] predicate so transport
+/// reconnect logic and downstream consumers share one definition.
 pub(crate) fn is_connection_error(error: &Error) -> bool {
-    match error {
-        Error::Io(io_err) => matches!(
-            io_err.kind(),
-            ErrorKind::ConnectionReset | ErrorKind::ConnectionAborted | ErrorKind::UnexpectedEof | ErrorKind::BrokenPipe
-        ),
-        Error::ConnectionReset | Error::ConnectionFailed => true,
-        _ => false,
-    }
+    error.is_connection_lost()
 }
 
 /// Checks if the error is a timeout that can be safely ignored

src/client/error_handler/tests.rs

@@ -37,9 +37,11 @@ fn test_is_connection_error() {
             expected: true,
         },
         TestCase {
-            name: "connection_failed",
+            // ConnectionFailed is returned only after reconnection is exhausted —
+            // terminal, not a recoverable mid-stream loss — so it is not a reconnect trigger.
+            name: "connection_failed_is_terminal",
             error: Error::ConnectionFailed,
-            expected: true,
+            expected: false,
         },
         TestCase {
             name: "cancelled_not_connection",

src/errors.rs

@@ -183,6 +183,54 @@ impl Error {
     pub(crate) fn eof_at(i: usize, label: &str) -> Error {
         Error::Parse(i, String::new(), format!("expected {label} and found end of message"))
     }
+
+    /// Returns `true` if this error means the TWS/Gateway connection was lost
+    /// mid-stream and the client should reconnect, rather than retry the in-flight
+    /// request.
+    ///
+    /// Matches [`Error::ConnectionReset`] and connection-kind [`Error::Io`] errors
+    /// (broken pipe, unexpected EOF, connection reset/abort) — recoverable losses
+    /// where re-establishing the connection is the right response.
+    ///
+    /// Returns `false` for failures reconnecting cannot recover, so a read loop can
+    /// branch on them separately to stop retrying: intentional teardown
+    /// ([`Error::Shutdown`]), handshake refusal ([`Error::ConnectionRejected`]), and
+    /// exhausted reconnection ([`Error::ConnectionFailed`], returned only after the
+    /// transport already gave up).
+    ///
+    /// # Examples
+    ///
+    /// In a subscription read loop, branch on this predicate to decide whether to
+    /// re-establish the connection or surface a request-level failure:
+    ///
+    /// ```
+    /// use ibapi::Error;
+    ///
+    /// fn on_stream_error(err: Error) -> Result<(), Error> {
+    ///     if err.is_connection_lost() {
+    ///         // tear down and resubscribe, then keep going
+    ///         Ok(())
+    ///     } else {
+    ///         // a request-level failure (or terminal disconnect) — surface it
+    ///         Err(err)
+    ///     }
+    /// }
+    ///
+    /// assert!(on_stream_error(Error::ConnectionReset).is_ok());
+    /// assert!(on_stream_error(Error::ConnectionFailed).is_err()); // reconnect exhausted
+    /// assert!(on_stream_error(Error::Shutdown).is_err());
+    /// ```
+    pub fn is_connection_lost(&self) -> bool {
+        use std::io::ErrorKind;
+        match self {
+            Error::Io(io_err) => matches!(
+                io_err.kind(),
+                ErrorKind::ConnectionReset | ErrorKind::ConnectionAborted | ErrorKind::UnexpectedEof | ErrorKind::BrokenPipe
+            ),
+            Error::ConnectionReset => true,
+            _ => false,
+        }
+    }
 }
 
 // Manual Clone because `std::io::Error` and `time::error::Parse` don't derive it.

src/errors_tests.rs

@@ -261,3 +261,55 @@ fn error_is_non_exhaustive() {
     fn assert_non_exhaustive<T: StdError>() {}
     assert_non_exhaustive::<Error>();
 }
+
+#[test]
+fn is_connection_lost_true_for_connection_variants() {
+    assert!(Error::ConnectionReset.is_connection_lost());
+
+    for kind in [
+        io::ErrorKind::ConnectionReset,
+        io::ErrorKind::ConnectionAborted,
+        io::ErrorKind::UnexpectedEof,
+        io::ErrorKind::BrokenPipe,
+    ] {
+        let error = Error::Io(io::Error::new(kind, "disconnected"));
+        assert!(error.is_connection_lost(), "{kind:?} should count as connection-lost");
+    }
+}
+
+#[test]
+fn is_connection_lost_false_for_non_connection() {
+    let cases = [
+        Error::Shutdown,
+        // Reconnection exhausted — terminal, not a recoverable mid-stream loss.
+        Error::ConnectionFailed,
+        Error::ConnectionRejected("allow-list mismatch".to_string()),
+        Error::Cancelled,
+        tws_error_notice(200, "No security found"),
+        Error::Io(io::Error::new(io::ErrorKind::NotFound, "missing")),
+        Error::Simple("boom".to_string()),
+        Error::Parse(1, "v".to_string(), "m".to_string()),
+    ];
+
+    for error in cases {
+        assert!(!error.is_connection_lost(), "{error:?} should not count as connection-lost");
+    }
+}
+
+#[test]
+fn is_connection_error_delegates_to_is_connection_lost() {
+    use crate::client::error_handler::is_connection_error;
+
+    let cases = [
+        Error::ConnectionReset,
+        Error::ConnectionFailed,
+        Error::Io(io::Error::new(io::ErrorKind::BrokenPipe, "x")),
+        Error::Shutdown,
+        Error::Cancelled,
+        Error::Io(io::Error::new(io::ErrorKind::NotFound, "x")),
+    ];
+
+    for error in cases {
+        assert_eq!(is_connection_error(&error), error.is_connection_lost(), "diverged for {error:?}");
+    }
+}