Repository navigation
feat(protocol): a ble-to-wi-fi fast link between devices that meet over bluetooth (adr 0038) - #756
Merged
Merged
Conversation
throwaway phase 1 hooks, not a design. android hosts a wi-fi direct group with given credentials (or a localonlyhotspot) on an adb broadcast, and can stop its lan carrier so a pair on one network meets only over ble. ios joins with nehotspotconfiguration from a config file in its container and dials the host's existing peer-stream listener directly. no udl or js surface.
adr 0038 records the decision from the phase 1 spike: two devices that share a confirmed session but meet only over bluetooth le bring up a wi-fi direct network on request, with fresh credentials sealed in the session, and the stream over it fills the peer-stream slot. the fast link state machine specifies roles, frames, timers and teardown. threat model r34 records what the network exposes in range and what the offer trusts.
the literal lives in offline-protocol-sealed with the other pair frames and is reserved in the engine registry and the control-messages chapter, which also specifies the request, offer and close bodies and their bounds. until the handler lands, a fast-link frame is consumed wherever it is found: bare on the wire, in a 1:1 plaintext, and on all three group plaintext arms, so it is never shown to anyone as text.
link_versions entry 1 says a peer routes __fast_link__ frames. it is omitted from the payload when empty, so a key package that does not advertise it is byte for byte what it was, and a leaf advertises nothing. the engine advertises it, records it per peer from each key package, persists it with the other capabilities and restores it at startup. the key package vectors gain a case, and from_advertised now takes the payload rather than one argument per list.
crate::fast_link is the state machine of the fast link state machine document, pure and unit-tested for both ends of a pair: roles, credentials drawn fresh per link, offer validation, the lower-address rule when both host, timers, idle teardown, and one close per end. the engine glue gates a request on capability, a confirmed session and a live direct link, seals every frame with the strict encryptor and sends it once with no ack or outbox, routes a decrypted frame from the session, wakes the platform through the peer-stream callback when a directive waits, and emits fast_link_changed, which never carries a credential.
request_fast_link and close_fast_link for the application, and four calls for the peer-stream driver: declare its roles, drain directives on the callback it already drains bodies on, report its network up, and report an end. the directive record redacts its passphrase in debug. a stream's proof, loss, the layer going down and inbound bodies feed the engine's fast link. every binding, the c dispatcher and the python local api table are regenerated together, and the local api chapter classifies the new calls.
…m slot a 1 mib file over a fast link took 8.0 to 8.7 s with four 32 kib chunks in flight: about 128 kib per acknowledgement round, so the transfer waited on receipts rather than on the link. the peer-stream slot now keeps sixteen in flight, 512 kib, well inside the 4 mib a platform manager queues per stream. every other slot keeps its window.
…o apps the android manager declares both roles on android 10 and later and drains the engine's directives on the transport callback. it hosts a wi-fi direct group with the engine's credentials and reports the owner's address and its listener's port once the group exists; it joins one by name and passphrase and dials the offered address and port claiming the host. while hosting, an inbound stream on the group must prove the invitee, and a group whose client has left ends its stream at once instead of waiting out keepalive. the phase 1 spike hooks are gone. requestFastLink and closeFastLink reach apps on react native and flutter on both platforms, through the generated bridges, the swift host bridge and the error manifest. the registration guard learns the callback's second post.
the ios manager declares it can join and not host, and drains the engine's directives on the transport callback, off the core's mutex. a join applies a joinonce hotspot configuration, reports a declined prompt as declined, and dials the offered address and port bound to wi-fi with the host as its claim, again every two seconds until the stream proves the host or the offer runs out. backgrounding leaves the network and tells the engine at once, because ios drops it 15 s later anyway and the host would otherwise wait on keepalive. the phase 1 spike is gone.
on two phones the example app's presence update every 15 s kept the link from ever going idle, which kept the iphone off its own wi-fi for as long as the app ran. only a body of at least 16 kib, half a media chunk on the slot, now moves the idle clock; a transfer in flight still holds it as before.
…ones two bugs found on the phones with an iphone-initiated link. the engine sends a direct frame down the peer stream when it holds one, so a close went down the stream it was ending and reached the iphone 22 s late, and a request went down a lan stream the iphone had just left and reached the android 63 s late. fast-link frames now go over bluetooth le whenever the peer is linked there. and that late request was hosted, and its offer prompted the iphone's user to join a network the android had already removed: a device now remembers the links it ended for ten minutes, drops a late request for one, and answers a late offer with close expired so the host takes it down.
a link that ended while its platform was paused left its host or join directive in the queue, and the platform ran it on resume: android brought up a group for a dead link, and an iphone would prompt for a network already gone. the machine now counts the platform as holding a link only once it drains the link's directive, withdraws an untaken one when the link ends, and skips a host or join whose time ran out.
WifiP2pConfig.Builder throws for a network name that does not start DIRECT- and two characters, and the engine accepts any name an iphone could join. an offer with such a name, from any session peer or another implementation of the spec, threw on the transport looper and killed an android joiner, again on every offer. the builder is now guarded and the offer answered invalid, and each directive runs inside a catch so a framework exception (a revoked permission, say) ends the link as failed instead.
android skipped its fast-link directives while paused, close included, so a link that ended with the app in the background left its wi-fi direct group on the air, and blocking every later link, until the app came back. the directives are now drained whatever the pause; while paused a close still runs and a new host or join is refused as background, on ios too, where a join would have prompted a user who is not looking.
…at once an offer needs no request, so any session peer could put the ios join prompt in front of a user who never asked, and again the moment it was declined. after the user declines a peer's network, that peer's offers are answered declined for ten minutes and never shown; the user's own request to it ends the pause. threat model r34 records what is left: one prompt per ten minutes per session.
a host's close can reach the joiner before the late offer it ends, and a close for a link the joiner did not hold was dropped without trace, so the offer then prompted. its link id is now remembered like an ended link's, and the offer is refused as late when it lands.
formation checked only inGroup, which turns true when the group broadcast lands, seconds after a fast link's createGroup or connect: in that window it could issue its own join or create and break the one-group rule of adr 0038. it now waits while a fast link is hosted or joined.
blocking removed the peer's capability but left its link standing: the android group stayed up for the blocked peer, an iphone joiner stayed off its own wi-fi, and the blocked peer's own bodies kept the link from going idle. block_user now ends the link, telling this device's platform to take the network down and sending nothing to the blocked peer.
a new offer from the same peer replaced a link being joined. on ios the replaced join's completion then never reported the user's decline, so a peer that re-offered while each prompt was on screen never started the ten-minute decline pause that r34 relies on. the second offer is now answered busy and the first stands; an honest host's new network follows its own close. r34 also records that an android joiner joins with no prompt at all.
…s group is gone when two android devices host for each other the higher address closes its own link and joins the other's, and the engine hands its platform the close and the join in one drain. removeGroup is asynchronous, so the join found the device still in its group and failed, and both links ended. the join now waits for the group-gone broadcast, within the offer's lifetime, then runs. not exercised on hardware: it needs two android phones.
a peer could close its link while the ios prompt was on screen: the user's cancel then landed on a link the engine no longer held and was dropped, so the decline pause never began and the next offer prompted again. the engine remembers which peer each ended join belonged to and records a decline reported after the end against it, and ios reports the refusal even when the link is already gone.
…'s host the dial went to the address the offer named, checked only to be private or link-local. an android joiner stays on its own wi-fi while in a p2p group, so an offer naming a host on the user's home network sent the dial, and a preamble, there instead of over the group. the dial now always goes to the owner's own address as the group reports it, on the offer's port.
…closed a close that landed while createGroup was still negotiating sent a removeGroup the framework can refuse as busy, and the group then came up with nothing tracking it, blocking every later link and group formation until the transport stopped. the name of a group closed before it came up is now remembered, and the group is removed when it appears.
any session peer could make an android host bring up a group by asking, and by asking again each time the offer expired keep a group on the air and the device's own formation locked out indefinitely. after two links in a row hosted for a peer's requests expire with no stream from it, the host answers that peer's requests busy for ten minutes; a used link resets the count, and the host's own request to the peer ends the pause. r34 records what is left. also, an offer that answers this device's request under another id now leaves the request's id remembered as ended, so a host acting on the request late cannot prompt the user for a second network.
the unreleased changelog gains the fast link under added and the 16-chunk peer-stream window under changed, and the mobile permissions guide says what an integrator needs: the hotspot configuration entitlement and local-network keys on ios, the wi-fi direct grants and android 10 on android, and what the user sees.
the fast_link prefix comment said a leaf with a wi-fi radio can host or join a link, while the capability chapter and the leaf's key package say a leaf advertises nothing and is never offered one. the comment now agrees.
the c# sdk's generated local api lacked the six fast-link calls, and the two react native adapters had requestFastLink and closeFastLink placed by hand where their generators sort them otherwise, so gen_csharp_local_api.py and check-binding-generators.sh failed their --check. both are regenerated; the c# suite was not run here (no dotnet).
…ost backoff the host counted only links that expired toward its request backoff, so a peer could close each link with any other reason just before it expired and ask again, holding the android's one group on the air for as long as it liked. an unused link the peer ended now counts too, whatever its reason; ends this device caused do not.
any outbound transfer to the peer held the link open, but a transfer's carrier is fixed when it starts, so one begun over bluetooth before the link came up never moved to it, and the iphone stayed off its own wi-fi while the link carried nothing. only a transfer pinned to the peer-stream slot holds the link now, and the request docs say to send after the link is up.
…er against the peer
…ter its link was given up
…engine takes any name
…efore its streams are lost
…y, not its name NEHotspotNetwork.fetchCurrent names no joinOnce network without location permission, so on an iphone 16 every join was given up failed five seconds after the phone was on the group. the host's offered address is the group owner, the gateway of the wi-fi path, so the dial now waits for that. the access wi-fi information entitlement and the ios 14 floor are no longer needed.
…es it android reports the device out of any group while createGroup is still forming one, which cleared the name written before it. a host killed while hosting left its group on the air with nothing on disk, and the next start adopted it as an ordinary group. device-checked: the group is now removed on restart.
the gateway check had no bound: a join that apply reported done while the phone stayed on its own wi-fi waited out its two-minute offer with nothing said, and the host's group refused every other link meanwhile. after ten looks, twenty seconds, it now ends failed with a diagnostic.
… forms the out-of-group broadcast that arrives during createGroup cleared the name before the group was first seen, so a host killed in that window still left its group adopted on restart. the broadcast now leaves the name alone while the hosted group is unseen, and a failed createGroup clears it.
…le is full returning ended the redial chain, so a join that reached the group with the table full sat out its two-minute offer with the host's group on the air. the deadline still bounds the retries.
…ateway the gateway check could not tell the offered group from the user's own network when the offer named the home router: a join that silently did not happen was dialled there on every redial until the offer expired. before the prompt the host must not already be the wi-fi gateway, looked at up to four times so a phone still leaving a previous group is not refused. device-checked: a join and an immediate re-link both reach the prompt.
… the peer first two phones back on one home network met over it while an offer was pending; the engine took that stream for the link's own and marked the link up, the iphone never dialled the group its user had just joined, and leaving the home network for it lost both. a platform now ends the link superseded before announcing a stream that is not the link's own, and answers a directive for a peer a stream already reaches the same way. the end never counts against the peer and fails no transfer on the slot.
…reached peer gets no link an android below 13 advertises on its group's interface, so an iphone's general bonjour dial could prove the host over the group before the link's own dial; taken for another stream, it superseded the link and tore down the group it ran on. on ios a stream whose path's gateway is the offered host, once joined, is now adopted as the link's. and the engine answers a request or offer from a peer another stream already reaches superseded itself, with no link: the peer's own superseded could overtake this device's report and count against the peer.
…d before dhcp stays the link's when both phones held a pending link and the peer's superseded close overtook this device's own report, it counted against the peer; with another stream reaching the peer it is now this device's own end. a peer's superseded for a link up here is any close, and releases its transfers. a join the platform has not taken gives way in the engine when a stream proves the peer. on ios, once joined, only a stream whose path has a gateway that is not the host supersedes the link: the bonjour stream over the group proves over a link-local address before dhcp, with no gateway, and was ended with the group it ran on. android lets a parked join give way too.
…nd the superseded guard says what it covers a stream that proves the peer while the host's group is still coming up cannot be the link's own, so the link now ends superseded before any offer is sent. the guard for a peer's superseded covers a stream this device has already proved but its platform did not recognise; one that arrives before this device proves the stream at all is still counted, and the docs, the comment and the test names now say so. the test also checks a peer's superseded for an up link releases its transfers and is counted.
mizanxali
marked this pull request as ready for review
November 17, 2026 13:02
…gate the named group on api 29 for lint main's typescript event parser keeps a list of every event tag, and its guard refused the branch's new one. android lint refused the named-group createGroup call below api 29; the fast link was already off there at runtime, and the check now sits where the call is made.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the fast link (ADR 0038): two devices that meet over Bluetooth LE and share a confirmed MLS session bring up a Wi-Fi network between them, and the stream over it fills the
wifi_directpeer-stream slot. Transfers move onto it on their own and back to Bluetooth when it ends.NEHotspotConfiguration(joinOnce), after a system prompt; an Android can also join.__FAST_LINK__frames (request,offer,close) are sent only inside the 1:1 session with the strict encryptor, once, over a live direct link (Bluetooth first), never queued, relayed or acknowledged. Frames found anywhere else, including ones that waited in the pending-decryption queue, are consumed and dropped.crates/offline-protocol/src/fast_link.rs): no clock, randomness or engine, three drained queues (frames, events, platform directives). That lets two-ended tests drive both sides through every transition.wifi_direct_set_fast_link_roles,wifi_direct_next_fast_link_directive,wifi_direct_fast_link_hosting,wifi_direct_fast_link_ended. Application callsrequest_fast_link/close_fast_link, plus afast_link_changedevent.wifiDirect.fastLink(any/requestedOnly/off) sets how far an app takes part.link_versions: [1]in the key package, which is additive and left out when empty.Docs: ADR 0038,
docs/state-machines/fast-link.md,docs/spec/control-messages.md(frame family, reasons, bounds), threat model R34,docs/mobile-permissions.md,docs/spec/stream-framing.md, CHANGELOG.Measured on two phones (iPhone 16, Samsung Galaxy M17 on Android 16)
superseded, no falseup, the home-network stream carries onIntegration notes
NEHotspotNetwork.fetchCurrentnames nojoinOncenetwork without location permission.NEARBY_WIFI_DEVICES(fine location below Android 13). A fast link and Wi-Fi Direct group formation share the one group a device can own.fastLink: 'any', a session peer can start a link, which shows that prompt without the app asking;requestedOnlystops that.requestFastLink/closeFastLinktoo, because the shared bridge has to match the Flutter method list.Known limits and follow-ups
loston the host: the close frame goes out over the stream being torn down. Sending closes over Bluetooth would fix it.supersededthat arrives before this device has proved the other stream at all is still counted against the peer (a Bluetooth frame has to beat the stream's preamble).Related issues
None.
Type of change
featnew featuredocsdocumentationtesttestsChecklist
cargo fmt --all -- --checkpassescargo clippy --workspace -- -D warningspassescargo test --workspacepassescargo-denyis satisfied (no new dependencies)CHANGELOG.mdupdatedunsafein core cratesTest plan
cargo test -p offline-protocol --lib fast_link): the state machine driven from both ends, and two engines over real MLS (sealing, ephemeral sends, Bluetooth preference, blocking, stop and pause, transfers failing with the link,superseded)offline-protocol-uniffi(tokens match the engine's, no directive logged whole, announce order, gateway checks, leftover-group record)