What Is the Event Pipeline in Buzz? Transport-Neutral Ingest Architecture Explained

The event pipeline in Buzz is a transport-neutral ingest system that processes all Nostr events through a unified entry point, applying cryptographic verification, schema validation, and community scoping before persisting and broadcasting to subscribers.

The event pipeline in Buzz serves as the central processing engine for the block/buzz repository, handling every inbound Nostr event regardless of whether it arrives via WebSocket or HTTP. This architecture ensures consistent validation, authorization, and storage logic by funneling all traffic through a single, test-covered ingestion point defined in the relay crate.

How the Pipeline Unifies WebSocket and HTTP Traffic

Both WebSocket "EVENT" messages and HTTP POST /events requests converge at the ingest_event function defined in crates/buzz-relay/src/handlers/ingest.rs. According to the source comments at the top of this file, this design eliminates separate code paths for different transport mechanisms. Desktop, web, mobile, and custom agent clients submit events identically, ensuring that validation semantics remain constant across all interfaces.

The Seven Stages of the Buzz Event Pipeline

The pipeline executes as a sequence of discrete, composable stages. Each stage is implemented as a focused function with dedicated test coverage, making the system maintainable and auditable.

1. Message Routing and Unified Entry

All inbound events enter through ingest_event, which acts as the sole gateway for the entire system. This function immediately abstracts transport details, meaning WebSocket frames and HTTP bodies receive identical processing from this point forward.

2. Signature Verification

Before any business logic executes, the pipeline calls buzz_core::verification::verify_event to cryptographically validate the event signature. As implemented in ingest.rs (lines 40-42), this signature serves as the trust anchor; if verification fails, processing halts immediately to prevent spoofed or tampered events from entering the system.

3. Kind-Specific Validation

Validated events proceed through a large match statement on the event kind field. The pipeline dispatches to specialized validators including:

• validate_huddle_lifecycle_event (lines 81-141) – Enforces state machine rules for ephemeral conferencing.
• validate_custom_emoji_tags (lines 45-58) – Validates emoji tag formatting.
• validate_reaction_emoji – Ensures reaction content complies with protocol expectations.

These functions enforce Nostr Improvement Proposal (NIP) compliance and business-specific schema rules.

4. Scope and Community Checks

Using buzz_auth::Scope and buzz_core::tenant::TenantContext, the pipeline verifies that the event is authorized for the target community and respects NIP-29 channel scoping rules (see lines 12-14 of ingest.rs). This stage guarantees strict isolation between different communities running on the same relay infrastructure.

5. Rate Limiting and Duplicate Detection

The pipeline queries the buzz_db layer to detect duplicate events, enforce rate-limit windows, and handle time-to-live (TTL) restrictions such as Huddle expiration (lines 70-74). These checks prevent spam and ensure stale data does not propagate through the system.

6. Persistence and Fan-Out Dispatch

After successful validation, dispatch_persistent_event (located in crates/buzz-relay/src/handlers/event.rs) writes the event to the database, updates counters for threads and reactions, and broadcasts the event to all subscribed clients. This stage transforms the validated event into durable state and real-time notifications.

7. Command Execution

For events representing privileged commands (such as KIND_AGENT_TURN_METRIC), the pipeline hands off to command_executor.rs after ingestion. This separation ensures that administrative actions execute only after passing through the same rigorous validation as standard events.

Practical Examples: Submitting Events Through the Pipeline

The following examples demonstrate how different interfaces utilize the same underlying pipeline.

Publish via CLI:

buzz events publish --kind 1 --content "Hello from Buzz!" \
    --tags '["p", "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef"]'

Submit via HTTP:

curl -X POST "$BUZZ_RELAY_URL/events" \
  -H "Authorization: Nostr <base64-signature>" \
  -H "Content-Type: application/json" \
  -d '{
        "id":"...", "pubkey":"...", "created_at":1700000000,
        "kind":1, "content":"Hello from HTTP",
        "tags":[], "sig":"..."
      }'

Trigger a command event:

buzz events publish --kind 40090 --content "" \
    --tags '[["e", "some-event-id"], ["p", "$MY_PUBKEY"]]'

Core Source Files and Architecture

The event pipeline spans several critical crates within the block/buzz repository:

• crates/buzz-relay/src/handlers/ingest.rs – Contains the ingest_event entry point, signature verification, and kind-specific validation logic.
• crates/buzz-relay/src/handlers/event.rs – Implements dispatch_persistent_event for database persistence and client fan-out.
• crates/buzz-relay/src/handlers/command_executor.rs – Executes privileged commands after pipeline validation.
• crates/buzz-core/src/kind.rs – Central registry of Nostr kind integers recognized by the pipeline.
• crates/buzz-auth/src/scope.rs – Defines community scoping rules enforced during ingestion.
• crates/buzz-db/src/lib.rs – Database interface for duplicate detection and rate limiting.

Summary

• The event pipeline in Buzz provides a single, transport-neutral entry point for all Nostr events via ingest_event in crates/buzz-relay/src/handlers/ingest.rs.
• Cryptographic verification via buzz_core::verification::verify_event serves as the mandatory first step.
• Kind-specific validation enforces schema compliance through dedicated helpers like validate_huddle_lifecycle_event.
• Community isolation is guaranteed by buzz_auth::Scope and buzz_core::tenant::TenantContext.
• The buzz_db layer prevents duplicates and enforces rate limits before persistence.
• Validated events are stored and broadcast via dispatch_persistent_event in crates/buzz-relay/src/handlers/event.rs.
• Command events receive additional processing through command_executor.rs after standard validation.

Frequently Asked Questions

What makes the Buzz event pipeline transport-neutral?

The pipeline achieves transport neutrality by routing both WebSocket "EVENT" messages and HTTP POST /events requests through the identical ingest_event function. This unified entry point ensures that validation logic, rate limiting, and persistence semantics remain consistent regardless of how the client connects.

How does Buzz add support for new Nostr event kinds?

Developers add new event kinds by registering the kind constant in buzz_core::kind and implementing a corresponding validation branch in the match statement within crates/buzz-relay/src/handlers/ingest.rs. This modular approach keeps kind-specific rules isolated and testable.

What prevents duplicate events from being processed?

During the rate-limiting stage, the pipeline queries the buzz_db layer to check for existing event IDs. If a duplicate is detected, processing halts before the persistence stage, preventing database bloat and redundant fan-out to subscribers.

Where does command execution fit in the pipeline lifecycle?

Command execution occurs after the standard ingest pipeline completes successfully. Events recognized as commands (such as those with KIND_AGENT_TURN_METRIC) are handed off to command_executor.rs only after passing signature verification, kind validation, and community scoping checks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}