BLE: deliver advertisement payloads with scan results

[jappeace-sloth]

Closes #238. First consumer: jappeace/kbeacon-ota-tool (identify KBeacons by their 0x2080 service data like KKM's own library, battery-at-scan, renamed beacons on iOS).

What

• New pure module Hatter.BleAdvertisement (re-exported from Hatter.Ble): parses raw AD structures (length : type : payload) into service data entries, keyed by full lowercase 128-bit UUID text (16/32-bit UUIDs expanded with the Bluetooth base UUID, matching the existing textual convention), and manufacturer data entries keyed by the 16-bit company id. serviceDataForUuid does case-insensitive lookup.
• BleScanResult gains bsrAdvertisement; the whole scan callback chain (Java/ObjC → C → haskellOnBleScanResult → dispatchBleScanResult) gains a bytes+length parameter, mirroring the existing notification-payload path.
• Android passes ScanRecord.getBytes() through unchanged. iOS re-encodes CoreBluetooth's parsed advertisementData dictionary back into the same AD structure format (CoreBluetooth never exposes the raw bytes), so Haskell has a single decoding path for both platforms.
• Malformed air data degrades to "no payload" rather than failing: a zero length byte terminates (Android zero-pads the buffer), truncated tails are dropped. Decision comment on the parser explains why lenient parsing is correct for radio input.

Tests

• Eight new unit tests: parser (16-bit/128-bit service data, manufacturer data, entry order, zero-padding, truncated tail), case-insensitive lookup, and the dispatch path end to end with real pointers.
• The virtual test peripheral now broadcasts a 0xFEED service data entry (payload 2A 63) and ble.sh asserts the parsed bytes arrive in Haskell; BleDemoMain logs advertisement service data as decimal byte lists like the GATT logs.
• Local verification: library + unit suite pass under cabal test (nix-build is blocked in my sandbox); NDK/ObjC sides mirror the existing onBleNotification byte-array plumbing and are CI-verified.

🤖 Generated with Claude Code

[jappeace]

this should report the failure condition, every branch should have a unique one explaining what it is as a parseError

[jappeace-sloth]

Done in 99d34d8: each branch now has its own constructor stating what failed, why and where: AdStructureTruncated offset declared remaining, ServiceDataUuidTruncated offset adType uuidWidth actual, ManufacturerDataTooShort offset actual. The zero-length byte stays a clean terminator (it is Android's buffer padding, not a defect), and unknown AD types stay non-failures since names/flags/UUID lists are legitimate structures this module deliberately does not surface. Decision comment links your failing-in-haskell post.

[jappeace]

typesig should be

parseBleAdvertisement :: ByteString -> Either ParseErrors BleAdvertisement

[jappeace-sloth]

Done in 99d34d8: parseBleAdvertisement :: ByteString -> Either AdvertisementParseErrors BleAdvertisement, with AdvertisementParseErrors a NonEmpty of every defect found (concrete types, no mtl, per your follow-up). The scan dispatch logs the defects with the sending device's address and still delivers the result, and bsrAdvertisement carries the full Either so apps can surface them too.

[jappeace]

put the failure conditions in the type signature

[jappeace-sloth]

Done in 99d34d8: addAdStructure/addServiceData/addManufacturerData all return Either AdvertisementParseError BleAdvertisement now.

[jappeace]

use the uuid package instead

[jappeace-sloth]

Done in 99d34d8 using uuid-types (the type-only package): UUID.fromWords is total and UUID.toText gives the canonical lowercase form, killing the hand-rolled hex. The full uuid package pulls network-info (OS ioctls) which would fight the Android cross build, so I stopped at uuid-types; its non-boot transitives (hashable, random, splitmix) are added to the cross-deps/ios-deps collection lists. The whole-API typed-UUID migration stays tracked in #240.

[jappeace]

actually for these it maybe better instead of a newtype for AdStructureOffset, you create a new data type for the two ints and StructureOffset. So that every error sum constructor get's it's own record, allowing us record access to the fields

[jappeace-sloth]

Done in 69e1ec3: each error constructor now wraps its own record (AdStructureTruncation, ServiceDataTruncation, ManufacturerDataTruncation) bundling the AdStructureOffset with the sizes, so every field has a total record accessor (single-constructor records dodge -Wpartial-fields).

[jappeace]

BS.index is partial, use index maybe and push out the maybe. in the typesignature.

[jappeace-sloth]

Done in 69e1ec3: no BS.index left in the module. word32BigEndianAt chains BS.indexMaybe and returns Maybe Word32; normalizedUuidFromLittleEndian pushes it out as Maybe NormalizedBleUuid (Nothing unless the slice is exactly 2/4/16 bytes), and addServiceData consumes that Maybe as its truncation check, so the length validation lives in exactly one place. addManufacturerData reads its two bytes via indexMaybe with all four cases written out, and the structure walker peels the type byte with BS.uncons.

[jappeace-sloth]

Addendum in c3445d7: the first indexMaybe version had a truncation hole (judging the slice by its own length let a 0x21 structure truncated to two bytes pass as a 16-bit UUID, and [0x80, 0x20] would read as 0x2080 itself). normalizedUuidFromLittleEndian now takes the declared width and returns Nothing unless the slice has exactly that width; regression tests cover 0x21 truncated to 2/4 bytes and 0x20 truncated to 2.

[jappeace]

this is silly, can't we just return the UUID type instead of converting it back to "normalized" text?

[jappeace-sloth]

Done in 119e58c: advServiceData is keyed by uuid-types' binary UUID (case differences unrepresentable by construction), uuidFromLittleEndian returns Maybe UUID, and serviceDataForUuid takes the UUID value; constants build with the total fromWords. Text now only appears at the logging edge. NormalizedBleUuid moved back to Hatter.Ble with the characteristic keys, its remaining users. This is also the first slice of #240.

[jappeace]

I guess we can expose the partially parsed advertisement on the right branch as well so you get Either BleAdvertiseWithErrors BleAdvertisement

data BleAdvertismentWIthError = BleWithErrors { advertisement :: BleAdvertistement, parseErrors :: AdvertisementParseErrors }

[jappeace-sloth]

Judged it worth doing, done in 079dadf. The comment makes sense and the partial is usually NOT empty: AD structures are independent TLVs, so a mid-stream defect skips only its own structure (everything before and after survives) and a truncation keeps everything before it; the salvage is empty only when the FIRST structure is truncated or every structure is defective. Since the link layer's CRC already dropped radio corruption, a defect here is a firmware quirk in one structure and the rest is trustworthy, so discarding it was wrong (a KBeacon with one garbled trailing structure would have lost its valid 0x2080 identity data). Implemented as your Either BleAdvertisementWithErrors BleAdvertisement with the record; tests pin a filled-salvage case (truncated tail keeps the manufacturer data before it) and an empty-salvage case (all structures defective).