mirror of
https://github.com/block/buzz.git
synced 2026-11-13 04:41:12 +00:00
d0fd96fca6
## Summary
Route every serving event write through one community-admitted
transaction entry point. `Db::begin_event_write_transaction(community)`
is now the only `Db` constructor for event-write transactions: it takes
the shared community admission lock before returning, so callers that
use it cannot take domain or row locks ahead of tenant admission, and a
quiescing community rejects the write at entry. Database triggers and
commit-time fences remain the authoritative backstop.
This migrates normal, replaceable, roster, relay membership, reaction,
reminder, admin-delete, push-owned, artifact-accept, huddle-join
(48101), workflow-deletion, and command-executor event writes. Coupled
mention writes stay in the same transaction; pool-level
`insert_mentions` now opens its own admitted transaction.
**Review fixes (since `950d5f6`):**
- The unguarded event-write constructor is gone. Removed with it: the
deprecated `begin_transaction` alias, the test-only replica-floor
constructor, and `begin_community_write_transaction` (now identical to
the single constructor). Artifact accept, the huddle join, and both
workflow-deletion paths now admit before any domain or row lock;
`persist_command_event` no longer hand-rolls `guard_transaction`;
read-only `query_artifacts` no longer opens an event-write transaction.
- `insert_channel_head_checked` is now `insert_canvas_head_checked`: it
rejects non-canvas kinds before opening a transaction and always takes
the coordinate lock.
- Source policy now also scans `buzz-relay`: any function that hands a
transaction to an event-write helper must have opened it through the
admitted constructor. The scan drops each `#[cfg(test)]` item instead of
stopping at the first one: it tracks brace depth and ends the item on a
line ending in `;` or `}` (ignoring a trailing `//` comment, even after
a string that contains `//`), with a column-0 `}` as fallback. Fixtures
pin a unit struct, a multi-line static, a `const { … }` block, a struct
with fields, a module, and one-line items with trailing comments,
including after `"https://…"` and `"ws://…"` strings; a raw opener after
each must still be flagged. Known limit: braces inside string or char
literals or comments are still counted, and only `//` trailing comments
are recognized, so a test-only item with unbalanced braces in a literal
or comment, or with a trailing `/* */`, would hide what follows; none
exists today. The scan checks that admission is present; the per-path
PostgreSQL tests pin that it comes before domain locks.
- `just test-unit` (and the non-nextest fallback in
`scripts/run-tests.sh`) now runs `buzz-db --test observability_source`.
Before this, no CI job ran these source-policy tests: the unit lane ran
`buzz-db --lib` only and the PostgreSQL lane runs only ignored tests.
- Renamed or removed since `950d5f6`: `begin_transaction`,
`begin_community_write_transaction`, and the replica-floor test
constructor are gone; `insert_channel_head_checked` →
`insert_canvas_head_checked`; test helper `quiesce_community_for_tests`
now delegates to `main`'s `set_deletion_state`, which reads the real
`deletion_fence_generation` instead of hard-coding `'0'`;
`runtime::insert_mentions` is pinned to the admitted constructor by
`pool_level_insert_mentions_opens_the_tenant_local_chokepoint`.
**What got simpler:** four transaction constructors collapse to one, and
the hand-rolled admission guard is deleted. The compiler rejects callers
of the removed constructors, but a transaction opened from `Db::pool()`
can still reach the public `*_in_transaction` helpers; only the
source-policy scan and the database fences catch that until BUZZ-254.
**Behavior note:** #7932 made `insert_event` skip the transaction for
kinds that are not listener mentions. Every serving event write now has
to run in a transaction that holds the community admission lock, so
`insert_event` always opens the admitted transaction again. `main`'s
`soft_delete_event_and_update_thread` / `_in_tx` split and its
removal-marker guard are kept; the outer function now opens the admitted
transaction.
### Related issue
[BUZZ-175](https://linear.app/squareup/issue/BUZZ-175). Caller-migration
stage following #7706 (merged); rebased onto `main` at `5173fad66`.
Follow-up: [BUZZ-254](https://linear.app/squareup/issue/BUZZ-254) makes
event-write helpers require a type-level admitted transaction.
**Known debt, out of scope:** `create_channel`, `update_channel`, and
`insert_thread_metadata` write channel and thread rows (not events)
outside the admitted constructor.
### Testing
At `efe4a94623dd69973780a3c39f16dd972cf7cb76` on a cloud workstation:
fmt; `buzz-db` clippy (all targets, `-D warnings`);
`observability_source` 14/14; `just --dry-run test-unit` includes the
new step. Reverting just the end-of-item check to an earlier rule makes
a trailing-comment fixture fail.
At `eaf190ae59d1595741c3d19dc4c23ce492b5f4d4` (the commit after it only
changes this test file, `Justfile`, and `scripts/run-tests.sh`): full
GitHub CI green; on the workstation, clippy for `buzz-db` and
`buzz-relay`, ordinary `buzz-db` 154/154, `just test-unit` green, and
the PostgreSQL lane 805 of 806 (exception below). An end-to-end run
against a local relay and the built desktop app covered artifact accept,
huddle join, and workflow deletion for both a healthy and a quiescing
community, plus p-tag reaction rollback and replay of the same signed
event.
New tests: one fenced-community test per migrated path (artifact accept,
huddle join, both workflow deletions) puts the community into
`quiescing`, holds the lock the path takes next, and asserts rejection
at entry with nothing stored; a DB-free test pins the non-canvas
rejection.
Exceptions:
-
`runtime::postgres_tests::writer_pool_rejects_non_read_committed_database_default`
hangs on that workstation's local Postgres 16 at both this head and an
earlier `main` base, `f0eb5575f` (2/2 runs each). The test, `Db::new`,
and the pool setup are unchanged by this PR, and the test passes in
GitHub CI. Live traces put the hang in the client, not the database: the
1 s acquire timeout stops firing after sqlx's `after_connect` rejection
path under tokio's `current_thread` runtime. No database lock waits were
observed.
- Two `observability_source` assertions were already failing on `main`,
unnoticed because no CI job ran that test binary: a stale
`fetch_optional` pin after #8005, and lease-seam attribution that now
lives in the `bounded_serving_lease_sql` helper. Both are corrected
here, and the binary now runs in `just test-unit`.
Generated with Codex
---------
Signed-off-by: tornquist <tornquist@squareup.com>
Signed-off-by: Elrond <28d6302a099e5225b02c4155ac4236e4912603df2ab08dbfc2f4fef08ce598c8@buzz.block.builderlab.xyz>
Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Elrond <28d6302a099e5225b02c4155ac4236e4912603df2ab08dbfc2f4fef08ce598c8@buzz.block.builderlab.xyz>
88 lines
3.7 KiB
Rust
88 lines
3.7 KiB
Rust
#![deny(unsafe_code)]
|
||
#![warn(missing_docs)]
|
||
//! buzz-db — Postgres event store for Buzz.
|
||
//!
|
||
//! ## Design invariants
|
||
//! - AUTH events (kind 22242) are never stored — they carry bearer tokens.
|
||
//! - Ephemeral events (20000–29999) are never stored — Redis pub/sub only.
|
||
//! - Events table is partitioned by month on `created_at`.
|
||
//! - No FK references to partitioned tables.
|
||
//! - Uses `sqlx::query()` (runtime) not `sqlx::query!()` (compile-time).
|
||
//!
|
||
//! ## Runtime and store ownership
|
||
//! Database runtime infrastructure and domain persistence are physically
|
||
//! separated behind this crate-root compatibility facade:
|
||
//!
|
||
//! - Runtime concerns own pool construction, writer/replica routing,
|
||
//! transactions, sessions, metrics, health support, and migrations.
|
||
//! - Store concerns own domain-specific SQL, row mapping, locking, mutation
|
||
//! rules, indexes, and focused persistence tests.
|
||
//!
|
||
//! Existing crate-root modules, records, and [`Db`] methods remain the public
|
||
//! API. The internal `runtime` and `store` namespaces are not public APIs.
|
||
|
||
mod runtime;
|
||
mod store;
|
||
|
||
/// Database error types.
|
||
pub mod error;
|
||
|
||
#[cfg(test)]
|
||
mod test_support;
|
||
|
||
pub use runtime::{
|
||
insert_mentions, migration, replica_fence, Db, DbConfig, DbConnectionOutcome, DbConnectionStep,
|
||
DbPoolRole, DbPoolStats, DbReadinessOutcome, ReadSession,
|
||
};
|
||
|
||
/// Valid low-cardinality `(pool_role, operation)` pairs for pool-acquisition telemetry.
|
||
pub const DB_POOL_ACQUIRE_VALID_PAIRS: [(&str, &str); 11] =
|
||
runtime::observability::POOL_ACQUIRE_VALID_PAIRS;
|
||
|
||
/// Raw Prometheus series ceiling per relay pod for the operation-aware contract.
|
||
pub const DB_POOL_ACQUIRE_RAW_SERIES_PER_POD: usize =
|
||
runtime::observability::POOL_ACQUIRE_RAW_SERIES_PER_POD;
|
||
|
||
/// Valid database connection role/step pairs with a start counter.
|
||
pub const DB_CONNECTION_STARTED_STEPS: [(DbPoolRole, DbConnectionStep); 4] =
|
||
runtime::CONNECTION_STARTED_STEPS;
|
||
|
||
/// Valid database connection role/step pairs with a duration histogram.
|
||
pub const DB_CONNECTION_DURATION_STEPS: [(DbPoolRole, DbConnectionStep); 4] =
|
||
runtime::CONNECTION_DURATION_STEPS;
|
||
|
||
/// Valid database connection role/step/outcome terminal combinations.
|
||
pub const DB_CONNECTION_TERMINALS: [(DbPoolRole, DbConnectionStep, DbConnectionOutcome); 15] =
|
||
runtime::CONNECTION_TERMINALS;
|
||
|
||
/// Raw Prometheus series ceiling per pod for connection-step telemetry.
|
||
pub const DB_CONNECTION_RAW_SERIES_PER_POD: usize = runtime::CONNECTION_RAW_SERIES_PER_POD;
|
||
pub(crate) use runtime::{
|
||
begin_community_event_write_transaction,
|
||
begin_community_event_write_transaction_with_legacy_metrics, insert_mentions_in_transaction,
|
||
observability, route_proof, ReadSessionInner, RouteDecision, RoutePredicate,
|
||
};
|
||
pub use store::{
|
||
admin_moderation, allowlist, api_token, archived_identities, artifact, channel,
|
||
channel_members, community, deletion, dm, event, feed, git_repo, moderation, operator_listener,
|
||
partition, product_feedback, push, reaction, read_state, relay_admin_actions, relay_invite,
|
||
relay_members, relay_operators, reminder, replaceable, storage_accounting, thread,
|
||
thread_window, usage, user, workflow,
|
||
};
|
||
|
||
pub use allowlist::AllowlistEntry;
|
||
pub use api_token::{ApiTokenRecord, TokenSummary};
|
||
pub use community::{
|
||
ArchivedCommunityRecord, CommunityRecord, CreateCommunityWithOwnerResult,
|
||
CreatedCommunityRecord, EnsuredCommunityRecord, OwnedCommunityRecord, UnarchiveCommunityResult,
|
||
UnarchivedCommunityRecord,
|
||
};
|
||
pub use error::{DbError, Result};
|
||
pub use event::{ChannelHeadPrecondition, ChannelHeadWriteStatus};
|
||
pub use event::{EventQuery, DEFAULT_MAX_PAGE_LIMIT};
|
||
pub use reaction::ReactionEventInsertOutcome;
|
||
pub use reminder::DueReminder;
|
||
pub use usage::UsageMetricsLeader;
|
||
|
||
use buzz_core::CommunityId;
|