@weavo/membership

CASPaxos-based membership, presence, liveness, and GC frontier for Weavo rooms.

Install

npm install @weavo/membership

What it owns

• Membership — versioned UUID → shortId tables committed with prepare / accept / commit
• Presence — LWW map of live peers (cursor, name, color) updated from HEARTBEATs
• Heartbeats — ~2s broadcast after join; carries presence plus piggybacked membershipVersion and state vector
• Liveness — silent peers become suspect (~10s, presence dropped) then proposed for removal (~30s)
• Leave — graceful LEAVE or ungraceful timeout → removeMember via the same consensus spine as join
• GC frontier — min of peer state vectors from heartbeats; client runs tombstone GC after grace

import { createMembership } from "@weavo/membership";

const membership = createMembership(send, {
  clientId,
  getPresence: () => ({ cursor, name, color }),
  getStateVector: () => Object.fromEntries(sv),
});

membership.onPresence((peers) => {
  // Map<ClientId, { clientId, cursor, name, color }>
});

const frontier = membership.computeGCFrontier();

// Graceful exit — peers remove you via CASPaxos
membership.leave();

Pass heartbeatIntervalMs: 0 to disable the timer (tests). Tune presenceTimeoutMs / removalTimeoutMs for suspect vs remove thresholds.

Development

# from packages/membership
bun test
bun run build

Related packages

| Package | Role | | ------------------ | ---------------------------- | | @weavo/core | CRDT operations and replicas | | @weavo/sync | State-vector synchronization | | @weavo/transport | Wire transport | | @weavo/client | Browser client |

License

MIT