Skip to content

Commit 4aef33b

Browse files
committed
Describe event fencing rules and remaining coordination work
Signed-off-by: Ravneet Arora <[email protected]>
1 parent b76879c commit 4aef33b

1 file changed

Lines changed: 92 additions & 19 deletions

File tree

‎docs/user-deletion-message-fencing.md‎

Lines changed: 92 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,112 @@
11
# User-deletion fencing: event database writes
22

3-
This PR checks existing restrictions in the two shared event insertion functions in `buzz-db/src/store/event.rs`: `insert_event_on` and `insert_event_with_thread_metadata_tx`. Every event kind reaching those functions is checked. HTTP and WebSocket event handlers report the restriction as a client refusal.
3+
The two shared event insertion functions in `crates/buzz-db/src/store/event.rs`,
4+
`insert_event_on` and `insert_event_with_thread_metadata_tx`, refuse events
5+
whose signer has a user-deletion restriction. Every event kind reaching these
6+
functions is checked, including relay-signed events.
47

58
## Transaction flow
69

7-
1. Enter the existing community-admitted database transaction.
8-
2. Read the event author's stored owner in this community, if present.
9-
3. Acquire shared global author/owner identity locks and the scoped author lock in canonical order.
10-
4. Read the owner again. If it changed while acquiring locks, reject for retry in a new transaction.
11-
5. Read the author's global and community-scoped restrictions. Reject a restricted author.
12-
6. Persist the event and its transactional derived changes. Commit or rollback releases the locks.
10+
1. Enter a community-admitted, writer-pool READ COMMITTED transaction.
11+
2. Read the signer's stored owner in this community, if present.
12+
3. Acquire shared global signer/owner locks and the scoped signer lock. Each
13+
call sorts its global keys before its scoped keys.
14+
4. Read the owner again. If it changed while acquiring locks, return
15+
`EventAuthorOwnershipChanged`; the caller must roll back and retry in a new
16+
transaction.
17+
5. Query the signer's global and community-scoped restrictions together. If
18+
either exists, return `UserDeletionRestricted` and roll back.
19+
6. Persist the event and its transactional derived changes. Hold the locks
20+
until commit or rollback.
1321

14-
Human restrictions are global by public key; agent restrictions are community-scoped. The author's own restriction decides whether the event is rejected. An owner's restriction is not an additional authorization check for an independently admitted agent. Restrictions still apply when profile rows are absent or recreated.
22+
Human restrictions apply across communities by public key. Agent restrictions
23+
apply in their specified community. The signer's own restriction decides
24+
whether the event is rejected; the owner's restriction is not an additional
25+
check for an independently admitted agent. Missing or recreated profile rows do
26+
not bypass restrictions.
1527

16-
The writer uses the existing identity lock keys used by restriction insertion. If an event transaction wins first, the fence waits for it to finish. If the fence commits first, a waiting event sees the restriction and is rejected. If the fence rolls back, the event may proceed. No user-specific lease is involved.
28+
If a writer holds the shared identity lock first, an exclusive fence waits for
29+
its transaction to finish. If the fence commits first, the waiting writer sees
30+
the restriction and rolls back. If the fence rolls back, the writer may proceed.
31+
No user-specific lease is involved in this database-write protocol.
1732

18-
## Scope
33+
## Errors and atomicity
1934

20-
The guard covers persistence through these two functions, including messages, replies, reactions, edits, votes, canvas, channel changes, deletion events and artifacts. Tests exercise actual callers and check that rejection rolls back transactional domain rows and reply counters.
35+
`event_write_error` maps `UserDeletionRestricted` to the client refusal
36+
`restricted: identity is restricted for user deletion`. Ownership changes use
37+
the retryable internal-error category: HTTP responds with 500; WebSocket
38+
responds with `error: internal server error`. This classification permits a
39+
retry; it does not implement client retries. Unrelated database errors retain
40+
the caller's existing mapping rather than becoming restriction errors.
2141

22-
Separate replaceable-event writers (profiles, emoji collections, bookmarks and workflow definitions), personal read state, uploads, git, audio and ephemeral activity are outside this PR. Authentication, agent creation/owner assignment, affected-user checks and background work are also separate work. This is not complete user-activity fencing.
42+
Archive/unarchive requests (9035/9036) validate consent without changing state.
43+
Their persistence transaction stores the guarded request, changes
44+
`archived_identities`, and stores the relay delta (8002/8003). A failure rolls
45+
back all three. Notifications are dispatched after commit. Duplicate requests
46+
do not reapply the archive change or create another delta.
2347

