Add a true read-only probe mode for CL.THROTTLE

[REASY]

Motivation

CL.THROTTLE is documented as Dragonfly's native GCRA/leaky-bucket rate-limiting command and returns useful limiter state (limited, limit, remaining, retry-after, reset). In the current implementation, OpThrottle uses mutable access and persists state on the non-limited path, so there does not appear to be a side-effect-free way to ask "would this request be allowed right now?" without updating limiter state or creating state for a missing key. (dragonflydb.io)

Use case

We are building a global rate-limiter service on top of Dragonfly and would like to rely on native CL.THROTTLE for GCRA-style throttling, but we also need probe semantics for:

• dark launches / observe-only mode
• candidate selection across multiple keys before consuming quota
• preflight/debug endpoints that show remaining, retry-after, and reset without mutating state
• safer migration/canary workflows where "would throttle" must not burn quota

Requested behavior

Please add one of the following:

• a new CL.PROBE command with the same arguments and response shape as CL.THROTTLE
• or a READONLY / NOAPPLY mode on CL.THROTTLE

Desired semantics:

• no TAT update
• no TTL refresh
• no key creation for a missing key
• same response shape as CL.THROTTLE
• should work for arbitrary quantity, not only via a special-case workaround

Why this would help

This would make Dragonfly's native throttling much easier to use in higher-level control planes and shared rate-limiter services, where "check" and "consume" are separate operations. It would also make CL.THROTTLE easier to use for observability, dry runs, and staged rollouts.

Backward compatibility

This could be a purely additive feature. Existing CL.THROTTLE behavior would stay unchanged.

[romange]

Interesting suggestion. I am open to explore it but I would like to understand better the use-cases.
btw, you have a workaround, you could replicate the "read-only" logic to a lua script and run it via EVAL_RO.

Could you expand on the following points?

1. how dark launches would use CL.PROBE?
2. what does it mean "should work for arbitrary quantity, not only via a special-case workaround"?
3. candidate selection across multiple keys before consuming quota? (could lead to incorrect selection as you have a window of time where the state will change and you won't know about it)

[REASY]

@romange Thanks, this is helpful.

You're right that EVAL_RO is a workable short-term experiment path. My ask is mainly for a first-class primitive because the workaround means re-implementing the read-only throttle decision in Lua instead of using the native CL.THROTTLE logic directly.

On your questions:

1. Dark launches

By "dark launch" I mean evaluating throttle behavior on real production traffic without consuming limiter state.

Typical examples:

• validating a new throttle before enabling it
• comparing two parameter sets on the same traffic
• emitting “would have throttled” metrics/logs during rollout

Yes, this can be approximated with EVAL_RO today, but a native CL.PROBE would guarantee that the dry-run answer stays aligned with the native CL.THROTTLE behavior and response shape.

2. "Should work for arbitrary quantity, not only via a special-case workaround"

What I meant is: probe should answer the same question as CL.THROTTLE for any requested cost, not only for quantity=1, and not by relying on a special trick like quantity=0.

Example:

• request A costs 1 unit
• request B costs 5 units

I want to ask: "would quantity=5 be allowed right now?" without consuming those 5 units.

3. Candidate selection across multiple keys

Fair point: this is not an atomic correctness use case, and I’m happy to de-emphasize or remove it from the motivation.

What I meant was only advisory / best-effort selection:

• probe several candidate keys
• pick one to try
• then CL.THROTTLE remains the authoritative consume step

If state changes between probe and consume, the consume can fail, and the caller has to handle that race. So I agree this should not be presented as a strong correctness argument for CL.PROBE.

[romange]

Plan

Context

CL.THROTTLE implements GCRA rate limiting but always mutates state when a request is allowed: it updates the TAT (Theoretical Arrival Time) in the key's value and refreshes the key's TTL. There is no way to ask "would this request be allowed right now?" without consuming quota. Issue #7128 requests a read-only probe mode for use cases like dark launches, candidate selection across keys, and preflight/debug endpoints.

The solution is a new CL.PROBE command with identical arguments and response shape to CL.THROTTLE but with strictly read-only semantics:

• No TAT update
• No TTL refresh
• No key creation for missing keys
• Same 5-element integer array response as CL.THROTTLE:

Index	Field	Meaning
0	limited	1 if the request would be throttled (rejected), 0 if it would be allowed
1	limit	Total bucket capacity (max_burst + 1)
2	remaining	Number of tokens remaining in the bucket after this (hypothetical) request
3	retry_after	Seconds until the request would be allowed (rounded up); -1 if already allowed
4	reset_after	Seconds until the bucket resets to full (rounded up); always >= 0

retry_after and reset_after are in whole seconds (ms precision is truncated during response formatting). Both are -1 only when there is no wait at all.

---

Critical Files

File	Change
src/server/string_family.cc	Add OpProbe, CmdClProbe, and register CL.PROBE
src/server/string_family_test.cc	Add TEST_F(StringFamilyTest, ClProbe)

No changes needed to acl_commands_def.h — CL.PROBE reuses the existing acl::THROTTLE category.

---

Implementation

1. Extend OpThrottle with a bool probe parameter (~line 378)

Add bool probe = false as a final parameter. Inside the function, two spots change:

a) Key lookup — use read-only access when probing:

