Skip to content

Commit 17a481a

Browse files
bradseilerHonor
andcommitted
fix(protocol): keep membership contract portable
Register both relay-only membership kinds in the contract layer. Describe committed-state freshness and quota behavior without implementation or deployment details. Co-authored-by: Honor <e0bf479eeebe47dde1e35705212a4df70616a7bc834d907ddfb18cf0405f8b1b@seiler-test.communities.public.builderlabstaging.xyz> Signed-off-by: Brad Seiler <[email protected]>
1 parent fb57445 commit 17a481a

2 files changed

Lines changed: 41 additions & 40 deletions

File tree

‎crates/buzz-core/src/kind.rs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -486,6 +486,9 @@ pub const KIND_THREAD_WINDOW_BOUNDS: u32 = 39007;
486486
/// NIP-CL: request-bound compact viewer membership overlay; query-time only, never stored.
487487
pub const KIND_MEMBERSHIP_SNAPSHOT: u32 = 39008;
488488

489+
/// NIP-CL: request-bound public membership overlay; query-time only, never stored.
490+
pub const KIND_MEMBERSHIP_PUBLIC: u32 = 39009;
491+
489492
/// Workflow definition (parameterized replaceable, d=workflow_uuid).
490493
pub const KIND_WORKFLOW_DEF: u32 = 30620;
491494

@@ -751,6 +754,7 @@ pub const ALL_KINDS: &[u32] = &[
751754
KIND_WINDOW_BOUNDS,
752755
KIND_THREAD_WINDOW_BOUNDS,
753756
KIND_MEMBERSHIP_SNAPSHOT,
757+
KIND_MEMBERSHIP_PUBLIC,
754758
KIND_PRESENCE_UPDATE,
755759
KIND_TYPING_INDICATOR,
756760
KIND_AGENT_PRESENCE,
@@ -907,6 +911,7 @@ pub const fn is_relay_only_kind(kind: u32) -> bool {
907911
| KIND_WINDOW_BOUNDS
908912
| KIND_THREAD_WINDOW_BOUNDS
909913
| KIND_MEMBERSHIP_SNAPSHOT
914+
| KIND_MEMBERSHIP_PUBLIC
910915
)
911916
}
912917

@@ -994,6 +999,9 @@ mod tests {
994999
fn compact_membership_snapshot_is_relay_only() {
9951000
assert_eq!(KIND_MEMBERSHIP_SNAPSHOT, 39008);
9961001
assert!(is_relay_only_kind(KIND_MEMBERSHIP_SNAPSHOT));
1002+
assert_eq!(KIND_MEMBERSHIP_PUBLIC, 39009);
1003+
assert!(is_relay_only_kind(KIND_MEMBERSHIP_PUBLIC));
1004+
assert!(ALL_KINDS.contains(&KIND_MEMBERSHIP_PUBLIC));
9971005
}
9981006

9991007
#[test]

‎docs/nips/NIP-CL.md‎

Lines changed: 33 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -301,8 +301,7 @@ These independent, optional query modes reserve distinct response kinds:
301301
| `membership_snapshot` v1 | 39008 | NIP-98 signer only | Own active memberships, including private channels and DMs as specified below. |
302302
| `membership_public` v1 | 39009 | Any public key | Active memberships in listed, open forum/stream/workflow channels only. |
303303

304-
Kind 39009 is reserved by this specification for public membership lookups;
305-
its runtime registration and implementation are separate work. Supporting
304+
Kinds 39008 and 39009 are relay-only, request-bound projections. Support for
306305
39008 does not imply support for 39009, or conversely. Each mode key MUST
307306
appear only with its own kind; a mismatched mode key and kind returns 400.
308307

@@ -330,7 +329,7 @@ information document:
330329
}
331330
```
332331

333-
The operator switch `BUZZ_MEMBERSHIP_SNAPSHOT_ENABLED` defaults to false.
332+
The operator switch for this capability is off by default.
334333
Disabled relays omit the descriptor and return HTTP 404 with
335334
`{"error":"membership_snapshot unsupported"}` for this query mode. Capability
336335
advertisement alone is not authentication or membership authority. Clients
@@ -407,10 +406,8 @@ The signed content is:
407406
}
408407
```
409408