24-
There are no schema changes, lease changes, or changes to restriction insertion behavior. The existing restriction reader is exposed within the database module so event writers can read after acquiring the full ordered lock set. Tests install restrictions through the previously merged helper solely as fixture setup.
48+
The archival snapshot (13535) is refreshed after commit. A refresh failure
49+
propagates to the caller; retrying the request refreshes the snapshot without
50+
repeating the mutation. The committed request and delta remain available for
51+
query/replay. This is not a durable background retry queue: a process exit
52+
between commit and snapshot refresh can leave the snapshot stale until a later
53+
refresh. Existing freshness/consent validation still applies to retries.
2554

26-
The real user-deletion worker remains disabled. Before enabling it, ownership/admission writes and other serving paths must be coordinated, and the worker must atomically fence the user and the approved owned-agent set. The owner recheck here only detects changes observed while obtaining locks; it does not implement a complete ownership-assignment protocol.
55+
## Actual lock order and exclusive-worker requirements
2756

28-
## Validation
57+
Shared identity locking occurs at event insertion, not necessarily at the
58+
start of the transaction. Artifact and channel writers can already hold domain
59+
row/advisory locks. An artifact Move inserts the author's revision and then a
60+
relay-signed removal, acquiring another global identity lock after the first
61+
signer's scoped lock. Per-call sorting is not a transaction-wide lock order.
2962

30-
Regression tests cover global/scoped restrictions, unaffected users and communities, missing profiles, fence commit/rollback, writes already in flight, observed ownership changes, and the channel-TTL lock interleaving. Relay tests exercise signed HTTP requests and WebSocket EVENT handling before and after restrictions, including replies and unchanged database snapshots on refusal.
63+
An exclusive fencing transaction must:
64+
65+
- Acquire community admission, then the deletion request row, then its complete
66+
global identity set, then its complete scoped identity set.
67+
- Write only restriction/request/checkpoint state while holding those locks.
68+
Do not lock or mutate users, channels, artifacts, events or other serving
69+
domain rows. Read ownership without row locks and perform cleanup in later
70+
transactions.
71+
- Never upgrade a shared identity lock to exclusive. Audit complete exclusive
72+
sets against transactions containing multiple signers before wiring a worker;
73+
per-call sorting alone does not prove arbitrary multi-key batches safe.
74+
75+
The domain-row restriction prevents a fence from waiting on a row held by a
76+
writer that is itself waiting on the fence. PostgreSQL regressions exercise
77+
channel-TTL and artifact Move interleavings and assert that no deadlock was
78+
recorded. Those cases are evidence for the tested paths, not a proof about every
79+
future worker or lock combination.
80+
81+
## Coverage and remaining work
82+
83+
Persistence through the two guarded functions includes messages, replies,
84+
reactions, edits, votes, canvas, channel changes, deletion events, artifacts,
85+
and identity archive/unarchive requests. A refusal rolls back domain changes
86+
performed in the same transaction, including counters and notification events.
87+
88+
Separate replaceable-event writers (profiles, emoji collections, bookmarks and
89+
workflow definitions), personal read state, uploads, git, audio and ephemeral
90+
activity are outside this guard. Authentication, agent creation/owner
91+
assignment, checks on affected users other than the signer, and background work
92+
need separate coordination.
93+
94+
The real user-deletion worker remains disabled. Before enabling it, coordinate
95+
all remaining serving paths and external work, and atomically fence the user
96+
and the approved owned-agent set. The owner reread detects changes observed
97+
while obtaining locks; it is not a complete ownership-assignment protocol.
98+
Restriction insertion behavior and the schema are unchanged by event guards.
99+
100+
## Regression tests
101+
102+
The directly registered `user_deletion_*_postgres_tests` modules in `buzz-db`
103+
and `buzz-relay` cover scopes, missing profiles, unaffected actors, commit and
104+
rollback races, ownership changes, transport errors and transactional state.
105+
The artifact fence race lives in `artifact_postgres_tests`.
31106

32107
With isolated PostgreSQL and Redis configured:
33108

34109
```sh
35110
scripts/postgres-test-run.sh -p buzz-db -p buzz-relay --lib \
36-
-E 'test(/user_deletion_write_guard|user_deletion_message/)' --test-threads 4
111+
-E 'test(/user_deletion/) or test(/artifact_move_and_identity/)' --test-threads 4
37112
```
38-
39-
The earlier 510-case live matrix validated a broader revision that included leases. It is not evidence of this narrowed revision's scope or coverage. Current validation results belong in the PR description.

0 commit comments

Comments
 (0)