// Before:
auto res = db_slice.FindMutable(op_args.db_cntx, key, OBJ_STRING);
// After:
auto res = probe ? db_slice.FindReadOnly(op_args.db_cntx, key, OBJ_STRING)
                 : db_slice.FindMutable(op_args.db_cntx, key, OBJ_STRING);

b) Write block — skip when probing (lines 460-481):

if (!limited && !probe) {
  // ... existing TTL update + key create/update code unchanged ...
}

All GCRA math, overflow checks, and the return value are unchanged.

2. Add CmdClProbe handler (after CmdClThrottle, ~line 1737)

CmdClProbe is a copy of CmdClThrottle with one change in the lambda:

// Before (in CmdClThrottle):
return OpThrottle(t->GetOpArgs(shard), key, limit, emission_interval_ns, quantity);
// After (in CmdClProbe):
return OpThrottle(t->GetOpArgs(shard), key, limit, emission_interval_ns, quantity, /*probe=*/true);

Argument parsing, validation, error handling, and response formatting are identical.

3. Register CL.PROBE in StringFamily::Register (~line 1778)

<< CI{"CL.PROBE", CO::READONLY | CO::FAST, -5, 1, 1, acl::THROTTLE}.HFUNC(ClProbe)

Key differences from CL.THROTTLE registration:

• Flags: CO::READONLY | CO::FAST (drop CO::JOURNALED and CO::DENYOOM — no writes occur)
• Everything else (arity -5, key positions 1,1, ACL category) is the same

---

Tests

Add TEST_F(StringFamilyTest, ClProbe) in string_family_test.cc covering:

1. No key creation: CL.PROBE on a non-existent key → key still does not exist afterward (EXISTS returns 0)
2. No TAT mutation: After several CL.THROTTLE calls consuming quota, CL.PROBE with same args reports same remaining as the next peek without changing it (verified by two consecutive probes returning identical results)
3. Missing key response: Probe on missing key returns [0, limit, max_burst, -1, ...] — same as a fresh first throttle would, because TAT defaults to now_ns
4. Limited detection: After exhausting quota via CL.THROTTLE, CL.PROBE returns limited=1 without consuming any retry budget (a subsequent CL.THROTTLE sees the same retry_after as the probe did)
5. Quantity parameter: Probe with quantity > max_burst returns limited=1 (can never exceed burst), matching CL.THROTTLE behaviour

---

Verification

# Build
cd build-dbg && ninja string_family_test

# Run new test
./string_family_test --gtest_filter="*ClProbe*"

# Run full string family suite to check for regressions
./string_family_test

# Manual smoke test
dragonfly --port 6379 &
redis-cli CL.THROTTLE mykey 4 1 10     # consume one token
redis-cli CL.PROBE   mykey 4 1 10     # same remaining, no change
redis-cli CL.PROBE   mykey 4 1 10     # still same remaining
redis-cli CL.THROTTLE mykey 4 1 10    # remaining decremented

redis-cli EXISTS mykey2                # 0 — probe never created it
redis-cli CL.PROBE mykey2 4 1 10      # returns [0, 5, 4, -1, ...]
redis-cli EXISTS mykey2                # still 0