block / block/buzz

ARCHITECTURE.md drift: rate-limiting claim inverted, stale limits and pipeline description

Open
#4,210 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
32.7k
Forks
4.3k
Avg merge
1d 13h
Merged PRs (30d)
253

Description

Audited ARCHITECTURE.md against the code at `ac4fa13` (main). Several load-bearing claims have drifted; the first one is security-relevant for operators.

## 1. Rate limiting — doc states the opposite of the code

Doc (§ buzz-auth "Does NOT", and Known Limitations #2) says no rate limiter is implemented or enforced. The code has a Redis-backed limiter, wired and enforced:

- `crates/buzz-pubsub/src/rate_limiter.rs` — `RedisRateLimiter`
- `crates/buzz-relay/src/state.rs:584,713` — wired as `admission_rate_limiter`
- `crates/buzz-relay/src/connection.rs:615,638` — enforced on WS connect + per-message
- `crates/buzz-relay/src/api/bridge.rs:30` — enforced on the HTTP bridge

An operator reading the doc's gap table would assume the relay is unprotected.

## 2. Client-facing limits are stale

- Max frame: doc says 65,536; code default is `DEFAULT_MAX_FRAME_BYTES = 512 * 1024` (`crates/buzz-relay/src/config.rs:14`, env-overridable). `nip11.rs:226` still advertises `max_content_len: 65536` (separate value — worth clarifying which is which).
- Historical query cap: doc says 500; code is `DEFAULT_MAX_PAGE_LIMIT = 1_000` (`crates/buzz-db/src/event.rs:25`), advertised as NIP-11 `max_limit`.

## 3. Event pipeline step 10 / search description stale

- The `search_index_tx` bounded worker queue described in the pipeline no longer exists — FTS is a generated `search_tsv` column populated by the insert itself (comment at `crates/buzz-relay/src/handlers/event.rs:502-506`).
- The privacy exclusion list is no longer `(1059, 30300, 30622)`: `migrations/0001` had 5 kinds, and `migrations/0008_fresh_install_search_allowlist.sql:15-21` flips fresh installs to a positive allowlist `kind IN (0, 9, 40002, 45001, 45003)`.
- Pipeline ordering note: redis/fan-out/workflow now run in a spawned task (`event.rs:342-390`).

## 4. Stale counts (least load-bearing — consider dropping exact numbers)

- `ALL_KINDS`: doc says "127 kinds" in §2 and "80 entries" in §6; actual count is 129 (`crates/buzz-core/src/kind.rs:622`).
- buzz-acp LOC table is ~2× off across the board (e.g. relay.rs 6246 vs doc 3143; main.rs is now a 3-line shim, logic in lib.rs).
- e2e test table: rows say 27/7/18/15 with total 134, but the rows sum to 67; current per-file counts are 43/7/21/25, with 242 test fns across 18 files.

## Verified accurate (no action)

Zero-I/O buzz-core, channel fan-out security boundary (global subs excluded), audit hash-chain design, huddle caps (25 soft / 255 hard / 8-byte header), NIP-42 ±60s, workflow approval-gate and send_dm/set_channel_topic gaps.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Contributor guide

Open the contributing guide

Research direction

Start with ARCHITECTURE.md and compare each affected section against the referenced Rust files, migrations, and test-count details. Update the rate-limiting, limits, pipeline, search, and count descriptions while preserving the items marked accurate; done means the documented claims match the code at the referenced main revision.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.