VMOD using the synchronous hiredis library API to access Redis servers from VCL. For an alternative using libvalkey + Valkey, please check the libvmod-valkey VMOD project.
Highlights:
- Full support for execution of Lua scripts (i.e.
EVALcommand), including optimistic automatic execution ofEVALSHAcommands. - All Redis reply data types are supported, including partial support to access to components of simple (i.e. not nested) array replies.
- Redis pipelines are not (and won't be) supported. Lua scripting, which is fully supported by the VMOD, it's a much more flexible alternative to pipelines for atomic execution and minimizing latency. Pipelines are hard to use and error prone, specially when using the
WATCHcommand. - Support for classic Redis deployments using multiple replicated Redis servers and for clustered deployments based on Redis Cluster.
- Support for multiple databases and multiple Redis connections, local to each Varnish worker thread, or shared using one or more pools.
- Support for smart command execution, selecting the destination server according with the preferred role (i.e. master or slave) and with distance and healthiness metrics collected during execution.
- Support for Redis Sentinel, allowing automatic discovery of sick / healthy servers and changes in their roles.
Please, check out the project wiki for some extra information and useful links.
Looking for official support for this VMOD? Please, contact Allenta Consulting, a Varnish Software Premium partner.
import redis;
##
## Weights.
##
Function weights(STRING rules="")
##
## Sentinels.
##
Function sentinels(
STRING locations="",
INT period=60,
INT connection_timeout=500,
INT command_timeout=0,
ENUM { RESP2, RESP3, default } protocol="default",
BOOL tls=false,
STRING tls_cafile="",
STRING tls_capath="",
STRING tls_certfile="",
STRING tls_keyfile="",
STRING tls_sni="",
STRING password="",
BOOL debug=false)
##
## Proxy.
##
# Instance selection.
Function VOID use(STRING db)
# Proxied methods.
Method VOID .add_server(..., STRING db="")
Function VOID command(..., STRING db="")
Function VOID timeout(..., STRING db="")
Function VOID retries(..., STRING db="")
...
Method STRING .stats(..., STRING db="")
Method INT .counter(..., STRING db="")
##
## Databases.
##
# Constructor.
Object db(
STRING location="",
ENUM { master, slave, auto, cluster } type="auto",
INT connection_timeout=1000,
INT connection_ttl=0,
INT command_timeout=0,
INT max_command_retries=0,
BOOL shared_connections=true,
INT max_connections=128,
ENUM { RESP2, RESP3, default } protocol="default",
BOOL tls=false,
STRING tls_cafile="",
STRING tls_capath="",
STRING tls_certfile="",
STRING tls_keyfile="",
STRING tls_sni="",
STRING user="",
STRING password="",
INT sickness_ttl=60,
BOOL ignore_slaves=false,
BOOL debug=false,
INT max_cluster_hops=32)
Method VOID .add_server(
STRING location,
ENUM { master, slave, auto, cluster } type)
# Command execution.
Method VOID .command(STRING name)
Method VOID .timeout(INT command_timeout)
Method VOID .retries(INT max_command_retries)
Method VOID .push(STRING arg)
Method VOID .execute(BOOL master=true)
Method VOID .easy_execute(STRING command, [STRING command_args...], BOOL master=true, INT command_timeout, INT max_command_retries)
# Access to replies.
Method BOOL .replied()
Method BOOL .reply_is_error()
Method BOOL .reply_is_nil()
Method BOOL .reply_is_status()
Method BOOL .reply_is_integer()
Method BOOL .reply_is_boolean()
Method BOOL .reply_is_double()
Method BOOL .reply_is_string()
Method BOOL .reply_is_array()
Method STRING .get_reply()
Method STRING .get_error_reply()
Method STRING .get_status_reply()
Method INT .get_integer_reply()
Method BOOL .get_boolean_reply()
Method REAL .get_double_reply()
Method STRING .get_string_reply()
Method INT .get_array_reply_length()
Method BOOL .array_reply_is_error(INT index)
Method BOOL .array_reply_is_nil(INT index)
Method BOOL .array_reply_is_status(INT index)
Method BOOL .array_reply_is_integer(INT index)
Method BOOL .array_reply_is_boolean(INT index)
Method BOOL .array_reply_is_double(INT index)
Method BOOL .array_reply_is_string(INT index)
Method BOOL .array_reply_is_array(INT index)
Method STRING .get_array_reply_value(INT index)
# Other.
Method VOID .free()
Method STRING .stats(
ENUM { json, prometheus } format="json",
BOOL stream=0,
STRING prometheus_name_prefix="vmod_redis_",
BOOL prometheus_default_labels=1,
STRING prometheus_extra_labels="")
Method INT .counter(STRING name)
Simple case, keeping up to one Redis connection per Varnish worker thread. Beware this is just a toy example: using shared connections is usually a better approach.
sub vcl_init {
new db = redis.db(
location="192.168.1.100:6379",
type=master,
connection_timeout=500,
command_timeout=1000,
shared_connections=false,
max_connections=1);
}
sub vcl_deliver {
# Simple command execution.
db.command("SET");
db.push("foo");
db.push("Hello world!");
db.execute();
# Alternatively, the same can be achieved with one single command
db.easy_execute("SET", "foo", "Hello world!");
# Lua scripting.
db.command("EVAL");
db.push({"
redis.call('SET', KEYS[1], ARGV[1])
redis.call('SET', KEYS[2], ARGV[1])
"});
db.push("2");
db.push("foo");
db.push("bar");
db.push("Atomic hello world!");
db.execute();
# Array replies, checking & accessing to reply.
db.command("MGET");
db.push("foo");
db.push("bar");
db.execute();
if ((db.reply_is_array()) &&
(db.get_array_reply_length() == 2)) {
set resp.http.X-Foo = db.get_array_reply_value(0);
set resp.http.X-Bar = db.get_array_reply_value(1);
}
}
Master-slave replication, keeping up to two Redis connections per Varnish worker thread (up to one to the master server & up to one to the closest slave server). Beware this is just a toy example: using shared connections is usually a better approach.
sub vcl_init {
redis.weights(
rules={"
0 ^192[.]168[.]1[.]102:.*$
1 ^192[.]168[.]1[.]103:.*$
"});
new db = redis.db(
location="192.168.1.100:6379",
type=master,
connection_timeout=500,
command_timeout=1000,
shared_connections=false,
max_connections=2);
db.add_server("192.168.1.101:6379", slave);
db.add_server("192.168.1.102:6379", slave);
db.add_server("192.168.1.103:6379", slave);
}
sub vcl_deliver {
# SET submitted to the master server.
db.command("SET");
db.push("foo");
db.push("Hello world!");
db.execute();
# GET submitted to one of the slave servers.
db.command("GET");
db.push("foo");
db.execute(false);
set req.http.X-Foo = db.get_string_reply();
}
Same example as above, but specifying the location of the Redis Sentinel servers. This configuration will:
- Launch a dedicated thread that will run an initial discovery using the
SENTINEL mastersandSENTINEL slavescommands, and then repeat it every 60 seconds to discover sick / healthy servers and changes in their roles. - The same thread will use
PSUBSCRIBEto be notified about events published by the Sentinel servers, reacting to role and health changes as soon as they happen instead of waiting for the next periodic discovery. - Populate an internal inventory of known Redis servers, compared against the locations of the servers explicitly registered for any database object. Matching servers get their roles and healthiness statuses automatically updated. Beware locations registered in the VCL configuration must exactly match the values advertised by the Sentinel servers. If using DNS names, check the USING DNS NAMES section for some important considerations to be taken into account.
Beware Sentinels are only used to track servers already registered in the VCL configuration: servers will never be automatically added to (or removed from) database objects as a result of Sentinel discoveries.
sub vcl_init {
redis.sentinels(
locations={"
192.168.1.200:26379,
192.168.1.201:26379,
192.168.1.202:26379
"},
period=60,
connection_timeout=500,
command_timeout=1000);
new db = ...
}
Clustered setup keeping up to 128 Redis connections per server, all shared between all Varnish worker threads. Two initial cluster servers are provided; remaining servers are automatically discovered using the CLUSTER SHARDS command.
sub vcl_init {
new db = redis.db(
location="192.168.1.100:6379",
type=cluster,
connection_timeout=500,
command_timeout=1000,
shared_connections=true,
max_connections=128,
max_cluster_hops=16);
db.add_server("192.168.1.101:6379", cluster);
}
sub vcl_deliver {
# SET internally routed to the destination server.
db.command("SET");
db.push("foo");
db.push("Hello world!");
db.execute();
# GET internally routed to the destination server.
db.command("GET");
db.push("foo");
db.execute(false);
set req.http.X-Foo = db.get_string_reply();
}
The source tree is based on autotools to configure the building, and does also have the necessary bits in place to do functional unit tests using the varnishtest tool.
Beware this project contains multiples branches (main, 4.1, 4.0, etc.). Please, select the branch to be used depending on your Varnish Cache version (Varnish trunk → main, Varnish 4.1.x → 4.1, Varnish 4.0.x → 4.0, etc.).
Dependencies:
- hiredis - minimalistic C Redis client library.
- libev - full-featured and high-performance event loop.
The test suite is executed using make check. Each .vtc test is wrapped by src/tests/runner.sh, which launches the Redis servers required by the test (i.e., standalone masters & replicas plus Sentinels, or a Redis Cluster, depending on the test file name) and injects their locations and other useful macros into the test.
By default tests use plaintext connections and let the VMOD select the protocol version. Both behaviors can be changed using environment variables, both for the whole test suite and for a single test:
# Whole test suite using TLS connections & the RESP3 protocol. TLS=true PROTOCOL=RESP3 make check # Single test using defaults. make check TESTS=tests/standalone.template.vtc # Single test using plaintext connections & the RESP2 protocol. PROTOCOL=RESP2 make check TESTS=tests/standalone.template.vtc
PROTOCOL(default,RESP2orRESP3; defaults todefault): injected into tests as the${redis_protocol}macro, used by most of them as the value of theprotocolparameter.TLS(trueorfalse; defaults tofalse): injected into tests as the${redis_tls}macro, used by most of them as the value of thetlsparameter. When enabled, the${redis_*_port}macros reference the TLS ports of the launched servers instead of the plaintext ones (both are always available as${redis_*_plain_port}and${redis_*_tls_port}).
This VMOD supports the use of DNS names when configuring the Redis server locations, but some considerations must be taken into account:
- When using a Redis Sentinel setup, the names used in the VCL configuration must be the exact same names advertised by the Sentinel servers in order for the VMOD to be able to perform automatic discovery of sick / healthy servers and changes in their roles. So, when using DNS names, all Redis instances should be configured using hostnames for properties
replica-announce-ipandreplicaof, whereas the Sentinel instances should be configured using hostnames as well for propertiessentinel monitorandsentinel announce-ip. Finally,sentinel resolve-hostnamesandsentinel announce-hostnamesshould be set toyesin the Sentinel configuration files as well. Check the official Redis documentation for more details on this topic. - When using a Redis Cluster setup, the cluster must be explicitly configured to use DNS names or by default it will use IP addresses. This includes setting the
cluster-announce-hostnameproperty in the configuration files of all Redis instances to the hostname of the server, as well as settingcluster-preferred-endpoint-typetohostname. Regarding VCL configuration, same considerations apply as in the Sentinel case, i.e. names used in the VCL configuration must be the exact same names advertised by cluster commands likeCLUSTER SHARDS.
See LICENSE for details.
Public domain implementation of the SHA-1 cryptographic hash function by Steve Reid and embedded in this VMOD (required for the optimistic execution of EVALSHA commands) has been borrowed from this project:
BSD's implementation of the CRC-16 cryptographic hash function by Georges Menie & Salvatore Sanfilippo and embedded in this VMOD (required for the Redis Cluster slot calculation) has been borrowed from the Redis project:
Copyright (c) Carlos Abalde <carlos.abalde@gmail.com>