Skip to content

[DEV-1902] Add opt-in rich subscription liveness - #424

Merged
Inok merged 1 commit into
masterfrom
pavel/dev-1902-subscription-fellbehind
Oct 8, 2026
Merged

Inok merged 1 commit into
masterfrom
pavel/dev-1902-subscription-fellbehind

Conversation

@Inok

@Inok Inok commented Oct 5, 2026 •

Copy link
Copy Markdown
Member

Opt-in richer liveness for subscriptions, built on the FellBehind message that KurrentDB 26.2.2+ sends to clients declaring read compatibility level 2 (kurrent-io/KurrentDB#5750).

Changes

  • Setting: KurrentDBClientSettings.EnableRichSubscriptionLiveness, default false. When on, subscriptions declare level 2.
  • Messages: with the setting on, subscription.Messages yields StreamCaughtUp / StreamFellBehind (Timestamp, StreamPosition) or AllStreamCaughtUp / AllStreamFellBehind (Timestamp, Position). They derive from StreamMessage.CaughtUp / FellBehind, so existing matches still work.
  • Per-subscription check: await subscription.Features gives StreamSubscriptionFeatures.RichLiveness: the setting is on and the node the subscription connected to reports 26.2.2 or later.
  • Settings copy: client.GetSettings() and KurrentDBClientSettings.Clone().
  • ServerCapabilities gains a SupportsSubscriptionFellBehind constructor parameter.

Compatibility

With the setting off, requests and messages are identical to before.

The ServerCapabilities constructor changes, as it did in 1.1.0 and 1.4.0: code that constructs that record needs recompiling.

Tests

  • Any server: works with the setting on and off; default request, CaughtUp type and Features are pinned.
  • 24.10+: no FellBehind at default settings.
  • 25.1+: CaughtUp carries timestamp and checkpoint with the setting on.
  • 26.2.2+: FellBehind then CaughtUp, with timestamp and checkpoint.

No user docs yet.

🤖 Generated with Claude Code

@linear-code

linear-code Bot commented Oct 5, 2026

Copy link
Copy Markdown

DEV-1902

@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Allow clients to opt in to subscription FellBehind messages

✨ Enhancement 🧪 Tests 🕐 20-40 Minutes

Grey Divider

AI Description

• Add a validated read-compatibility setting, defaulting to existing behavior and configurable
 through connection strings.
• Send the selected level on reads and subscriptions; expose server timestamps and checkpoints when
 opted in.
• Test legacy behavior and FellBehind transitions for stream and $all subscriptions.
Diagram

graph TD
  Conn["Connection string"] --> Settings["Client settings"] --> Requests["Read requests"] --> Server["KurrentDB server"] --> Pump["Subscription pump"] --> Choice{"Level 2?"}
  Choice -->|No| Legacy["Singleton CaughtUp"]
  Choice -->|Yes| Rich["Checkpoint messages"]
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Per-subscription opt-in
  • ➕ Allows different subscriptions on one client to request different compatibility levels.
  • ➖ Expands subscription APIs and leaves read compatibility configured separately.

Recommendation: Use the client-wide setting as proposed: it gives reads and subscriptions one consistent compatibility declaration while keeping level 2 explicitly opt-in. Per-subscription control would add API complexity without a demonstrated need.

Files changed (11) +289 / -17

Enhancement (6) +102 / -7
KurrentDBClientSettings.ConnectionString.csParse and validate readCompatibility +10/-0

Parse and validate readCompatibility

• Recognizes the integer connection-string key and accepts only compatibility levels 1 and 2. Invalid values produce an InvalidSettingException.

src/KurrentDB.Client/Core/KurrentDBClientSettings.ConnectionString.cs

KurrentDBClientSettings.csExpose a validated compatibility setting +14/-0

Expose a validated compatibility setting

• Adds ReadCompatibility with a default of StreamPositions. Its setter rejects unsupported enum values.

src/KurrentDB.Client/Core/KurrentDBClientSettings.cs

ReadCompatibilityLevel.csDefine supported read compatibility levels +20/-0

Define supported read compatibility levels

• Introduces public levels for stream-position behavior and opt-in subscription FellBehind behavior.

src/KurrentDB.Client/Core/ReadCompatibilityLevel.cs

KurrentDBClient.Read.csDeclare configured compatibility on reads +2/-2

Declare configured compatibility on reads

• Replaces the hard-coded compatibility level in stream and $all read requests with the configured level.

src/KurrentDB.Client/Streams/KurrentDBClient.Read.cs

KurrentDBClient.Subscriptions.csOpt subscriptions in and map lifecycle metadata +16/-4

Opt subscriptions in and map lifecycle metadata

• Adds the configured level to stream and $all subscription requests. The message pump retains the data-less CaughtUp singleton below level 2 and maps server timestamps and optional checkpoints into CaughtUp and FellBehind messages.

src/KurrentDB.Client/Streams/KurrentDBClient.Subscriptions.cs

StreamMessage.csExpose subscription lifecycle checkpoints +40/-1

Expose subscription lifecycle checkpoints

• Adds nullable UTC timestamps, stream revisions, and $all positions to CaughtUp and FellBehind records. The CaughtUp singleton remains available for legacy handling.

src/KurrentDB.Client/Streams/StreamMessage.cs

Tests (4) +175 / -6
KurrentDBPermanentFixture.csPreserve compatibility in permanent fixture settings +2/-1

Preserve compatibility in permanent fixture settings

• Copies ReadCompatibility when constructing the permanent fixture's client settings.

test/KurrentDB.Client.Tests.Common/Fixtures/KurrentDBPermanentFixture.cs

KurrentDBTemporaryFixture.csPreserve compatibility in temporary fixture settings +2/-1

Preserve compatibility in temporary fixture settings

• Copies ReadCompatibility when constructing the temporary fixture's client settings.

test/KurrentDB.Client.Tests.Common/Fixtures/KurrentDBTemporaryFixture.cs

ConnectionStringTests.csTest compatibility parsing and validation +30/-4

Test compatibility parsing and validation

• Covers defaults, accepted levels, case-insensitive keys, invalid values, and setter validation. Adds the setting to connection-string round-trip comparisons.

test/KurrentDB.Client.Tests/ConnectionStringTests.cs

SubscriptionFellBehindTests.csTest FellBehind opt-in for stream and $all +141/-0

Test FellBehind opt-in for stream and $all

• Integration tests force subscriptions to fall behind and verify default clients retain data-less CaughtUp messages without FellBehind. Level-2 tests check lifecycle ordering, UTC timestamps, and checkpoints against the last delivered event; they require a server with FellBehind support.

test/KurrentDB.Client.Tests/Streams/Subscriptions/SubscriptionFellBehindTests.cs

Documentation (1) +12 / -4
streams.protoClarify compatibility and checkpoint semantics +12/-4

Clarify compatibility and checkpoint semantics

• Documents the protocol levels and when lifecycle-message checkpoints may be absent. No protocol fields change.

src/KurrentDB.Client/Core/proto/kurrentdb/protocol/v1/streams.proto

@qodo-code-review

qodo-code-review Bot commented Oct 5, 2026 •

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Grey Divider


Remediation recommended

1. Active subscriptions can lose checkpoints ✓ Resolved
Description
PumpMessages checks the mutable _settings.ReadCompatibility when converting CaughtUp, rather
than the compatibility level captured in the subscription's ReadReq. If settings change after a
level-2 subscription starts, later CaughtUp messages can be replaced with the data-less singleton
even though the server sent a checkpoint.
Code

src/KurrentDB.Client/Streams/KurrentDBClient.Subscriptions.cs[229]

+                                    CaughtUp when _settings.ReadCompatibility < ReadCompatibilityLevel.SubscriptionFellBehind => StreamMessage.CaughtUp.Instance,
Evidence
The request sets ControlOption.Compatibility when SubscribeToStream is called, while the result
stores the same settings object and the asynchronous pump reads its current value for each response.
The settings property is publicly settable, so those values can diverge.

src/KurrentDB.Client/Streams/KurrentDBClient.Subscriptions.cs[114-125]
src/KurrentDB.Client/Streams/KurrentDBClient.Subscriptions.cs[183-193]
src/KurrentDB.Client/Streams/KurrentDBClient.Subscriptions.cs[228-234]
src/KurrentDB.Client/Core/KurrentDBClientSettings.cs[66-73]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Subscription message conversion reads mutable settings after the request has captured its compatibility level, so changing settings during a subscription can discard a server-supplied checkpoint.
## Fix Focus Areas
- src/KurrentDB.Client/Streams/KurrentDBClient.Subscriptions.cs[118-123]
- src/KurrentDB.Client/Streams/KurrentDBClient.Subscriptions.cs[183-193]
- src/KurrentDB.Client/Streams/KurrentDBClient.Subscriptions.cs[228-234]
## Recommended Fix
Capture the compatibility level from the subscription request when it is constructed and use that fixed value to select the CaughtUp mapping throughout the subscription.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


2. Timed-out tests leave subscriptions open ✓ Resolved
Description
WithTimeout(60_000) stops awaiting FallBehind but does not cancel that task. If the test stalls
in MoveNextAsync, FallBehind remains blocked before its await using disposals, leaving the
subscription's server read active while subsequent tests run.
Code

test/KurrentDB.Client.Tests/Streams/Subscriptions/SubscriptionFellBehindTests.cs[20]

+		var messages = await FallBehind(Fixture.Streams, subscribeToAll).WithTimeout(60_000);
Evidence
Both new tests use the same non-canceling timeout. The helper awaits the enumerator inside `await
using` scopes, and enumerator cancellation is the path that cancels the underlying subscription
read.

test/KurrentDB.Client.Tests/Streams/Subscriptions/SubscriptionFellBehindTests.cs[17-20]
test/KurrentDB.Client.Tests/Streams/Subscriptions/SubscriptionFellBehindTests.cs[33-38]
test/KurrentDB.Client.Tests.Common/Extensions/TaskExtensions.cs[8-27]
test/KurrentDB.Client.Tests/Streams/Subscriptions/SubscriptionFellBehindTests.cs[101-125]
src/KurrentDB.Client/Streams/KurrentDBClient.Subscriptions.cs[150-174]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Both FellBehind tests time out their await without canceling the underlying helper, so a stalled test retains its subscription and server read.
## Fix Focus Areas
- test/KurrentDB.Client.Tests/Streams/Subscriptions/SubscriptionFellBehindTests.cs[20-38]
- test/KurrentDB.Client.Tests/Streams/Subscriptions/SubscriptionFellBehindTests.cs[93-125]
## Recommended Fix
Use a timeout cancellation token and pass it into FallBehind, the subscription, and its message enumerator. Ensure cancellation exits the helper and executes its async disposals before the test finishes.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

Context sources
✅ Cross-repo context — repo relationships
  Explored: repo: kurrent-io/KurrentDB (branch: master, sha: 11351956) — View relationship
  Explored: repo: kurrent-io/kcap-server (sha: b2344077) — View relationship
Review mode: Auto: ⚖️ Balanced: Behavioral protocol, API, subscription, and compatibility changes require careful review.

Grey Divider

Tip of the day
💡 Did you know, you can keep summaries lean with Findings visible per group, which tucks the rest behind a View link

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

@Inok
Inok force-pushed the pavel/dev-1902-subscription-fellbehind branch 10 times, most recently from f3718bf to 3c5de6c Compare October 7, 2026 18:45
@Inok Inok changed the title [DEV-1902] Let clients opt in to subscription FellBehind [DEV-1902] Add opt-in rich subscription liveness Oct 7, 2026
@Inok
Inok requested a review from w1am October 7, 2026 19:01
KurrentDB 26.2.2 and later send FellBehind to subscriptions of clients
that declare read compatibility level 2.

KurrentDBClientSettings.EnableRichSubscriptionLiveness makes
subscriptions declare that level. They then yield StreamCaughtUp /
StreamFellBehind or AllStreamCaughtUp / AllStreamFellBehind, with the
timestamp and checkpoint sent by the server. These derive from
StreamMessage.CaughtUp / FellBehind, so code that matches the base
messages keeps matching.

StreamSubscriptionResult.Features tells whether a subscription has the
feature: it is enabled and the node the subscription connected to
supports it, which is detected from the version the node reports.

KurrentDBClientBase.GetSettings() returns a copy of the client's
settings, made by the new KurrentDBClientSettings.Clone().

Without the setting nothing changes: requests are the same, and
CaughtUp is the same data-less instance.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Inok
Inok force-pushed the pavel/dev-1902-subscription-fellbehind branch from 3c5de6c to 4a81d9f Compare October 7, 2026 19:05
@Inok
Inok requested a review from timothycoleman October 8, 2026 08:36
@Inok
Inok merged commit 5f2e2e6 into master Oct 8, 2026
76 checks passed
@Inok
Inok deleted the pavel/dev-1902-subscription-fellbehind branch October 8, 2026 12:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants