Skip to content

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

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

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions