From 9d3d710dc15aa3d0bf0923a9ca51928f109b35cb Mon Sep 17 00:00:00 2001 From: Tom Brow Date: Fri, 9 Oct 2026 12:47:05 -0700 Subject: [PATCH] docs(push): clarify acceptable enrollment overlap Signed-off-by: Tom Brow --- crates/buzz-db/src/runtime/push_enqueue.rs | 6 +++--- crates/buzz-db/src/store/event_follow_up_postgres_tests.rs | 5 +++-- docs/push-gateway-deployment.md | 7 +++++-- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/crates/buzz-db/src/runtime/push_enqueue.rs b/crates/buzz-db/src/runtime/push_enqueue.rs index ca72694257..40b1dcb52f 100644 --- a/crates/buzz-db/src/runtime/push_enqueue.rs +++ b/crates/buzz-db/src/runtime/push_enqueue.rs @@ -158,9 +158,9 @@ async fn enqueue(pool: &PgPool, job: &Job) -> crate::Result<()> { .bind(crate::push::push_gate_lock_key(job.community)) .execute(&mut *tx) .await?; - // Do not enqueue solely because a lease first appeared after the - // message arrived. Updates racing this check may drop a wake, which is - // permitted by the best-effort contract; message storage is authoritative. + // Compare recorded receipt/update times without imposing commit ordering. + // Registration overlapping message arrival may send or suppress a wake. + // This bounded job never scans historical messages on lease activation. sqlx::query( "INSERT INTO push_match_queue (community_id, event_id) \ SELECT $1, $2 FROM events e \ diff --git a/crates/buzz-db/src/store/event_follow_up_postgres_tests.rs b/crates/buzz-db/src/store/event_follow_up_postgres_tests.rs index d2eb680519..5a61e288d3 100644 --- a/crates/buzz-db/src/store/event_follow_up_postgres_tests.rs +++ b/crates/buzz-db/src/store/event_follow_up_postgres_tests.rs @@ -998,8 +998,9 @@ async fn assert_async_isolation(db: &Db, community: CommunityId, keys: &Keys) { .unwrap(); assert_eq!(match_count(&isolated, community, &healthy).await, 1); - // If activation finishes while a post-commit job waits, it must not create - // a wake solely for a lease that appeared after the message was received. + // Exercise the timestamp filter with a lease timestamp explicitly newer + // than this message. This is not a production activation-order regression: + // registration overlapping message arrival may send or suppress a wake. let later = create_community(db.pool()).await; let mut activation = db.pool().begin().await.unwrap(); sqlx::query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))") diff --git a/docs/push-gateway-deployment.md b/docs/push-gateway-deployment.md index 25756e4bdd..b6474946b0 100644 --- a/docs/push-gateway-deployment.md +++ b/docs/push-gateway-deployment.md @@ -294,8 +294,11 @@ reject or roll back a committed message, and there is no replay/backfill of in-memory work. Monitor `buzz_push_enqueue_total` by result (`completed`, `full`, `transaction_full`, `closed`, `error`, `timeout`, `shutdown`). `completed` includes jobs with no eligible lease. Database enqueue is conditional on a live event and -an eligible lease last updated no later than event receipt. A concurrent lease -update can suppress a notification under this best-effort contract. +an eligible lease whose recorded update timestamp is no later than event receipt. +These timestamps do not establish transaction commit order. When registration +and message arrival overlap, either sending or suppressing the notification is +acceptable; there is no exact enrollment-order guarantee. Activation never scans +historical messages or deliberately backfills older notifications. This isolation requires the overlap migration and updated writers. Old images and raw SQL writers can still run the legacy transactional trigger until replaced.