fix(stream): align XINFO GROUPS entries-read and lag with Redis by wengsht · Pull Request #3581 · apache/kvrocks

wengsht · 2026-08-09T17:29:16Z

Follow-up to #3578, split out per review (SRP + clean cherry-pick).

XINFO GROUPS can diverge from Redis in two related ways when a group's entries-read is out of range or its cursor is behind the stream head. Fixed here in one focused commit each.

1. Clamp `entries-read` to `entries-added` on write

XGROUP CREATE/SETID stored the ENTRIESREAD value verbatim, even past entries-added. XINFO GROUPS served it back, and lag = entries_added - entries_read (unsigned) underflowed to ~2^64, overflowing the signed-64 integer clients decode the RESP reply as. Redis clamps on write (t_stream.c L3663-3665); mirrored in Stream::CreateGroup/GroupSetId.

2. Report `lag` as stream length when the group is behind the first entry

Even with an in-range entries-read, if the group's last-delivered-id is behind the first live entry, computing lag from entries_read is wrong. Redis's streamReplyWithCGLag reports lag = length in that case (and 0 for an emptied stream); CheckLagValid was missing both branches. Added them.

Result: matches Redis exactly

Same repro against reference Redis 8.10 and this patch:

127.0.0.1:PORT> XADD repro-lag 1-0 f v ; XADD repro-lag 2-0 f v ; XADD repro-lag 3-0 f v
127.0.0.1:PORT> XGROUP CREATE repro-lag grp 0 ENTRIESREAD 1000000
OK
127.0.0.1:PORT> XINFO GROUPS repro-lag
    ...
    9) "entries-read"
   10) (integer) 3
   11) "lag"
   12) (integer) 3

Both report entries-read = 3, lag = 3. Before this patch kvrocks returned entries-read = 1000000.

Test

XGROUP CREATE/SETID with ENTRIESREAD beyond entries-added, asserting XINFO GROUPS stays decodable and reports entries-read = entries-added and lag = length. The unit/type/stream gocase suite passes.

AI assistance: diagnosis and drafting were done with AI help; I've reviewed the changes and tests and understand the behavior.

An ENTRIESREAD larger than the stream's entries-added was stored verbatim and served back by XINFO GROUPS, and the group's lag (entries_added - entries_read, an unsigned field) underflowed to a near-2^64 value that overflows the signed 64-bit integer clients decode the RESP reply as, breaking XINFO GROUPS. Redis clamps entries-read down to entries-added on write in XGROUP CREATE and SETID (t_stream.c). Mirror that so the stored counter can never exceed entries-added: the reported entries-read now matches Redis and lag can no longer underflow.

github-actions · 2026-08-09T17:29:28Z

Hi @wengsht,

Thank you for your pull request. Please review our Contributing Guide.

Please make sure you understand your changes and explain your reasoning in this pull request. Low-quality pull requests may be closed.

…e stream head lag is entries_added - entries_read on an unsigned field. When the group's last-delivered-id is behind the first live entry (a group created at 0, or one whose entries_read was set inconsistently via XGROUP SETID/ENTRIESREAD), trusting entries_read yields a wrong or underflowing lag. Mirror Redis streamReplyWithCGLag: when the cursor and the max tombstone are both behind the first entry, report lag = current stream length; and report lag = 0 for an emptied stream. XINFO GROUPS lag now matches Redis exactly.

wengsht · 2026-08-09T18:08:12Z

@LindaSummer can you look at this one when you get a chance?

` # kvrocks with PR #3581 (:6666)
127.0.0.1:6666> DEL repro-lag
(integer) 1
127.0.0.1:6666> XADD repro-lag 1-0 f v
"1-0"
127.0.0.1:6666> XADD repro-lag 2-0 f v
"2-0"
127.0.0.1:6666> XADD repro-lag 3-0 f v
"3-0"
127.0.0.1:6666> XGROUP CREATE repro-lag grp 0 ENTRIESREAD 1000000
OK
127.0.0.1:6666> XINFO GROUPS repro-lag

1. "name"
2. "grp"
3. "consumers"
4. (integer) 0
5. "pending"
6. (integer) 0
7. "last-delivered-id"
8. "0-0"
9. "entries-read"
  10) (integer) 3
  11) "lag"
  12) (integer) 3`

LindaSummer

Hi @wengsht ,

Thanks for your effort.

Left some comments, and we'd better fix the linter issue with ./x.py format before committing.

LindaSummer · 2026-08-10T07:55:11Z

+// clients decode the RESP reply as, breaking XINFO GROUPS.
+static int64_t clampEntriesRead(int64_t entries_read, uint64_t entries_added) {
+  if (entries_read != -1 && static_cast<uint64_t>(entries_read) > entries_added) {
+    return static_cast<int64_t>(entries_added);


Do we have a risk of overflow here?

LindaSummer · 2026-08-10T07:57:54Z

  if (stream_metadata.entries_added == 0) {
    group_metadata.lag = 0;
    valid = true;
+  } else if (stream_metadata.size == 0) {


Could this be merged into the above branch?

LindaSummer · 2026-08-10T08:04:18Z

+    // All entries deleted; the stream is empty.
+    group_metadata.lag = 0;
+    valid = true;
+  } else if (group_metadata.last_delivered_id < stream_metadata.first_entry_id &&


Do we have a case to cover this branch?

Copilot

Pull request overview

Aligns XINFO GROUPS entries-read and lag reporting with Redis.

Changes:

Clamps ENTRIESREAD to entries-added.
Handles empty streams and cursors behind the stream head.
Adds integration coverage for CREATE and SETID clamping.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
`src/types/redis_stream.cc`	Updates entries-read clamping and lag calculation.
`tests/gocase/unit/type/stream/stream_test.go`	Tests CREATE/SETID clamping behavior.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+  } else if (stream_metadata.size == 0) {
+    // All entries deleted; the stream is empty.
+    group_metadata.lag = 0;
+    valid = true;


+static int64_t clampEntriesRead(int64_t entries_read, uint64_t entries_added) {
+  if (entries_read != -1 && static_cast<uint64_t>(entries_read) > entries_added) {
+    return static_cast<int64_t>(entries_added);
+  }
+  return entries_read;


wengsht changed the title ~~fix(stream): clamp XGROUP CREATE/SETID entries-read to entries-added~~ fix(stream): align XINFO GROUPS entries-read and lag with Redis Aug 9, 2026

wengsht mentioned this pull request Aug 9, 2026

fix(stream): decrement pending_number when XAUTOCLAIM removes deleted PEL entries #3578

Open

LindaSummer reviewed Aug 10, 2026

View reviewed changes

LindaSummer requested a balanced review from Copilot August 10, 2026 08:06

Copilot started reviewing on behalf of LindaSummer August 10, 2026 08:06 View session

Copilot AI reviewed Aug 10, 2026

View reviewed changes

Navigation Menu

Uh oh!

fix(stream): align XINFO GROUPS entries-read and lag with Redis - #3581

fix(stream): align XINFO GROUPS entries-read and lag with Redis#3581
wengsht wants to merge 2 commits into
apache:unstablefrom
wengsht:fix-xgroup-entries-read-clamp

wengsht commented Aug 9, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 9, 2026

Uh oh!

wengsht commented Aug 9, 2026

Uh oh!

LindaSummer left a comment

Uh oh!

LindaSummer Aug 10, 2026

Uh oh!

LindaSummer Aug 10, 2026

Uh oh!

LindaSummer Aug 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

wengsht commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1. Clamp entries-read to entries-added on write

2. Report lag as stream length when the group is behind the first entry

Result: matches Redis exactly

Test

Uh oh!

github-actions Bot commented Aug 9, 2026

Uh oh!

wengsht commented Aug 9, 2026

Uh oh!

LindaSummer left a comment

Choose a reason for hiding this comment

Uh oh!

LindaSummer Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

LindaSummer Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

LindaSummer Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

wengsht commented Aug 9, 2026 •

edited

Loading

1. Clamp `entries-read` to `entries-added` on write

2. Report `lag` as stream length when the group is behind the first entry