You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+4-4Lines changed: 4 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
# Valkey.io website
2
2
3
3
This repo contains the source for the valkey.io website (build scripts, template, blog posts, stylesheets, etc.).
4
-
The build integrates content from [`valkey-io/valkey-doc`](https://github.com/valkey-io/valkey-doc) and the commands definitions from [`valkey-io/valkey`](https://github.com/valkey-io/valkey) and [`valkey-io/valkey-bloom`](https://github.com/valkey-io/valkey-bloom) (see [Build Locally](#build-locally) below for more details).
4
+
The build integrates content from [`valkey-io/valkey-doc`](https://github.com/valkey-io/valkey-doc) and the commands definitions from [`valkey-io/valkey`](https://github.com/valkey-io/valkey), [`valkey-io/valkey-bloom`](https://github.com/valkey-io/valkey-bloom), and [`valkey-io/valkey-json`](https://github.com/valkey-io/valkey-json) (see [Build Locally](#build-locally) below for more details)
5
5
6
6
## Contributing
7
7
@@ -64,7 +64,7 @@ Commit your changes to your local copy of `valkey-io/valkey-doc`.
64
64
### Building the command reference
65
65
66
66
The command reference (i.e. `/commands/set/`, `/commands/get/`, `/commands/lolwut/`) sources information from `valkey-io/valkey`, `valkey-io/valkey-bloom`, and `valkey-io/valkey-doc`.
67
-
`valkey-io/valkey`and `valkey-io/valkey-bloom` provides the command metadata (items like computational complexity, version history, arguments, etc) whilst `valkey-io/valkey-doc` provides the command description and the command reply.
67
+
`valkey-io/valkey`, `valkey-io/valkey-bloom`and `valkey-io/valkey-json` provides the command metadata (items like computational complexity, version history, arguments, etc) whilst `valkey-io/valkey-doc` provides the command description and the command reply.
68
68
69
69
```mermaid
70
70
flowchart TD
@@ -75,13 +75,13 @@ flowchart TD
75
75
H --> J[Files: /resp2_replies.json,<br/>/resp3_replies.json] --> Z[Command Reply]
76
76
```
77
77
78
-
Let's say that this repo and your local copy of `valkey-io/valkey-doc`, `valkey-io/valkey-bloom` and `valkey-io/valkey` reside in the same directories.
78
+
Let's say that this repo and your local copy of `valkey-io/valkey-doc`, `valkey-io/valkey-bloom`, `valkey-io/valkey-json`, and `valkey-io/valkey` reside in the same directories.
79
79
First, stop the `zola serve` process if you're running it.
80
80
From the root directory of this repo run:
81
81
82
82
```shell
83
83
# You should only need to run this once or when you add a new command.
Copy file name to clipboardExpand all lines: content/blog/2025-04-27-valkey-modules-rust-sdk-updates.md
+41-25Lines changed: 41 additions & 25 deletions
Original file line number
Diff line number
Diff line change
@@ -6,23 +6,25 @@ authors= ["dmitrypol"]
6
6
categories= "modules"
7
7
+++
8
8
9
-
In an earlier [article](/blog/modules-101/) we explored the process of building Valkey Modules—extensions that let developers add new commands and data types to Valkey without modifying its core.
9
+
In an earlier [article](/blog/modules-101/) we explored the process of building Valkey Modules to enable developers to add features such as new commands and data types to Valkey without modifying its core.
10
10
We also introduced the [Valkey Modules Rust SDK](https://github.com/valkey-io/valkeymodule-rs) demonstrating how to use it to create a basic module.
11
11
In this follow-up article, we’ll dive deeper into the SDK and highlight several new features and improvements introduced over the past year.
12
+
This article assumes that the reader is well familiar with Rust and Valkey modules.
12
13
13
14
## What is the Valkey Modules Rust SDK?
14
15
15
-
The SDK is based on [Redis Modules Rust SDK](https://github.com/RedisLabsModules/redismodule-rs) and provides abstraction APIs on top of Valkey Modules own API.
16
+
The SDK is based on [Redis Modules Rust SDK](https://github.com/RedisLabsModules/redismodule-rs) and provides abstraction APIs on top of Valkey's own modules API.
16
17
For those familiar with Rust development the SDK is a Rust crate that can be added to `Cargo.toml` file like any other Rust dependency.
17
-
It requires the underlying Valkey version to have appropriate module APIs but allows writing Valkey modules in Rust, without needing to use raw pointers or unsafe code.
18
-
The recently released [Bloom Filters module](/blog/introducing-bloom-filters/) is built using this crate and several of the developers who worked on the module contributed to the SDK.
19
-
Let's deep dive into to new features.
18
+
It requires the underlying Valkey server to have appropriate module APIs but allows writing Valkey modules in Rust, without needing to use raw pointers or unsafe code.
19
+
The recently released [Bloom Filters module](/blog/introducing-bloom-filters/) is built using this SDK and several of the developers who worked on the module contributed to the SDK.
20
+
Let's deep dive into the new features.
20
21
21
22
## Client
22
23
23
-
`Context` struct now has several new functions to get information about the client connected to Valkey.
24
+
We begin with enhancements that give developers deeper insight into the clients connected to Valkey.
25
+
The `Context` struct has been extended with several new functions that allow retrieving client specific data, such as client name, username or IP address.
24
26
It provides Rust wrappers around `Module_GetClient*` functions in the underlying Valkey Module API.
25
-
Most new functions return `ValkeyResult` so the module developer can handle the error appropriately.
27
+
Most of these new functions return `ValkeyResult` so that the module developer can handle the error appropriately.
26
28
The functions can be called for the current client or by specifying `client_id`.
27
29
28
30
```rust
@@ -41,8 +43,9 @@ valkey_module! {
41
43
42
44
## Auth callback
43
45
44
-
Valkey 7.2 introduced support for callbacks after authentication.
45
-
Now it can be leveraged in modules.
46
+
Another key improvement is support for authentication callbacks introduced in Valkey 7.2.
47
+
Thanks to the new features in the SDK Rust modules can now integrate directly with Valkey's auth flow, making it possible to implement custom authentication logic or enhance security policies on a per-client basis.
48
+
One potential use case is to combine it with `ctx.get_client_ip` function described above to allow some users access only from specific IP addresses.
// can be combined with ctx.get_client_ip to control access by IP address
55
57
let_client_ip=ctx.get_client_ip()?;
56
58
...
57
59
returnOk(AUTH_HANDLED);
@@ -66,10 +68,10 @@ valkey_module! {
66
68
67
69
## Preload validation
68
70
69
-
While the `valkey_module!` macro already provided an init callback to execute custom code during module load, init executed at the very end of the module load after new commands and data types are created.
70
-
That can be useful but what if we wanted to stop module load before any of that happens?
71
+
While the `valkey_module!` macro already provided an `init` callback to execute custom code during module load, it executed at the very end of the module load after new commands and data types were created.
72
+
That can be useful but what if we wanted to stop module load before any of that happened?
71
73
For example, we might need to restrict a module to be loaded only on specific version of Valkey.
To execute custom code before specific Valkey commands we can use command filters. This can be leveraged to replace default commands with custom comands or modify arguments.
91
+
To execute custom code before specific Valkey commands we can use command filters which is now supported in the SDK.
92
+
Filters can be leveraged to replace default commands with custom comands or modify arguments.
90
93
Thanks to the abstractions provided by the SDK we simply need to create a Rust function and register it in the `valkey_module!` macro.
91
-
Note of caution - since filters are executed before every command this code needs to be optimized.
94
+
Note of caution - since filters are executed before every command this code needs to be optimized for performance.
Valkey 8 introduced support for custom ACL categories. To implement that we need to enable `required-features = ["min-valkey-compatibility-version-8-0"]` in `Cargo.toml` and register new categories in `valkey_module!` macro. Then we can restrict our custom commands to these ACL categories.
149
+
Valkey 8 introduced support for custom ACL categories which simplifies access control for custom commands introduced in a module.
150
+
To implement that we need to enable `required-features = ["min-valkey-compatibility-version-8-0"]` in `Cargo.toml` and register new categories in `valkey_module!` macro.
151
+
Then we can restrict our custom commands to these custom ACL categories.
145
152
146
153
```rust
147
154
valkey_module! {
@@ -158,7 +165,10 @@ valkey_module! {
158
165
159
166
## Validating / Rejecting CONFIG SET
160
167
161
-
The SDK now supports specifying optional callback functions to validate or reject custom configuations. This is available for `String`, `i64`, `bool` and `enum` configs. Here is an example of validation for i64 custom config.
168
+
Configuration flexibility is important but so is validation.
169
+
The SDK now supports specifying optional callback functions to validate or reject custom configuations.
170
+
This is available for `String`, `i64`, `bool` and `enum` configs.
171
+
Here is an example of such validation for i64 custom config.
162
172
163
173
```rust
164
174
lazy_static! {
@@ -188,7 +198,9 @@ valkey_module! {
188
198
189
199
## Defrag
190
200
191
-
There is a new `Defrag` struct abstracting away the raw C FFI calls to implement defrag for custom data types.
201
+
For memory-sensitive applications, defragmentation is essential.
202
+
The SDK now offers a safe and idiomatic Rust abstraction over the defrag API for custom data types.
203
+
The new `Defrag` struct abstracts away the raw C FFI calls.
192
204
193
205
```rust
194
206
staticMY_VALKEY_TYPE:ValkeyType=ValkeyType::new(
@@ -219,7 +231,8 @@ valkey_module! {
219
231
220
232
## Redis support
221
233
222
-
There is a new feature flag if your module needs to run on both Valkey and Redis.
234
+
Need your module to work with both Valkey and recent versions Redis?
235
+
The SDK includes a compatibility feature flag to ensure your module runs on both Valkey and Redis.
223
236
Specify `use-redismodule-api` so that module used RedisModule API Initialization for backwards compatibility.
This feature flag supports running unit tests outside of Valkey or Redis. As the result it cannot use Vakey Allocator and instead relies on the System Allocator instead. The core logis is present in `alloc.rs` but developers only need to specify this in the module `Cargo.toml`.
248
+
This feature enables writing unit tests to run outside of Valkey or Redis.
249
+
Instead of using Vakey Allocator it relies on the System Allocator.
250
+
Unit tests allow us to perform much more granular testing and execute much faster.
251
+
The core logic lives in `alloc.rs` but developers only need to specify this feature in the module `Cargo.toml`.
236
252
237
253
```rust
238
254
[features]
@@ -245,15 +261,15 @@ cargo test --features enable-system-alloc
245
261
246
262
The Valkey Modules Rust SDK has seen exciting improvements over the past year, making it easier and more powerful to extend Valkey.
247
263
But we are not stopping.
248
-
Some of ideas for future development include mock context support for unit testing, enhanced context access within filters, and environment-specific config to streamline development and testing.
249
-
Additionally, the introduction of crontab scheduling will allow executing custom logic on a defined schedule using cron_event_handler.
264
+
Some of the ideas for future development include [mock context support for unit testing](https://github.com/valkey-io/valkeymodule-rs/issues/202), [enhanced context access within filters](https://github.com/valkey-io/valkeymodule-rs/issues/203), and [environmentspecific configs](https://github.com/valkey-io/valkeymodule-rs/issues/204) to streamline development and testing.
265
+
Additionally, the introduction of [crontab scheduling](https://github.com/valkey-io/valkeymodule-rs/issues/205) will allow executing custom logic on a defined schedules using `cron_event_handler`.
250
266
251
267
We hope this overview helped you understand how to leverage the SDK and inspired you to explore what's possible with Valkey modules.
252
268
Stay tuned for future updates.
253
269
254
-
We also want to express appreciation to the engineers who contibuted to the SDK in the past year - [KarthikSubbarao](https://github.com/KarthikSubbarao), [dmitrypol](https://github.com/dmitrypol), [sachinvmurthy](https://github.com/sachinvmurthy), [zackcam](https://github.com/zackcam), [YueTang-Vanessa](https://github.com/YueTang-Vanessa), [hahnandrew](https://github.com/hahnandrew), [Mkmkme](https://github.com/Mkmkme).
270
+
We also want to express appreciation to the engineers who contributed to the SDK in the past year - [KarthikSubbarao](https://github.com/KarthikSubbarao), [dmitrypol](https://github.com/dmitrypol), [sachinvmurthy](https://github.com/sachinvmurthy), [zackcam](https://github.com/zackcam), [YueTang-Vanessa](https://github.com/YueTang-Vanessa), [hahnandrew](https://github.com/hahnandrew), [Mkmkme](https://github.com/Mkmkme).
0 commit comments