modules/measurement-rate-control/hyper-p2p-bucket-rate-limit/docs/architecture.md

Architecture: hyper-p2p-bucket-rate-limit

Category: Measurement & rate control

flowchart LR
  App[Application] --> Mod[HyperP2PBucketRateLimit]
  Mod --> Mux[Protomux bucket-rate-limit/v1]
  Mux --> Swarm[Hyperswarm]

Sequence (P2P)

sequenceDiagram
  participant App
  participant Mod as Module
  participant SW as Hyperswarm
  participant Peer
  App->>Mod: ready(topic)
  Mod->>SW: join(topic)
  SW->>Peer: connection
  Mod->>Peer: gossip / Protomux
  Peer-->>Mod: onmessage
  Mod-->>App: emit(event)

Wire messages

type	fields	direction	behavior
bucket	peerId, tokens, updatedAt	gossip	Handled in onmessage / gossipSend
configure	buckets, burst, rate, type	gossip	Handled in onmessage / gossipSend
sync	buckets, type	gossip	Handled in onmessage / gossipSend

State model

• In-memory Map / Set structures for hot path
• Optional Hyperbee/Hypercore persistence when storageDir or memoryOnly is configured
• close() tears down swarm, timers, and clears ephemeral state

Composition

Composes with: hyper-p2p-congestion-signal, hyper-p2p-bandwidth-broker.