Add kable-server module (BLE peripheral role / GATT server)

[twyatt]

Summary

Adds a new kable-server module (com.juul.kable.server) providing the peripheral (server) side of BLE: hosting a GATT server and advertising it to remote centrals, declared via a coroutines-first DSL:

val server = GattServer {
    service(Uuid.service("heart_rate")) {
        characteristic(Uuid.characteristic("heart_rate_measurement")) {
            onSubscription {                       // Launched per subscribed central,
                while (true) {                     // cancelled on unsubscribe/disconnect.
                    send(measureHeartRate())
                    delay(1.seconds)
                }
            }
        }
        characteristic(Uuid.characteristic("body_sensor_location")) {
            value = byteArrayOf(0x01)              // Static (read-only) value.
        }
    }
    service(customServiceUuid) {
        characteristic(customCharacteristicUuid) {
            onRead { byteArrayOf(/* ... */) }      // "Long read" offsets handled by Kable.
            onWrite { value -> process(value) }    // Prepared writes assembled by Kable.
        }
    }
}

server.start()                                     // Suspends until services are published.
server.advertise {                                 // Active while suspended; cancel to stop.
    name = "Example"
    services = listOf(Uuid.service("heart_rate"))
}
server.notify(characteristicOf(serviceUuid, characteristicUuid), data)

Characteristic properties are inferred from declared behavior (value/onRead → read, onWrite → write/writeWithoutResponse, onSubscription → notify/indicate). Requests are rejected by throwing GattErrorException(AttError...) from handlers. The entire public surface is @ExperimentalKableApi.

Platform	Supported	Notes
Android	✓	BluetoothGattServer + BluetoothLeAdvertiser
Apple (iOS/macOS)	✓	CBPeripheralManager; advertising limited to local name + service UUIDs; dynamic descriptors unsupported (per Core Bluetooth)
Apple (watchOS)	✗	Core Bluetooth peripheral role is unavailable on watchOS (peripheral-role initializers are API_UNAVAILABLE, which also breaks commonized appleMain metadata compilation — so watchOS targets are not configured for this module)
JS / wasmJs	✗	Web Bluetooth is client-only
JVM	✗	btleplug is central-only

Architecture

Platform engines translate callbacks into a common InboundRequest stream consumed by a common RequestDispatcher, which owns the tricky (and unit-tested) logic:

• Read offset ("long read") slicing — handlers return full values.
• Prepared ("long"/queued) write assembly — handlers always receive complete values.
• CCCD management — auto-attached on Android (reads/writes answered internally, translated to subscribe/unsubscribe); handled by the OS on Apple (subscription events used directly). Never declared by users.
• Subscription lifecycle — one SubscriptionAction coroutine per subscribed central, with backpressure-aware send (Android: serialized via onNotificationSent; Apple: updateValue + isReadyToUpdateSubscribers).

Also included

• README section (usage, platform support matrix, permissions documentation — kable-default-permissions intentionally untouched).
• samples/gatt-server: minimal Compose sample app (heart rate server with simulated bpm slider) + nRF Connect verification steps, with a GATT Server / Android CI workflow (mirrors sensortag workflows).

Testing

• 44 tests run via :kable-server:testAndroidHostTest (all passing):
  • 31 common tests: DSL validation + RequestDispatcher/GattServerImpl behavior against a FakeServerEngine (offsets, prepared writes/abort, CCCD subscribe/unsubscribe + state reads, subscription coroutine lifecycle, disconnect cleanup, notify routing/validation, start/stop/restart/close state machine, advertise structured-concurrency semantics). These also run against the Apple (native) targets via check on CI.
  • 13 Robolectric tests: Android profile mapping (properties/permissions bitfields, auto-CCCD attachment incl. secure CCCD) and AdvertiseSettings/AdvertiseData mapping.
• :kable-server:check (incl. ktlint) green locally; CI build job (macos-latest) green — validates Apple target compilation, native test execution, and publishToMavenLocal.
• Sample app: :app:assembleDebug and :app:check green locally and on CI.
• Hardware (radio) validation via the sample app + nRF Connect steps documented in samples/gatt-server/README.md has not been performed on-device.

Notes for reviewers

• Peripheral in kable-core means remote peripheral, so the new module avoids that term: the entry point is GattServer and remote devices are Centrals.
• kable-server reuses kable-core's public Uuid helpers, Characteristic/characteristicOf, WriteType, and logging { } DSL; kable-core internals (Logger, applicationContext) are intentionally not touched — small internal equivalents live in kable-server.
• Binary-compatibility-validator: no JVM target in this module, so apiCheck is a no-op for it (klib validation is not enabled repo-wide).

  

[cursor]

Cursor Bugbot has reviewed your changes and found 4 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit c896b10. Configure here.}

[cursor]

Android long read double offset

High Severity

Long reads with a non-zero offset return the wrong payload on Android. RequestDispatcher already slices attribute data before invoking the response callback, but ServerCallback still passes the original read offset into BluetoothGattServer.sendResponse, so the stack applies the offset again to an already-truncated byte array.

Additional Locations (2)

• kable-server/src/commonMain/kotlin/RequestDispatcher.kt#L125-L130
• kable-server/src/androidMain/kotlin/ServerCallback.kt#L119-L121

 

^{Reviewed by Cursor Bugbot for commit c896b10. Configure here.}

[cursor]

Prepared write not atomic

Medium Severity

When a committed prepared-write transaction spans multiple attributes, onExecuteWrite invokes each onWrite handler sequentially. If a later attribute fails assembly, permission checks, or the handler, earlier attributes may already have been written while the ATT response reports failure.

 

^{Reviewed by Cursor Bugbot for commit c896b10. Configure here.}

[cursor]

Apple prepared write queue leak

Medium Severity

Prepared-write fragments are stored per central until ExecuteWrite or CentralDisconnected. The Apple engine never emits CentralDisconnected, so an interrupted long write can leave stale fragments that merge into a later transaction from the same central identifier.

 

^{Reviewed by Cursor Bugbot for commit c896b10. Configure here.}

[cursor]

Advertising toggle race

Low Severity

Stopping advertising only cancels the job and returns; advertiseJob stays non-null until the coroutine’s finally runs. A quick stop-then-start can hit the stop branch again instead of launching a new advertisement.

 

^{Reviewed by Cursor Bugbot for commit c896b10. Configure here.}