Skip to content

Commit c4c8600

Browse files
feat(relay): deliver pubkey mentions to relay companions (#7793)
We are introducing a companion service to the relay that needs pubkey event mentions for pubkeys it manages. This PR introduces an outbox for pubkey mentions that will be sent to these "operator listener" services. ## Summary Deliver mentions of registered pubkeys to deployment-global operator listeners. - Configure listeners with `BUZZ_OPERATOR_LISTENERS`; listeners manage target pubkeys through NIP-98-authenticated `POST`/`DELETE /operator/listener/pubkeys` requests. - During supported event ingestion, match `p` tags to registrations and insert one outbox row per listener in the event transaction. - A background worker claims up to 10 rows, sends NIP-98-signed notifications, and retries transient failures with exponential backoff for up to 9 attempts (idle polling backs off from 250 ms to 2 s). - Outbox rows are ineligible for delivery after 15 minutes and are reaped every 5 minutes. Registered pubkeys live for 30 days; re-registering renews them, and a daily reaper removes expired registrations. - Keep persistence app-managed: no database triggers, functions, foreign keys, or separate match queue. ## Changed behavior Listener outbox rows are enqueued inside the shared event-insert and thread-metadata transactions; enqueue failure rolls back the event. `event_mentions` behavior is unchanged: ordinary event/reaction mention indexing remains post-commit best effort with warning-only failures. ## Testing - `cargo fmt --all` - `cargo test -p buzz-db --lib` - `cargo test -p buzz-relay --lib config::tests::operator_listener_routes` - `cargo check -p buzz-db -p buzz-relay`
1 parent b0d6fb8 commit c4c8600

18 files changed

Lines changed: 2587 additions & 46 deletions

‎.env.example‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,12 @@ BUZZ_PUSH_GATEWAY_DELIVERY_URL=https://push.buzz.xyz/v1/deliveries/apns
120120
# and provisioning requests fail closed until it is set.
121121
# RELAY_OPERATOR_API_ORIGIN=http://127.0.0.1:3000
122122

123+
# Deployment-global operator-listener routes. Each configured Nostr identity
124+
# may register target pubkeys and receives mention notifications at its URL.
125+
# Format: pubkey:deliveryUrl;pubkey:deliveryUrl
126+
# BUZZ_OPERATOR_LISTENER_TIMEOUT_MS=5000
127+
# BUZZ_OPERATOR_LISTENERS=<64-char hex pubkey>:https://listener.example/mentions
128+
123129
# Optional relay-owned KLIPY key. When set, NIP-11 advertises GIF search and
124130
# authenticated desktop clients use this relay as the metadata/search proxy.
125131
# Keep the real value in your deployment's secret manager; never commit it.

‎crates/buzz-db/src/lib.rs‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,9 +63,10 @@ pub(crate) use runtime::{
6363
};
6464
pub use store::{
6565
admin_moderation, allowlist, api_token, archived_identities, channel, channel_members,
66-
community, deletion, dm, event, feed, git_repo, moderation, partition, product_feedback, push,
67-
reaction, read_state, relay_admin_actions, relay_invite, relay_members, relay_operators,
68-
reminder, replaceable, storage_accounting, thread, thread_window, usage, user, workflow,
66+
community, deletion, dm, event, feed, git_repo, moderation, operator_listener, partition,
67+
product_feedback, push, reaction, read_state, relay_admin_actions, relay_invite, relay_members,
68+
relay_operators, reminder, replaceable, storage_accounting, thread, thread_window, usage, user,
69+
workflow,
6970
};
7071

7172
pub use allowlist::AllowlistEntry;

‎crates/buzz-db/src/runtime/migration.rs‎

Lines changed: 59 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -490,6 +490,8 @@ mod postgres_tests {
490490
"relay_admin_outbox",
491491
"relay_operator_audit",
492492
"storage_accounting_snapshots",
493+
"operator_listener_pubkeys",
494+
"operator_listener_outbox",
493495
] {
494496
if normalized[insert_pos..].contains(&format!("'{value}'")) {
495497
globals.insert(value.to_owned());
@@ -703,7 +705,7 @@ mod postgres_tests {
703705
let mut migrations: Vec<_> = MIGRATOR.iter().collect();
704706
migrations.sort_by_key(|migration| migration.version);
705707

706-
assert_eq!(migrations.len(), 49);
708+
assert_eq!(migrations.len(), 50);
707709
assert_eq!(migrations[48].version, 49);
708710
assert!(migrations[48]
709711
.sql
@@ -1293,10 +1295,63 @@ mod postgres_tests {
12931295
.sql
12941296
.as_str()
12951297
.contains("CREATE TABLE storage_accounting_snapshots"));
1296-
// schema.sql exclusion list must match the restored (pre-0041) body.
1298+
assert_eq!(migrations[47].version, 48);
1299+
assert!(migrations[47]
1300+
.sql
1301+
.as_str()
1302+
.contains("ADD COLUMN hash_version SMALLINT"));
1303+
assert_eq!(migrations[49].version, 50);
1304+
assert!(migrations[49]
1305+
.sql
1306+
.as_str()
1307+
.contains("CREATE TABLE operator_listener_pubkeys"));
1308+
assert!(migrations[49]
1309+
.sql
1310+
.as_str()
1311+
.contains("CREATE TABLE operator_listener_outbox"));
1312+
assert!(migrations[49]
1313+
.sql
1314+
.as_str()
1315+
.contains("CREATE OR REPLACE FUNCTION community_write_fence_excluded_table"));
1316+
assert!(migrations[49]
1317+
.sql
1318+
.as_str()
1319+
.contains("'rate_limit_violations', 'operator_listener_outbox'"));
1320+
for index in [
1321+
"operator_listener_pubkeys_target",
1322+
"operator_listener_pubkeys_created_at",
1323+
"operator_listener_outbox_due",
1324+
"operator_listener_outbox_recovery",
1325+
"operator_listener_outbox_created_at",
1326+
] {
1327+
assert!(
1328+
migrations[49].sql.as_str().contains(index),
1329+
"migration 0050 must declare {index}"
1330+
);
1331+
assert!(
1332+
desired_schema.contains(index),
1333+
"schema.sql must declare {index}"
1334+
);
1335+
}
1336+
for index_shape in [
1337+
"ON operator_listener_outbox (next_attempt_at, created_at, id)",
1338+
"ON operator_listener_outbox (lease_until, created_at, id)",
1339+
] {
1340+
assert!(
1341+
migrations[49].sql.as_str().contains(index_shape),
1342+
"migration 0050 must declare {index_shape}"
1343+
);
1344+
assert!(
1345+
desired_schema.contains(index_shape),
1346+
"schema.sql must declare {index_shape}"
1347+
);
1348+
}
1349+
// schema.sql keeps the restored (pre-0041) deletion exclusions and also
1350+
// leaves the deployment-global listener outbox outside tenant fencing.
12971351
assert!(
1298-
desired_schema.contains("'rate_limit_violations'\n ]::TEXT[])"),
1299-
"schema.sql exclusion list must match the pre-0041 body after ledger removal"
1352+
desired_schema
1353+
.contains("'rate_limit_violations', 'operator_listener_outbox'\n ]::TEXT[])"),
1354+
"schema.sql must exclude the deployment-global listener outbox from tenant fencing"
13001355
);
13011356
}
13021357

‎crates/buzz-db/src/runtime/tests.rs‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -638,6 +638,26 @@ async fn migration_schema_database_guard_covers_legacy_writer_and_nip09_deletion
638638
assert_eq!(watermark.1, c.id.as_bytes().as_slice());
639639
}
640640

641+
#[tokio::test]
642+
#[ignore = "requires Postgres"]
643+
async fn migration_schema_operator_listener_outbox_is_not_tenant_scoped() {
644+
let db = setup_db().await;
645+
let community = CommunityId::from_uuid(make_community(&db.pool).await);
646+
let inventory = db
647+
.deletion_store()
648+
.inventory_schema(community)
649+
.await
650+
.expect("migrated deletion catalog should validate");
651+
652+
assert!(
653+
!inventory
654+
.scoped_tables
655+
.iter()
656+
.any(|table| table == "operator_listener_outbox"),
657+
"operator-listener outbox is deployment-global, not tenant-scoped"
658+
);
659+
}
660+
641661
// ---- Read-replica routing ------------------------------------------------
642662
//
643663
// These tests pin the routing contract of `Db::read()` and the two routed

‎crates/buzz-db/src/runtime/tests/thread_window_postgres_tests.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -311,7 +311,7 @@ async fn migration_schema_thread_window_prebuild_does_not_queue_behind_writer()
311311
production_result.is_ok(),
312312
"production migrator must preserve ingestion progress: {production_result:?}"
313313
);
314-
assert_eq!(version, 49);
314+
assert_eq!(version, 50);
315315
assert_eq!(final_oid, oid, "prebuild must not be replaced");
316316
assert_eq!(count, 4, "all writer witnesses must persist");
317317
}

‎crates/buzz-db/src/store/event.rs‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -355,12 +355,15 @@ pub async fn insert_event(
355355
event: &Event,
356356
channel_id: Option<Uuid>,
357357
) -> Result<(StoredEvent, bool)> {
358-
let mut connection = crate::observability::acquire_writer(
358+
let connection = crate::observability::acquire_writer(
359359
pool,
360360
crate::observability::WriterOperation::EventWrite,
361361
)
362362
.await?;
363-
insert_event_on(&mut connection, community_id, event, channel_id).await
363+
let mut tx = Transaction::begin(connection, None).await?;
364+
let result = insert_event_in_transaction(&mut tx, community_id, event, channel_id).await?;
365+
tx.commit().await?;
366+
Ok(result)
364367
}
365368

366369
/// Insert a Nostr event in a caller-owned PostgreSQL transaction.
@@ -374,7 +377,11 @@ pub async fn insert_event_in_transaction(
374377
event: &Event,
375378
channel_id: Option<Uuid>,
376379
) -> Result<(StoredEvent, bool)> {
377-
insert_event_on(tx.as_mut(), community_id, event, channel_id).await
380+
let result = insert_event_on(tx.as_mut(), community_id, event, channel_id).await?;
381+
if result.1 {
382+
crate::operator_listener::enqueue_mentions_in_transaction(tx, community_id, event).await?;
383+
}
384+
Ok(result)
378385
}
379386

380387
async fn insert_event_on(
@@ -1528,6 +1535,8 @@ pub(crate) async fn insert_event_with_thread_metadata_tx(
15281535
}
15291536
}
15301537
}
1538+
1539+
crate::operator_listener::enqueue_mentions_in_transaction(tx, community_id, event).await?;
15311540
}
15321541

15331542
Ok((

‎crates/buzz-db/src/store/mod.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ pub mod feed;
2626
pub mod git_repo;
2727
/// Community moderation: reports, bans/timeouts, audit actions.
2828
pub mod moderation;
29+
/// Deployment-global operator-listener mention registrations and delivery queues.
30+
pub mod operator_listener;
2931
/// Monthly table partition management.
3032
pub mod partition;
3133
/// Buzz product-feedback sidecar persistence.

0 commit comments

Comments
 (0)