From c3583737267685327cdf9cf518416535fa8d0299 Mon Sep 17 00:00:00 2001 From: Matthew Date: Wed, 4 Nov 2026 10:41:53 -0500 Subject: [PATCH 1/2] blockstream: make subscription channel size configurable The block stream server closed a subscription once 200 blocks were queued for it. A reader catching up after a stall can push more than that in one burst, which drops every connected relayer at the same time. Add ServerOptionWithSubscriptionChannelSize, keeping 200 as the default. Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 1 + blockstream/server.go | 32 +++++++++++++++++++++++++------- blockstream/server_test.go | 30 ++++++++++++++++++++++++++++++ 3 files changed, 56 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b3a801..c624b5f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- `blockstream.ServerOptionWithSubscriptionChannelSize` (default `blockstream.DefaultSubscriptionChannelSize`, `200`): how many blocks a block stream subscriber (e.g. a relayer connected to a reader) can lag behind before its subscription is closed. It was hard-coded to `200`, which a reader catching up after a stall can exceed in one burst, dropping every relayer at once. - `ForkableHub.WithoutPartials` and `stream.WithoutPartialBlocks`: stream from a hub fed with partial blocks without getting them, the last partial of each block arriving as the complete block, as for a relayer client that does not ask for partials. Lets an app that does not handle partial blocks share its hub with one that does. - `hub.SubscriptionCatchUpTimeout` (default `30s`): a hub subscription is now closed with `hub.ErrSubscriptionBehind` when its consumer has not emptied its waiting blocks for that long, which catches a consumer that is stuck or slower than the chain. A consumer draining a burst within the timeout is not affected. `ErrSubscriptionBehind` matches `ErrSubscriptionChannelFull` with `errors.Is`, so callers that reconnect on one reconnect on both. - `hub.SubscriptionMaxBufferedBlocks` (default `10000`): how many blocks a hub subscription can have waiting before it is closed with `ErrSubscriptionChannelFull`. Both are meant to be set once at process startup. diff --git a/blockstream/server.go b/blockstream/server.go index 7c914de..0c8eb62 100644 --- a/blockstream/server.go +++ b/blockstream/server.go @@ -32,6 +32,10 @@ import ( "google.golang.org/grpc/status" ) +// DefaultSubscriptionChannelSize is the number of blocks a subscriber can lag +// behind before its subscription is closed, on top of the initial burst. +const DefaultSubscriptionChannelSize = 200 + type ServerOption func(s *Server) func ServerOptionWithLogger(logger *zap.Logger) ServerOption { @@ -47,12 +51,25 @@ func ServerOptionWithBuffer(size int) ServerOption { } } +// ServerOptionWithSubscriptionChannelSize sets how many blocks a subscriber can +// lag behind before its subscription is closed. A slow subscriber, or a burst of +// blocks when the reader catches up, fills this channel. Values below 1 are +// ignored and DefaultSubscriptionChannelSize is used. +func ServerOptionWithSubscriptionChannelSize(size int) ServerOption { + return func(s *Server) { + if size > 0 { + s.subscriptionChanSize = size + } + } +} + type Server struct { - headInfo *headInfo - buffer *bstream.Buffer - bufferSize int - subscriptions []*subscription - grpcServer dgrpcserver.Server + headInfo *headInfo + buffer *bstream.Buffer + bufferSize int + subscriptionChanSize int + subscriptions []*subscription + grpcServer dgrpcserver.Server lock sync.RWMutex @@ -82,7 +99,8 @@ func NewServer(server dgrpcserver.Server, opts ...ServerOption) *Server { // Moreover, management methods like `Close` func NewUnmanagedServer(opts ...ServerOption) *Server { s := &Server{ - logger: zlog, + logger: zlog, + subscriptionChanSize: DefaultSubscriptionChannelSize, } for _, opt := range opts { @@ -193,7 +211,7 @@ func (s *Server) subscribe(requestedBurst int, subscriber string) *subscription s.lock.Lock() defer s.lock.Unlock() - chanSize := 200 + chanSize := s.subscriptionChanSize var blocks []*pbbstream.Block if s.buffer != nil { diff --git a/blockstream/server_test.go b/blockstream/server_test.go index 3f66e4f..6eadfb3 100644 --- a/blockstream/server_test.go +++ b/blockstream/server_test.go @@ -15,6 +15,7 @@ package blockstream import ( + "fmt" "testing" "github.com/streamingfast/bstream" @@ -37,3 +38,32 @@ func TestBlockServerSubscribe(t *testing.T) { s.unsubscribe(sub) require.Len(t, s.subscriptions, 0) } + +func TestBlockServerSubscriptionChannelSize(t *testing.T) { + s := NewUnmanagedServer() + sub := s.subscribe(0, "default") + require.Equal(t, DefaultSubscriptionChannelSize, cap(sub.incomingBlock)) + + s = NewUnmanagedServer(ServerOptionWithSubscriptionChannelSize(0)) + sub = s.subscribe(0, "ignored") + require.Equal(t, DefaultSubscriptionChannelSize, cap(sub.incomingBlock)) + + s = NewBufferedServer(testCreateGRPCServer(), 2, ServerOptionWithSubscriptionChannelSize(5)) + s.PushBlock(bstream.TestBlock("00000002a", "00000001a")) + s.PushBlock(bstream.TestBlock("00000003a", "00000002a")) + sub = s.subscribe(2, "burst") + require.Equal(t, 7, cap(sub.incomingBlock)) +} + +func TestBlockServerSubscriptionClosedWhenFull(t *testing.T) { + s := NewUnmanagedServer(ServerOptionWithSubscriptionChannelSize(3)) + sub := s.subscribe(0, "slow") + + for i := 0; i < 3; i++ { + require.NoError(t, s.PushBlock(bstream.TestBlockWithNumbers(fmt.Sprintf("%08xa", i+2), fmt.Sprintf("%08xa", i+1), uint64(i+2), 0))) + } + require.False(t, sub.closed, "subscription should hold up to its capacity") + + require.NoError(t, s.PushBlock(bstream.TestBlockWithNumbers("00000005a", "00000004a", 5, 0))) + require.True(t, sub.closed, "subscription should close once over capacity") +} From 74411f1e62b5686916f14b31826f9430bd7173ff Mon Sep 17 00:00:00 2001 From: Matthew Date: Wed, 4 Nov 2026 10:45:56 -0500 Subject: [PATCH 2/2] blockstream: make subscription channel size configurable The block stream server closed a subscription once 200 blocks were queued for it. A reader catching up after a stall can push more than that in one burst, which drops every connected relayer at the same time. Add ServerOptionWithSubscriptionChannelSize, keeping 200 as the default. Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c624b5f..588dcad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- `blockstream.ServerOptionWithSubscriptionChannelSize` (default `blockstream.DefaultSubscriptionChannelSize`, `200`): how many blocks a block stream subscriber (e.g. a relayer connected to a reader) can lag behind before its subscription is closed. It was hard-coded to `200`, which a reader catching up after a stall can exceed in one burst, dropping every relayer at once. - `blockstream.ServerOptionWithSubscriptionChannelSize` (default `blockstream.DefaultSubscriptionChannelSize`, `200`): how many blocks a block stream subscriber (e.g. a relayer connected to a reader) can lag behind before its subscription is closed. It was hard-coded to `200`, which a reader catching up after a stall can exceed in one burst, dropping every relayer at once. - `ForkableHub.WithoutPartials` and `stream.WithoutPartialBlocks`: stream from a hub fed with partial blocks without getting them, the last partial of each block arriving as the complete block, as for a relayer client that does not ask for partials. Lets an app that does not handle partial blocks share its hub with one that does. - `hub.SubscriptionCatchUpTimeout` (default `30s`): a hub subscription is now closed with `hub.ErrSubscriptionBehind` when its consumer has not emptied its waiting blocks for that long, which catches a consumer that is stuck or slower than the chain. A consumer draining a burst within the timeout is not affected. `ErrSubscriptionBehind` matches `ErrSubscriptionChannelFull` with `errors.Is`, so callers that reconnect on one reconnect on both.