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

> Discover the Buzz event pipeline, a transport-neutral ingest system. Learn how it unifies Nostr event processing with verification, validation, and scoping before persistence and broadcasting.

- Repository: [Block Open Source/buzz](https://github.com/block/buzz)
- Tags: internals
- Published: 2026-08-28

---

**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`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/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:

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

```

Submit via HTTP:

```bash
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:

```bash
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`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/crates/buzz-relay/src/handlers/command_executor.rs)** – Executes privileged commands after pipeline validation.
- **[`crates/buzz-core/src/kind.rs`](https://github.com/block/buzz/blob/main/crates/buzz-core/src/kind.rs)** – Central registry of Nostr kind integers recognized by the pipeline.
- **[`crates/buzz-auth/src/scope.rs`](https://github.com/block/buzz/blob/main/crates/buzz-auth/src/scope.rs)** – Defines community scoping rules enforced during ingestion.
- **[`crates/buzz-db/src/lib.rs`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/crates/buzz-relay/src/handlers/event.rs).
- Command events receive additional processing through [`command_executor.rs`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/command_executor.rs) only after passing signature verification, kind validation, and community scoping checks.