Skip to content

Commit d41a0d7

Browse files
matt2eclaude
andcommitted
fix(communities): keep sent sync operations and land dropped selections
Address review 17465b64 on the known-communities sync. The outbox replaced a destination's pending operation with a newer intent, so an operation whose acknowledgement was lost was never re-sent and the opposite intent went out under a fence the server had already moved past. A destination now holds at most a head (possibly sent, never replaced, the only operation the drain dispatches) and one intent queued behind it, which a newer intent replaces until the head settles. Settling rebases the queued intent onto the server's revision or drops it when the record already satisfies it, and reports a divergence only when no local intent remains. `parseSync` normalises a saved record to that shape, and settling removes every operation for the URL before re-adding the queued one, so a duplicate can never cause a resend without backoff. A join the service already holds queues nothing; re-adding after a tombstone still does. The rail shows "Community list not synced" only while a sync owner reports, and the Builderlab plugin starts no owner without a configured service or a native sign-in, so users without them see no indicator. Returning to the window re-checks only communities whose last access answer was not ok; coming online and membership changes still run a full pass. The client parks any other 4xx (except 401/408/429) with its status in the reason instead of retrying forever. A selection cleared by the service, by a leave here or a removal synced from another device, lands on Channels through one App effect on the communities snapshot (respecting ingress recovery), so the rail no longer navigates after a leave. Tests cover both lost-answer orders at the pure-module and sync-owner levels, the no-op join, the indicator without an owner, the partial visibility re-check, the device record failing to save during a drain with an identical replay, an intent queued while the list is in flight, and the App-level landing for both leave and synced removal. docs/communities.md and the Builderlab README describe the outbox model, indicator visibility and selection fallback. Co-Authored-By: Claude Fable 5.1 <[email protected]> Signed-off-by: Matt Toohey <[email protected]>
1 parent 09faa2b commit d41a0d7

16 files changed

Lines changed: 921 additions & 331 deletions

‎docs/communities.md‎

Lines changed: 103 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -104,10 +104,11 @@ in the rail and says so, naming the storage error so a store that never saves
104104
is not the same promise every attempt, and leaving it again finishes through
105105
the not-a-member answer; a store that will not clear is logged by name and the
106106
success notice says some saved data remains. A left community that was selected
107-
lands on Personal space through the host's selection path, exactly as clicking
108-
Personal space would; a host callback that fails there is logged as the host's
109-
own error, and the leave still reports success because the device did finish.
110-
Messages shows an intentional
107+
falls back to Personal space in the service, and the app lands that dropped
108+
selection exactly as clicking Personal space would (Channels, unless ingress
109+
recovery owns the next destination); a community removed from the account on
110+
another device lands the same way, since both go through the one reaction to
111+
the snapshot rather than a callback from the rail. Messages shows an intentional
111112
empty state there. Try drafting in A, switching to B, then returning to A.
112113
Selected channels, drafts and reading offsets are partitioned by the canonical
113114
community origin and viewer; channel IDs alone are not sufficient keys.
@@ -122,58 +123,77 @@ spells them, `wss://host[:port]` with a lowercase host, no default port and no
122123
trailing slash; a configured alias resolves to its origin first and never
123124
leaves the device. Records from before this field existed, or a field this
124125
reader cannot understand, read as empty, and a malformed entry is dropped on
125-
its own.
126-
127-
Each destination has at most one queued operation. Joining queues an add and
128-
leaving a removal; a newer intent for the same destination replaces the queued
129-
one under a fresh operation ID and keeps its revision fence, so removing a
130-
destination that never reached the service still uploads revision 0, and
131-
adding one again after it was removed elsewhere carries that removal's
132-
revision. An acknowledged upload stores the service's record and drops the
133-
operation; an intent queued behind it is dropped when the record already
134-
satisfies it and otherwise moves onto the record's revision. When the service
135-
refuses an upload because another device's change won, the service wins: its
136-
record is adopted, the refused intent is dropped rather than re-sent under a
137-
newer revision, and the contradiction (removed or added elsewhere) is reported
138-
for the memberships to follow. A complete list from the service adds
126+
its own, as is anything between a destination's first and last operations.
127+
128+
Each destination has at most two queued operations: a head, which may already
129+
have been sent and is therefore never replaced or re-fenced, and one intent
130+
waiting behind it, which is not sent until the head settles and is replaced by
131+
any newer intent meanwhile. Joining queues an add and leaving a removal; an
132+
intent the latest word on the destination already satisfies (the waiting
133+
intent, the head, or the service's record) queues nothing, so re-running a
134+
join the service already holds bumps no revision. A fresh head fences on the
135+
last known revision, so removing a destination that never reached the service
136+
still uploads revision 0, and adding one again after it was removed elsewhere
137+
carries that removal's revision. An acknowledged upload stores the service's
138+
record and drops the head; the intent waiting behind it is dropped when the
139+
record already satisfies it and otherwise becomes the head on the record's
140+
revision, sent as a fresh edit under its own operation ID. This is what makes
141+
a lost answer safe: the head is replayed as sent, the service answers for what
142+
it wrote, and the newer intent follows, so joining then leaving (or leaving
143+
then rejoining) across a lost acknowledgement converges on the latest intent.
144+
When the service refuses a head because another device's change won, the
145+
service wins: its record is adopted and the refused intent is dropped rather
146+
than re-sent under a newer revision. The contradiction (removed or added
147+
elsewhere) is reported for the memberships to follow only when nothing waits
148+
behind the head; a waiting intent resolves the destination itself. A complete
149+
list from the service adds
139150
destinations saved on another device under their host name without opening a
140151
session, forgets ones removed elsewhere like the banned answer to a leave (no
141152
relay request, device state kept, Personal space when one was selected), and
142153
queues an upload for saved memberships the service has never seen, which is how
143-
a device list from before sync existed reaches the account. Joining and leaving
144-
never wait for sync. The `knownCommunities` capability exposes the record, the
145-
queue and these writes to one owner, the bundled Builderlab plugin, and carries
146-
that owner's report back for the rail.
147-
148-
The plugin syncs only while signed in to Builderlab, in the native app. Each
149-
sign-in first reads the key the account is bound to: an account bound to
154+
a device list from before sync existed reaches the account; the newest intent
155+
for a destination speaks for it in that merge. Joining and leaving never wait
156+
for sync. The `knownCommunities` capability exposes the record, the queue and
157+
these writes to one owner, the bundled Builderlab plugin, and carries that
158+
owner's report back for the rail.
159+
160+
The plugin starts a sync owner only where signing in is possible: the native
161+
app with a configured Builderlab service. The owner syncs only while signed in.
162+
Each sign-in first reads the key the account is bound to: an account bound to
150163
another key, or to none, stops everything until the next sign-in, and the app
151164
never binds the key itself; that is Hosted communities' job. A matching
152-
binding reads the complete list, merges it as above, then uploads queued
153-
operations one at a time, so a destination never has two in flight. A newly
154-
queued operation, the window coming online or becoming visible runs the drain
155-
again at once. A failed request retries the identical operation, under the
156-
same operation ID, at 1, 2, 4… seconds, capped at a minute, so the service can
157-
replay its answer. The service's refusals are never retried as sent: an
158-
address it refuses or an account that is full parks that one operation until
159-
the next sign-in while the rest continue, an account that cannot sync stops
160-
until then, and a session the service has ended signs the plugin out. Signing
161-
out or disabling the plugin abandons the request in flight and leaves the
162-
queue intact.
165+
binding reads the complete list, merges it as above, then uploads heads one at
166+
a time, so a destination never has two in flight and an intent waiting behind
167+
a head is never sent in its place, whether the head is in flight, awaiting a
168+
retry or parked. A newly queued operation, the window coming online or
169+
becoming visible runs the drain again at once. A failed request, or a device
170+
record that would not take the answer, retries the identical operation, under
171+
the same operation ID, at 1, 2, 4… seconds, capped at a minute, so the service
172+
can replay its answer; a timeout, a rate limit and a server error are such
173+
failures. The service's refusals are never retried as sent: an address it
174+
refuses, an account that is full or any other client error (named with its
175+
HTTP status) parks that one operation until the next sign-in while the rest
176+
continue, an account that cannot sync stops until then, and a session the
177+
service has ended signs the plugin out. Signing out or disabling the plugin
178+
abandons the request in flight and leaves the queue intact.
163179

164180
In the native app, the rail checks each saved community with one signed read
165181
after it mounts, for communities it has not yet read when the list changes,
166-
and again when the window comes online or becomes visible. The development
167-
broker holds lazy, scoped relay connections and has no lighter route, so the
168-
check does not run there. The answer is shown, never acted on:
182+
and again for every one when the window comes online. Coming back to the
183+
window re-checks only communities whose last answer was a refusal or an
184+
unreachable relay, so switching apps is not a round trip per community. The
185+
development broker holds lazy, scoped relay connections and has no lighter
186+
route, so the check does not run there. The answer is shown, never acted on:
169187
a relay that refuses this identity or cannot be reached keeps its place, its
170188
hint says so (**Access refused** or **Unreachable**) and its menu explains, so
171189
a community restored from the account whose relay has since removed the viewer
172190
is not silently dropped. Beside **Add a community**, a quiet indicator reads
173191
**Community list not synced** while an upload is queued or the account needs
174-
binding; its hint names the reason: signing in, the binding, a refusal, or the
175-
retry under way. The indicator and the hints promise nothing about how long a
176-
refusal lasts.
192+
binding, but only while a sync owner is reporting; without the Builderlab
193+
plugin, a configured service or the native app there is no sync to promise, so
194+
nothing is shown. Its hint names the reason: signing in, the binding, a
195+
refusal, or the retry under way. The indicator and the hints promise nothing
196+
about how long a refusal lasts.
177197

178198
## Session lifetime
179199

@@ -299,38 +319,52 @@ change), that join and leave each write the membership change and its queued
299319
upload in one record write which a restart restores, applying a server list
300320
(additions under the host name, forgetting without a purge or relay request,
301321
one record write) and a native sync write that will not save.
302-
`known-communities.test.ts` covers the queue rules on their own: replacement
303-
under a fresh operation ID with the inherited fence, the revision 0 removal
304-
fence and tombstone re-add revision, acknowledgements merged into a newer
305-
intent (dropped or rebased), conflicts with and without a record and their
306-
divergences, every list-merge branch including the pre-sync migration upload
307-
and deference to queued intents, and the tolerant reader of saved state.
322+
It also covers that re-running a join the service already holds queues nothing
323+
while a join after a tombstone queues on its revision.
324+
`known-communities.test.ts` covers the queue rules on their own: the head kept
325+
and a newer intent queued behind it, replacement of only the queued intent,
326+
nothing queued when the latest word already agrees, the revision 0 removal
327+
fence and tombstone re-add revision, the head settled with its queued intent
328+
(dropped or rebased), both lost-acknowledgement orders converging on the latest
329+
intent, conflicts with and without a record and their divergences (none while
330+
an intent waits), duplicates settled by destination, every list-merge branch
331+
including the pre-sync migration upload and deference to the newest intent, and
332+
the tolerant reader of saved state including its head-and-last normalisation.
308333
`src/bundled/builderlab/known-communities/client.test.ts` covers the account
309334
service's routes against the native host transport: the exact request shapes,
310335
int64 strings and omitted repeated fields, every named refusal in JSON and in
311-
the framework's plain text, conflicts with and without a record, malformed
312-
records, a 401 that ends the session and an unreachable service. `sync.test.ts`
313-
covers the owner under a controlled clock: sign-in and a loading record,
314-
the binding check that stops without binding, the complete list merged once per
315-
sign-in, one upload in flight at a time in queue order, identical retries at
316-
each backoff boundary and the reset after a success, the `online` and
317-
`visibilitychange` triggers, parked and halting refusals, the conflict rule's
318-
three outcomes, an abandoned upload on sign-out that keeps the queue, a session
319-
ended by the service and disposal. `index.test.tsx` runs the real plugin wiring
320-
through to the binding and list requests under the signed-in credential.
336+
the framework's plain text, unnamed client errors returned as rejections on
337+
every route while timeouts, rate limits and server errors remain failures,
338+
conflicts with and without a record, malformed records, a 401 that ends the
339+
session and an unreachable service. `sync.test.ts` covers the owner under a
340+
controlled clock: sign-in and a loading record, the binding check that stops
341+
without binding, the complete list merged once per sign-in and an intent queued
342+
while it is in flight, one upload in flight at a time in queue order, identical
343+
retries at each backoff boundary and the reset after a success, a device record
344+
that will not take an answer backing off and replaying, the `online` and
345+
`visibilitychange` triggers, parked and halting refusals including rejections
346+
named by status and the intent that waits behind a parked head, both
347+
lost-acknowledgement orders against the service's own replay rules, the
348+
conflict rule's three outcomes, an abandoned upload on sign-out that keeps the
349+
queue, a session ended by the service and disposal. `index.test.tsx` runs the
350+
real plugin wiring through to the binding and list requests under the
351+
signed-in credential, and that an unconfigured build starts no owner.
321352
`CommunityRail.native.test.tsx` covers the access check (refused and
322353
unreachable communities keep their items with their hints and notes, one read
323-
per saved community per pass, the `online` re-check), and
324-
`CommunityRail.test.tsx` the not-synced indicator with each reason, its
325-
clearing once the queue drains and its return for an unbound account, and that
326-
no check reaches the broker. It also covers the leave flow end to end against the
327-
broker route: confirm, publish, then remove; cancel; refusals and timeouts that
328-
keep the membership; the not-a-member answers (purging) and the banned answer
329-
(keeping device state); a device record that will not save after the relay
330-
answered, naming the storage error; a host selection callback that throws after
331-
a completed leave; residual saved data; the host selection of Personal space for
332-
a left selection; focus placement; the in-flight state; and that no inactive
333-
session is acquired. `device-state.test.ts` covers the per-origin purge and its
354+
per saved community per pass, the partial `visibilitychange` re-check and the
355+
full `online` one), and `CommunityRail.test.tsx` the not-synced indicator with
356+
each reason, its absence without an owner's report, its clearing once the queue
357+
drains and its return for an unbound account, and that no check reaches the
358+
broker. It also covers the leave flow end to end against the broker route:
359+
confirm, publish, then remove; cancel; refusals and timeouts that keep the
360+
membership; the not-a-member answers (purging) and the banned answer (keeping
361+
device state); a device record that will not save after the relay answered,
362+
naming the storage error; residual saved data; that the rail selects nothing
363+
itself after a left selection; focus placement; the in-flight state; and that
364+
no inactive session is acquired. `src/app/App.communities.test.tsx` runs the
365+
real app to show a selection dropped by a leave or by a synced removal landing
366+
on Channels while another community going leaves the page alone.
367+
`device-state.test.ts` covers the per-origin purge and its
334368
per-store failure report. The broker and native adapter tests sign the exact
335369
leave shape and pass through only the relay's known refusals.
336370
`broker.test.ts` runs real localhost HTTP with signed fixture events to verify

