fix(bindings): null-guard BluetoothDevice.connectGatt return in connectToDevice

[taayyohh]

Problem

BluetoothDevice.connectGatt is declared @Nullable in the Android framework. Kotlin treats the return as a platform type, but MeshConnectionRegistry.registerGatt takes a non-null BluetoothGatt, so a null return trips the compiler-inserted Intrinsics.checkNotNullParameter and crashes with NullPointerException.

connectGatt returns null when the adapter has just turned off, when the underlying hardware handle is stale, or when the device unbonded between scan and connect — the same adapter-race conditions that already motivate the SecurityException handler at the tail of connectToDevice.

Fix

Guard the connectGatt return before it reaches registerGatt. On null:

• Log at info and emit an info-level diagnostic (adapter-off is a user action, not an SDK error).
• Call connections.consumePendingRole(device.address) to release the pending role reserved for this address. This mirrors the RSSI-skip, connection-cap, and SecurityException paths — without it, the pending-role reservation leaks and blocks future connection attempts to that address.
• return out of the synchronized(connectionLock) { ... } block, matching the early-return convention used by the existing skip paths in the same block.

Why this is a real crash and not theoretical

Same adapter-off race as the IllegalStateException scan-site crashes filed as a sibling PR. Three users, three events on the pre-patch version of the MINE app before this shipped as a patch-package override.

Notes

• Diff is purely additive.
• Comments describe the invariant in plain language — no Linear or Sentry IDs in source per MINE's style guide.
• Retires Linear OFF-1985 on the MINE side.
• Part of a 3-PR patch-elimination series against fix(bindings): promote MeshForegroundService to foreground in onCreate + add Stop action #278 (foreground-service promotion + Stop action) and fix(bindings): catch IllegalStateException from BluetoothLeScanner scan sites #279 (BLE scan-site IllegalStateException catch). All three retire the same MINE-side mesh-sdk patch.

[linear]

OFF-1985 mesh-sdk: BleTransportFacade.connectToDevice NPE — connectGatt platform-nullable

Upstream request for Gokul (mesh-sdk maintainer)

Repro / observation

On v1.0.14 (mesh-sdk 0.12.0), Play Console reports 3 users / 3 events hitting:

NullPointerException:
  at com.offlineprotocol.ble.BleTransportFacade.connectToDevice (BleTransportFacade.kt:2099)
  at com.offlineprotocol.ble.BleTransportFacade.handleScanResult (BleTransportFacade.kt:1792)
  at com.offlineprotocol.ble.BleTransportFacade.access$handleScanResult (BleTransportFacade.kt:152)
  at BleTransportFacade$startScanning$1.onScanResult$lambda$0 (BleTransportFacade.kt:1356)
  at BleTransportFacade$startScanning$1$$ExternalSyntheticLambda2.run

Flow: BLE scan callback fires → onScanResult$lambda$0 posts a Runnable to a Handler → handleScanResult → connectToDevice at line 2099 crashes with NPE.

Root cause

BleTransportFacade.connectToDevice at lines 2098–2099:

val gatt = device.connectGatt(context, false, centralClient.callback, BluetoothDevice.TRANSPORT_LE)
connections.registerGatt(device.address, gatt)  // line 2099 — NPE here

BluetoothDevice.connectGatt() is declared @Nullable BluetoothGatt in the Android framework — the documented contract is that it returns null when the adapter is off, the hardware handle is stale, or the device unbonded between scan and connect (see e.g. Android source).

Kotlin treats this as a platform type (BluetoothGatt!), but MeshConnectionRegistry.registerGatt(address: String, gatt: BluetoothGatt) declares its second parameter as non-null. The Kotlin compiler inserts Intrinsics.checkNotNullParameter(gatt, "gatt") at the call site — so when connectGatt returns null, the intrinsic throws NullPointerException before registerGatt even executes.

This is the same class of adapter race that motivated OFF-1896 (BT adapter flips off between the isScanning check and the framework call, or the discovered device unbonds between the scan callback and the connect attempt), but on the connect path rather than the scan path — different code path, different exception class, requires its own guard.

Suggested fix (upstream, minimal)

Null-guard the return of connectGatt in connectToDevice:

val gatt = device.connectGatt(context, false, centralClient.callback, BluetoothDevice.TRANSPORT_LE)
if (gatt == null) {
    Log.i(TAG, "connectGatt returned null for ${device.address} — adapter unavailable")
    connections.consumePendingRole(device.address)  // release the pending-connection slot reserved above
    return
}
connections.registerGatt(device.address, gatt)

The consumePendingRole(device.address) call mirrors the cleanup already done in the sibling SecurityException catch below at line 2107 — without it, the pending role reserved earlier in connectToDevice hangs half-set-up and blocks the next connect attempt to the same address.

Alternative shapes: change MeshConnectionRegistry.registerGatt to accept BluetoothGatt? and no-op on null, or wrap the connectGatt return in a ?.let { ... }. The above is the least invasive.

MINE-side interim (documented exception under CLAUDE.md carve-out)

Extending our existing patches/offline-protocol+mesh-sdk+0.12.0.patch with this guard as a third fix family alongside OFF-1801 (foreground-service) and OFF-1896 (scan-site IllegalStateException). Retire the patch line when mesh-sdk 0.12.x ships the guard upstream.

Related

• OFF-1896 (scan-site IllegalStateException, same adapter-race class)
• OFF-1897 (MINE-side patch extension for OFF-1896)
• OFF-1977 (MINE-side tracking ticket for this NPE — sibling of OFF-1897)

Review in Linear

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[taayyohh]

recheck

[taayyohh]

I have read the CLA Document and I hereby sign the CLA