WebSocket Cannot Reconnect When `isConnecting` Stays `true` Forever

[yoheimuta]

Describe the Bug

After Fix connection race when using WSEngine was merged, the isConnecting property was introduced to prevent multiple connection attempts. However, as reported in this comment, isConnecting sometimes remains true, which prevents users from reconnecting indefinitely.

Steps to Reproduce

1. Call connect()
2. Put the device into sleep mode so that the WebSocket connection closes.
3. The server goes down while the device is asleep.
4. Call connect() again to attempt a reconnection.
5. The server is back online.
6. The isConnecting flag remains true, preventing connect() from proceeding.

Expected Behavior

• The WebSocket can reconnect when the server is back online.
• The isConnecting flag should be reset to false once a previous connection attempt fails, allowing new connections.

Environment

• OS/Version: iOS 18.3.1
• Starscream Version: 4.0.6 and later
• Xcode Version: 16.0

Additional Context

• This issue is caused by isConnecting staying true after a failed connection attempt.
• A potential fix might involve resetting isConnecting when a connection is explicitly closed or when an error occurs.

[yoheimuta]

I was able to reproduce this issue using a sample project:

🔗 Sample Project: [SampleStarscream](https://github.com/yoheimuta/SampleStarscream)
🔗 Client Implementation: [WebSocketEventHandler.swift](https://github.com/yoheimuta/SampleStarscream/blob/main/SampleStarscream/WebSocketEventHandler.swift)

Additional Context

• This WebSocket handler attempts to connect on app initialization, when returning to the foreground, and during ping/pong reconnections.
• I added NSLog statements to a local Starscream project to debug the WebSocket state.
• Below are the logs when I reproduced the issue following the steps in the issue description:

# Start the app
Mar  3 19:05:27 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: connect
Mar  3 19:05:27 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: start isConnecting=false
Mar  3 19:05:27 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: start set isConnecting to true

# Shutdown server while the device is asleep
Mar  3 19:05:58 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: .peerClosed
Mar  3 19:05:58 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: disconnect
Mar  3 19:05:58 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: reset set isConnecting to false
Mar  3 19:05:58 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: forceStop set isConnecting to false
Mar  3 19:05:58 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: reset set isConnecting to false
Mar  3 19:05:58 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: forceStop set isConnecting to false
Mar  3 19:05:58 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: .cancelled set isConnecting to false

# Unlock the sleep screen
Mar  3 19:06:14 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: connect
Mar  3 19:06:14 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: start isConnecting=false
Mar  3 19:06:14 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: start set isConnecting to true
Mar  3 19:06:16 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: .peerClosed

# Enter foreground
Mar  3 19:06:25 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: connect
Mar  3 19:06:25 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: start isConnecting=true

# Cannot proceed
Mar  3 19:07:26 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: connect
Mar  3 19:07:26 SampleStarscream(Foundation)[18997] <Notice>: SS: WebSocket: start isConnecting=true

local Starscream project diff

diff --git a/Sources/Engine/WSEngine.swift b/Sources/Engine/WSEngine.swift
index 82fa5b2..552135a 100644
--- a/Sources/Engine/WSEngine.swift
+++ b/Sources/Engine/WSEngine.swift
@@ -67,6 +67,7 @@ FrameCollectorDelegate, HTTPHandlerDelegate {
         mutex.wait()
         let isConnecting = self.isConnecting
         let isConnected = canSend
+        NSLog("SS: WebSocket: start isConnecting=\(isConnecting)")
         mutex.signal()
         if isConnecting || isConnected {
             return
@@ -82,6 +83,7 @@ FrameCollectorDelegate, HTTPHandlerDelegate {
         }
         mutex.wait()
         self.isConnecting = true
+        NSLog("SS: WebSocket: start set isConnecting to true")
         mutex.signal()
         transport.connect(url: url, timeout: request.timeoutInterval, certificatePinning: certPinner)
     }
@@ -100,6 +102,7 @@ FrameCollectorDelegate, HTTPHandlerDelegate {
     public func forceStop() {
         mutex.wait()
         isConnecting = false
+        NSLog("SS: WebSocket: forceStop set isConnecting to false")
         mutex.signal()
         
         transport.disconnect()
@@ -164,14 +167,17 @@ FrameCollectorDelegate, HTTPHandlerDelegate {
         case .cancelled:
             mutex.wait()
             isConnecting = false
+            NSLog("SS: WebSocket: .cancelled set isConnecting to false")
             mutex.signal()
             
             broadcast(event: .cancelled)
         case .peerClosed:
             mutex.wait()
             isConnecting = false
+            NSLog("SS: WebSocket: .peerClosed set isConnecting to false")
             mutex.signal()
 
+            //NSLog("SS: WebSocket: .peerClosed")
             broadcast(event: .peerClosed)
         }
     }
@@ -187,6 +193,7 @@ FrameCollectorDelegate, HTTPHandlerDelegate {
             }
             mutex.wait()
             isConnecting = false
+            NSLog("SS: WebSocket: didReceiveHTTP set isConnecting to false")
             didUpgrade = true
             canSend = true
             mutex.signal()
@@ -262,6 +269,7 @@ FrameCollectorDelegate, HTTPHandlerDelegate {
         isConnecting = false
         canSend = false
         didUpgrade = false
+        NSLog("SS: WebSocket: reset set isConnecting to false")
         mutex.signal()
     }
     
diff --git a/Sources/Starscream/WebSocket.swift b/Sources/Starscream/WebSocket.swift
index 2f529a5..f15db92 100644
--- a/Sources/Starscream/WebSocket.swift
+++ b/Sources/Starscream/WebSocket.swift
@@ -127,11 +127,13 @@ open class WebSocket: WebSocketClient, EngineDelegate {
     }
     
     public func connect() {
+        NSLog("SS: WebSocket: connect")
         engine.register(delegate: self)
         engine.start(request: request)
     }
     
     public func disconnect(closeCode: UInt16 = CloseCode.normal.rawValue) {
+        NSLog("SS: WebSocket: disconnect")
         engine.stop(closeCode: closeCode)
     }
     

[yoheimuta]

Additional Related Scenario: .waiting connection

In addition to the previously reported issue where isConnecting remains true indefinitely after .peerClosed, we've identified another scenario where isConnecting fails to reset when a .waiting(error) event occurs.

Steps to Reproduce

1. Connect to WiFi.
2. Start the app and establish a WebSocket connection.
3. Wait for AutoLock (Sleep mode).
4. After 2 minutes, unlock the screen (but do not switch to the app).
5. Stay on the unlocked screen for 1 minute, then let the device go back to sleep.
6. Wait for another 1 minute, then enter the app foreground.
7. The isConnecting flag remains true, preventing connect() from proceeding.

Observed Behavior (Logs)

1️⃣ App Starts Normally

# Start the app
Mar  4 16:17:50 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: start set isConnecting to true
Mar  4 16:17:50 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: connect
Mar  4 16:17:50 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: start isConnecting=true
Mar  4 16:17:50 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: didReceiveHTTP set isConnecting to false

2️⃣ Device Wakes Up After Sleep

# Unlock the sleep screen
Mar  4 16:19:54 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: .peerClosed set isConnecting to false
Mar  4 16:19:54 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: reset set isConnecting to false
Mar  4 16:19:54 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: forceStop set isConnecting to false
Mar  4 16:19:54 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: disconnect
Mar  4 16:19:54 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: .cancelled set isConnecting to false

3️⃣ WebSocket Reconnects During Sleep

# Wait at the sleep screen
Mar  4 16:20:03 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: connect
Mar  4 16:20:03 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: start isConnecting=false
Mar  4 16:20:03 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: start set isConnecting to true

4️⃣ Enter Foreground & Encounter .waiting(error)

# Enter foreground
Mar  4 16:21:33 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: .waiting error=Optional(POSIXErrorCode(rawValue: 57): Socket is not connected)

5️⃣ Connection Fails to Proceed

# Cannot proceed
Mar  4 16:21:45 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: connect
Mar  4 16:21:45 SampleStarscream(Foundation)[24701] <Notice>: SS: WebSocket: start isConnecting=true

Root Cause

• The WebSocket enters a .waiting(error) state, but isConnecting is never reset to false.
• Because of this, subsequent connect() calls do nothing, since isConnecting is already true.

Expected Behavior After Fix

• When the WebSocket enters .waiting(error), isConnecting is now reset to false.
• The app can reconnect properly after unlocking from sleep.