Skip to content

Subscription improvements: backpressure, contiguity, multi-namespace #14

@tac0turtle

Description

@tac0turtle

Summary

Improve on celestia-node's subscription model with configurable backpressure, gap-free delivery guarantees, and multi-namespace support.

Parent: #2

Problems in celestia-node

  1. Hardcoded buffer of 16 — slow consumer gets silently disconnected, no warning
  2. No contiguity guarantee — headers can arrive with gaps (known bug celestia-node#3578), breaking consumers that expect sequential delivery
  3. One subscription per namespace — each independently fetches blobs per header, redundant work when tracking multiple namespaces

Requirements

Configurable backpressure

  • Configurable buffer size per subscription (default: 64)
  • Log warning at 75% capacity
  • Drop subscription at 100% with an error the client can observe (not silent)
  • Expose apex_subscription_drops metric (Observability: metrics, logging, and tracing #7)

Contiguous delivery

  • Guarantee strict monotonic height ordering: if height N is delivered, height N+1 is next
  • Sync engine already handles gap detection and backfill (Sync engine: backfill, streaming, and gap recovery #11) — subscriptions must wait for gaps to be filled before delivering
  • If a gap cannot be filled within a timeout, deliver an explicit gap notification rather than silently skipping

Multi-namespace subscribe

  • Single subscription call that covers all tracked namespaces
  • Internal fan-out: one "new block" event from the sync engine triggers delivery to all matching subscriptions
  • No redundant data fetching — blobs for all namespaces are already fetched by the sync engine
  • Per-namespace filtering on the subscription side

References

  • celestia-node blob/service.go — current Subscribe implementation
  • celestia-node#3578 — header subscription gap bug
  • celestia-node#3390 — planned BlobModule v1 rewrite

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions