Skip to content

Commit b789548

Browse files
author
Ian Oberst
committed
Merge remote-tracking branch 'upstream/main' into Areson/pgschema-ignore-runtime-partitions
* upstream/main: feat(relay): add announce channels with a join_role setting (#8143) fix(mobile): keep token labels visible in authored Markdown links (#7545) test(relay): cover system channels in the workflows API and push matcher (#8509) fix(relay): push system channel events to a lease that names them (#8517) fix(relay): scope push matches with the read path's channel rule (#8507) feat(ws-client): send custom headers on the WebSocket upgrade (#8159) feat(mobile): show inline human typing and outgoing avatars (#8505) BUZZ-357: feat(cli): token-lean agent output format for event reads (#8234) fix(desktop): surface a missing DATABRICKS_HOST instead of loading models forever (#8504) feat(audio-client): accept a client request in connect (#8497) fix(mobile): lazily lay out new-DM recipients (#8435) fix(mobile): lazily lay out channel member groups (#8437) perf(mobile): retain preference crypto across reconnects (#8442) fix(deps): bump webpki crates for RUSTSEC-2026-0381/0382/0383 (#8499) fix(mobile): simplify and refine the quick actions menu (#8491) fix(sdk): reject malformed mention pubkeys before signing p tags (#6372) fix(mobile): resolve DM display labels once per sort (#8488) docs(db): database target architecture and schema-change rules (#8273) fix(mobile): restore channel icons and align chat colors with desktop (#8478) Signed-off-by: Ian Oberst <[email protected]> # Conflicts: # AGENTS.md
2 parents f6aecb1 + d97f6b4 commit b789548

117 files changed

Lines changed: 8246 additions & 1617 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/_ci-relay.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -627,6 +627,10 @@ jobs:
627627
cargo test -p buzz-test-client --test e2e_relay invite -- --ignored --nocapture
628628
cargo test -p buzz-test-client --test e2e_relay nip43_membership_snapshots_are_rejected -- --ignored --nocapture
629629
cargo test -p buzz-test-client --test e2e_relay nip29_departure_wire -- --ignored --nocapture
630+
cargo test -p buzz-test-client --test e2e_relay nip29_announce_channel_wire -- --ignored --nocapture
631+
cargo test -p buzz-test-client --test e2e_relay nip29_member_raises_guest_agent -- --ignored --nocapture
632+
cargo test -p buzz-test-client --test e2e_relay nip29_guest_is_read_only_in_normal_channel -- --ignored --nocapture
633+
cargo test -p buzz-test-client --test e2e_relay nip29_relay_rejects_role_change_by_unprivileged_actor -- --ignored --nocapture
630634
env:
631635
RELAY_URL: ws://localhost:3000
632636
GIT_CREDENTIAL_NOSTR_BIN: ${{ github.workspace }}/target/ci/git-credential-nostr

‎AGENTS.md‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,12 @@ Before planning or reviewing a non-trivial change:
1414
2. Read the `VISION_*.md` documents relevant to the affected product surface.
1515
3. Read the applicable guidance in [TESTING.md](TESTING.md) and any
1616
package-local `TESTING.md`.
17-
4. Check that the proposed design advances, or at least does not contradict,
17+
4. For any change to `migrations/`, `schema/`, or schema-dependent `buzz-db`
18+
queries, read [docs/database.md](docs/database.md): no new triggers,
19+
functions, or foreign keys; no data backfills in migrations; update every
20+
schema location; and keep every migration compatible with the relay that
21+
is currently deployed.
22+
5. Check that the proposed design advances, or at least does not contradict,
1823
that product intent. Call out any intentional tension explicitly.
1924

2025
Implementation describes the product today; the vision documents describe the
@@ -128,7 +133,8 @@ crates/
128133
desktop/ # Tauri 2 + React 19 desktop app
129134
web/ # Browser web client (repo browser, served by the relay)
130135
mobile/ # Flutter mobile app
131-
migrations/ # SQL migrations (auto-applied on relay startup)
136+
migrations/ # SQL migrations (run at relay startup when BUZZ_AUTO_MIGRATE is on: binary default off, Helm default on; deployments at scale apply them out of band — see docs/database.md)
137+
schema/ # Desired-state schema (schema/tables/public/ is the declarative schema source)
132138
scripts/ # Dev tooling
133139
.env.example # Config template — copy to .env before running
134140
```
@@ -365,8 +371,13 @@ canonical signed Nostr event fields (`id`, `pubkey`, `kind`, `content`,
365371
`{event_id, accepted, message}`; creates add the entity ID. Exit codes:
366372
0=ok, 1=input error, 2=network/relay, 3=auth, 4=other, 5=write conflict (NIP-33 LWW).
367373

368-
`--format compact` is a **global** flag — it goes before the subcommand:
374+
`--format` is a **global** flag — it goes before the subcommand:
369375
`buzz --format compact channels list`, NOT `buzz channels list --format compact`.
376+
Without the flag it falls back to `BUZZ_OUTPUT_FORMAT` (unknown values mean
377+
`json`); buzz-acp sets that to `agent` for agent
378+
processes, so their event reads drop `sig`, trim the NIP-OA `auth` tag to
379+
`["auth", <owner>]`, and fold the NIP-10 `root`/`reply` tags into `reply_to`
380+
(plus `thread_root` on nested replies); other tags remain.
370381

371382
See `crates/buzz-cli/TESTING.md` for the full live-testing runbook.
372383

@@ -602,7 +613,7 @@ description. See [PR #803](https://github.com/block/buzz/pull/803).
602613
4. **Worktrees: `cd` in the same command** — shell CWD doesn't persist between tool calls. Use `cd /path && cargo build` as one command.
603614
5. **Desktop crate excluded from root workspace** — `cargo test` at repo root does NOT run desktop tests. Use `cargo test --manifest-path desktop/src-tauri/Cargo.toml` explicitly.
604615
6. **React render perf: `React.memo` is all-or-nothing** — it only skips a re-render when *every* prop is reference-stable; one unstable prop (inline arrow/JSX, or a hook returning a fresh `{}`/`[]`/`Map` each render) defeats it. Two repeat offenders: (a) React Query results (`useMutation`/`useQuery`) are a **new object each render** — depend on the stable method (`mutation.mutateAsync`), not the object; (b) derived `Map`/array state that recomputes on a version bump — wrap in a content-equality ref cache (`shared/hooks/useStableReference.ts`). When chasing interaction lag, **measure with DevTools closed and no perf probes** (an open Web Inspector + per-keystroke `console.log` inflate the numbers), and isolate by removing one suspect at a time rather than guessing.
605-
7. **`pgschema` omits seed DML and some storage parameters** — `schema/schema.sql` is an ordered `\i` manifest: `schema/tables/public/<table>.sql` holds only that table's `CREATE TABLE` and `CREATE INDEX` statements (one table per file, the shape SchemaBot reads), and types, functions, partitions, triggers, and seed rows live in the sibling `schema/` directories. Fresh desired-state bootstraps use `./bin/pgschema apply`, which does not execute `INSERT` statements or preserve every table storage parameter from `schema/schema.sql`. Put each unsupported invariant in `scripts/reconcile-schema-after-pgschema.sql` as an idempotent convergence statement plus a live catalog or data assertion. Every `pgschema apply` caller must run that script, and must run pgschema from the repository root so it reads `.pgschemaignore`; from any other directory a re-apply plans to drop the partitions the relay created at runtime. A string assertion against `schema.sql` alone does not prove the pgschema-created database has the intended state.
616+
7. **`pgschema` omits seed DML and some storage parameters** — `schema/schema.sql` is an ordered `\i` manifest: `schema/tables/public/<table>.sql` holds only that table's `CREATE TABLE` and `CREATE INDEX` statements (one table per file, the shape out-of-band schema tools read), and types, functions, partitions, triggers, and seed rows live in the sibling `schema/` directories. Fresh desired-state bootstraps use `./bin/pgschema apply`, which does not execute `INSERT` statements or preserve every table storage parameter from `schema/schema.sql`. Put each unsupported invariant in `scripts/reconcile-schema-after-pgschema.sql` as an idempotent convergence statement plus a live catalog or data assertion. Every `pgschema apply` caller must run that script, and must run pgschema from the repository root so it reads `.pgschemaignore`; from any other directory a re-apply plans to drop the partitions the relay created at runtime. A string assertion against `schema.sql` alone does not prove the pgschema-created database has the intended state.
606617

607618
---
608619

‎ARCHITECTURE.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -525,6 +525,11 @@ shape is an explicit transition, not a flag day:
525525
behavior, pgschema bootstraps run reconciliation, and lock/pool metrics remain
526526
the operational evidence path for rollout safety.
527527

528+
The database end state (a declarative schema source, applied out of band at
529+
scale; no triggers, functions, or foreign keys; backfills outside migrations)
530+
and the expand → deploy → backfill → contract rules every schema change follows
531+
are in [docs/database.md](docs/database.md).
532+
528533
**Does NOT:** cache queries, implement connection pooling logic (delegated to sqlx), or make network calls outside Postgres.
529534

530535
---

‎Cargo.lock‎

Lines changed: 13 additions & 13 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎NOSTR.md‎

Lines changed: 65 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -51,13 +51,13 @@ PGPASSWORD=buzz_dev psql -h localhost -U buzz -d buzz -c \
5151
| **Deletions (kind:5)** | ✅ | Standard NIP-09; self-authored only. `#h` optional, `#e` required |
5252
| **User profiles (kind:0)** | ✅ | NIP-01 metadata; synced to users table (display_name, avatar, about, NIP-05). NIP-05 handles must canonicalize to this relay's domain — off-domain or invalid handles are silently cleared. If a NIP-05 handle collides with another user's (UNIQUE constraint), the handle is skipped but other profile fields (display_name, avatar, about) are still synced. |
5353
| **Group creation (kind:9007)** | ✅ | NIP-29; include `name` tag, optional `visibility`, `channel_type` and label `t` tags |
54-
| **Add user (kind:9000)** | ✅ | Open: any user, subject to target's `channel_add_policy` (`owner_only`/`nobody` can block). Private: owner/admin only. Self-add bypasses agent policy but not private-channel auth. |
54+
| **Add user (kind:9000)** | ✅ | Open: any user, subject to target's `channel_add_policy` (`owner_only`/`nobody` can block). Private: owner/admin only. Self-add bypasses agent policy but not private-channel auth. A guest cannot add anyone. A new member with no role tag gets the channel's `join_role`; a non-member adding themselves may ask for `join_role` or a lower role. |
5555
| **Remove user (kind:9001)** | ✅ | Self-remove allowed (with last-owner guard). Removing others: owner/admin only. |
56-
| **Edit group metadata (kind:9002)** | ✅ | `name`/`about`/label `t` tags: owner/admin. `topic`/`purpose` tags: any member. |
56+
| **Edit group metadata (kind:9002)** | ✅ | `name`/`about`/label `t`/`visibility`/`ttl`/`archived`/`join_role` tags: owner/admin. `topic`/`purpose` tags: any member except a guest. Buzz applies 9002 as a partial update: an absent tag leaves that setting unchanged. |
5757
| **Admin delete event (kind:9005)** | ✅ | Event author can always delete own. Otherwise owner/admin required. Target must be in same channel. |
5858
| **Group deletion (kind:9008)** | ✅ | Owner only. |
5959
| **Leave group (kind:9022)** | ✅ | Any member. Last-owner guard prevents orphaned groups. |
60-
| **Group metadata (kind:39000)** | ✅ | Relay-signed; always `d`, `name`, `closed`, `["t", <channel_type>]`, `["P", <creator>]` and `["created_at", <unix seconds>]` tags; `about` only if description non-empty; `private` if applicable; `hidden` for DM channels and private system channels |
60+
| **Group metadata (kind:39000)** | ✅ | Relay-signed; always `d`, `name`, `t`, `P`, `created_at`, `join_role`; `public` or `private`; `restricted` and `closed` per the access flags below; `about` only if description non-empty; `hidden` for DM channels and private system channels |
6161
| **Group admins (kind:39001)** | ✅ | Relay-signed; `d`, channel type `t` and creator `P` tags + `p` tags with roles (`owner`, `admin`) |
6262
| **Group members (kind:39002)** | ✅ | Relay-signed; `d`, channel type `t` and creator `P` tags + `p` tags for all members |
6363
| **Membership notifications** | ✅ | kind:44100 (added) / kind:44101 (removed); relay-signed, community-global scope (`channel_id=None` inside the connected community) |
@@ -71,7 +71,7 @@ PGPASSWORD=buzz_dev psql -h localhost -U buzz -d buzz -c \
7171
| **NIP-10 threads** | ✅ | WS-submitted replies with `["e","<root>","","reply"]` tags create `thread_metadata` atomically. Visible in REST thread queries. Unknown parents rejected. |
7272
| **NIP-17 DMs (gift wrap)** | ✅ | kind:1059 accepted with ephemeral signing keys. Stored community-globally (`channel_id=None` inside the connected community). Delivered via `#p`-filtered subscriptions. Not indexed in search. |
7373
| **DM discovery** | ✅ | DM creation emits kind:39000 (with `hidden` tag) + kind:44100 membership notifications. NIP-29 clients discover DMs via standard group discovery flow. |
74-
| **Join request (kind:9021)** | ✅ | Open channels only. Adds member, emits system message + group discovery events + kind:44100 membership notification. Private channels rejected at ingest. |
74+
| **Join request (kind:9021)** | ✅ | Open channels only. Adds the joiner with the channel's `join_role` (`member` by default), emits system message + group discovery events + kind:44100 membership notification. Private channels rejected at ingest. |
7575
| **Edits (kind:40003)** | ⚠️ | Works on the wire but Buzz-only — no standard NIP-29 client renders these |
7676
| **Rich content (kind:40002)** | ⚠️ | Works on the wire but Buzz-only — no standard NIP-29 client renders these |
7777

@@ -100,6 +100,61 @@ relay to specific external Nostr identities without granting full access.
100100
SELECT encode(pubkey, 'hex'), added_at, note FROM pubkey_allowlist;
101101
```
102102

103+
### Announce channels
104+
105+
Roles have the same permissions in every channel. A channel's settings
106+
decide only who can join and which role a new person gets:
107+
108+
- `visibility` (`open` | `private`) decides who can find, join and read.
109+
- `join_role` (`member` | `guest`) is the role a person gets when nobody
110+
picks one: a self-join (kind:9021, or a kind:9000 self-add), or a kind:9000
111+
add with no `role` tag. The default, `member`, keeps today's behavior.
112+
113+
An open channel with `join_role = guest` is an **announce channel**: anyone
114+
can find, read and join it, but people who join are guests and cannot write.
115+
116+
What each role can do:
117+
118+
| Action | Guest | Member or bot | Admin / owner |
119+
|--------|-------|---------------|---------------|
120+
| Read, leave | Yes | Yes | Yes |
121+
| Post, reply, edit, delete own, react, artifacts, canvas, forum, pins, typing, workflow messages, huddles | No | Yes | Yes |
122+
| Topic, purpose (kind:9002) | No | Yes | Yes |
123+
| Add people (kind:9000) | No | Yes, as member, guest or bot | Yes, any role |
124+
| Push to the channel's git repositories | No | Yes | Yes |
125+
| Name, about, visibility, TTL, `join_role` | No | No | Yes |
126+
127+
A non-member may write only where joining would give a role that can write:
128+
an open channel with `join_role = member`. A refused write gets
129+
`restricted: only members can post in this channel`.
130+
131+
Other rules:
132+
133+
- A non-member adding themselves with kind:9000 may ask for `join_role` or a
134+
lower role. A higher role is refused.
135+
- Any member who can write (member, bot, owner or admin) can make a guest a
136+
member with kind:9000 (`role` `member`). This is the same for a person and
137+
an agent. Only owners and admins can make any other role change.
138+
- The human owner of an agent can edit (kind:40003) and delete (kind:9005)
139+
that agent's messages, also as a guest or a non-member. This is existing
140+
behavior. It lets a person correct or remove what their agent posted; it
141+
does not let them post.
142+
- Owners and admins change the setting with kind:9002
143+
`["join_role", "guest"]` or `["join_role", "member"]`. A missing tag means
144+
"no change". Changing it does not change anyone's role: existing members
145+
can still write after a change to `guest`, and existing guests stay
146+
read-only after a change to `member`. A stored value the relay does not
147+
know is treated as `guest`.
148+
149+
kind:39000 publishes the NIP-29 access flags from these settings, and an
150+
explicit `["join_role", ...]` tag so clients can tell what joining gives:
151+
152+
| `visibility` | `join_role` | `private` | `public` | `restricted` | `closed` |
153+
|--------------|-------------|-----------|----------|--------------|----------|
154+
| open | `member` | | ✓ | | |
155+
| open | `guest` | | ✓ | ✓ | |
156+
| private | either | ✓ | | ✓ | ✓ |
157+
103158
### Group Discovery
104159

105160
The relay emits NIP-29 group state events when channels are created, updated, or membership changes.
@@ -109,7 +164,7 @@ All discovery events include a `d` tag set to the channel UUID (NIP-29 addressab
109164

110165
| Kind | Tags | Content |
111166
|------|------|---------|
112-
| **39000** | `d=<uuid>`, `name`, `closed`, `t=<channel_type>`, `P=<creator>`, `created_at=<unix seconds>` (always); `about` (if description non-empty); `private` (if applicable); `hidden` (DM channels and private system channels) | Group metadata. **Note:** `closed` is always emitted per NIP-29 convention (Buzz channels require explicit membership), but open channels are still readable/writable by non-members at runtime. The tag reflects the membership model, not access enforcement. |
167+
| **39000** | `d=<uuid>`, `name`, `t=<channel_type>`, `P=<creator>`, `created_at=<unix seconds>`, `join_role` (always); `public` or `private`; `restricted` (private channels, and `join_role=guest`); `closed` (private channels only); `about` (if description non-empty); `hidden` (DM channels and private system channels) | Group metadata. The access flags follow the channel settings (see [Announce channels](#announce-channels)). |
113168
| **39001** | `d=<uuid>`, `t=<channel_type>`, `P=<creator>`, `p` tags with role label (`owner`, `admin`) | Admin list |
114169
| **39002** | `d=<uuid>`, `t=<channel_type>`, `P=<creator>`, `p` tags for all members | Member list |
115170

@@ -156,10 +211,11 @@ out unless they ask for it:
156211
combine with OR, so `#t:["system", <label>]` does not mean "a system
157212
channel with this label".
158213

159-
Push notifications skip system channels. Every kind:44100/44101 membership
160-
notification carries its channel type as `t`, and a filter without `#t` sees
161-
only the legacy types, so system channel notices reach only a filter with
162-
`#t:["system"]` (see NIP-CL).
214+
Push notifications use the same rule: a lease filter pushes events from a
215+
system channel only when its `#h` names that channel. Every kind:44100/44101
216+
membership notification carries its channel type as `t`, and a filter without
217+
`#t` sees only the legacy types, so system channel notices reach only a filter
218+
with `#t:["system"]` (see NIP-CL).
163219

164220
Events are stored **channel-scoped** so access control applies — private channel member lists are
165221
only visible to members. Discover groups via historical REQ:

0 commit comments

Comments
 (0)