lua-resty-redis-cluster-fast

The repository of the binary installer

First, we need to configure the repository of the binary installer using the commands below. (The CLIENT_TOKEN in the commands needs to be replaced with a valid Token from the subscription email)

For OpenResty 1.21.4.x

curl -o get-xray-priv-lib-repo.sh https://pkg2.openresty.com/scripts/get-xray-priv-lib-repo.sh

sudo bash get-xray-priv-lib-repo.sh -l coro-nginx-module-1.21.4 -t CLIENT_TOKEN

sudo bash get-xray-priv-lib-repo.sh -l coro-hiredis-nginx-module-1.21.4 -t CLIENT_TOKEN

For OpenResty 1.25.3.x

curl -o get-xray-priv-lib-repo.sh https://pkg2.openresty.com/scripts/get-xray-priv-lib-repo.sh

sudo bash get-xray-priv-lib-repo.sh -l coro-nginx-module-1.25.3 -t CLIENT_TOKEN

sudo bash get-xray-priv-lib-repo.sh -l coro-hiredis-nginx-module-1.25.3 -t CLIENT_TOKEN

We also rely on Openresty’s open-source repositories in addition to the above-mentioned repository. If you have not previously configured the open-source repository, you can refer to this page for configurations.

Installation

For OpenResty-1.21.4.x

For CentOS/RockyLinux/Amazon Linux/Alibaba Cloud Linux/Tecent Linux operating systems using yum as the package manager, execute the following command to install the private libraries.

sudo yum install --disablerepo="*" --enablerepo="coro-nginx-module-1.21.4 coro-hiredis-nginx-module-1.21.4" -y lua-resty-redis-cluster-fast-1.21.4

For operating systems such as Fedora that use dnf as package manager, execute the following command to install the private library.

sudo dnf install --disablerepo="*" --enablerepo="coro-nginx-module-1.21.4 coro-hiredis-nginx-module-1.21.4" -y lua-resty-redis-cluster-fast-1.21.4

For operating systems such as Ubuntu/Debian that use apt as the package manager, run the following command to install the private libraries.

sudo apt-get install -y lua-resty-redis-cluster-fast-1.21.4

For OpenResty 1.25.3.x

For CentOS/RockyLinux/Amazon Linux/Alibaba Cloud Linux/Tecent Linux operating systems using yum as the package manager, execute the following command to install the private libraries.

sudo yum install --disablerepo="*" --enablerepo="coro-nginx-module-1.25.3 coro-hiredis-nginx-module-1.25.3" -y lua-resty-redis-cluster-fast-1.25.3

For operating systems such as Fedora that use dnf as package manager, execute the following command to install the private library.

sudo dnf install --disablerepo="*" --enablerepo="coro-nginx-module-1.25.3 coro-hiredis-nginx-module-1.25.3" -y lua-resty-redis-cluster-fast-1.25.3

For operating systems such as Ubuntu/Debian that use apt as the package manager, run the following command to install the private libraries.

sudo apt-get install -y lua-resty-redis-cluster-fast-1.25.3

Upgrade OpenResty

If openresty has been previously installed, please execute the following upgrade command:

sudo yum upgrade -y openresty

Usage

Nginx configuration

Before you can use lua-resty-redis-cluster-fast, you need to add the following configuration items to the configuration file nginx.conf to load the related dynamic modules.

    ...

    load_module "/usr/local/openresty-coro-nginx-module/lib/ngx_http_coro_module.so";
    load_module "/usr/local/openresty-coro-nginx-module/lib/ngx_http_coro_hiredis_module.so";

    http {
        coro_preload /usr/local/openresty/openssl111/lib/libcrypto.so;
        coro_preload /usr/local/openresty/openssl111/lib/libssl.so;
        coro_preload /usr/local/openresty-plus/hiredis/lib/libhiredis.so;
        coro_preload /usr/local/openresty-plus/hiredis/lib/libhiredis_ssl.so;

        coro_stack_size  32768;
        ...
    }

Lua interface

Interfaces connect and set_keepalive are changed. Other interfaces of this library are consistent with those of the open-source lua-resty-redis. Let’s see the following example:

    load_module "/usr/local/openresty-coro-nginx-module/lib/ngx_http_coro_module.so";
    load_module "/usr/local/openresty-coro-nginx-module/lib/ngx_http_coro_hiredis_module.so";

    http {
        coro_preload /usr/local/openresty/openssl111/lib/libcrypto.so;
        coro_preload /usr/local/openresty/openssl111/lib/libssl.so;
        coro_preload /usr/local/openresty-plus/hiredis/lib/libhiredis.so;
        coro_preload /usr/local/openresty-plus/hiredis/lib/libhiredis_ssl.so;
        coro_stack_size  32768;

        server {
            location /test {
                # need to specify the resolver to resolve the hostname
                resolver 8.8.8.8;

                content_by_lua_block {
                    local redis = require "resty.redis.cluster.fast"
                    local red = redis:new()

                    red:set_timeouts(1000, 1000, 1000) -- 1 sec

                    -- connect via ip address directly
                    local ok, err = red:connect("127.0.0.1", 6379, {
                        cluster = "cluster",
                        other_nodes = {
                            { "127.0.0.1", 6380 },
                            { "127.0.0.1", 6381 },
                            { "127.0.0.1", 6382 },
                        },
                        no_slaves = true
                    })

                    if not ok then
                        ngx.say("failed to connect: ", err)
                        return
                    end

                    ok, err = red:set("dog", "an animal")
                    if not ok then
                        ngx.say("failed to set dog: ", err)
                        return
                    end

                    ngx.say("set result: ", ok)

                    local res, err = red:get("dog")
                    if not res then
                        ngx.say("failed to get dog: ", err)
                        return
                    end

                    if res == ngx.null then
                        ngx.say("dog not found.")
                        return
                    end

                    ngx.say("dog: ", res)

                    local ok, err = red:set_keepalive()
                    if not ok then
                        ngx.say("failed to set keepalive: ", err)
                        return
                    end

                    -- or just close the connection right away:
                    -- local ok, err = red:close()
                    -- if not ok then
                    --     ngx.say("failed to close: ", err)
                    --     return
                    -- end
                }
            }
        }
    }

Interfaces connect and set_keepalive are described as follows:

connect

TODO: unix domain socket and SSL are currently not supported.

syntax: ok, err = red:connect(host, port, options_table)

Connects to the host and port that the ingress node of Redis is listening on. This method will always look for a matching free connection in the connections pool created by a previous call of this method before actually connecting to the remote backend.

The parameter options_table is a Lua table that includes the following parameters:

  • cluster

    This is a mandatory field that specifies a custom name for the Redis cluster connection pool being used.

  • pool_size

    Specifies the size of the connections pool. The default value is 128.

  • other_nodes

    Specifies other Redis nodes that can be connected to. When the connection to the ingress node fails, it will try to connect to other nodes.

    The parameter other_nodes is a Lua table that stores configuration information of multiple nodes, e.g:

    {
        { "127.0.0.1", 6379 },
        { "127.0.0.1", 6380 },
        { "127.0.0.1", 6381 },
    }
    
  • no_slaves

    Whether to disable reading data from Redis slave nodes. The default value is false.

set_keepalive

syntax: ok, err = red:set_keepalive()

To be compatible with the set_keepalive(max_idle_timeout, pool_size) method of the open-source lua-resty-redis library, we still allow passing two arguments, but we will ignore the incoming arguments.

Add the current Redis connection into the cosocket connections pool.

Call this method only where you want to call the close method. Calling this method will immediately turn the current Redis object into a closed state. Any subsequent operation on the current object other than connect() will return a closed error.