410-
Kind 39008 is registered as `KIND_MEMBERSHIP_SNAPSHOT` in
411-
[`buzz-core/src/kind.rs`](../../crates/buzz-core/src/kind.rs). Like the
412-
39005–39007 query overlays, it occupies the addressable range but is an
413-
on-demand projection: it is never persisted, replaced, broadcast or returned
409+
Like the 39005–39007 query overlays, kind 39008 occupies the addressable
410+
range but is an on-demand projection: it is never persisted, replaced, broadcast or returned
414411
by ordinary REQ, COUNT or `/query`. Clients cannot submit it through EVENT.
415412
The `d` tag is a request coordinate, not a durable per-viewer list.
416413

@@ -437,13 +434,12 @@ Never interpret these as an empty complete list. An empty **valid signed**
437434

438435
### Canonical selection and bounds
439436

440-
The relay reads the primary database in one SQL statement's MVCC snapshot.
441-
It selects only the viewer's active `channel_members` rows, joined to live
442-
`channels` in the same community, ordered by channel UUID. It does not load,
443-
parse or serialize full rosters, other members' keys, or profiles. The existing
444-
partial `(community_id, pubkey) WHERE removed_at IS NULL` index supports this
445-
projection. Channel UUID, role, type, visibility and archive state all come
446-
from that same statement, never a separately sampled version query.
437+
The relay MUST derive the complete response from one consistent read of
438+
committed state that reflects every change committed before the relay
439+
received the request. Select only the viewer's active memberships in nondeleted
440+
channels in the same community, ordered by channel UUID. Channel UUID,
441+
role, type, visibility and archive state MUST reflect that same read.
442+
The projection MUST NOT include full rosters, other members' keys or profiles.
447443

448444
There is one entry per active membership in the requested type set:
449445

@@ -525,7 +521,7 @@ The relay continues to enforce current read/write authorization independently.
525521
This response is discovery authority, never a bearer capability. Relay-wide
526522
ban/removal invalidates the session even if channel rows remain active.
527523

528-
### Compatibility and rollout
524+
### Compatibility
529525

530526
A client MUST require the descriptor before selecting this mode. An explicit
531527
absent/disabled capability uses legacy full-roster discovery. If a pod returns
@@ -540,11 +536,9 @@ switch authority models. Old relays may ignore unknown filter fields and
540536
return an ordinary array; this is not a valid compact response. Rollback may
541537
explicitly select legacy discovery with a new authority/session generation,
542538
without deleting saved display/user data. New relays keep legacy 39002 events,
543-
query shape, type opt-ins and signatures intact. Roll out the image to the
544-
**entire fleet with the flag off**, then enable the flag in a separate rollout.
545-
Rollback turns the flag off; clients recheck support and explicitly select
546-
legacy authority as above. Client opt-in and production-shaped throttled
547-
validation follow separately.
539+
query shape, type opt-ins and signatures intact. Disabling the capability
540+
requires clients to recheck support and explicitly select legacy authority
541+
as above.
548542

549543
## Compact public membership lookup (version 1)
550544

