DOC-6968 Complete cmds_generic, and make C examples able to fail

[andy-stark-redis]

DOC-6968 — the four SCAN steps for seven clients

Adds scan1–scan4 to hiredis, go-redis, jedis, lettuce-async, lettuce-reactive, ioredis and predis in the cmds_generic set. 27 implementations, 822 lines.

Omission warnings: 63 → 36. content/commands/scan.md is back to 12 client tabs on scan1, scan2 and scan4 (from 5), and 12 on scan3 where PHP is legitimately absent — see below.

@dwdougherty this is the "next PR" from #3811: the warnings that triggered your OCD are now down by 43%, and scan.md was the page paying the visible price.

18 is not the number of matching keys

*11* matches 19 of key:1…key:1000 — I counted them. The reference gets 18 because its COUNT 1000 call continues from the cursor left by four preceding default-COUNT iterations, one of which has already yielded a match. My first ioredis attempt restarted at cursor 0, got 19, and failed its own assertion, which is how this surfaced.

Every tab now mirrors the reference's continuation semantics. One nuance for the record: on Redis 8.8 the observed split is 0, 0, 0, 1, 18, whereas the page's CLI transcript shows the match landing on the first iteration. Same total, different distribution — the split depends on iteration order, which matters for the next point.

Why Go's scan2 prints less than its siblings

A Go Example function only runs under go test if it has an // Output: block, and that block must match stdout exactly. Encoding the per-iteration counts (0,0,0,1) would make the Go test fail whenever SCAN's iteration order shifted — a red build for a reason unrelated to the docs.

So Go runs the four iterations but prints only the final 18. Same headline number, less visible narrative, no new fragility. The alternative (match the siblings exactly, accept Go as the canary that breaks first) was considered and rejected.

predis cannot express scan3, so PHP is absent from it

SCAN.php::prepareOptions in predis 3.5.1 emits only MATCH and COUNT. TYPE is silently dropped — probed against a live server:

with TYPE=zset -> geokey, stringkey, zkey
without TYPE   -> geokey, stringkey, zkey

stringkey is a plain string. An idiomatic-looking $r->scan(0, ['TYPE' => 'zset']) returns everything, which is worse than an absent tab, and using executeRaw in a docs example teaches the wrong thing. PHP therefore has scan1, scan2 and scan4 only.

This is the first real use of the behaviour added in #3811: PHP's absence renders as a cleanly omitted tab rather than a 46-line whole-file dump, and the one remaining warning for cmds_generic/scan3 is a truthful record rather than noise.

Verification

All seven PASS against Redis 8.8.0 via build/example-test-harness/run.sh cmds_generic, including hiredis through the portable C runner added earlier in this ticket. Observed output was checked against every >>> comment.

Two pre-existing failures in that sweep are not from this change — verified by re-running both with these changes stashed:

Client	Failure	Cause
nredisstack	CS0246: SkipIfRedisFactAttribute could not be found	the portable C# stub lacks that attribute
rust-async	unresolved import futures_util, AsyncIter is not an iterator	async iteration API drift in the pinned redis-rs

Neither file is touched here. Both deserve their own tickets.

What's left

36 warnings: cmds_generic 18 (del/expire/ttl 5 each, exists 2, scan3 1 for PHP), cmds_hash 12 (C and ioredis), query_vector 4 (deliberately out of scope), cmds_stream 2.

🤖 Generated with Claude Code

---

Note

Low Risk
Changes are limited to documentation examples, test harness behavior, and author guidance—no production services or runtime APIs.

Overview
Finishes cmds_generic doc examples: scan1–scan4 across seven clients, plus del, exists, expire, and ttl where they were missing. Command pages regain full client tabs; predis still omits scan3 because SCAN … TYPE is not supported in the client API.

SCAN scan2 examples use cursor continuation and expect 18 keys for *11* after a high-COUNT pass, matching reference semantics (not a fresh cursor at 0).

hiredis C examples now use a CHECK_REPLY guard (in REMOVE blocks) after every redisCommand, with failed value checks return 1, so the harness can fail on error replies—not only on exit 0. Fixes SET mykey %s for values with spaces (no CLI-style quoting). The pattern is documented in HIREDIS_TEST_PATTERNS.md.

cmds_hash gains hiredis steps and ioredis hash command snippets; cmds_string and landing.c get the same reply checking.

^{Reviewed by Cursor Bugbot for commit 833febc. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

Second commit — del, exists, expire, ttl: cmds_generic is now complete

Adds the remaining 17 steps across hiredis, ioredis, lettuce-async, lettuce-reactive and predis.

Omission warnings site-wide: 36 → 19. commands/del.md, exists.md, expire.md and ttl.md are all back to 12 client tabs. The only cmds_generic warning left is PHP's scan3, which predis cannot express (see above).

Remaining 19: cmds_hash 12, query_vector 4 (out of scope by decision), cmds_stream 2, cmds_generic/scan3 1.

A bug in the C example, and a worse gap behind it

The bug. redisCommand(c, "SET mykey \"Hello World\"") does not work — hiredis splits its format string on whitespace and doesn't honour CLI-style quoting, so that became four tokens and the server replied ERR syntax error. Binding the value as an argument ("SET mykey %s", "Hello World") fixes it, and the expiry sequence then comes out correctly: OK, 1, 10, OK, -1, 0, -1, 1, 10.

The gap that let it through. The harness reported PASS the entire time. C examples' assertions only printf("ASSERTION FAILED") — they never touch the exit code — and hiredis doesn't abort on an error reply. So for C, a green run has only ever meant "the binary exited 0". This failure even left the final TTL at 10 by coincidence, so the value check would have passed anyway. I found it by reading the output.

The 13 assertions in that file now return 1 as well as printing. Proven, not assumed: changing one expected value from 2 to 999 turns the sweep red; restoring it turns it green.

Being explicit about what this does not fix: it would not have caught today's bug. A mid-example error reply still slips through, because nothing checks reply->type == REDIS_REPLY_ERROR. Catching that class needs a guard after each command across every C example — worth doing deliberately rather than bolting on here.

Verification

Every client in cmds_generic passes against Redis 8.8.0 except the two pre-existing, unrelated failures already documented on the first commit (nredisstack's missing SkipIfRedisFact stub; rust-async's futures_util/AsyncIter drift). Neither file is touched by this PR.

Per-client output was checked line by line against every >>> comment, including the expire NX/XX sequence, where XX must be a no-op on a key whose expiry SET has just cleared.

---

Third commit — make C examples able to fail at all

The bug in the previous commit exposed something bigger than the bug: a green harness run has never told you anything about a C example. There's no assertion framework, hiredis returns an error reply rather than failing the call, and it doesn't abort — so an example can send a malformed command, print a wrong value, and exit 0.

This adds a CHECK_REPLY guard after all 62 redisCommand calls across the four C examples, plus the macro behind it — everything inside REMOVE blocks, so published snippets stay plain redisCommand:

reply = redisCommand(c, "SET mykey %s", "Hello World");
// REMOVE_START
CHECK_REPLY(reply);
// REMOVE_END

Proven on the hardest case, not the convenient one

Reintroducing an error reply that gets printed with %lld — which prints 0, never the error text — now fails the sweep:

REDIS ERROR: ERR wrong number of arguments for 'incr' command
  hiredis            FAIL

Restoring the file returns it to PASS.

That case is why I rejected the cheap version. I'd floated scanning hiredis's stdout for ERR in run_hiredis — one line, covers every C example forever. It's the wrong call: it misses the %lld case entirely (the error never reaches stdout), and it would false-positive on any future example that deliberately demonstrates an error reply. The guard has to sit at the call site.

Also

• Two unassigned cleanup DELs in cmds_hash.c could be neither checked nor freed. Now assigned, guarded and freed — both in REMOVE blocks, so the page is unchanged.
• Value assertions now return 1 as well as printing, in the file where that was added earlier in this branch.
• The rule is written into assets/hiredis/HIREDIS_TEST_PATTERNS.md in the tce-examples skill, with the reasoning and the quoting trap, because the guard is only as good as the next author remembering it.

Verification

All four files compile clean under -Wall. hiredis passes cmds_generic, cmds_hash and cmds_string.

landing.c is compile-checked only — the harness reports SKIP (no source) for the landing set, because that file lives at local_examples/client-specific/c/ rather than the conventional local_examples/<set>/<client>/. Its guard is therefore unexercised, which is worth knowing rather than assuming.

[github-actions]

DOC-6968

[github-actions]

🧠 Redis Memory

Found 10 related items from repository history (1 new this commit):

• Commit — DOC-6968 Add the missing incr step to nine cmds_string client examples

  DOC-6968 Add the missing incr step to nine cmds_string client examples

• PR — DOC-6968 Fix two node-redis step names, and add the missing incr step for nine clients

  DOC-6968 — two node-redis step names that never matched their sets

• PR — DOC-6887 Add hash field expiration examples to hash data type page

  What

• PR — DOC-6767 added Go scan/buffer API page

• PR — DOC-6968 Omit a clients-example tab when that client lacks the requested step

  DOC-6968 — omit a clients-example tab when the client lacks the requested step

• Commit — DOC-6968 Add the four SCAN steps to seven cmds_generic client examples

  DOC-6968 Add the four SCAN steps to seven cmds_generic client examples

• PR — Mark SCAN command examples as runnable="false"

  The redis.io/cli sandbox is one shared, per-session-namespaced database (~100k keys), so keyspace SCAN examples cannot reproduce their docum

• Commit — DOC-6968 Add del, exists, expire and ttl to the remaining cmds_generic clients

  DOC-6968 Add del, exists, expire and ttl to the remaining cmds_generic clients

• PR — DOC-6909 Fix pre-existing broken links across the docs

  Part 1 of 4 of a stack that splits DOC-6909 Add link render hook to replace relref (investigation) #3732 into independently reviewable pieces, after @paoloredis noted the single PR was too much to review

• Commit — DOC-6968 Complete cmds_hash, and fix nested REMOVE anchors from the guard commit 🆕

  DOC-6968 Complete cmds_hash, and fix nested REMOVE anchors from the guard commit

Memory updated at 833febc

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 589cc53. Configure here.}

[dwdougherty]

LGTM.

[andy-stark-redis]

Thanks @dwdougherty !