iOS: Thread-safety race condition on skipDescriptorDiscovery causes connection timeout on reconnect

[jisaballo]

Bug Description

When skipDescriptorDiscovery: true is passed in the connect options, the first connection always succeeds, but subsequent connections to the same peripheral consistently fail with "Connection timeout".

Root Cause

Device.swift stores skipDescriptorDiscovery as a plain Bool property with no synchronization:

private var skipDescriptorDiscovery = false

• setOnConnected() writes this property from Capacitor's bridge thread
• didDiscoverCharacteristicsFor() reads it from the main thread (CoreBluetooth delegate queue, set in DeviceManager.swift via CBCentralManager(delegate: self, queue: DispatchQueue.main))

On the first connect, CoreBluetooth performs real GATT discovery (~1s), giving the bridge thread's write enough time to propagate to the main thread. On subsequent connects, CoreBluetooth uses cached GATT data, making didDiscoverCharacteristicsFor fire near-instantly — before the bridge thread's write is visible on the main thread. The stale default value false is read, causing the code to wait for descriptor discovery that never completes (since descriptors were never requested), and the connection times out.

Steps to Reproduce

1. Call BleClient.connect(deviceId, callback, { skipDescriptorDiscovery: true })
2. Perform a BLE operation (read/write)
3. Disconnect
4. Immediately connect again with the same options
5. → "Connection timeout" every time

Expected Behavior

All connections should succeed when skipDescriptorDiscovery: true is passed, regardless of whether it's the first or subsequent connection.

Proposed Fix

Use NSLock to synchronize access to skipDescriptorDiscovery:

// Device.swift

// Replace:
private var skipDescriptorDiscovery = false

// With:
private let skipDescriptorDiscoveryLock = NSLock()
private var _skipDescriptorDiscovery = false

Write in setOnConnected():

self.skipDescriptorDiscoveryLock.lock()
self._skipDescriptorDiscovery = skipDescriptorDiscovery
self.skipDescriptorDiscoveryLock.unlock()

Read in didDiscoverCharacteristicsFor():

self.skipDescriptorDiscoveryLock.lock()
let skipDescriptors = self._skipDescriptorDiscovery
self.skipDescriptorDiscoveryLock.unlock()

if !skipDescriptors {
    for characteristic in service.characteristics ?? [] {
        peripheral.discoverDescriptors(for: characteristic)
    }
}

let shouldResolve = skipDescriptors
    ? self.servicesDiscovered >= self.servicesCount
    : self.servicesDiscovered >= self.servicesCount && self.characteristicsDiscovered >= self.characteristicsCount

Environment

• Plugin version: 8.1.0
• Capacitor: 7.x
• iOS: 17/18
• Device: iPhone (not simulator — requires real BLE hardware)

Additional Context

We're currently using patch-package with this fix in production. Happy to submit a PR if the maintainers agree with the approach.

---

Update: Deeper Root Cause Found

After testing PR #810, I found that DispatchQueue.main.sync alone does not fix the issue. The actual root cause is in ThreadSafeDictionary.swift — the subscript setter uses queue.async(flags: .barrier):

set {
    queue.async(flags: .barrier) { self.dictionary[key] = newValue }
}

This means self.callbackMap[key] = callback in setOnConnected returns before the write completes. On reconnect, CoreBluetooth delegates fire near-instantly (cached GATT) and call self.callbackMap.removeValue(forKey: "connect") — which uses queue.sync — but the async write hasn't materialized yet. The callback is nil, the resolve is skipped, and the connection times out.

Fix: Change the setter to synchronous:

set {
    queue.sync(flags: .barrier) { self.dictionary[key] = newValue }
}

Tested with this one-line change + PR #810's DispatchQueue.main.sync approach — all reconnections succeed consistently (6/6 connects, zero timeouts).

[peitschie]

Thanks for this, and the offer to raise a fix too! Very helpful 🙂

Can I trouble you to try this patch instead before I merge it? #810

I've gone a slightly different route, as I realised that there is a slight risk with the other variables in the particular flow of a similar problem.

If this fixes your issue too... we can land it and cut a new release.

[jisaballo]

Hi @peitschie, I tested PR #810 and unfortunately the reconnection timeout still occurs. The DispatchQueue.main.sync approach in setOnConnected is correct and necessary, but it's not sufficient on its own.

The deeper issue is in ThreadSafeDictionary.swift. The subscript setter dispatches writes with queue.async(flags: .barrier):

// ThreadSafeDictionary.swift, line 12
set {
    queue.async(flags: .barrier) { self.dictionary[key] = newValue }
}

While the getter and removeValue(forKey:) both use queue.sync, the setter is fire-and-forget. This creates a race window: setOnConnected writes the callback via the async setter, then on fast reconnects the delegates fire and didDiscoverCharacteristicsFor tries to read/remove the callback — but the async write hasn't completed yet. The callback is nil, resolve("connect") silently returns, and the timeout fires.

Reproduction with PR #810 applied:

• 1st connection: ✅ (real GATT discovery takes ~1s, async write completes in time)
• 2nd+ connections: ❌ Connection timeout (cached GATT, delegates fire before async write)

Fix: Change the setter from async to sync:

set {
    queue.sync(flags: .barrier) { self.dictionary[key] = newValue }
}

With both PR #810 + this one-line fix, I tested 6 consecutive reconnections — all successful, zero timeouts.

This also affects skipDescriptorDiscovery indirectly: even if the boolean is written correctly (via DispatchQueue.main.sync), the callback stored in callbackMap may not be visible when the delegate tries to resolve it.

Happy to open a PR with this additional fix if you'd like.

[peitschie]

@jisaballo excellent diagnostics. I've added your fix + another spot (removeAll) that also had the same error.

Can you confirm this again?

I appreciate your patience!

[jisaballo]

Hi @peitschie, I've tested the updated PR #810 (with both the DispatchQueue.main.sync changes and the ThreadSafeDictionary fixes for setter + removeAll) and can confirm reconnections work reliably now — multiple connect → disconnect → reconnect cycles with zero timeouts.

Thank you for the prompt response and for taking the time to identify the removeAll spot as well. Much appreciated!

[peitschie]

The fix for this has been released in 8.1.1.

Thanks again for your work helping troubleshoot and test this @jisaballo ... makes me much more confident we've solved this!