@@ -573,8 +567,8 @@ NIP-11 information document:
573567
}
574568
```
575569

576-
`BUZZ_MEMBERSHIP_PUBLIC_ENABLED` defaults to false, independently of
577-
`BUZZ_MEMBERSHIP_SNAPSHOT_ENABLED`. Disabled relays omit this descriptor and
570+
The operator switch for public lookup is off by default and independent of
571+
the self-snapshot switch. Disabled relays omit this descriptor and
578572
return HTTP 404 with `{"error":"membership_public unsupported"}` for this
579573
mode. An unresolved host never advertises it. Clients MUST obtain and pin
580574
this descriptor using the TLS-origin and relay-key rules of self mode.
@@ -607,9 +601,8 @@ between requester and subject expands the public scope or grants private
607601
access. A subject need not have a profile or current community membership;
608602
selection uses their active channel memberships in this community only.
609603

610-
Every attempt MUST consume the existing shared HTTP API-call quota keyed by
611-
community and requester (the bridge's `ApiCalls` bucket and configured
612-
`human_api_calls_per_min` limit), before selection. Changing subjects MUST NOT
604+
Every attempt MUST consume the requester's existing per-community API-call
605+
quota before selection. Changing subjects MUST NOT
613606
reset that quota. Exhaustion returns 429 using the bridge's existing
614607
`rate-limited: quota exceeded; retry in <seconds>s` error convention; shared
615608
admission unavailability returns 503 and fails closed. Clients MUST respect
@@ -684,13 +677,14 @@ its signature and identity do not prove present visibility or authorization.
684677

685678
### Selection, completeness and bounds
686679

687-
The relay MUST read the primary database in one SQL statement's MVCC
688-
snapshot. Select the subject's active `channel_members` rows joined to
689-
nondeleted channels in the same community, restricted to requested types,
690-
`visibility=open` and not unlisted, ordered by channel UUID. This is the
691-
listed-open discovery predicate, with no shared-private-channel exception.
692-
All entry fields MUST come from that same statement. Do not load, parse or
693-
serialize full rosters, peers' public keys or profiles.
680+
The relay MUST derive the complete response from one consistent read of
681+
committed state that reflects every change committed before the relay
682+
received the request. Select the subject's active memberships in nondeleted
683+
channels in the same community, restricted to requested types, open and not
684+
unlisted, ordered by channel UUID. This is the listed-open discovery
685+
predicate, with no shared-private-channel exception. All entry fields MUST
686+
reflect that same read. The projection MUST NOT include full rosters,
687+
peers' public keys or profiles.
694688

695689
There is one entry per matching membership. Preserve the subject's role
696690
(`owner`, `admin`, `member`, `bot` or `guest`); include archived channels with
@@ -702,7 +696,8 @@ existing read rules.
702696
`complete:true` means all of the subject's memberships satisfying this
703697
public predicate and requested type set at that instant. It never means
704698
the subject's full membership set. A channel absent on refresh may have
705-
become private, unlisted or deleted, or its membership may have ended; absence MUST NOT establish loss of membership.
699+
become private, unlisted or deleted, or its membership may have ended;
700+
absence MUST NOT establish loss of membership.
706701

707702
The snapshot identity is SHA-256 of the UTF-8 compact JSON array
708703
`["nip-cl-public-membership-v1", community_id, subject, types, channels]`,
@@ -719,7 +714,7 @@ partial list. Database/signing failure returns an error, never complete
719714
empty state. There are no pages, tokens, server snapshot caches or resume
720715
semantics in v1. A retry requires fresh NIP-98 auth.
721716

722-
### Discovery authority and rollout
717+
### Discovery authority and compatibility
723718

724719
A validated result MAY replace a cached public discovery list keyed by
725720
community, subject and exact requested types. It MUST NOT populate or alter
@@ -737,12 +732,10 @@ an ordinary array or the exact disabled 404 after another pod advertised
737732
support, mark public lookup unsupported for that generation, recheck its
738733
host-bound descriptor and back off capability probes. Keep any saved public
739734
list explicitly stale; this does not switch the self authority model.
740-
Auth failures,
741-
invalid signatures, malformed responses and transient errors MUST NOT be
742-
accepted as an empty result or silently retried through self mode.
743-
Deploy support to the entire fleet with the public flag off, then enable
744-
it separately. Public and self capability rollout and rollback are
745-
independent. Turning off public lookup stops its use without changing the
735+
Auth failures, invalid signatures, malformed responses and transient errors
736+
MUST NOT be accepted as an empty result or silently retried through self mode.
737+
Public and self capabilities can be enabled and disabled independently.
738+
Turning off public lookup stops its use without changing the
746739
self-membership authority/session generation or deleting saved display data.
747740

748741
### Normative examples and rejection cases

0 commit comments

Comments
 (0)