@@ -1,780 +0,0 @@
|
||||
# Using the Concord backend
|
||||
|
||||
`crates/concord` is a protocol crate: derivations, envelopes, folds and the local
|
||||
state document. It has no GPUI dependency and owns no strings a user reads — the
|
||||
UI layer decides every rendering. This document is the map from a UI action to
|
||||
the calls it makes.
|
||||
|
||||
A community is addressed by a `community_id` (never on the wire) plus three
|
||||
secrets: `community_root` (read access — holding it *is* membership),
|
||||
`control_root` (write access to the Control Plane, held by staff), and per-Channel
|
||||
keys for private channels. Authority is a roster of owner-rooted signed grants,
|
||||
folded independently by every client.
|
||||
|
||||
## Modules
|
||||
|
||||
Files follow the CORD documents. The frozen derivations of Appendix A and the id
|
||||
vocabulary are shared substrate — every document calls them — so they live outside
|
||||
`cords` in `utils::derive` (re-exported as `derive`) and `types`.
|
||||
|
||||
| Module | Owns |
|
||||
| --- | --- |
|
||||
| `cord01` | Private Streams: the seal/wrap envelope and the NIP-44 helpers |
|
||||
| `cord02` | Communities: identity, epochs, metadata, the Control Plane fold and writer |
|
||||
| `cord02::guestbook` | Joins, leaves, kicks, snapshots, the member list |
|
||||
| `cord02::list` | The Community List (a member's own memberships, across devices) |
|
||||
| `cord03` | Channels: Channel metadata and the Chat Plane |
|
||||
| `cord04` | Roles: chained editions, parse/hash/fold, the roster, permissions, the banlist |
|
||||
| `cord04::pins` | Pin Lists, and the key disclosure a keyless reader verifies |
|
||||
| `cord05` | Invite bundles, links, the Direct Invite, the Invite List |
|
||||
| `cord06` | Key rotations, refounding, compaction, dissolution |
|
||||
| `derive` | Every frozen HKDF derivation and coordinate |
|
||||
| `state` | The community state document and its pure folds — no I/O |
|
||||
|
||||
`CommunityId`, `ChannelId`, `RoleId`, `Epoch` and `Extra` (crate-internal) come from
|
||||
the private `types` module and are re-exported at the crate root.
|
||||
|
||||
Nothing in `concord` touches a relay or a database. The local rumor cache, the
|
||||
state documents and the relay paging walk live one crate up, in
|
||||
`community::cache` and `community::history`, and are what a client actually calls
|
||||
(read on below).
|
||||
|
||||
CORD-07 (audio/video) is unimplemented. CORD-08's timer has no file of its own: it
|
||||
lives in the metadata it reads (`cord02`) and the fold it filters (`cord03`).
|
||||
|
||||
Read `CommunityId` as "this community", `ChannelId` as "this channel", `Epoch` as
|
||||
"which key generation". Nothing else in the API needs internal state.
|
||||
|
||||
## Creating a community
|
||||
|
||||
```rust
|
||||
use concord::cord02::{self, CommunityMetadata};
|
||||
use concord::state::CommunityState;
|
||||
use community::cache::save_state;
|
||||
|
||||
let metadata = CommunityMetadata { name: "Room".into(), ..Default::default() };
|
||||
let minted = cord02::genesis(&owner_keys, &metadata, now_secs).await?;
|
||||
|
||||
// minted.identity — community_id, owner, owner_salt (verify() recomputes it)
|
||||
// minted.wraps — the two owner-signed genesis editions, already sealed
|
||||
// minted.channel_id — the #general channel
|
||||
for wrap in &minted.wraps {
|
||||
client.send_event(wrap).to(&relays).await?;
|
||||
}
|
||||
```
|
||||
|
||||
The owner then needs the folded state, which is also what every member does on
|
||||
join:
|
||||
|
||||
```rust
|
||||
use concord::derive::{control_group_key, control_signer_group_key};
|
||||
use concord::cord04::ParsedEdition;
|
||||
|
||||
let read = control_group_key(&minted.community_root, &minted.identity.community_id, Epoch(0))?;
|
||||
let signer = control_signer_group_key(&minted.control_root, &minted.identity.community_id, Epoch(0))?;
|
||||
let editions: Vec<ParsedEdition> = minted
|
||||
.wraps
|
||||
.iter()
|
||||
.map(|wrap| cord02::open_edition(wrap, &read, &signer.pk(), true))
|
||||
.collect::<Result<_, _>>()?;
|
||||
|
||||
let mut state = CommunityState::from_genesis(&minted, &editions, added_at_ms)?;
|
||||
save_state(&client, &state).await?;
|
||||
```
|
||||
|
||||
Put the community's relay list into `state.relays` and add those relays to the
|
||||
client explicitly — coop's client is a gossip client with no background refresh.
|
||||
|
||||
Creating is not finished until the membership is announced. The two writes are
|
||||
independent and both best-effort: the genesis wraps go to the community's
|
||||
relays, and the membership goes to the account's own Community List (below), so a
|
||||
new device — or another client — can find the community without an invite.
|
||||
`crates/community`'s `sync::create` performs both.
|
||||
|
||||
## Joining
|
||||
|
||||
An invite link resolves to a bundle:
|
||||
|
||||
```rust
|
||||
use concord::cord05::{self, BundleState, invite_bundle_key};
|
||||
|
||||
let link = cord05::parse_link(url)?; // link_signer, token, bootstrap_relays, naddr
|
||||
|
||||
// The crate does no I/O: fetch the naddr from the fragment's relays, then:
|
||||
let invite = match cord05::parse_bundle_event(&event, &link.link_signer, &invite_bundle_key(&link.token))? {
|
||||
BundleState::Live(invite) => invite, // validate() already ran
|
||||
BundleState::Revoked => return Ok(None), // a tombstone at the coordinate
|
||||
};
|
||||
```
|
||||
|
||||
A Direct Invite arrives as a NIP-59 gift wrap addressed to the member:
|
||||
|
||||
```rust
|
||||
let (inviter, invite) = cord05::unwrap_direct_invite(&wrap, &my_keys).await?;
|
||||
```
|
||||
|
||||
Either way the invite carries `community_id`, `owner`, `owner_salt`,
|
||||
`community_root`, `root_epoch`, `control_pk`, the granted `channels`
|
||||
(`ChannelGrant { id, key, epoch, name }`) and the relay set. `invite.expired(now_ms)`
|
||||
is a preview rule: a past expiry still renders, but the join is refused.
|
||||
|
||||
Then publish a join so the member list sees the member before any backfill:
|
||||
|
||||
```rust
|
||||
use concord::derive::guestbook_group_key;
|
||||
use concord::cord02::guestbook;
|
||||
|
||||
let guestbook = guestbook_group_key(&invite.community_root, &invite.community_id, invite.root_epoch)?;
|
||||
let rumor = cord02::guestbook::build_join(my_pk, Some((creator_npub, label)), now_ms);
|
||||
let (wrap, _) = cord02::guestbook::seal_rumor(&rumor, &guestbook, &my_keys).await?;
|
||||
client.send_event(&wrap).to(&relays).await?;
|
||||
```
|
||||
|
||||
## Reading the Control Plane
|
||||
|
||||
```rust
|
||||
use concord::cord02::{self, ControlFold};
|
||||
|
||||
let editions: Vec<ParsedEdition> = wraps
|
||||
.iter()
|
||||
.filter_map(|wrap| cord02::open_edition(wrap, &read, &control_pk, true).ok())
|
||||
.collect();
|
||||
|
||||
let control: ControlFold =
|
||||
cord02::fold_control(&owner, &community_id, &editions, &state.floors(), &state.banned);
|
||||
state.apply_fold(&control);
|
||||
```
|
||||
|
||||
`ControlFold` is everything the community UI needs:
|
||||
|
||||
| Field | Use |
|
||||
| --- | --- |
|
||||
| `community` | name, description, icon, banner, `message_expiration` |
|
||||
| `channels` | the channel list; `deleted: true` means drop it |
|
||||
| `roles` | `role()`, `roles_of()`, `effective_permissions()`, `is_authorized()`, `is_staff()` |
|
||||
| `banned` | the banlist |
|
||||
| `registries` / `is_public()` | each invite creator's live link signers |
|
||||
| `pins` / `pin_content(id, channel)` | Pin List content per channel |
|
||||
| `floors` | the committed heads the next fold is judged against |
|
||||
| `gapped` | a chain hole: refetch the Control Plane before trusting what is missing |
|
||||
|
||||
`None` on `community` or a channel means "this client saw no authorized edition",
|
||||
never "the value is gone" — keep what the state already holds rather than walking
|
||||
the community backwards. Feed `state.floors()` and `state.banned` into the next
|
||||
fold; they are its memory.
|
||||
|
||||
## Sending a message
|
||||
|
||||
```rust
|
||||
use concord::cord03::{self, build_message};
|
||||
use concord::derive::channel_group_key;
|
||||
|
||||
let plane = channel_group_key(&community_root, &channel, epoch)?; // public channel
|
||||
let rumor = build_message(my_pk, &channel, epoch, text, None, at_ms, timer);
|
||||
let (wrap, wrap_key) = cord03::seal_rumor(&rumor, &plane, &my_keys, false).await?;
|
||||
client.send_event(&wrap).to(&relays).await?;
|
||||
```
|
||||
|
||||
- `epoch` is the **root** epoch for a public channel: its plane is
|
||||
`channel_group_key(community_root, channel, root_epoch)`, so a Refounding moves
|
||||
it along with the root. A private channel passes its own current channel epoch
|
||||
(`state.channels` carries it) and derives from its own key instead of
|
||||
`community_root`.
|
||||
- `timer` is `control.community.message_expiration`; pass `None` when it is off.
|
||||
The builder attaches the NIP-40 tag and `seal_rumor` mirrors it onto the wrap,
|
||||
so relays drop the ciphertext too.
|
||||
- `ephemeral: true` picks kind `21059` for typing indicators. Keep the returned
|
||||
wrap key if the message may be deleted later — a kind-5 delete needs it.
|
||||
- That `send_event` is the whole publish path; there is no optimistic echo. Feed
|
||||
the wrap through the same ingest path the subscription uses so send-then-read
|
||||
never waits on a relay round trip.
|
||||
|
||||
`build_edit`, `build_reaction` and `build_delete` are the same shape, each a rumor
|
||||
about an existing `EventId` rather than a mutation.
|
||||
|
||||
## Reading a channel
|
||||
|
||||
```rust
|
||||
use concord::cord03::{self, fold, plane_keys};
|
||||
use community::cache;
|
||||
|
||||
let planes = plane_keys(&held, &channel)?; // &[(Epoch, secret)]
|
||||
let mut rumors = Vec::new();
|
||||
|
||||
for wrap in &wraps {
|
||||
let Some((epoch, group)) = planes.iter().find(|(_, group)| group.pk() == wrap.pubkey) else {
|
||||
continue;
|
||||
};
|
||||
let Ok((opened, rumor)) = cord03::open(wrap, group, &channel, *epoch) else {
|
||||
continue;
|
||||
};
|
||||
cache::cache_rumor(&client, &channel, &opened).await?;
|
||||
rumors.push(rumor);
|
||||
}
|
||||
|
||||
let messages = fold(&rumors, Timestamp::now(), |actor, citation, author| {
|
||||
citation_ok(&owner, &community_id, actor, citation, &control.roles.floors)
|
||||
&& control.roles.can_act_on_member(actor, &owner, author, Permissions::MANAGE_MESSAGES)
|
||||
});
|
||||
```
|
||||
|
||||
`ChatMessage` carries `content`, `at_ms`, `edited_at`, `deleted`, `reactions`,
|
||||
`reply_to` and `thread_root` already resolved. The fold drops expired rumors; a
|
||||
`deleted` row is still returned so the timeline keeps its shape.
|
||||
|
||||
Relay history pages through the local cache:
|
||||
|
||||
```rust
|
||||
use community::history::{self, PageRegistry, Window};
|
||||
|
||||
// Every key the client still holds for the channel, newest epoch first: the
|
||||
// state's current key (`ChannelKeyRef::key` at `epoch`) plus every `priors`
|
||||
// entry a rotation stepped off. A public channel derives one per held root.
|
||||
let held: Vec<concord::state::HeldKey> = state.held_keys(&channel);
|
||||
|
||||
// The same registry `CommunityRegistry` shares with its notification pump: it is
|
||||
// what carries each page's EOSE and CLOSED back to the round waiting on it.
|
||||
let page = history::page(
|
||||
client,
|
||||
&pages,
|
||||
&channel,
|
||||
&held,
|
||||
&relays,
|
||||
Window::opening(cursor),
|
||||
20,
|
||||
50,
|
||||
)
|
||||
.await?;
|
||||
let cached = cache::query_rumors(&client, &channel, None, 50, Some(&cord03::ROW_KINDS)).await?;
|
||||
```
|
||||
|
||||
A key's `retired_at` (a `Timestamp`, set when a rotation supersedes it) is a read
|
||||
cutoff: a wrap at that epoch with a later `created_at` is refused, so a retired
|
||||
epoch is history and never a live plane an ejected holder can keep writing into.
|
||||
|
||||
A relay is only ever *asked*: `history::page` installs **one REQ per page** over
|
||||
`ReqTarget::manual` for the community's own relays (which is what makes the client
|
||||
verify a wrap, deduplicate it and persist it), waits for every relay to settle,
|
||||
and then reads the page back out of the local database — no wrap is ever consumed
|
||||
straight off the wire, and `fetch_events` is not used anywhere. The wrap lands in
|
||||
the client's shared event store through that ordinary ingest path; `cache_rumor`
|
||||
then puts the decrypted rumor beside it, and only the rumor is ever served to a
|
||||
reader.
|
||||
|
||||
EOSE and CLOSED are **not** watched inside the page. The registry's notification
|
||||
pump is the only consumer of `client.notifications()`; it delivers one
|
||||
`PageReport` per settling relay into the `PageRegistry` under the page's
|
||||
subscription id, and the page waits on that channel with `PAGE_TIMEOUT`. The id
|
||||
is opaque (`concord-history-<n>`) because a NIP-01 id is capped at 64 characters,
|
||||
and the registry is what maps it back to the waiting round.
|
||||
|
||||
A page ends on EOSE. A CLOSED ends it as unanswered, *except* NIP-42's
|
||||
`auth-required`: the SDK re-issues that REQ under the same subscription id once
|
||||
the handshake completes, so the page waits for the resubscribed answer rather
|
||||
than writing off a relay that only wanted to authenticate.
|
||||
|
||||
`history::page` walks newest-first across every held epoch, caches what it opens, and
|
||||
reports what it saw: `oldest`/`newest` feed the caller's `ChannelCursor`,
|
||||
`exhausted` is earned only by a short page *after* history was seen, and an
|
||||
all-empty answer sets `failed` so a later round re-asks instead of sealing the
|
||||
channel at "no more history". `unreadable` counts the wraps the page reached that
|
||||
no held key could open — sealed past the cutoff their key's rotation set, or bound
|
||||
to another channel — because those are history the reader is missing, not history
|
||||
that is not there. Page down with `Window::older_than(seen.oldest)`,
|
||||
open a channel with `Window::opening(cursor)` (wide cold, `newest - 60s` warm),
|
||||
and read the region between two cursors with `Window::between(..)`. A `Window`
|
||||
carries `Timestamp`s, so its bounds go straight into a NIP-01 filter with no unit
|
||||
conversion; only a reader's millisecond `at_ms` narrows to a second at the query.
|
||||
`query_rumors` is the read path when the group keys are gone; pass `kinds` to
|
||||
budget rows apart from the events that only decorate them. `cache::wrapper_index`
|
||||
reads the cached rows back keyed by the wrap they came from, which is what lets
|
||||
`sync::fold` observe author and message times without re-opening a wrap it already
|
||||
cached, and `cache::purge_expired(client, &channel, now)` runs at the top of every
|
||||
round — the timer is cooperative, so the local store is the artifact that has to
|
||||
forget.
|
||||
|
||||
`sync::fold` counts the same thing over the whole store, per channel, in
|
||||
`Snapshot.unreadable`. `sync_round` sums a round's pages into
|
||||
`Progress.unreadable`, and `Community` keeps both per channel: `progress(channel)`
|
||||
is the last completed round, `unreadable(channel)` is the count, and
|
||||
`missing_key(channel)`, `channel_removed_at(channel)`, `removed_at()` and
|
||||
`stranded()` are the rest of the honest read surface a panel needs to tell an
|
||||
empty room from one it cannot read. `Community::due(channel)` is the other half —
|
||||
whether a round is worth asking for yet (a round for `Older` and an explicit retry
|
||||
never ask it), and `Community::tick`, driven by `CommunityRegistry` once per
|
||||
`community::MIN_ROUND_INTERVAL`, re-folds and re-rounds the active channel of a
|
||||
community whose last round is older than `STALE_AFTER`.
|
||||
|
||||
`ChatAction::TimerNotice { seconds }` is a policy notice, not a message: render it
|
||||
as an inline row only when its author passes
|
||||
`control.roles.is_authorized(&author, &owner, Permissions::MANAGE_METADATA)`.
|
||||
|
||||
## Membership
|
||||
|
||||
```rust
|
||||
let states = cord02::guestbook::coalesce(&rumors, now_ms, &refounders, |actor, target, citation| {
|
||||
citation_ok(&owner, &community_id, actor, citation, &control.roles.floors)
|
||||
&& control.roles.can_act_on_member(actor, &owner, target, Permissions::KICK)
|
||||
});
|
||||
let members = cord02::guestbook::complete_memberlist(&states, &observed, &granted, &control.banned, &BTreeMap::new());
|
||||
```
|
||||
|
||||
- `refounders` is the set of npubs whose rotations minted an epoch this client
|
||||
verified (`CommunityState.refounders`) — a snapshot chunk is honored only from
|
||||
one of them, and an empty set honors none. A rotation that delivered this
|
||||
client no key still names its minter, so the set is filled by any base rotation
|
||||
whose continuity verifies against a root held (`rekey::walk`); a List entry's
|
||||
`refounder`, read by `list::JoinMaterial::refounder`, is the other source.
|
||||
- `observed` is npub → ms for every author this client has seen publish anything
|
||||
usable, which is what makes a member visible before their Join arrives. Only
|
||||
count it forward.
|
||||
- `granted` is every npub the roster ranks; they are members with no Guestbook
|
||||
entry at all.
|
||||
- `banned_at` is empty today, so a ban is terminal in the fold. Fill it when the
|
||||
banlist head's timestamp is plumbed through.
|
||||
- Removal is three separate actions, composed by the caller: strip the grant
|
||||
(immediate and cheap), then the kick directive, then — for a ban — the rotation
|
||||
that actually enforces it.
|
||||
|
||||
## Moderation writes
|
||||
|
||||
Every Control Plane write goes through one writer and one edition shape:
|
||||
|
||||
```rust
|
||||
let writer = ControlWriter { author: my_pk, read: read.clone(), signer: signer.clone() };
|
||||
let head = control.floors.get(entity).cloned();
|
||||
|
||||
let (wrap, new_head) = writer.set_community_metadata(
|
||||
&my_keys, &community_id, &metadata, head.as_ref(), citation, now_secs).await?;
|
||||
```
|
||||
|
||||
`citation` is the `vac` the actor acts under — `None` only for the owner. Build it
|
||||
from the folded Grant that ranks them (`AuthorityCitation { entity, version, hash }`)
|
||||
and pass the head from the current fold, so the chain cannot silently fork.
|
||||
|
||||
Wrappers: `set_community_metadata`, `set_channel_metadata`, `set_role`,
|
||||
`set_grant`, `set_banlist`, `set_registry`, `set_pin_list`, plus raw `publish`.
|
||||
A ban is a `set_banlist` followed by a base rekey; a kick is a `set_grant` with an
|
||||
empty `role_ids` followed by `cord02::guestbook::build_kick`.
|
||||
|
||||
## Pins
|
||||
|
||||
```rust
|
||||
use concord::cord04::pins;
|
||||
|
||||
let entry = cord04::pins::build_entry(&opened_message, &plane, &channel)?;
|
||||
let head_content = control.pin_content(&community_id, &channel).unwrap_or("");
|
||||
let read = cord04::pins::read_list(head_content, |epoch| channel_group_key(&root, &channel, epoch).ok());
|
||||
let content = cord04::pins::publishable(&read, channel_is_private, &plane, epoch)?;
|
||||
let (wrap, _) = writer.set_pin_list(
|
||||
&my_keys, &community_id, &channel, &content, head, citation, now_secs).await?;
|
||||
```
|
||||
|
||||
Reading is verification: `read_list` decodes either content form (public, or
|
||||
sealed under the channel key at the named epoch), and
|
||||
`cord04::pins::verify_entry(entry, &channel)` returns a `VerifiedPin` with the proven
|
||||
author, words and time — no history and no old keys needed. `read.sealed` means
|
||||
the list is sealed under an epoch this client never held: show it as unavailable,
|
||||
and never write from it (`publishable` refuses). `cord04::pins::killed_by(&pin, &delete)`
|
||||
answers whether a folded kind-5 erases an entry.
|
||||
|
||||
## Invites
|
||||
|
||||
```rust
|
||||
use concord::derive::{invite_bundle_key, TOKEN_LEN};
|
||||
use concord::cord05::{self, InviteEntry, InviteTombstone};
|
||||
|
||||
let token: [u8; TOKEN_LEN] = /* 16 bytes from any CSPRNG */;
|
||||
let bundle_key = invite_bundle_key(&token);
|
||||
let link_signer = Keys::generate();
|
||||
let bundle = cord05::build_bundle_event(&link_signer, &invite, &bundle_key)?;
|
||||
let url = cord05::build_invite_url(BASE, &link_signer.public_key(), &token, &relays)?;
|
||||
```
|
||||
|
||||
A link is a coordinate plus a fragment: the naddr fetches the bundle, the token
|
||||
unlocks it, and the fragment names the relays to fetch from.
|
||||
`cord05::stock_relays()` is what a fragment with no relays of its own means.
|
||||
|
||||
The `link_signer` secret is what lets the creator refresh or retire the link, so
|
||||
keep it against the token in the member's own Invite List — a local document
|
||||
encrypted to self, exactly like the Community List:
|
||||
|
||||
```rust
|
||||
let mut list = cord05::parse_invite_list(&my_keys, &event).await?;
|
||||
list.entries.push(InviteEntry {
|
||||
token: HEXLOWER.encode(&token),
|
||||
signer_sk: link_signer.secret_key().to_secret_hex(),
|
||||
community_id: invite.community_id,
|
||||
url,
|
||||
label: None,
|
||||
created_at: now_ms,
|
||||
expires_at: None,
|
||||
extra: Default::default(),
|
||||
});
|
||||
let event = cord05::build_invite_list(&my_keys, &list).await?; // kind 13303
|
||||
|
||||
// Retiring is a tombstone, never a deletion: it beats a stale copy terminally.
|
||||
list.tombstones.push(InviteTombstone {
|
||||
token: HEXLOWER.encode(&token),
|
||||
community_id: invite.community_id,
|
||||
extra: Default::default(),
|
||||
});
|
||||
```
|
||||
|
||||
`merge_invite_lists` merges two devices' copies, `is_live(&token_hex)` answers
|
||||
whether a link still stands, and `fits()` is the write gate.
|
||||
|
||||
## Rekeys, refounding and dissolution
|
||||
|
||||
A rotation is authority plus delivery: `rekey_authorized(&control.roles, &owner, &me, permission, &removed)`
|
||||
gates it, `plan_rotation(scope, epoch)` mints what it delivers, and
|
||||
`build_rekey_chunks` seals one blob per remaining member:
|
||||
|
||||
```rust
|
||||
use concord::derive::epoch_key_commitment;
|
||||
use concord::cord06::{self, RekeyScope, RotationPlan};
|
||||
|
||||
let scope = RekeyScope::Channel(channel_id); // or RekeyScope::Base
|
||||
let plan = cord06::plan_rotation(scope, Epoch(epoch + 1))?;
|
||||
let new_key = plan.new_key();
|
||||
|
||||
// A base rotation delivers the new control-plane keys beside the root; a channel
|
||||
// rotation delivers only that channel's fresh key.
|
||||
let (control_pk, control_root) = match &plan {
|
||||
RotationPlan::Base(refounding) => {
|
||||
let pk = refounding.signer(&community_id)?.pk().to_bytes();
|
||||
(Some(pk), is_staff.then_some(&refounding.new_control_root))
|
||||
}
|
||||
RotationPlan::Channel { .. } => (None, None),
|
||||
};
|
||||
|
||||
let mut blobs = Vec::with_capacity(members.len());
|
||||
|
||||
for member in &members {
|
||||
blobs.push(
|
||||
cord06::build_blob(
|
||||
&my_keys,
|
||||
member,
|
||||
scope,
|
||||
plan.epoch(),
|
||||
&new_key,
|
||||
control_pk.as_ref(),
|
||||
control_root,
|
||||
)
|
||||
.await?,
|
||||
);
|
||||
}
|
||||
|
||||
let rekey_group = cord06::rekey_group(scope, &community_root, &community_id, plan.epoch())?;
|
||||
let wraps = cord06::build_rekey_chunks(
|
||||
&my_keys,
|
||||
&rekey_group,
|
||||
scope,
|
||||
plan.epoch(),
|
||||
Epoch(epoch),
|
||||
&epoch_key_commitment(Epoch(epoch), &community_root),
|
||||
&blobs,
|
||||
citation,
|
||||
false,
|
||||
now_secs,
|
||||
)
|
||||
.await?;
|
||||
```
|
||||
|
||||
On the receiving side, `cord06::parse_rekey_chunk(&opened)` per wrap, then
|
||||
`collect_rotations(&chunks)`, then `am_i_removed(&rotation, &me)` — which is
|
||||
`None` until every chunk is held, because an incomplete set is never a removal. A
|
||||
member finds their delivery with `find_my_blobs` / `open_blob`, and adopts the key
|
||||
only if the plaintext binds to the scope and epoch they expect and its `prevcommit`
|
||||
matches the key they already hold. Two concurrent rotations settle on `fork_winner`.
|
||||
|
||||
`community::rekey::adopt` is that receiver, run against the local database: it
|
||||
walks a scope forward one epoch at a time off the key actually held (never
|
||||
waiving a gap, never adopting a fork), keeps each stepped-off key as a prior
|
||||
with the rotation's publish time as its read cutoff, and reports a removal or a
|
||||
strand when a complete rotation carries no blob for the member.
|
||||
|
||||
`community::rekey::rotate` is the sender, run against the held state: it resolves
|
||||
the epoch and key the scope is stepping off, refuses a rotation that would skip or
|
||||
cut off its own rotator, delivers one blob per recipient (`Rewrite.recipients`,
|
||||
which the caller names because a private channel's audience is not in the local
|
||||
state), marks the rotation severed when it excludes somebody, and — for a base
|
||||
scope — carries the settled Control Plane heads onto the new epoch's groups with
|
||||
`cord06::compact`. `Community::rotate` checks `Rewrite::authorized` first, the same
|
||||
`rekey_authorized` under the same permissions `adopt` applies, publishes to the
|
||||
community's relays, and then adopts what it published through `rekey::adopt`
|
||||
rather than by construction: a rotation this client wrote and one it received take
|
||||
one path.
|
||||
|
||||
The blob plaintext is a fixed-width binary record, but a signer's NIP-44 is
|
||||
text-only, so `build_blob` carries it base64-encoded inside the envelope.
|
||||
`open_blob` mirrors that, so the record layout and the `locator` are unchanged.
|
||||
|
||||
Dissolution is owner-only and terminal:
|
||||
|
||||
```rust
|
||||
let rumor = cord06::dissolved_tombstone_rumor(owner_pk, &community_id, now_secs);
|
||||
let wrap = cord06::seal_dissolved(&rumor, &community_id, &my_keys, now_secs).await?;
|
||||
|
||||
// A receiver seals the community read-only on sight.
|
||||
if cord06::verify_dissolved(&wrap, &identity) {
|
||||
state.dissolved = true;
|
||||
}
|
||||
```
|
||||
|
||||
## The Community List
|
||||
|
||||
A member's own memberships, synced across their devices:
|
||||
|
||||
```rust
|
||||
use concord::cord02::list;
|
||||
|
||||
let entry = concord::state::list_entry(&state, &metadata.name); // state → §8 material
|
||||
let held = list::parse_list_event(&my_keys, &event).await?; // validates the d tag
|
||||
let mine = held.joined(entry); // community_id-keyed union
|
||||
let event = list::build_list_event(&my_keys, &mine, 0, now_secs).await?; // kind 33302, d = 0
|
||||
client.send_event(&event).to_nip65().await?; // account's own write relays
|
||||
```
|
||||
|
||||
The publish needs no separate database write: `send_event` persists the event
|
||||
locally *before* it resolves targets, so the fragment is available to the
|
||||
`concord/list` read path even if every relay is unreachable.
|
||||
|
||||
`join_material(&invite, control_root)` makes the §8 material from a CORD-05
|
||||
invite; `concord::state::list_entry(state, name)` makes it from a `CommunityState`, and is
|
||||
what a write path uses after a create, join or rename. `joined` and `tombstoned`
|
||||
are the two mutations: both are `community_id`-keyed unions, so neither an append
|
||||
nor a leave can lose a membership the other writer has.
|
||||
|
||||
The entry is signed by the member's real key and sealed to that same key
|
||||
(`seal_to_self`), so only the member's devices read it — a stranger's
|
||||
`parse_list_event` fails rather than returning a partial list. Publishing goes to
|
||||
the member's **NIP-65 write relays**, the same set the `concord/list`
|
||||
subscription resolves for its `author` filter.
|
||||
|
||||
Kind `33302` is **addressable and fragmented**: one event per fragment, its `d`
|
||||
tag the fragment index in decimal. `frags` in the payload declares how many the
|
||||
List has, and `is_complete(held_indices)` answers whether the client has a
|
||||
fragment at every index below it. `merge` resolves a `frags` disagreement to the
|
||||
larger value. (`13302`, the single-event List, is retired by the spec — a
|
||||
replaceable kind cannot fragment.)
|
||||
|
||||
A join material may also carry two hex extensions this crate does not write but
|
||||
does read, because they are the only place a device that never held a rotation can
|
||||
learn who minted an epoch: `refounder` names the npub whose Refounding minted the
|
||||
entry's `root_epoch`, and `held_roots` is the retained prior epochs
|
||||
(`[{epoch, key, refounder?, control_pk?, retired_at?}]`). `JoinMaterial::refounder()`
|
||||
and `JoinMaterial::held_roots()` decode both; unknown fields are round-tripped
|
||||
regardless, so a document that carries them keeps them.
|
||||
|
||||
The payload's 32-byte values are **unpadded base64url at every depth**, which is
|
||||
section-scoped to §8: CORD-05 invites stay hex. The writer re-encodes them on
|
||||
every serialization, so its output is always the canonical 43-character spelling;
|
||||
the reader also accepts non-zero trailing bits, because the spec's own worked
|
||||
example contains them and no reader can tell a mis-encoded named field from a
|
||||
correct one. The codec is `utils::base64url` and the wire structs behind the
|
||||
List's `Serialize`/`Deserialize` are the only callers, so no other encoding path
|
||||
is touched.
|
||||
|
||||
Three write-time rules are folded into serialization, so an in-memory document
|
||||
and its wire form differ:
|
||||
|
||||
- an embedded snapshot omits `community_id` and inherits the entry's;
|
||||
- `seed` is omitted when it equals `current`, and its cosmetic fields (`name`,
|
||||
`relays`, each channel's `name`) are overwritten from `current` first, so a
|
||||
rename collapses the snapshots instead of forking them;
|
||||
- an entry whose `added_at` does not outrun its tombstone is omitted — the
|
||||
tombstone alone carries the state.
|
||||
|
||||
`is_live(&id)` answers joined-versus-left: a tombstone is terminal until a
|
||||
strictly newer join outruns it. `fits()` is the write gate: 50 memberships and
|
||||
the NIP-44 plaintext cap. The 50 is a stopgap inherited from the retired
|
||||
single-event design — §8 has **no membership limit**, its only bound is the
|
||||
65,536-byte encoded event, and the real fix is to start a new fragment on write.
|
||||
Until that lands, an append onto a List that already spans more than one fragment
|
||||
is refused rather than performed against a partial read, because placing a new
|
||||
membership needs a repack. The community stays local (`load` keeps a membership
|
||||
the List never mentions) and the write is deferred with a warning.
|
||||
|
||||
Discovery is a **subscription, not a fetch**: subscribe with
|
||||
`Filter::new().kind(Kind::Custom(KIND_COMMUNITY_LIST)).author(my_pk)` and read the
|
||||
fragments back out of `client.database()`. The client persists a relay's event
|
||||
before it notifies, so a subscription plus a database read loses nothing and
|
||||
needs no explicit save. Parse each event with `parse_list_event`, keep the newest
|
||||
per `fragment_index`, and `merge` them — reading an incomplete List is safe, since
|
||||
a missing fragment is only news not yet heard.
|
||||
|
||||
## GPUI integration
|
||||
|
||||
`crates/concord` stays GPUI-free; the registry and sync engine live in
|
||||
`crates/community`. That layer adds a registry global and one
|
||||
entity per community, and moves every decrypt, verification, fold and I/O off
|
||||
the foreground thread.
|
||||
|
||||
### Entities
|
||||
|
||||
Same shape as `ChatRegistry`:
|
||||
|
||||
```rust
|
||||
pub fn init(cx: &mut App) {
|
||||
CommunityRegistry::set_global(cx.new(CommunityRegistry::new), cx);
|
||||
}
|
||||
|
||||
impl CommunityRegistry {
|
||||
pub fn global(cx: &App) -> Entity<Self> {
|
||||
cx.global::<GlobalCommunityRegistry>().0.clone()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Call it after `cord03::init` in `desktop/src/main.rs` and `web/src/lib.rs`, and
|
||||
subscribe to `NostrRegistry` for `SignerChanged` so the communities reset with
|
||||
the account.
|
||||
|
||||
- `CommunityRegistry` holds `communities: Vec<Entity<Community>>`, an index by
|
||||
`CommunityId`, and `tasks: SmallVec<[Task<Result<()>>; 2]>`.
|
||||
- `Community` owns one `CommunityState`, the last `ControlFold`, the member list
|
||||
and the channel list. Views render `Entity<Community>`; no protocol state
|
||||
lives in a view.
|
||||
- `CommunityState::apply_fold` is one assignment: run it in the task that
|
||||
produced the fold and send only the result to the foreground.
|
||||
- Emit an event on every fold so dependents re-read.
|
||||
|
||||
### Foreground and background
|
||||
|
||||
A background task never touches an entity. It sends results through a bounded
|
||||
`flume` channel that a foreground `cx.spawn` drains with `this.update(...)`.
|
||||
|
||||
```rust
|
||||
let (signal_tx, signal_rx) = flume::bounded::<Signal>(256);
|
||||
let client = client.clone();
|
||||
|
||||
// Background: open, verify, fold — no entities.
|
||||
self.ingress = Some(cx.background_spawn(async move {
|
||||
for wrap in &wraps {
|
||||
let Some(plane) = planes.iter().find(|plane| plane.group.pk() == wrap.pubkey) else {
|
||||
continue;
|
||||
};
|
||||
let (opened, rumor) = cord03::open(wrap, &plane.group, &plane.channel, plane.epoch)?;
|
||||
cache::cache_rumor(&client, &plane.channel, &opened).await?;
|
||||
signal_tx.send_async(Signal::Chat { channel: plane.channel, rumor }).await?;
|
||||
}
|
||||
Ok(())
|
||||
}));
|
||||
|
||||
// Foreground: the only place entities change.
|
||||
self.consumer = Some(cx.spawn(async move |this, cx| {
|
||||
while let Ok(signal) = signal_rx.recv_async().await {
|
||||
this.update(cx, |this, cx| this.apply(signal, cx))?;
|
||||
}
|
||||
Ok(())
|
||||
}));
|
||||
```
|
||||
|
||||
- Every cache function takes the `&Client` and reaches the database through
|
||||
`client.database()`, so clone the `Client` into the background task.
|
||||
- Keep long-lived tasks in fields — dropping a `Task` cancels it. Assign `None`
|
||||
to an `Option<Task<_>>` before respawning it; a signer change replaces both
|
||||
the listener and the consumer.
|
||||
- `cx.spawn` when the work updates an entity after awaiting, and
|
||||
`cx.background_spawn` when it only produces a value. A query the foreground awaits can be returned straight out: `fn messages(&self, cx: &App) -> Task<Result<Vec<ChatMessage>, Error>>`.
|
||||
- Do the first load in `cx.defer_in(window, ...)` so `init` returns before the
|
||||
first relay request.
|
||||
- NIP-46 signing is async: call `signer.get_public_key_async()` /
|
||||
`sign_event_async` inside the background task. Every account-key writer takes
|
||||
any signer (`Keys` or the app's `UniversalSigner`) and is `async`, so `await`
|
||||
it there rather than requiring device keys.
|
||||
|
||||
### Subscriptions
|
||||
|
||||
A wrap is addressed to a plane, so the plane's public key is the routing key and
|
||||
one `Filter` per held plane is enough:
|
||||
|
||||
```rust
|
||||
let filter = Filter::new()
|
||||
.kinds([Kind::from(KIND_WRAP), Kind::from(KIND_WRAP_EPHEMERAL)])
|
||||
.pubkey(plane.group.pk())
|
||||
.since(joined_at);
|
||||
client.subscribe(filter).with_id(sub_id).await?;
|
||||
```
|
||||
|
||||
- `pubkeys([...])` carries every plane of a community on one subscription. Call
|
||||
`subscribe` again with the new address whenever a join, a channel add or a
|
||||
rekey fold changes it.
|
||||
- Route inbound events by `subscription_id` from `RelayMessage::Event`, never by
|
||||
kind.
|
||||
- Watch one epoch ahead for the base, and a **window** of channel epochs under
|
||||
every held root for private channels: `base_rekey_group_key(&root_N, &id,
|
||||
Epoch(N + 1))`, plus `channel_rekey_group_key(&root, &channel, Epoch(channel_epoch
|
||||
+ ahead))` for `ahead in 1..=8` and each root in `state.roots()`. A Refounding
|
||||
seals its channel rekeys under the root current when it was minted, so a member
|
||||
who adopted the base rotation first must still ask under the prior root; the
|
||||
window is what lets a member who missed a rotation catch up, or learn they were
|
||||
cut. This is `community::rekey::watches`, installed as a second standing REQ
|
||||
whose id resolves back to its community through `rekey::WatchRegistry` (the id
|
||||
cannot carry a 64-hex community id within the NIP-01 length cap).
|
||||
- `community::rekey::adopt` then reads those wraps **from the database** and walks
|
||||
each scope forward one epoch at a time: a complete, authorized rotation whose
|
||||
`prevcommit` extends the key actually held hands over the next key (raced
|
||||
rotations settle on the lowest); a gap is fetched, never waived; a fork is never
|
||||
adopted. An addressed-but-unverifiable rotation is neither adopted nor read as a
|
||||
removal. Only a complete rotation at/after the join, from a rotator who outranks
|
||||
the member, with no blob for them, is a removal; one that predates the join is a
|
||||
strand — a stale invite landed the member on a superseded epoch.
|
||||
|
||||
### Tests
|
||||
|
||||
`cx.background_executor().timer(..)` for delays, never `smol::Timer`, or
|
||||
`run_until_parked()` finds nothing left to run. Push a wrap into the channel and
|
||||
`run_until_parked()` to drive the foreground consumer.
|
||||
|
||||
## Not wired up yet
|
||||
|
||||
- **`crates/concord` stays protocol-only; the registry lives in
|
||||
`crates/community`.** `concord` has no subscriptions, no `init`, and no
|
||||
`Entity<Community>`; `community::CommunityRegistry` owns one `Entity<Community>`
|
||||
per state document, subscribes when a community's plane set changes, and
|
||||
re-folds on an inbound wrap. The sidebar subscribes to the registry, surfaces
|
||||
`CommunityEvent::Error` as a window notification, and its "New community" row
|
||||
in the Communities tab dispatches `Command::NewCommunity`, whose name prompt
|
||||
calls `CommunityRegistry::create`. `create` persists the
|
||||
genesis locally, publishes the wraps to the community's relays, and records the
|
||||
membership in the account's Community List — all best-effort, so a relay that is
|
||||
down warns without losing the community. Discovery
|
||||
subscribes to the account's CORD-02 Community List (`33302`) under the
|
||||
`concord/list` subscription id and reads the fragments back out of
|
||||
`client.database()` — the SDK persists a relay's event before notifying, so the
|
||||
read is always current. A `concord/list` notification re-runs `load`, which
|
||||
materializes a community from each live List entry (`from_join_material`) and
|
||||
keeps any state document the List does not mention, so a fresh install — or one
|
||||
signing in as an account that joined elsewhere — finds its communities. See
|
||||
`docs/concord-community-discovery-plan.md` (including its note on the retired
|
||||
`13302` the current reference client still writes).
|
||||
- **Account-key writers take any signer, not `&Keys`.** `genesis`,
|
||||
`ControlWriter`, the guestbook and chat `seal_rumor`s, the `list` builders, and
|
||||
the `cord05` invite writers (`build_direct_invite` / `unwrap_direct_invite`,
|
||||
`build_invite_list` / `parse_invite_list`) and `cord06` blob writers
|
||||
(`build_blob` / `open_blob`) are `async` and generic over the SDK's
|
||||
`AsyncGetPublicKey` / `AsyncSignEvent` / `AsyncNip44` traits, so a `Keys` and an
|
||||
app `UniversalSigner` both work. The NIP-59 paths (`build_direct_invite`,
|
||||
`unwrap_direct_invite`) stay `Sized` because the SDK's gift-wrap helpers are.
|
||||
Group-key and locally-held-secret writers (`cord01` wrap functions,
|
||||
`cord05::build_bundle_event`, `community::cache`) still take the raw key material they
|
||||
genuinely need.
|
||||
- **`crates/chat/src/lib.rs::handle_notifications` treats every kind 1059 event as
|
||||
a NIP-59 gift wrap for the current user.** Concord wraps are kind 1059 too, so
|
||||
that handler must route by subscription id before any concord subscription goes
|
||||
live, or every stream wrap lands in the DM trash and raises a toast.
|
||||
- **Rotation-delivered plane keys are persisted, and history spans them.**
|
||||
`CommunityState.held_roots` keeps every root a rotation stepped off (with the
|
||||
retired root's Control signer and the publish time that retires it), and each
|
||||
`ChannelKeyRef.priors` keeps every channel key a rotation stepped off. The read
|
||||
side derives planes from all of them, and a retired key's `retired_at` is a hard
|
||||
read cutoff at both `history::page` and `sync::fold`. The state
|
||||
`Community::removed_at`/`Community::stranded`/`channel_removed_at` carries is
|
||||
rendered as a notice **and** enforced at write time: `Community::send` refuses
|
||||
when `channel_secret` is `None` (a removal, a strand, a channel cut, or a key we
|
||||
never held), because a wrap sealed under a superseded root would reach nobody who
|
||||
rotated. A rotation this client publishes itself (`Community::rotate`) is adopted
|
||||
through the same `rekey::adopt` an arriving one goes through, so the held state
|
||||
and the wire cannot diverge.
|
||||
@@ -0,0 +1,384 @@
|
||||
# NIP-29 migration plan
|
||||
|
||||
`crates/nip29` is complete and reviewed; `docs/nip29-usage.md` is its API contract. This
|
||||
plan replaces the Concord stack — `crates/concord`, `crates/community` and
|
||||
`crates/community_ui` — with it, and lays out the UI surfaces the backend was built for.
|
||||
|
||||
Every phase ends with the app building and running. The last phase deletes the old crates,
|
||||
so nothing is removed until the replacement is in place.
|
||||
|
||||
## What is being replaced
|
||||
|
||||
| Today | Replacement |
|
||||
| --- | --- |
|
||||
| `crates/concord` (`cord01`–`cord06`, `state`, `derive`) | deleted — the relay owns identity, membership, roles and history |
|
||||
| `crates/community` (`CommunityRegistry`, `Community`, `sync`, `cache`, `rekey`, `history`) | `crates/nip29` (`GroupsRegistry`, `Group`) — already built |
|
||||
| `crates/community_ui` (`CommunityPanel`) | new `crates/nip29_ui` (`GroupPanel`) |
|
||||
| Sidebar `Communities` tab + two-level community view (channels / admins / members) | one-level `Groups` tab; admins and members move into a details dialog |
|
||||
| `dialogs/new_community.rs` | `dialogs/new_group.rs` and a new `dialogs/join_group.rs` |
|
||||
| `panels/browse.rs` stub | a working browse panel over `GroupsRegistry::browse` |
|
||||
| `settings.recent_communities` (dead, nothing reads it) | removed |
|
||||
|
||||
## Capability disposition
|
||||
|
||||
| Concord capability | On NIP-29 |
|
||||
| --- | --- |
|
||||
| End-to-end encrypted channels | Dropped. NIP-29 groups are relay-readable; `private` only means members-only read. |
|
||||
| Channels inside a community | Dropped. A group is one timeline; subgroups are the only hierarchy. |
|
||||
| Roles and control plane | Relay owns them (`39001`, `39003`); the client reads and displays, never derives authority. |
|
||||
| Rekey, rotation, refounding, dissolution | Dropped with `cord06`; leaving and deleting are relay operations. |
|
||||
| Invites | `9009` `create-invite` + the `?invite=` suffix on a group `naddr`. |
|
||||
| Pins | `9010` → relay mirrors `39005`; the backend is ready. |
|
||||
| Message deletion | `9005`; the local eviction lands in Phase 0. |
|
||||
| Reactions | Kind `7` rows arrive as ordinary timeline rows; grouping them under the target is a later enhancement. |
|
||||
| Members list | `39002` when the relay publishes it; may be absent or partial by design. |
|
||||
| Community list | `10009`, owned entirely by the backend. |
|
||||
| Multi-relay communities | One relay per group; migration and forks surface through `Group::elsewhere()`. |
|
||||
| Attachments | Any kind the relay supports; v1 renders media URLs already parsed by `chat::Message`. |
|
||||
|
||||
## Rules the implementation keeps
|
||||
|
||||
Carried over from the backend review; they apply to every phase.
|
||||
|
||||
- New code goes into `crates/nip29` and `crates/nip29_ui`. Never create a `groups` crate.
|
||||
- Implementation-block style: methods on the type they belong to, `self` first.
|
||||
- Read model is subscribe → pump → envelope cache → hydrate. Never `fetch_events`.
|
||||
- Short-lived subscriptions close on EOSE (`SubscribeAutoCloseOptions`), long-lived ones use a
|
||||
prefix the pump recognises; dedup events by id before they mutate state.
|
||||
- I/O runs on `cx.background_spawn`, called from a foreground `cx.spawn` task; tasks are
|
||||
stored on the entity so they cancel with it.
|
||||
- No comments, no docs, no tests inside the crates. `docs/` is the only place for prose.
|
||||
- No premature optimization: scan the small vectors, don't build index maps.
|
||||
- No `unwrap`, no `let _ =` on fallible calls; propagate with `?` and surface errors to the UI
|
||||
(relay messages verbatim).
|
||||
- Views read entities; protocol state never lives in a view. A panel re-reads on the event.
|
||||
- UI follows the existing components (`ui::button`, `ui::input`, `ui::dock`, `ui::message`,
|
||||
`ui::markdown`, `theme` tokens). Copy is sentence case; a dialog names its object
|
||||
(`Leave "Pizza Lovers"?` with a `Leave` button).
|
||||
- `Monitor` stays unadopted; the fork watch already works without relay status.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — `9005` deletes reach local state
|
||||
|
||||
Today a `9005` stops the relay serving the event, but the envelope cache and the timeline keep
|
||||
it. Everything else about deletion is done (the write, the `OK false` path).
|
||||
|
||||
Files: `crates/nip29/src/protocol.rs`, `crates/nip29/src/group.rs`, `crates/nip29/src/lib.rs`.
|
||||
|
||||
1. `TimelineWindow::remove(&mut self, id: EventId)` — drop the reference so a `previous` tag
|
||||
never points at a deleted event.
|
||||
2. `Group::forget(&mut self, id: EventId, cx: &mut Context<Self>)` (crate-private) —
|
||||
`messages.retain`, `index.remove`, `window.remove`; when something was removed, emit
|
||||
`GroupEvent::Updated` and `cx.notify()`. `hydrate` stays additive, so a later reload cannot
|
||||
resurrect the row once its envelope is gone.
|
||||
3. The registry's ingestion of our accepted delete: in `ensure`'s `GroupEvent::Sent` arm, when
|
||||
`event.kind == Kind::Custom(9005)`, take the target from `event.tags.event_ids().next()`,
|
||||
delete its envelope (`Kind::ApplicationSpecificData` + `Tag::identifier(target)` +
|
||||
`r = key.cache_tag()`) on the background executor, wait for that to finish, then
|
||||
`group.forget(target)` and the usual `reload(key, Some(event))`. The deletion must complete
|
||||
before the reload reads the envelopes, or the reload would see the target still cached.
|
||||
|
||||
Remote deletes (another admin's `9005` arriving live) are out of scope; the standing REQ does
|
||||
not carry them, and a relay that no longer serves the event cannot be asked for it.
|
||||
|
||||
Validation: `cargo clippy -p nip29 --all-targets`, `cargo fmt -p nip29`,
|
||||
`cargo check -p coop -p coop_web`. Manually: as an admin, delete a message and confirm the row
|
||||
disappears and stays gone after a restart.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — `crates/nip29_ui`: the group panel
|
||||
|
||||
A new crate, modeled on `community_ui`, that renders one `Entity<Group>`.
|
||||
|
||||
Files: `crates/nip29_ui/Cargo.toml`, `crates/nip29_ui/src/lib.rs`,
|
||||
`crates/nip29_ui/src/message.rs`; one line in `crates/chat_ui/src/lib.rs`.
|
||||
|
||||
```toml
|
||||
# Cargo.toml
|
||||
[dependencies]
|
||||
nip29 = { path = "../nip29" }
|
||||
chat = { path = "../chat" }
|
||||
chat_ui = { path = "../chat_ui" }
|
||||
state = { path = "../state" }
|
||||
ui = { path = "../ui" }
|
||||
theme = { path = "../theme" }
|
||||
common = { path = "../common" }
|
||||
person = { path = "../person" }
|
||||
settings = { path = "../settings" }
|
||||
|
||||
gpui.workspace = true
|
||||
nostr-sdk.workspace = true
|
||||
anyhow.workspace = true
|
||||
smallvec.workspace = true
|
||||
```
|
||||
|
||||
Make `chat_ui`'s text helper shared by flipping `mod text;` to `pub mod text;`. It is the only
|
||||
change to an existing UI crate in this phase.
|
||||
|
||||
```rust
|
||||
pub fn init(group: Entity<Group>, window: &mut Window, cx: &mut App) -> Entity<GroupPanel>;
|
||||
|
||||
pub struct GroupPanel {
|
||||
id: SharedString, // "group-<cache_tag>"
|
||||
focus_handle: FocusHandle,
|
||||
group: WeakEntity<Group>,
|
||||
list_state: ListState,
|
||||
rendered_texts_by_id: BTreeMap<EventId, RenderedText>,
|
||||
input: Entity<TextareaState>,
|
||||
tasks: SmallVec<[Task<Result<()>>; 4]>,
|
||||
_subscriptions: SmallVec<[Subscription; 2]>,
|
||||
}
|
||||
```
|
||||
|
||||
The panel keeps **no copy of the timeline**. Rows are `group.read(cx).messages()`; the only
|
||||
local cache is parsed markdown keyed by event id. Deleting a message, a page arriving, or a
|
||||
live tail all reduce to "the entity changed, re-read it" — no merge, no index.
|
||||
|
||||
Rows: `0` welcome, `1` load-older, then the messages.
|
||||
|
||||
- Welcome — `WelcomeMessage` with the group avatar; `Welcome to {name}` and
|
||||
`This is the start of {name}.`
|
||||
- Load older — visible when `group.oldest().is_some()`, disabled while
|
||||
`group.loading_more()`, click → `GroupsRegistry::global(cx).update(|registry, cx| registry.load_more(&key, cx))`.
|
||||
- Message — `MessageRow` with avatar, author (`PersonRegistry`), `created_at.to_human_time()`,
|
||||
and `chat_ui::text::rendered_text(&message.content, &message.mentions, &persons, true, cx)`
|
||||
cached in `rendered_texts_by_id`. Show the author on a run start (same author, gap under a
|
||||
few minutes) like `community_ui` does. Render `message.media` as chat does: one image
|
||||
full-width, several in a wrapped row.
|
||||
|
||||
Events: subscribe to the group and drive everything from it.
|
||||
|
||||
| `GroupEvent` | Panel |
|
||||
| --- | --- |
|
||||
| `Incoming` / `Updated` | sync `list_state` (`reset(item_count)` when the count changed) and `cx.notify()` |
|
||||
| `Eose` | `cx.notify()` — `group.loading()` is now false |
|
||||
| `Refused(reason)` | show the notice |
|
||||
| `Sent` | ignore; the registry reloads through the same cache path |
|
||||
|
||||
Composer, gated exactly on the NIP's flags:
|
||||
|
||||
```rust
|
||||
let metadata = group.metadata();
|
||||
let supports_text = metadata.is_none_or(|m| m.supports(Kind::ChatMessage));
|
||||
let writable = metadata.is_none_or(|m| !m.restricted) || matches!(group.membership(), Membership::Member);
|
||||
let can_send = supports_text && writable;
|
||||
```
|
||||
|
||||
Send mirrors `community_ui::send`: read `input.value()`, clear the textarea, spawn
|
||||
`group.send_message(&text, vec![], cx)` and turn an `Err` into an
|
||||
`autohide(false)` notification — that string is the relay's refusal, verbatim. The panel does
|
||||
not reload anything; `GroupEvent::Sent` already routes the accepted event through the registry.
|
||||
|
||||
Notice above the composer (and centered when there are no messages):
|
||||
|
||||
| State | Notice | Action |
|
||||
| --- | --- | --- |
|
||||
| `group.refused()` | Relay message | none |
|
||||
| not a member (`Unknown` / `Removed` / `Refused { reason }`) | `Request to join`, preceded by the refusal reason when there is one | `registry.join_key(key, None, cx)` |
|
||||
| any of the above while `metadata.closed` | `This group is closed; an invite link is required.` | disabled |
|
||||
| `Membership::Pending { .. }` | `Waiting for the relay to approve.` | disabled |
|
||||
| `!supports_text` | `This group doesn't support text messages.` | disabled |
|
||||
|
||||
`Panel` impl: `panel_id` is `group-{cache_tag}` so a group opens once; `title` is the avatar
|
||||
plus the name; `toolbar_buttons` starts empty (Phase 4 fills it).
|
||||
|
||||
Validation: `cargo clippy -p nip29_ui --all-targets`, `cargo fmt -p nip29_ui`,
|
||||
`cargo check -p coop -p coop_web`. The crate is not reachable from the UI until Phase 2, so
|
||||
review is by code and compile.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — the sidebar and its dialogs
|
||||
|
||||
The `Communities` tab becomes one level: a list of groups, a `New Group` dialog and a
|
||||
`Join Group` dialog. The two-level community view (channels, admins, members, the back
|
||||
button) is removed; with no channels it has nothing to show, and details move to Phase 4's
|
||||
dialog.
|
||||
|
||||
Files: `crates/workspace/src/sidebar/mod.rs`, `crates/workspace/src/sidebar/tab.rs`,
|
||||
`crates/workspace/src/lib.rs`, `crates/workspace/src/dialogs/mod.rs`,
|
||||
`crates/workspace/src/dialogs/new_group.rs` (replaces `new_community.rs`),
|
||||
`crates/workspace/src/dialogs/join_group.rs`, `crates/workspace/Cargo.toml`.
|
||||
|
||||
Add `nip29` and `nip29_ui` to the workspace crate.
|
||||
|
||||
`tab.rs`: `Communities` → `Groups`, label and list title `Groups`, list id `sidebar-groups`.
|
||||
`lib.rs`: `Command::NewCommunity` → `Command::NewGroup`; add `Command::JoinGroup`; both arms
|
||||
open the dialogs below.
|
||||
|
||||
`mod.rs`:
|
||||
|
||||
- `SidebarRow::Community { community }` → `SidebarRow::Group { group: Entity<Group> }`.
|
||||
- Delete `CommunitySection`, `CommunityRow`, `community_scroll`, `channels_open`,
|
||||
`admins_open`, `members_open`, `Sidebar::community`, `reset_community`,
|
||||
`render_community`, `render_community_rows`, `section_row`, `channel_row`, `member_row`,
|
||||
and the back button in `render_user`. `render` loses its community branch.
|
||||
- `rows_for(Groups)` reads `GroupsRegistry::global(cx).read(cx).groups()` in registry order
|
||||
(the `10009` order, then joins).
|
||||
- The group row: name from `metadata.name()`, falling back to `key.id().as_str()`; avatar from
|
||||
`metadata.picture`, seeded with `key.cache_tag()`; suffix for the membership state —
|
||||
`Requested` (`Pending`), `Refused`, `Removed`, and `Moved` when `elsewhere().is_some()`;
|
||||
nothing for a plain member. Click opens
|
||||
`PanelHandle::new(nip29_ui::init(group.clone(), window, cx))` in `DockPlacement::Center`.
|
||||
- Subscriptions: replace the `CommunityRegistry` subscription with `GroupsRegistry` —
|
||||
`GroupsEvent::Updated` → `cx.notify()`, `GroupsEvent::Error(error)` → notification.
|
||||
- `render_tabs`'s Groups section: `New Group` (`Command::NewGroup`), `Join Group`
|
||||
(`Command::JoinGroup`), `Browse` (`Command::ShowBrowse`, still the Phase 3 stub).
|
||||
- Remove `dialogs/new_community.rs` and its `pub mod` line — nothing dispatches it any more.
|
||||
|
||||
The two dialogs, both modeled on `new_community.rs`:
|
||||
|
||||
**New group.** Three inputs — name, group id, relay — with ok/validation:
|
||||
|
||||
```rust
|
||||
let id = GroupId::new(if raw_id.is_empty() { slug(&name) } else { raw_id })?;
|
||||
let relay = RelayUrl::parse(relay_input)?;
|
||||
registry.create(GroupKey::new(relay, id), GroupMetadata { name: Some(name), ..Default::default() }, cx);
|
||||
```
|
||||
|
||||
A parse failure keeps the dialog open and pushes a notification. The relay's answer arrives
|
||||
asynchronously as `GroupsEvent::Error(reason)` — the sidebar already shows it. There is no
|
||||
default relay; the account has no "groups relay" setting yet, so the field starts empty.
|
||||
|
||||
**Join.** One naddr input:
|
||||
|
||||
```rust
|
||||
let reference = GroupReference::parse(input)?; // accepts naddr1…?invite=CODE
|
||||
GroupsRegistry::global(cx).update(cx, |registry, cx| registry.join(reference, cx));
|
||||
```
|
||||
|
||||
Validation: `cargo check -p workspace`, `cargo clippy -p workspace --all-targets`,
|
||||
`cargo fmt -p workspace`, then run the app: the tab lists whatever the account's `10009`
|
||||
holds, no Concord screen is reachable from it, and a pasted naddr joins and opens.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — browse panel
|
||||
|
||||
`panels/browse.rs` stops being a stub. `init` takes the dock (`WeakEntity<DockArea>`) the way
|
||||
`search::init` does, so a joined group can be opened directly.
|
||||
|
||||
- Header: relay `Input` + a `Go` button; Enter submits. `RelayUrl::parse` → `registry.browse(relay, cx)`.
|
||||
- Body: `registry.browsed(&relay)` — a spinner while `Browse::loading`, then rows of
|
||||
`GroupCandidate`: avatar, name (or id), `id@relay`, and `Join`
|
||||
(`registry.join_key(candidate.key, None, cx)`, then open the panel). Rows for keys already
|
||||
in `registry.groups()` show `Joined` instead.
|
||||
- Subscribes to `GroupsEvent::Updated` and re-renders. Empty state: `No groups found.`;
|
||||
before a relay is entered: `Enter a relay to browse its groups.`
|
||||
|
||||
Validation: `cargo check -p workspace`; manually browse a public NIP-29 relay and join from a
|
||||
result, and create a group on a relay that accepts `9007`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — details, delete, pins, leave
|
||||
|
||||
Read-mostly group management, the surfaces the sidebar gave up in Phase 2 plus the two writes
|
||||
that need Phase 0.
|
||||
|
||||
- **Group details** — a dialog opened from the panel's header row: name, picture, banner,
|
||||
about, flags (`private`, `restricted`, `hidden`, `closed`, `livekit`, `parent`, `children`),
|
||||
admins with their role labels (`Group::admins().entries()`), the roles the relay advertises
|
||||
(`Group::roles()`), members when the relay publishes `39002` (`Group::members()`), and pins
|
||||
(`Group::pins()`). Read-only in this phase.
|
||||
- **Delete a message** — admin-only entry in the message row's context menu (current user in
|
||||
`admins()`) → `group.delete_event(id, cx)`; Phase 0 makes the row disappear.
|
||||
- **Pin / unpin** — the same menu: `group.update_pins(pins, cx)` with the current list plus or
|
||||
minus `Pin::Event(id)`; show `Group::pins()` as a strip above the list.
|
||||
- **Leave** — header `Leave…` opens a confirmation naming the group (`Leave "Pizza Lovers"?`);
|
||||
on confirm `registry.leave(&key, cx)` and the panel closes (dispatch `ClosePanel`, as the
|
||||
screening dialog does).
|
||||
- **Fork / migration banner** — when `group.elsewhere()` is `Some(moved)`, a banner:
|
||||
`This group may have moved to {relay}.` with a `Join` button calling
|
||||
`registry.join_key(moved, None, cx)`. Never auto-join: the NIP asks the client to offer.
|
||||
|
||||
Validation: same commands; manually delete a message, pin and unpin, leave and re-join.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — admin writes
|
||||
|
||||
The remaining moderation surface, all through the calls the backend already exposes.
|
||||
|
||||
- **Edit metadata** — a dialog opened from the panel header's `Manage` menu, started from
|
||||
`group.metadata().cloned().unwrap_or_default()`: name, about, picture, the flags. `children`
|
||||
is preserved as-is — `edit_metadata` re-emits the full list, and a `9002` that drops one is
|
||||
rejected by the relay.
|
||||
- **Invite** — `create_invite(code, cx)` with an input or generated code, then
|
||||
`metadata.naddr(relay, Some(code))` copied to the clipboard (`naddr` needs parsed metadata;
|
||||
a group whose relay publishes no `39000` cannot mint a link).
|
||||
- **Users and roles** — add by `npub` → `put_user(pubkey, roles, cx)`, remove →
|
||||
`remove_user(pubkey, cx)`; role choices come from `Group::roles()`. The relay is the
|
||||
authority for both the roles it supports and who may call these.
|
||||
- **React** — a `React` submenu in the same row menu sends `send_reaction(target, emoji, cx)`;
|
||||
a kind `7` row appears inline (that is the current backend behaviour). Unlike the items above
|
||||
it is not admin-only, so the menu now exists for every member.
|
||||
|
||||
Validation: same commands; manually exercise each write against a relay that grants the
|
||||
account admin, and confirm the refusal path shows the relay's message.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — delete the Concord stack
|
||||
|
||||
Nothing in the app may reference Concord before this phase starts.
|
||||
|
||||
1. Delete `crates/community`, `crates/concord`, `crates/community_ui`.
|
||||
2. `crates/workspace/Cargo.toml`: drop `community` and `community_ui`.
|
||||
`desktop/Cargo.toml` and `web/Cargo.toml`: drop `community`; `nip29` stays.
|
||||
3. `desktop/src/main.rs` and `web/src/lib.rs`: drop `community::init(cx)` and its comment.
|
||||
4. `crates/settings/src/lib.rs`: drop `recent_communities` and `record_recent_community` —
|
||||
nothing reads them (verified), and the concept no longer exists.
|
||||
5. `docs/nip29-usage.md`: replace the "Not wired up yet" section. Remaining known gaps then
|
||||
are: LiveKit's response field names (a guess until checked against a real relay), the AV
|
||||
room itself, local handling of remote `9005`s, the subgroup tree, and reaction grouping.
|
||||
6. Confirm no `concord`/`community` string remains outside `docs/` history, and run a full
|
||||
`cargo check -p coop -p coop_web` plus `cargo clippy --workspace --all-targets`.
|
||||
|
||||
---
|
||||
|
||||
## Later (not part of the migration)
|
||||
|
||||
- **LiveKit** — `Group::livekit_supported` and `Group::livekit_session` are ready; check
|
||||
`metadata.livekit`, then build the AV room UI. Verify the token response fields first.
|
||||
- **Subgroups** — `parent`/`children` are parsed; assemble the tree in the sidebar when the
|
||||
relay advertises `nip29.subgroups`.
|
||||
- **Replies and threads** — `send_message` already takes reply ids and `chat::Message` reads
|
||||
them back; the panel needs a reply affordance and a quoted row.
|
||||
- **Remote deletions** — fold a `9005` seen live into `Group::forget`, the same eviction as
|
||||
Phase 0.
|
||||
- **Recent groups** — if a local recency list is wanted, store group keys, not the removed
|
||||
`recent_communities` strings.
|
||||
|
||||
## Validation checklist (every phase)
|
||||
|
||||
```sh
|
||||
cargo clippy -p <touched-crates> --all-targets
|
||||
cargo fmt -p <touched-crates> # check the exit code, not the output
|
||||
cargo check -p coop -p coop_web
|
||||
```
|
||||
|
||||
Plus the manual smoke for the phase, run in the app. The wasm target is not build-verified in
|
||||
this repo; `coop_web` check is the proxy.
|
||||
|
||||
## Decisions taken
|
||||
|
||||
- The tab is renamed `Groups`; the vocabulary is the NIP's.
|
||||
- The sidebar keeps one level; admins and members move to the details dialog.
|
||||
- The panel reads `Group` directly and keeps no timeline copy.
|
||||
- Mentions are rendered (shared `chat_ui::text::rendered_text`); replies and attachments are
|
||||
not offered for sending in v1.
|
||||
- `Join` never happens implicitly — not from `10009` alone, and not from `elsewhere()`.
|
||||
- The old crates are deleted only at the end, so any phase can be stopped and the app still
|
||||
runs.
|
||||
- The dock renders no per-panel toolbar — `Panel::toolbar_buttons` is defined but never called —
|
||||
so the group's `Details` and `Leave` actions live in a header row inside the panel.
|
||||
- The fork banner's button joins the target group rather than opening it: the panel holds no
|
||||
dock handle and the plan's call is `join_key` alone; the joined group then appears in the
|
||||
sidebar.
|
||||
- The admin writes sit behind a `Manage` menu in the panel header, shown only while the current
|
||||
user is in `Group::admins()`; the details dialog stays read-only. The message row menu is now
|
||||
built for every member — `React` is not moderation — and only its `Pin`/`Delete` items are
|
||||
gated on being an admin.
|
||||
@@ -0,0 +1,625 @@
|
||||
# Using the groups backend
|
||||
|
||||
`crates/nip29` is the backend for [NIP-29](https://github.com/nostr-protocol/nips/blob/master/29.md)
|
||||
relay-based groups. It is a GPUI crate: it owns one registry entity and one entity
|
||||
per group, subscribes to the relays, caches everything locally and hands the UI
|
||||
`chat::Message`s. It owns no strings a user reads — the UI layer decides every
|
||||
rendering. This document is the map from a UI action to the calls it makes.
|
||||
|
||||
A group is a `(relay, id)` pair. The relay enforces membership and signs the
|
||||
group's state; there is no cross-relay identity, no encryption, and no portable
|
||||
"create". The same `id` on two relays is two groups (a fork), which the backend
|
||||
models as two entities.
|
||||
|
||||
## Modules
|
||||
|
||||
| File | Owns |
|
||||
| --- | --- |
|
||||
| `src/protocol.rs` | Pure NIP-29 value types and their `impl` blocks: `GroupId`, `GroupKey`, `GroupReference`, `GroupMetadata`, `GroupAdmins`/`GroupMembers`/`GroupRoles`/`GroupParticipants`, `Pin`/`GroupPins`, `LivekitSession`, `GroupList`/`GroupListEntry`, `Membership`, `TimelineWindow`, plus the filter and event builders on `GroupId`. No I/O. |
|
||||
| `src/group.rs` | The `Group` entity: one group's state, timeline, membership, writes, the envelope cache helpers and the two LiveKit calls. `GroupEvent`. |
|
||||
| `src/lib.rs` | The `GroupsRegistry` global, `init`, the notification pump, the account's `10009` list, the fork watch and relay browsing. `GroupsEvent`. |
|
||||
|
||||
`protocol` is re-exported at the crate root (`pub use protocol::*`), so callers
|
||||
write `nip29::GroupKey`, `nip29::GroupMetadata`. `group` is re-exported the same
|
||||
way (`Group`, `GroupEvent`).
|
||||
|
||||
The crate's constants are the protocol's: `RENDER_KINDS` (`1`, `9`, `11`, `1111`,
|
||||
`7`), `STATE_KINDS` (`39000`–`39004` and `39005`), `MEMBERSHIP_KINDS` (`9000`,
|
||||
`9001`), `PIN_LIST` (`39005`), `UPDATE_PIN_LIST` (`9010`), `TIMELINE_WINDOW`
|
||||
(50) and the `previous`-tag shape (3 refs, 8 hex chars).
|
||||
|
||||
## Turning it on
|
||||
|
||||
One line, after the other registries and gated on nothing — the registry does its
|
||||
own sign-in check:
|
||||
|
||||
```rust
|
||||
nip29::init(cx);
|
||||
```
|
||||
|
||||
It builds the global entity, subscribes to `NostrRegistry`, and on the first
|
||||
sign-in (or a signer change) resets its state, restarts the pump and loads the
|
||||
account's `10009`. No groups exist before a sign-in, and everything is torn down
|
||||
when the signer changes, so the crate never leaks one account's groups into
|
||||
another.
|
||||
|
||||
`nip29::init(cx)` is already called in `desktop/src/main.rs` and `web/src/lib.rs`.
|
||||
|
||||
```rust
|
||||
use nip29::GroupsRegistry;
|
||||
|
||||
let groups = GroupsRegistry::global(cx); // Entity<GroupsRegistry>
|
||||
groups.read(cx).groups(); // &[Entity<Group>]
|
||||
groups.read(cx).group(&key, cx); // Option<Entity<Group>>
|
||||
```
|
||||
|
||||
`GroupsEvent` is emitted on the registry; read it back on the event. The sidebar
|
||||
subscribes to `GroupsEvent` and renders `groups()` — pending and refused groups
|
||||
are in that list alongside members, and their `Group::membership()` says which.
|
||||
|
||||
```rust
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum GroupsEvent {
|
||||
Updated,
|
||||
Error(String),
|
||||
Browsed(Box<GroupCandidate>),
|
||||
BrowseSettled(RelayUrl),
|
||||
}
|
||||
```
|
||||
|
||||
`Updated` fires on any change to `groups()`; `Error` is only emitted when
|
||||
publishing a `9007` (create) is refused, and carries the relay's message.
|
||||
`Browsed` and `BrowseSettled` carry a browse: one group the relay announced, and
|
||||
the end of the answer (see [Browsing a relay](#browsing-a-relay)). They are
|
||||
fan-out, not stored — whatever opened the browse owns the candidates.
|
||||
|
||||
## Value types
|
||||
|
||||
```rust
|
||||
use nip29::{GroupId, GroupKey, GroupReference, GroupMetadata};
|
||||
|
||||
let id = GroupId::new("pizza-lovers")?; // trimmed, non-empty
|
||||
let key = GroupKey::new(relay_url.clone(), id); // the (relay, id) pair
|
||||
```
|
||||
|
||||
A `GroupKey` is the identity of a group *as this backend sees it*: everything
|
||||
that addresses a group — `group`, `join_key`, `create`, `load_more`, `leave`,
|
||||
`browse` results — takes one. `Group::key()` returns the one an entity was built
|
||||
with, and `GroupReference::key()` returns the one a link resolves to.
|
||||
|
||||
A reference is a link, and only a link:
|
||||
|
||||
```rust
|
||||
let reference = GroupReference::parse("naddr1…?invite=CODE")?; // or .parse::<GroupReference>()
|
||||
```
|
||||
|
||||
`GroupReference::parse` (and `FromStr`) accepts only a kind-`39000` `naddr` with a
|
||||
relay hint. The `?invite=` suffix the NIP defines is split off before bech32
|
||||
decoding and lives on `reference.invite()`; a missing relay hint is an error,
|
||||
because there is nowhere to send the join request. `id@relay` is deliberately not
|
||||
accepted.
|
||||
|
||||
`GroupMetadata` is both the read model and the `9002`/`9007` payload, and it is
|
||||
`Default`:
|
||||
|
||||
```rust
|
||||
let metadata = GroupMetadata {
|
||||
name: Some("Pizza Lovers".into()),
|
||||
private: true,
|
||||
..Default::default()
|
||||
};
|
||||
```
|
||||
|
||||
`parse(event)` fills it from a relay-signed `39000` (and keeps the event's id and
|
||||
author privately, which is what `naddr` is built from). `name()`, `supports(kind)`
|
||||
and the public flag fields (`private`, `restricted`, `hidden`, `closed`,
|
||||
`livekit`, `parent`, `children`, `supported_kinds`) are what a group header reads.
|
||||
`supports` distinguishes "tag absent" (all kinds) from "tag present with no
|
||||
values" (no kinds) — that is the difference between a normal group and an AV-only
|
||||
one.
|
||||
|
||||
## The account's group list
|
||||
|
||||
`10009` ("simple groups") is the member's own list of memberships, synced across
|
||||
devices. The registry keeps it in `list: GroupList` and owns its whole lifecycle:
|
||||
it is loaded at sign-in, `upsert`ed on join/create, `remove`d on leave, and
|
||||
re-published to `to_nip65()` after every change. A caller never touches it.
|
||||
|
||||
```rust
|
||||
// `10009` tag shape: ["group", id, relay, name?] plus ["r", relay]
|
||||
```
|
||||
|
||||
Loading is a subscription plus a database read, the same read model as everything
|
||||
else: subscribe to our own `10009` under `nip29-list`, then read the newest from
|
||||
`client.database()` and merge it. A newer list arriving from another device is
|
||||
merged union-only — the backend never diffs, so a removal another client made is
|
||||
not detected, and the local state is never walked backwards. `GroupList::parse`
|
||||
requires `["group", id, relay]` and takes the third value as the display name.
|
||||
|
||||
## Joining
|
||||
|
||||
```rust
|
||||
GroupsRegistry::global(cx).update(cx, |registry, cx| {
|
||||
registry.join(reference, cx); // or join_key(key, invite, cx)
|
||||
});
|
||||
```
|
||||
|
||||
`join` is `join_key(reference.key(), reference.invite().to_owned())`, and
|
||||
`join_key` is what every other path calls too, because a browse result has a key
|
||||
and no `naddr`. The sequence is:
|
||||
|
||||
1. `ensure` the group: create the entity, register it in `groups()`, subscribe to
|
||||
its relay (the standing `grp-<hash>` REQ, below) and reload it from the local
|
||||
cache.
|
||||
2. Add the entry to `10009` optimistically and publish the list, so the group is
|
||||
listed the moment the user asks for it.
|
||||
3. Publish `key.id().join_request(invite, "")` — the `h` tag plus, when the link
|
||||
had one, a `code` tag. `Group::mark_pending(now)` runs immediately, so
|
||||
`Group::membership()` is `Pending { since }` while the relay decides.
|
||||
|
||||
The relay either emits `9000` (the standing subscription folds it into
|
||||
`Membership::Member`), or answers the `9021` with `OK false` — the registry
|
||||
catches that and sets `Membership::Refused { reason }` from the relay's message.
|
||||
The NIP promises that message explains whether the rejection is final, pending
|
||||
review or payment-required, so show it verbatim and offer a retry. A join to a
|
||||
`closed` group is refused the same way, unless the invite code is honoured.
|
||||
|
||||
Join needs no `39000` first: nothing is fetched, the `9021` is the whole request.
|
||||
A hidden group needs no special handling either — the state simply never arrives.
|
||||
|
||||
## Reading a group
|
||||
|
||||
`Group` is an entity with no protocol state in the view. A panel reads it and
|
||||
subscribes to `GroupEvent`:
|
||||
|
||||
```rust
|
||||
use nip29::{Group, GroupEvent};
|
||||
|
||||
let Some(group) = registry.read(cx).group(&key, cx) else {
|
||||
return;
|
||||
};
|
||||
let rows = group.read(cx).rows(); // &[nip29::Row]
|
||||
```
|
||||
|
||||
```rust
|
||||
cx.subscribe(&group, |this, group, event, cx| match event {
|
||||
GroupEvent::Incoming(..) | GroupEvent::Updated => cx.notify(),
|
||||
GroupEvent::Refused(reason) => this.show_error(reason, cx),
|
||||
GroupEvent::Eose => this.stop_spinner(cx),
|
||||
GroupEvent::Sent(_) => {}
|
||||
})
|
||||
```
|
||||
|
||||
`GroupEvent` is the full surface:
|
||||
|
||||
| Variant | Means |
|
||||
| --- | --- |
|
||||
| `Incoming(Event)` | a fresh renderable row was folded in (use it for system notifications when the window is inactive) |
|
||||
| `Sent(Event)` | our own event was accepted by the relay; the registry re-reads the group, the panel normally ignores it |
|
||||
| `Updated` | metadata, state, membership, pins or a finished page changed |
|
||||
| `Eose` | the standing subscription settled |
|
||||
| `Refused(String)` | the relay `CLOSED` the standing subscription, with its message |
|
||||
|
||||
The reads are all accessors: `key`, `metadata`, `members`, `admins`, `roles`,
|
||||
`participants`, `pins`, `membership`, `elsewhere`, `rows`, `loading`,
|
||||
`loading_more`, `oldest`, `refused`. `display_name` reads the group's name and
|
||||
falls back to its id; `display_image` is the picture, for a row or avatar.
|
||||
|
||||
`rows` is the whole timeline in `created_at` order, one entry per renderable
|
||||
event. `Row::Message(Box<chat::Message>)` is a chat row; `Row::Activity(Activity)`
|
||||
is a moderation row — who joined (`9021`), who left (`9022`), who was removed
|
||||
(`9001`) and who was given roles (`9000` with roles; a `9000` without roles is the
|
||||
relay echoing a join we already show and is not a row). `Activity::subject()` is
|
||||
the affected person (the `p` tag target, or the author when there is none) and
|
||||
`Activity::roles` the assigned roles, so the view only chooses wording and an
|
||||
icon. `Group::message(id)` looks a chat row up for a pin label.
|
||||
|
||||
### The read model
|
||||
|
||||
There is **no `fetch_events` anywhere** in the crate. A group is read by
|
||||
subscribing, then querying the local database — the same model as `crates/chat`
|
||||
and `crates/community`:
|
||||
|
||||
```
|
||||
subscribe grp-<hash> the global pump observes every REQ on the client
|
||||
│ (timeline + membership + one state filter per kind, one relay)
|
||||
▼
|
||||
save_envelope 30078, d = event id, r = "<relay>|<id>", k = kind
|
||||
│ content = the raw event JSON, signed by crate-local keys
|
||||
▼
|
||||
load_envelopes query by the r tag, parse, sort by created_at
|
||||
│
|
||||
▼
|
||||
Group::hydrate the only place entity state changes
|
||||
```
|
||||
|
||||
The standing REQ carries the timeline (`GroupId::timeline_filter(100)`), our own
|
||||
membership (`membership_filter(me)`) and `state_filters()` — **one filter per
|
||||
state kind**, because a relay that serves group metadata is allowed to refuse a
|
||||
filter that mixes metadata kinds with other kinds (`groups.hzrd149.com` answers
|
||||
`blocked: it's not allowed to mix metadata kinds with others` and drops the whole
|
||||
REQ, which is what hid a group's name and picture until the filters were split).
|
||||
Its id is `grp-` plus 8 hex of a hash of the
|
||||
key — NIP-01 caps ids at 64 characters, and the pump needs a prefix to recognise
|
||||
its own subscriptions, so the real key is held in the registry's `routes`, not
|
||||
encoded in the id.
|
||||
|
||||
The envelope cache is what makes the timeline fork-safe and restart-safe without
|
||||
teaching the nostr database about relays (a stored event carries no origin): the
|
||||
`r` tag *is* the relay scoping. It is also why every event is re-read instead of
|
||||
consumed off the wire — the pipeline dedups, sorts and survives a restart, and a
|
||||
page, a live tail and a local send all take the same path.
|
||||
|
||||
`hydrate` partitions an envelope run:
|
||||
|
||||
- `STATE_KINDS` → `metadata`, `admins`, `members`, `roles`, `participants`,
|
||||
`pins` (relay-signed, read-only, addressable by `d`).
|
||||
- `MEMBERSHIP_KINDS` → our membership only (see below).
|
||||
- `RENDER_KINDS` → a `Row::Message`, inserted in `created_at` order.
|
||||
- `ACTIVITY_KINDS` → a `Row::Activity`, inserted in `created_at` order. A `9001`
|
||||
that answers a `9022` from the same subject within five minutes is dropped, so a
|
||||
plain leave reads once.
|
||||
- everything else is kept only for the `previous` window.
|
||||
|
||||
Every `h`-tagged event feeds the window regardless of kind. The window is the
|
||||
NIP's timeline reference: the last 50 events seen on that relay, excluding our
|
||||
own, first 8 hex characters of their ids, up to 3 per send. The write path
|
||||
attaches it automatically via `Group::previous_tag(me)`, so callers never build
|
||||
`previous` themselves.
|
||||
|
||||
`Group::loading()` is true until EOSE; `Group::refused()` carries the relay's
|
||||
`CLOSED` message when it never settles. A relay may answer a restricted or
|
||||
private group with `restricted:` / `auth-required:` — the state stays, the group
|
||||
just reads empty, and that is not an error toast.
|
||||
|
||||
### Older messages
|
||||
|
||||
```rust
|
||||
GroupsRegistry::global(cx).update(cx, |registry, cx| {
|
||||
registry.load_more(&key, cx);
|
||||
});
|
||||
```
|
||||
|
||||
It is a no-op while a page is in flight (`Group::loading_more()`) or before
|
||||
anything is cached. Otherwise it sends a `pg-<hash>` REQ (`timeline_page(50,
|
||||
until)`) alongside the standing one — paging must not replace the live tail — and
|
||||
the pump caches each page event and reloads the group exactly like a live event.
|
||||
The cursor is `Group::oldest()`, the oldest `h`-tagged event ever hydrated; `until`
|
||||
is inclusive, so a page repeats its first event, which the dedup absorbs for free.
|
||||
EOSE, a page `CLOSED` or the 10s auto-close all clear the spinner.
|
||||
|
||||
One relay behaviour is worth a spinner that can be cancelled: a relay that accepts
|
||||
the REQ but never EOSEs leaves `loading_more` true, because the auto-close closes
|
||||
the subscription locally with no notification at all.
|
||||
|
||||
## Sending
|
||||
|
||||
Every write goes through one path — `Group::dispatch` builds the event with
|
||||
`key.id()` and the current `previous` tag, `Group::publish` adds and connects the
|
||||
relay, signs with the app signer and sends to that one relay:
|
||||
|
||||
```rust
|
||||
let sent = group.update(cx, |group, cx| group.send_message(&text, replies, cx));
|
||||
cx.spawn(async move |_, _| {
|
||||
if let Err(error) = sent.await {
|
||||
// the relay's OK-false message, verbatim: "invalid: ...", "restricted: ...", "duplicate: ..."
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
| Call | Wire |
|
||||
| --- | --- |
|
||||
| `send_message(content, replies: Vec<EventId>, cx)` | kind `9` + `h` + `e` per reply |
|
||||
| `send_reaction(target: EventId, emoji: String, cx)` | kind `7` + `h` + `e` |
|
||||
| `put_user(public_key, roles, cx)` | `9000` |
|
||||
| `remove_user(public_key, cx)` | `9001` |
|
||||
| `edit_metadata(&GroupMetadata, cx)` | `9002` |
|
||||
| `delete_event(EventId, cx)` | `9005` |
|
||||
| `create_invite(code, cx)` | `9009` |
|
||||
| `update_pins(Vec<Pin>, cx)` | `9010` |
|
||||
|
||||
Each returns `Task<Result<()>>` and each resolves only once the relay has
|
||||
answered: `OK true` emits `GroupEvent::Sent` and the registry reloads the event
|
||||
through the normal cache path, so the timeline shows a send without waiting for
|
||||
the live tail; `OK false` is an `Err` carrying the relay's message. There is no
|
||||
offline queue — NIP-29 relays reject late publication, so a send either goes now
|
||||
or fails visibly.
|
||||
|
||||
Kind 9 is the default message kind. When `metadata().supports(Kind::ChatMessage)`
|
||||
is false — an AV-only group, or one whose `supported_kinds` omits it — disable the
|
||||
composer instead of sending a kind the relay does not take.
|
||||
|
||||
`replies` are plain `EventId`s; they become `e` tags. There is no thread model in
|
||||
the backend beyond that: `chat::Message::replies_to` already reads them back.
|
||||
|
||||
## Membership
|
||||
|
||||
Membership is derived from the relay's own events, never guessed:
|
||||
|
||||
```rust
|
||||
pub enum Membership {
|
||||
Unknown,
|
||||
Pending { since: Timestamp },
|
||||
Member,
|
||||
Refused { reason: Option<String> },
|
||||
Removed,
|
||||
}
|
||||
```
|
||||
|
||||
`Membership::from_events(&[...], me)` takes the newest `9000`/`9001` whose `p`
|
||||
tags name us — on an exact timestamp tie it prefers `9001` — and `Unknown` when
|
||||
there is none, which the NIP says means "not a member". The `Group` keeps only
|
||||
the membership events that mention us, so `refresh_membership` costs nothing.
|
||||
|
||||
`Pending` and `Refused` are the two local states, because the relay does not fold
|
||||
them into an event: the join path sets them from the `9021` send result. A
|
||||
`Member` is never overwritten by `mark_pending` or `mark_refused`, so a stale
|
||||
refusal cannot demote a member.
|
||||
|
||||
Count a member who is `Unknown`, `Pending` or `Refused` as "not in the room" for
|
||||
writes, but keep the row visible: pending and refused groups stay in `groups()`
|
||||
with their state on the row.
|
||||
|
||||
## Moderation
|
||||
|
||||
The `9000`–`9010` writes are on `Group` and share `dispatch`, so they are the
|
||||
same shape as sending a message. The backend does not enforce authority — the
|
||||
relay owns roles and its own policy — it only surfaces the refusal. Gate the UI
|
||||
on the caller appearing in `Group::admins()` (each entry is a pubkey plus its role
|
||||
labels), read the relay's supported roles from `Group::roles()`, and let the relay
|
||||
reject anything it does not want.
|
||||
|
||||
`edit_metadata` takes a `GroupMetadata`, so a form can start from
|
||||
`Group::metadata().cloned().unwrap_or_default()`, mutate, and send. `children`
|
||||
must carry every child tag, because a `9002` that drops one is rejected by the
|
||||
relay; the builder re-emits them from the struct.
|
||||
|
||||
`delete_event` sends `9005`, and once the relay accepts it the registry drops the
|
||||
target's cached envelope, evicts the row and re-reads the group, so the timeline stops
|
||||
showing it. Remote deletions are not folded in: the standing REQ does not carry `9005`.
|
||||
|
||||
## Pins
|
||||
|
||||
```rust
|
||||
use nip29::Pin;
|
||||
|
||||
let pins: Vec<Pin> = vec![Pin::Event(event_id), Pin::Address(coordinate)];
|
||||
group.update(cx, |group, cx| group.update_pins(pins, cx));
|
||||
```
|
||||
|
||||
`9010` carries the whole list, so pinning, unpinning, reordering and clearing are
|
||||
all one call. The relay mirrors it into `39005`, which is in `STATE_KINDS` — so
|
||||
`Group::pins()` reflects the accepted list on the next reload.
|
||||
|
||||
## Subgroups
|
||||
|
||||
`GroupMetadata` carries `parent: Option<GroupId>` and `children: Vec<GroupId>`,
|
||||
and the metadata builder re-emits both, so a create or edit can declare the link.
|
||||
There is no tree helper: the tree is scoped to one relay, so assemble it from
|
||||
`Group::metadata()` across `groups()` where all the children have the same relay.
|
||||
Membership and admin roles do **not** cascade across the link — each group's
|
||||
`9000`/`9001` and `39001` are authoritative for its own scope — so never infer
|
||||
access from a parent.
|
||||
|
||||
## LiveKit
|
||||
|
||||
Two calls, both off the foreground thread and both `&App`:
|
||||
|
||||
```rust
|
||||
if group.read(cx).metadata().is_some_and(|m| m.livekit) {
|
||||
let available = group.read(cx).livekit_supported(cx).await?; // GET /.well-known/nip29/livekit
|
||||
let session = group.read(cx).livekit_session(cx).await?; // LivekitSession { token, server_url }
|
||||
}
|
||||
```
|
||||
|
||||
`livekit_supported` is an unauthenticated GET that answers `true` only for `204`.
|
||||
`livekit_session` signs a NIP-98 `Authorization` header (`27235`, with the `u` and
|
||||
`method` tags the SDK's verifier demands) and returns the JWT and server URL; the
|
||||
token is a per-join artifact, returned not stored. Both requests carry an explicit
|
||||
`RedirectPolicy::NoFollow` and a 10s timeout, because the header is signed for
|
||||
exactly one URL and GPUI applies no timeout unless asked. The backend stops at the
|
||||
JWT — no LiveKit client library is involved — so the AV room itself is UI work.
|
||||
|
||||
Check `metadata().livekit` before offering the button, and read
|
||||
`Group::participants()` (kind `39004`, `participant` tags, relay-published) for
|
||||
who is live. Absent and empty are the same value there: nobody is in the room.
|
||||
|
||||
## Forks and migration
|
||||
|
||||
A `10009` on the *admins'* relays says where each of them thinks the group is. The
|
||||
registry keeps one standing `nip29-forks` subscription over
|
||||
`{authors: every admin of every group, kinds: [10009]}` on `ReqTarget::auto` —
|
||||
which is why it still works when the group's own relay is down — folds each event
|
||||
into a per-author list, and recomputes every group's `elsewhere`.
|
||||
|
||||
```rust
|
||||
if let Some(moved) = group.read(cx).elsewhere() {
|
||||
// the group may have moved or been forked; offer:
|
||||
registry.update(cx, |registry, cx| registry.join_key(moved.clone(), None, cx));
|
||||
}
|
||||
```
|
||||
|
||||
`elsewhere()` is `Some(key)` when an admin of the group lists the same group id at
|
||||
a different relay. The data cannot distinguish a move from a fork, hence the
|
||||
neutral name; nothing is auto-joined, because the NIP asks the client to *offer*.
|
||||
Evaluation is incremental on each event rather than batched on EOSE, since
|
||||
`ReqTarget::auto` fans out and an early EOSE would evaluate against one relay's
|
||||
partial view. A 15-minute background tick re-subscribes regardless, which is the
|
||||
recovery path for a subscription that died or a client that was offline.
|
||||
|
||||
`Monitor` is not adopted: it is only reachable through `ClientBuilder::monitor`,
|
||||
so nothing can read per-relay status without changing `crates/state`. The fork
|
||||
check does not need it — the admin pubkeys come from the cached `39001`, so the
|
||||
check runs with the relay gone, just at the next tick.
|
||||
|
||||
## Browsing a relay
|
||||
|
||||
```rust
|
||||
registry.update(cx, |registry, cx| registry.browse(relay_url.clone(), cx));
|
||||
|
||||
// then, in a GroupsEvent handler:
|
||||
match event {
|
||||
GroupsEvent::Browsed(candidate) => push(candidate),
|
||||
GroupsEvent::BrowseSettled(relay) => settled(relay),
|
||||
_ => {}
|
||||
}
|
||||
```
|
||||
|
||||
A `GroupCandidate` is a `GroupKey` plus its parsed `GroupMetadata`; `display_name`
|
||||
falls back to the id and `display_image` is the picture, the same pair `Group`
|
||||
offers. `browse` connects the relay, sends one auto-closing `39000` REQ (limit
|
||||
500, EOSE or 10s) and returns immediately; the pump parses each relay-signed
|
||||
metadata event and re-emits it as `Browsed`.
|
||||
|
||||
**The registry stores no browse result.** It keeps only which relay each `brw-`
|
||||
REQ belongs to — the same routing bookkeeping as `routes`, and the reason
|
||||
`Browsed` can carry a boxed candidate instead of the registry holding a `Vec`:
|
||||
the only copy is the caller's. A browse is transient by nature, so the surface
|
||||
that asked for it owns it (the browse panel keeps `relay`, `candidates` and
|
||||
`loading` in its own state, and drops them with the panel).
|
||||
|
||||
`BrowseSettled` is driven by the subscribe task itself, not by `EOSE`/`CLOSED`
|
||||
notifications: it is sent once `subscribe(..).await` returns, which happens on
|
||||
EOSE, on a refusal, or when the auto-close timeout fires. So the answer always
|
||||
ends, even against a relay that never EOSEs. A candidate can still arrive after
|
||||
the settle — the pump and the subscribe task are different producers — which is
|
||||
why the relay stays mapped. Join a result with `join_key(candidate.key, None, cx)`.
|
||||
|
||||
## Creating a group
|
||||
|
||||
```rust
|
||||
let metadata = GroupMetadata { name: Some(name), ..Default::default() };
|
||||
registry.update(cx, |registry, cx| registry.create(key, metadata, cx));
|
||||
```
|
||||
|
||||
Creation mirrors join: `ensure` the entity, add it to `10009` and publish optimistically,
|
||||
then send the `9007`. There is no NIP-11 check to lean on, so "where the relay
|
||||
supports it" is enforced by the relay refusing the event — on refusal the registry
|
||||
forgets the group and emits `GroupsEvent::Error(reason)`. On success the relay
|
||||
republishes `39000`, which the standing subscription picks up like any other state.
|
||||
|
||||
## Leaving
|
||||
|
||||
```rust
|
||||
registry.update(cx, |registry, cx| registry.leave(&key, cx));
|
||||
```
|
||||
|
||||
`leave` sends `9022`; once the relay accepts, the registry forgets the group:
|
||||
unsubscribe both REQs, drop the entity and its observer, remove the `10009` entry,
|
||||
delete every cached envelope for that group's `r` tag, and publish the shortened
|
||||
list. A failed leave leaves everything untouched, so the group stays. There is no
|
||||
separate local removal — a group someone else removed us from stays listed until
|
||||
we leave it ourselves.
|
||||
|
||||
## GPUI integration
|
||||
|
||||
`init` builds the global; the registry and its groups are the only entities, and
|
||||
`protocol.rs` has no GPUI dependency at all.
|
||||
|
||||
```rust
|
||||
pub fn init(cx: &mut App) {
|
||||
GroupsRegistry::set_global(cx.new(GroupsRegistry::new), cx);
|
||||
}
|
||||
|
||||
impl GroupsRegistry {
|
||||
pub fn global(cx: &App) -> Entity<Self> {
|
||||
cx.global::<GlobalGroupsRegistry>().0.clone()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `GroupsRegistry` holds `groups: Vec<Entity<Group>>`, the `10009` `list`,
|
||||
`routes` (subscription id → `GroupKey`), the relay behind each live `brw-` REQ,
|
||||
one `Subscription` per group, the fork state, and its tasks. It holds no browse
|
||||
result: a browse is fan-out, and the caller keeps the candidates.
|
||||
- `Group` owns everything the panel draws: metadata, admins/members/roles,
|
||||
participants, pins, membership, the `Vec<Row>` timeline, the `previous`
|
||||
window, `loading`/`loading_more`/`refused`.
|
||||
- Views render `Entity<Group>` and re-read on `GroupEvent`; no protocol state
|
||||
lives in a view.
|
||||
- The registry re-broadcasts every `GroupEvent::Updated` as `GroupsEvent::Updated`
|
||||
and notifies itself, so a view that watches only the registry (the sidebar,
|
||||
which renders `groups()` as rows) stays in sync when a group's metadata,
|
||||
membership, pins or fork state change. `GroupEvent::Updated` fires for state and
|
||||
membership only, never for an arriving row — that is `GroupEvent::Incoming`,
|
||||
and it is why a rebuild of the row list does not happen per row. A view that
|
||||
renders the timeline watches the `Group` itself.
|
||||
|
||||
### Foreground and background
|
||||
|
||||
One background task drains `client.notifications()` and never touches an entity;
|
||||
it sends signals through an unbounded `flume` channel that one foreground
|
||||
`cx.spawn` consumes, which is the only place entities change:
|
||||
|
||||
```
|
||||
notifications() ──sig──► flume ──recv──► this.update(cx, …) ──► handle_event → reload → hydrate
|
||||
```
|
||||
|
||||
- `handle_notifications` runs on `cx.background_spawn`; it matches
|
||||
`ClientNotification::Message` and routes the message by subscription id.
|
||||
- The consumer runs on `cx.spawn`; every arm is one `this.update(cx, ..)`.
|
||||
- The listener and the consumer are replaced (`= None` first) on a signer change,
|
||||
because a dropped `Task` cancels; that is what makes the reset clean.
|
||||
- Both `save_envelope` and `load_envelopes` are `cx.background_spawn` work that
|
||||
clones the `Client` in, so no database call ever runs on the foreground thread.
|
||||
- NIP-46 signing is async, so all signing happens inside the background task.
|
||||
|
||||
### Subscriptions and routing
|
||||
|
||||
One `Client` and one notification stream are shared with `chat`, so every
|
||||
subscription the crate owns is identified by a prefix and nothing else:
|
||||
|
||||
| Id | Meaning |
|
||||
| --- | --- |
|
||||
| `nip29-list` | the account's `10009` |
|
||||
| `nip29-forks` | the admins' `10009` |
|
||||
| `grp-<hash>` | a group's standing REQ (timeline + membership + state filters) |
|
||||
| `pg-<hash>` | a "load more" page |
|
||||
| `brw-<hash>` | a relay browse |
|
||||
|
||||
Inbound events are routed by `subscription_id` from `RelayMessage::Event`, never
|
||||
by kind. That matters because `crates/chat` treats every kind-1059 event as a
|
||||
NIP-59 gift wrap — anything a new subscription adds must be recognisable by id, and
|
||||
the pump drops ids it did not mint. Duplicate event ids are filtered in the pump
|
||||
before they reach the consumer, so a replay cannot double-hydrate.
|
||||
|
||||
## Not wired up yet
|
||||
|
||||
- **Administration is built on the client side.** The sidebar's `Groups` tab lists
|
||||
`GroupsRegistry::groups()`, opens a `GroupPanel`, and offers the new-group and
|
||||
join dialogs; `crates/workspace/src/panels/browse.rs` browses a relay and joins
|
||||
from a result. The panel has a read-only details dialog, a message menu with
|
||||
reactions and admin pin/delete, a pins strip, a fork banner, and leave. Opening a
|
||||
group also fills the sidebar with the group itself — banner (the `39000` `banner`
|
||||
tag, falling back to its `picture`), avatar and name, a row of info / edit / invite /
|
||||
leave buttons, and the collapsible `Admins`/`Members` lists. Clicking a member opens
|
||||
a dropdown menu (view profile, copy npub, and — for admins — remove from group).
|
||||
There is no members-and-roles dialog: adding a member is done through the invite
|
||||
flow, and roles are read-only. The panel has no header: the group's `about` lives
|
||||
in the details dialog, and the composer's leading button shows or hides the
|
||||
sidebar's group information. What a given account may actually do is the relay's
|
||||
call; the client shows the refusal verbatim.
|
||||
- **The composer uploads to the configured blossom server.** `GroupPanel`'s
|
||||
paperclip uploads one file at a time, unencrypted, and appends its URL to the
|
||||
message on send — the same plain-attachment path the chat composer uses when a
|
||||
message is already being typed. The server comes from
|
||||
`AppSettings::get_file_server`; the upload itself is `state::upload`.
|
||||
- **Remote deletions are not folded in.** A `9005` from another admin never reaches the
|
||||
standing REQ, so only our own accepted deletes evict the row.
|
||||
- **The LiveKit response shape is a guess.** The NIP names no fields, so
|
||||
`LivekitSession::parse` reads `token` (or `jwt`) and `url` (or `server_url`) and
|
||||
fails loudly on anything else. Re-check it against the relay actually targeted
|
||||
before building the AV UI, or the join button fails silently.
|
||||
- **A relay that never EOSEs bounds how long "load more" spins.**
|
||||
`Group::loading_more` relies on EOSE or CLOSED, and the auto-close timeout
|
||||
closes the subscription with no notification at all; bind "load more" to
|
||||
`Group::loading_more()` and give the user a way out. A browse is fine by
|
||||
contrast: `BrowseSettled` comes from the subscribe task returning, so it
|
||||
always lands.
|
||||
- **Subgroups are parsed, not assembled.** `parent`/`children` are on
|
||||
`GroupMetadata` and the writes carry them; there is no tree builder, because
|
||||
the tree is scoped to a relay and that is a view concern.
|
||||
- **`GroupMetadata::naddr` needs a parsed metadata.** It builds from the `id` and
|
||||
author the `39000` left on the struct, so a hand-built `Default` value errors
|
||||
rather than minting a link that points nowhere. A group whose relay publishes
|
||||
no `39000` cannot be referenced or joined at all.
|
||||
Reference in New Issue
Block a user