mirror of
https://github.com/hanzoai/kv.git
synced 2026-11-09 16:05:35 +00:00
This PR introduces `ValkeyModule_CallArgv`, a new low-level module API
for calling server commands. It is designed as a complement to the
existing `ValkeyModule_Call` covering two scenarios where
`ValkeyModule_Call` is suboptimal:
1. **The module already holds the arguments as an argv array.**
`ValkeyModule_Call` always allocates a new argv array, creates a new
string object for the command name, and calls
`incrRefCount`/`decrRefCount` on every argument. `ValkeyModule_CallArgv`
borrows the caller's argv array directly — no allocation, no refcount
manipulation. Ownership of the array stays with the caller.
2. **The module wants to forward the reply to its own client without
inspecting it.** `ValkeyModule_Call` always parses the raw RESP bytes
into an intermediate `ValkeyModuleCallReply` tree and then re-serializes
it back to RESP to send to the caller. `ValkeyModule_CallArgv` exposes
the raw RESP bytes directly through a callback, allowing a pass-through
module command to copy bytes from the inner command's output buffer
straight into the outer client's output buffer.
---
## New API
### `ValkeyModule_CallArgv`
```c
int ValkeyModule_CallArgv(ValkeyModuleCtx *ctx,
ValkeyModuleString **argv,
int argc,
int flags,
ValkeyModuleReplyHandlers *reply_handlers,
void *reply_ctx);
```
Calls a server command using an existing argv array. The caller retains
ownership of `argv` and its elements — they are never freed or
ref-counted by the function.
Returns `VALKEYMODULE_OK` on success or `VALKEYMODULE_ERR` on error,
with `errno` set to the same values as `ValkeyModule_Call`. The function
does **not** return a `ValkeyModuleCallReply`; the reply is delivered
through `reply_handlers` instead.
`flags` is a bitwise OR of one or more `VALKEYMODULE_CALL_ARGV_*`
constants, which correspond directly to the format-string specifiers of
`ValkeyModule_Call`:
| Flag | Equivalent format char | Meaning |
|---|---|---|
| `VALKEYMODULE_CALL_ARGV_REPLICATE` | `!` | Propagate to replicas and
AOF |
| `VALKEYMODULE_CALL_ARGV_NO_AOF` | `A` | Skip AOF propagation |
| `VALKEYMODULE_CALL_ARGV_NO_REPLICAS` | `R` | Skip replica propagation
|
| `VALKEYMODULE_CALL_ARGV_RESP_3` | `3` | Force RESP3 for the inner call
|
| `VALKEYMODULE_CALL_ARGV_RESP_AUTO` | `0` | Match the calling client's
protocol (RESP2 or RESP3) |
| `VALKEYMODULE_CALL_ARGV_RUN_AS_USER` | `C` | Apply ACL checks for the
context user |
| `VALKEYMODULE_CALL_ARGV_SCRIPT_MODE` | `S` | Mark as script execution
|
| `VALKEYMODULE_CALL_ARGV_NO_WRITES` | `W` | Disallow write commands |
| `VALKEYMODULE_CALL_ARGV_ERRORS_AS_REPLIES` | `E` | Return error
replies instead of raising errno |
| `VALKEYMODULE_CALL_ARGV_RESPECT_DENY_OOM` | `M` | Honour deny-oom
policy |
| `VALKEYMODULE_CALL_ARGV_DRY_RUN` | `D` | Dry-run mode (implies
`ERRORS_AS_REPLIES`) |
| `VALKEYMODULE_CALL_ARGV_ALLOW_BLOCK` | `K` | Allow the inner command
to block |
| `VALKEYMODULE_CALL_ARGV_REPLY_EXACT` | `X` | Disable reply type
coercion |
---
### `ValkeyModuleReplyHandlers`
```c
typedef struct ValkeyModuleReplyHandlers {
/* Scalar types */
void (*null)(void *ctx);
void (*bulkString)(void *ctx, const char *str, size_t len);
void (*simpleString)(void *ctx, const char *str, size_t len);
void (*error)(void *ctx, const char *msg, size_t len);
void (*integer)(void *ctx, long long val);
void (*doubleVal)(void *ctx, double val);
void (*boolVal)(void *ctx, int val);
void (*bigNumber)(void *ctx, const char *str, size_t len);
void (*verbatimString)(void *ctx, const char *str, size_t len, const char *fmt);
/* Collection types — paired start/end callbacks */
void (*arrayStart)(void *ctx, size_t len);
void (*arrayEnd)(void *ctx);
void (*mapStart)(void *ctx, size_t len);
void (*mapEnd)(void *ctx);
void (*setStart)(void *ctx, size_t len);
void (*setEnd)(void *ctx);
void (*attributeStart)(void *ctx, size_t len);
void (*attributeEnd)(void *ctx);
/* Invoked on parse error */
void (*replyParsingError)(void *ctx);
/* Raw-bytes intercept — called before per-type callbacks */
int (*onRespAvailable)(void *ctx, ValkeyModuleCtx *module_ctx, const char *proto, size_t proto_len);
/* Blocking command support */
void (*onBlocked)(void *ctx, ValkeyModuleCtx *module_ctx, ValkeyModuleCallArgvBlockedHandle *handle);
void *context; /* Passed as first argument to every callback */
} ValkeyModuleReplyHandlers;
```
All fields are optional; set unused ones to `NULL`.
**`onRespAvailable`** is called first, before any per-type callback,
with the complete raw RESP reply in the `proto`/`proto_len` arguments.
Return `1` to continue into the per-type callbacks; return `0` to stop
after the raw bytes. Pass `NULL` to skip and go straight to per-type
dispatching.
**`onBlocked`** is only called when `VALKEYMODULE_CALL_ARGV_ALLOW_BLOCK`
is set and the inner command blocks. The `handle` can be passed to
`ValkeyModule_CallArgvAbort` to cancel the call. The handle is valid
until either `onRespAvailable` is invoked or
`ValkeyModule_CallArgvAbort` is called, whichever comes first.
---
### `ValkeyModule_CallArgvAbort`
```c
int ValkeyModule_CallArgvAbort(ValkeyModuleCallArgvBlockedHandle *handle);
```
Cancels a blocking call whose `onBlocked` callback has already fired.
Returns `VALKEYMODULE_OK` if the abort succeeded (neither
`onRespAvailable` nor any other reply callback will be invoked), or
`VALKEYMODULE_ERR` if the call has already completed.
---
### `ValkeyModule_ReplyRaw`
```c
int ValkeyModule_ReplyRaw(ValkeyModuleCtx *ctx, const char *proto, size_t proto_len);
```
Appends raw RESP bytes directly to the calling client's output buffer,
with no parsing or re-serialization. Intended for use inside an
`onRespAvailable` callback to implement zero-copy reply forwarding.
---
## Usage Example: `ValkeyModule_Call` vs `ValkeyModule_CallArgv`
The following two implementations of a generic pass-through proxy
command are functionally equivalent, but use different code paths
internally.
### With `ValkeyModule_Call` (existing API)
```c
int ProxyCommand(ValkeyModuleCtx *ctx, ValkeyModuleString **argv, int argc) {
if (argc < 2) return ValkeyModule_WrongArity(ctx);
/* VM_Call builds a new argv array internally, creates a string object for
* the command name, and calls incrRefCount/decrRefCount on every argument.
* The reply is parsed into a CallReply tree, then re-serialized to RESP. */
ValkeyModuleCallReply *reply =
ValkeyModule_Call(ctx, ValkeyModule_StringPtrLen(argv[1], NULL), "v",
argv + 2, (size_t)(argc - 2));
return ValkeyModule_ReplyWithCallReply(ctx, reply);
}
```
### With `ValkeyModule_CallArgv` and `onRespAvailable` (new API —
pass-through)
```c
static int forwardRawReply(void *ctx, ValkeyModuleCtx *mctx,
const char *proto, size_t proto_len) {
(void)ctx;
/* Write the raw RESP bytes directly to the outer client — no parse, no
* re-serialize, no intermediate allocation. */
ValkeyModule_ReplyRaw(mctx, proto, proto_len);
return 0; /* stop — do not invoke per-type callbacks */
}
static ValkeyModuleReplyHandlers passthrough_handlers = {
.onRespAvailable = forwardRawReply,
};
int ProxyCommand(ValkeyModuleCtx *ctx, ValkeyModuleString **argv, int argc) {
if (argc < 2) return ValkeyModule_WrongArity(ctx);
/* VM_CallArgv borrows argv directly (no copy, no refcount changes).
* The reply is written straight into the outer client's output buffer
* through the onRespAvailable callback above. */
if (ValkeyModule_CallArgv(ctx, argv + 1, argc - 1,
VALKEYMODULE_CALL_ARGV_RESP_AUTO,
&passthrough_handlers,
NULL) == VALKEYMODULE_ERR) {
return ValkeyModule_ReplyWithError(ctx, "ERR command failed");
}
return VALKEYMODULE_OK;
}
```
Use `VALKEYMODULE_CALL_ARGV_RESP_AUTO` to ensure the inner command
replies in the same protocol version as the outer client (RESP2 or
RESP3), so the raw bytes can be forwarded without modification.
---
## Internal changes
### `argv_borrowed` client flag
A new `argv_borrowed` bit is added to the client flags struct. When
`VM_CallArgv` runs the inner command on a temporary client, it sets this
flag to signal that the temp client does not own the argv array.
`freeClientArgv` and `freeClientOriginalArgv` respect the flag and skip
freeing. `resetClient` clears it unconditionally after each command.
Several string commands (`SET`, `MSET`, `APPEND`, …) that previously
encoded or reused argv objects in-place are guarded so they do not
mutate argv elements they do not own.
A debug-only assertion (enabled when `enable-debug-assert yes` is set in
the config) verifies at runtime that no command modifies the argv array
or decrements any element's ref-count when `argv_borrowed` is set.
---------
Signed-off-by: Ricardo Dias <[email protected]>
Signed-off-by: Ricardo Dias <[email protected]>
117 lines
3.7 KiB
Tcl
117 lines
3.7 KiB
Tcl
set testmodule [file normalize tests/modules/basics.so]
|
|
|
|
start_server {tags {"modules"}} {
|
|
r module load $testmodule
|
|
|
|
test {test module api basics} {
|
|
r test.basics
|
|
} {ALL TESTS PASSED}
|
|
|
|
test {test rm_call auto mode} {
|
|
r hello 2
|
|
set reply [r test.rmcallautomode]
|
|
assert_equal [lindex $reply 0] f1
|
|
assert_equal [lindex $reply 1] v1
|
|
assert_equal [lindex $reply 2] f2
|
|
assert_equal [lindex $reply 3] v2
|
|
r hello 3
|
|
set reply [r test.rmcallautomode]
|
|
assert_equal [dict get $reply f1] v1
|
|
assert_equal [dict get $reply f2] v2
|
|
}
|
|
|
|
test {test get resp} {
|
|
foreach resp {3 2} {
|
|
if {[lsearch $::denytags "resp3"] >= 0} {
|
|
if {$resp == 3} {continue}
|
|
} elseif {$::force_resp3} {
|
|
if {$resp == 2} {continue}
|
|
}
|
|
r hello $resp
|
|
set reply [r test.getresp]
|
|
assert_equal $reply $resp
|
|
r hello 2
|
|
}
|
|
}
|
|
|
|
test "Busy module name" {
|
|
assert_error {ERR Error loading the extension. Please check the server logs.} {r module load $testmodule}
|
|
verify_log_message 0 "*Module name is busy*" 0
|
|
}
|
|
|
|
test "test latency" {
|
|
r config set latency-monitor-threshold 0
|
|
r latency reset
|
|
r test.latency 0
|
|
r test.latency 1
|
|
assert_equal {} [r latency latest]
|
|
assert_equal {} [r latency history test]
|
|
|
|
r config set latency-monitor-threshold 1
|
|
r test.latency 0
|
|
assert_equal 0 [llength [r latency history test]]
|
|
r test.latency 1
|
|
assert_match {*test * 1 1*} [r latency latest]
|
|
r test.latency 2
|
|
assert_match {*test * 2 2*} [r latency latest]
|
|
}
|
|
|
|
test "Test CallArgv" {
|
|
set reply [r test.call_argv ping hello]
|
|
assert_equal hello $reply
|
|
|
|
set reply [r test.call_argv ping]
|
|
assert_equal PONG $reply
|
|
|
|
r set x hello
|
|
r set y world
|
|
set reply [r test.call_argv mget x y]
|
|
assert_equal [lindex $reply 0] hello
|
|
assert_equal [lindex $reply 1] world
|
|
|
|
assert_error "ERR Write command*" {r test.call_argv set mykey myvalue}
|
|
}
|
|
|
|
test "Test CallArgvRaw" {
|
|
set reply [r test.call_argv_raw ping hello]
|
|
assert_equal "\$5\r\nhello\r\n" $reply
|
|
|
|
set reply [r test.call_argv_raw ping]
|
|
assert_equal "+PONG\r\n" $reply
|
|
|
|
set reply [r test.call_argv_raw set mykey myvalue]
|
|
assert_match "-ERR Write command*" $reply
|
|
}
|
|
|
|
test "Test CallArgv with null arrayStart still consumes children" {
|
|
r set k1 v1
|
|
r set k2 v2
|
|
# The module calls MGET k1 k2 with arrayStart=NULL and counts how many
|
|
# bulkString callbacks fired. Before the parser-desync fix the array
|
|
# body was skipped entirely (result 0); with the fix children are always
|
|
# consumed and bulkString fires once per element (result 2).
|
|
assert_equal 2 [r test.call_argv_null_array_start k1 k2]
|
|
}
|
|
|
|
test "Test CallArgvScriptMode" {
|
|
# SCRIPT_MODE blocks dangerous administrative commands like SHUTDOWN
|
|
assert_error "ERR command 'shutdown' is not allowed on script mode" {r test.call_argv_s shutdown}
|
|
|
|
# SCRIPT_MODE alone does not block writes
|
|
assert_equal {OK} [r test.call_argv_s set x 1]
|
|
}
|
|
|
|
test "Unload the module - basics" {
|
|
assert_equal {OK} [r module unload test]
|
|
}
|
|
}
|
|
|
|
start_server {tags {"modules external:skip"} overrides {requirepass mypass enable-module-command no}} {
|
|
test {module command disabled} {
|
|
assert_error "NOAUTH *" {r module load $testmodule}
|
|
|
|
r auth mypass
|
|
assert_error "ERR *MODULE command not allowed*" {r module load $testmodule}
|
|
}
|
|
}
|