jerry/buzz
1
0
Fork 0
mirror of https://github.com/block/buzz.git synced 2026-10-28 13:01:10 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
f33ebaafa15626e0f8bc3e23341835e08ebf4a33
buzz/docs/buzz-push.md
Tom Brow f167c4c3e1 fix(push): accept canonical channel UUIDs across versions (#8609) 
Starter channels use UUIDv5 IDs, but mobile push accepted only UUIDv4
channel IDs, so building a subscription that included a starter channel
threw locally. After #8608, no non-v4 ID reaches mobile push today:
positive `#h` filters cover joined DMs only, and mutes are limited to
subscribed channels. This PR is therefore a safety net for future
starter-channel subscriptions, and it prepares mobile for a relay that
accepts them.

Mobile now accepts canonical lowercase, hyphenated UUIDs of any version
in subscriptions. It recognizes both the current `uuid-v4-lowercase`
relay descriptor and a future `uuid-lowercase` descriptor. Against a
`uuid-v4-lowercase` relay, mobile checks positive and mute channel
filters before enrollment or publication, keeps the desired filters, and
rechecks relay capabilities every five minutes instead of sending a
lease the relay would reject.

The relay is unchanged. It keeps validating and advertising
`uuid-v4-lowercase`. Installed mobile builds reject any other
`h_grammar`, and they parse the descriptor before renewal, opt-out and
revocation, so changing the advertisement now would leave their leases
active until expiry. The relay validation and advertisement change will
follow in a separate PR once those builds have drained.
`docs/buzz-push.md` records this sequencing.

### Validation
- Regression tests reproduced the UUIDv5 rejection in Dart before the
fix. Added coverage checks positive and mute filters, persisted
subscription round trips, encrypted lease content, malformed IDs,
retained bounds, parsing of both descriptor grammars, and
pre-publication rejection of non-v4 IDs against a `uuid-v4-lowercase`
relay.
- Mobile push tests on the current head: 104 passed, 4 skipped. `flutter
analyze` on the push code and tests is clean.
- Before the split, exercised actual mobile lease construction, NIP44
encryption and NIP42 publication against an isolated local relay. The
relay half of that exercise is no longer part of this PR.
- Relay source is identical to `main`, so the relay serves the same
descriptor that installed builds parse today.

The standing mobile test exception applies. Agent review and
changed-behavior exercise are complete.


buzz-review-completed

---------

Signed-off-by: Tom Brow <tomb@block.xyz>
Co-authored-by: george <973be878edd6d4f79692a3827f20a6f7fe0ed0362f269ff6b6ba8867033d7d8e@sprout-oss.stage.blox.sqprod.co>
2026-10-27 11:12:33 -07:00

2.0 KiB
Raw Blame History

Buzz push notes

Push is experimental. These notes capture current decisions; we will write a stable specification after validating the design through launch and use. NIP-PL is background, not the current Buzz contract.

  • Relays advertise buzz-push-v1, never nip-pl. Updated clients require it.
  • Compatible changes keep the capability name. Incompatible behavior that clients must distinguish gets a new version.
  • Each gateway serves one server-configured Apple application and APNs transport. Enrollment, transcripts, grants, leases and discovery have no application-profile selector. The relay advertises transport classes in class_support.
  • Existing grants and pending enrollment records are not migrated. The new client uses separate Keychain records and enrolls again. Keep old production push disabled so released clients never acquire legacy push authority.
  • Stop old gateway replicas before cutover. The gateway migration requires an empty authority store because endpoint fingerprints changed. The relay migration requires no active legacy leases. Neither migration deletes that state.
  • Publish the matching gateway image and chart, update deployment configuration, then enable the new relay capability. Verify enrollment, delivery, renewal and revocation on a physical device before production activation.

Channel identifier grammar

Relays advertise h_grammar: "uuid-v4-lowercase". Mobile also accepts uuid-lowercase, which drops the UUID version and variant restriction so UUIDv5 starter channels can be subscribed. Against a uuid-v4-lowercase relay, mobile checks positive and ignore channel filters before enrollment or publication. It keeps the desired filters and rechecks relay capabilities every five minutes rather than sending a lease the relay would reject.

Do not change the relay advertisement until mobile builds that only parse uuid-v4-lowercase have drained. Those builds parse the descriptor before renewal, opt-out and revocation, so a new grammar would leave their existing leases active until expiry.