buzz/perf/RELAY_BUS_SCALING.md

Buzz relay bus scaling harness

This harness gives reproducible evidence for the rewrite's Redis fan-out scaling claim:

• old/global bus: every relay pod receives every community's event;
• new/community-scoped bus: each pod retains only the server-resolved community topics for which it has local subscribers (buzz:{community_id}:global or buzz:{community_id}:channel:{channel_id}).

The measured default uses Redis PUB/SUB directly with simulated relay pod subscribers. It intentionally isolates the bus boundary: no DB ingest, websocket framing, client rendering, or relay business logic is included.

Run the measured Redis harness

Start Redis locally, or point at an existing instance with REDIS_URL:

REDIS_URL=redis://127.0.0.1:6379/0 ./perf/relay_bus_scaling.py --mode redis

--mode redis is the default. The script uses only Python stdlib and speaks RESP directly; no Python Redis dependency is required.

Baseline scenario used for the PR summary:

64 communities × 100 events/s, one subscribed community, all pods interested in that community, pods = 1,2,4

Measured output shape:

pods	old global cluster ingress/s	old avg pod ingress/s	new scoped cluster ingress/s	new avg pod ingress/s	reduction	old irrelevant/pod	new irrelevant/pod
1	6,400	6,400	100	100	64.0×	98.44%	0.00%
2	12,800	6,400	200	100	64.0×	98.44%	0.00%
4	25,600	6,400	400	100	64.0×	98.44%	0.00%

The harness fails non-zero by default unless:

• observed reduction is at least 95% of the ideal communities / subscribed_communities; and
• scoped-mode irrelevant delivery is at most --max-scoped-irrelevant-pct (default 0.0).

That makes the scaling claim load-bearing: if scoped subscribers are accidentally changed to receive the old global firehose, the assertion goes red.

No-service model mode

For quick review without Redis:

./perf/relay_bus_scaling.py --mode model

Model mode prints the same contract using deterministic arithmetic. It is useful for docs and unit tests, but the PR evidence should cite --mode redis because that path measures actual Redis PUB/SUB delivery.

Unit tests

python3 -m unittest discover -s perf -p 'test_*.py'

The unit tests pin the default 1/2/4-pod 64× contract and include a mutant row that represents scoped mode receiving irrelevant global-firehose traffic; that row must fail the assertion.

Code provenance

The scoped Redis channel format corresponds to buzz_pubsub::EventTopicKey::redis_channel() in crates/buzz-pubsub/src/topic.rs:

• global: buzz:{community_id}:global
• channel: buzz:{community_id}:channel:{channel_id}

retain_topic / release_topic drive dynamic local Redis SUBSCRIBE interest. This harness measures that bus-bound property only. Live relay latency, DB capacity, and client rendering should be measured separately with a full stack because they include unrelated bottlenecks.