‎src/app/App.communities.test.tsx‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
// @vitest-environment jsdom
2+
import "@testing-library/jest-dom/vitest";
3+
import { act, cleanup, render, waitFor } from "@testing-library/react";
4+
import { afterEach, expect, it, vi } from "vitest";
5+
import { StrictMode } from "react";
6+
import { App } from "./App";
7+
import { createServices, type AppServices } from "./services";
8+
import { composerDOMFixture } from "../features/messages/composer-testing";
9+
10+
composerDOMFixture();
11+
12+
// jsdom has no IndexedDB; nothing is sent here.
13+
vi.mock("../features/relay/outbox-storage", () => ({
14+
browserOutboxStorage: () => ({ load: () => [], save: () => {} }),
15+
}));
16+
vi.mock("../bundled", async () => ({
17+
bundledPlugins: [
18+
{
19+
manifest: { id: "buzz.channels", name: "Channels", apiVersion: 1 },
20+
module: await import("../bundled/channels"),
21+
},
22+
],
23+
}));
24+
const viewer = "6".repeat(64);
25+
const origin = "https://community.example";
26+
const other = "https://other.example";
27+
const scoped = {
28+
version: 1 as const,
29+
kind: "settings" as const,
30+
section: "appearance",
31+
scope: { viewer, communityOrigin: origin },
32+
};
33+
const channels = {
34+
version: 1,
35+
kind: "page",
36+
pluginId: "buzz.channels",
37+
pageId: "channels",
38+
scope: null,
39+
};
40+
let services: AppServices | undefined;
41+
afterEach(async () => {
42+
cleanup();
43+
await services?.dispose();
44+
services = undefined;
45+
vi.unstubAllGlobals();
46+
vi.unstubAllEnvs();
47+
localStorage.clear();
48+
window.history.replaceState(null, "", "/");
49+
});
50+
51+
/** The app open on a Settings card scoped to the selected community. */
52+
async function setup() {
53+
// jsdom has no media queries; responsive shell geometry is covered in browsers.
54+
vi.stubGlobal("matchMedia", (media: string) => ({
55+
media,
56+
matches: false,
57+
addEventListener() {},
58+
removeEventListener() {},
59+
}));
60+
vi.stubGlobal(
61+
"ResizeObserver",
62+
class {
63+
observe() {}
64+
unobserve() {}
65+
disconnect() {}
66+
},
67+
);
68+
vi.stubEnv("VITE_BUZZ_LIVE", "1");
69+
localStorage.setItem(
70+
`buzz-client.v1:${viewer}`,
71+
JSON.stringify({
72+
profile: { name: "Local name", picture: "" },
73+
memberships: [
74+
{ id: origin, name: "Fixture community" },
75+
{ id: other, name: "Other community" },
76+
],
77+
selected: origin,
78+
}),
79+
);
80+
vi.stubGlobal(
81+
"fetch",
82+
vi.fn(async (url: string) => {
83+
if (url.endsWith("/identity")) return Response.json({ viewer });
84+
if (url.endsWith("/session"))
85+
return Response.json({
86+
viewer,
87+
relayAuthor: viewer,
88+
relayUrl: decodeURIComponent(url.split("/").at(-2) ?? ""),
89+
});
90+
if (url.endsWith("/query")) return Response.json([]);
91+
return Response.json({});
92+
}),
93+
);
94+
window.history.replaceState(
95+
null,
96+
"",
97+
`/#buzz=${encodeURIComponent(JSON.stringify(scoped))}`,
98+
);
99+
services = createServices();
100+
const current = services;
101+
render(
102+
<StrictMode>
103+
<App services={current} />
104+
</StrictMode>,
105+
);
106+
await waitFor(() =>
107+
expect(current.navigation.snapshot()).toMatchObject({
108+
status: "opened",
109+
entry: { target: scoped },
110+
}),
111+
);
112+
expect(current.communities.snapshot().selected).toBe(origin);
113+
return current;
114+
}
115+
116+
it.each([
117+
{
118+
name: "a leave on this device",
119+
forget: (current: AppServices, id: string) => current.communities.leave(id),
120+
},
121+
{
122+
name: "a removal synced from another device",
123+
forget: (current: AppServices, id: string) =>
124+
current.communities.applySync(
125+
{ known: {}, outbox: [] },
126+
{ remove: [`wss://${new URL(id).host}`] },
127+
),
128+
},
129+
])(
130+
"a selection dropped by $name lands on Channels as clicking Personal space would; another community going does not move the page",
131+
async ({ forget }) => {
132+
const current = await setup();
133+
await act(async () => {
134+
await forget(current, other);
135+
});
136+
expect(current.communities.snapshot().memberships.map((m) => m.id)).toEqual(
137+
[origin],
138+
);
139+
expect(current.communities.snapshot().selected).toBe(origin);
140+
expect(current.navigation.snapshot().entry.target).toEqual(scoped);
141+
await act(async () => {
142+
await forget(current, origin);
143+
});
144+
expect(current.communities.snapshot().selected).toBeNull();
145+
await waitFor(() =>
146+
expect(current.navigation.snapshot()).toMatchObject({
147+
status: "opened",
148+
entry: { target: channels },
149+
}),
150+
);
151+
},
152+
);

0 commit comments

Comments
 (0)