OpenResty Plus™ lua-resty-hiredis Library
lua-resty-hiredis - a redis client driver based on the coro-nginx-module.
Table of Contents
Status
This library is considered production ready.
Description
This Lua library is a redis client using https://github.com/redis/hiredis.
Synopsis
lua_package_path "/path/to/lua-resty-hiredis/lib/?.lua;;";
server {
location /test {
content_by_lua_block {
local hiredis = require "resty.hiredis"
local redisConnectWithTimeout = hiredis.redisConnectWithTimeout
local redisCommand = hiredis.redisCommand
local redisFree = hiredis.redisFree
local replyToLuaVal = hiredis.replyToLuaVal
local ctx, err = redisConnectWithTimeout("127.0.0.1", 6379, 1000)
if err ~= nil then
ngx.log(ngx.ERR, "redisConnectWithTimeout failed: ", err)
return
end
local reply, err = redisCommand(ctx, "PING")
if err ~= nil then
ngx.log(ngx.ERR, "redisCommand failed: ", err)
redisFree(ctx)
return
end
ngx.say(replyToLuaVal(reply))
redisFree(ctx)
}
}
}
Methods
OPENSSL_cleanup
syntax: hiredis.OPENSSL_cleanup()
The OPENSSL_cleanup() function deinitialises OpenSSL (both libcrypto and libssl). All resources allocated by OpenSSL are freed. Typically there should be no need to call this function directly as it is initiated automatically on application exit. This is done via the standard C library atexit() function. In the event that the application will close in a manner that will not call the registered atexit() handlers then the application should call OPENSSL_cleanup() directly. Developers of libraries using OpenSSL are discouraged from calling this function and should instead, typically, rely on auto-deinitialisation. This is to avoid error conditions where both an application and a library it depends on both use OpenSSL, and the library deinitialises it before the application has finished using it.
freeReplyObject
syntax: hiredis.freeReplyObject(reply)
Parameters:
- reply - reply object
Function to free the reply objects hiredis returns by default.
redisAppendFormattedCommand
syntax: rc = hiredis.redisAppendFormattedCommand(redisCtx, cmd, len)
Parameters:
- redisCtx - redis context
- cmd - the cmd string returned by redisFormatCommand
- len - the length returned by redisFormatCommand
Write a formatted command to the output buffer. Use these functions in blocking mode to get a pipeline of commands.
This function returns 0 on success.
redisCommand
syntax: reply, errstr = hiredis.redisCommand(redisCtx, cmd)
Parameters:
- redisCtx - redis context
- cmd - the command string sent to redis
Issue a command to Redis server.
This function returns reply on success, or returns nil and a string describing the error otherwise.
redisConnect
syntax: redisCtx, errstr = hiredis.redisConnect(ip, port)
Parameters:
- ip - redis server host IP string
- port - redis server port
Connect to a Redis instance.
This function returns redisCtx on success, or returns nil and a string describing the error otherwise.
redisConnectUnix
syntax: redisCtx, errstr = hiredis.redisConnectUnix(path)
Parameters:
- path - domain socket path
Connect to a Redis instance.
This function returns redisCtx on success, or returns nil and a string describing the error otherwise.
redisConnectUnixWithTimeout
syntax: redisCtx, errstr = hiredis.redisConnectUnixWithTimeout(path, tv)
Parameters:
- path - domain socket path
- tv - connect timeout value
Same as the redisConnectUnix function, but with an additional connection timeout parameter.
redisConnectWithTimeout
syntax: redisCtx, errstr = hiredis.redisConnectWithTimeout(ip, port, tv)
Parameters:
- ip - redis server host IP string
- port - redis server port
- tv - connect timeout value
Same as the redisConnect function, but with an additional connection timeout parameter.
redisEnableKeepAlive
syntax: rc = hiredis.redisEnableKeepAlive(redisCtx)
Parameters:
- redisCtx - redis context
Enable connection KeepAlive.
This function returns 0 on success.
redisFormatCommand
syntax: rc, target = hiredis.redisFormatCommand(format)
Parameters:
- format - command string
Format a command according to the Redis protocol. returns the formatted value.
This function returns 0 and target on success.
redisFormatCommandArgv
syntax: rc, target = hiredis.redisFormatCommandArgv(argc, argv, argvlen)
Parameters:
- argc - number of command arrays
- argv - command arrays
- argvlen - command string length array
Format a command according to the Redis protocol. This function takes the number of arguments, an array with arguments and an array with their lengths. If the latter is set to NULL, strlen will be used to compute the argument lengths.
This function returns 0 and target on success.
redisFree
syntax: hiredis.redisFree(redisCtx)
Parameters:
- redisCtx - redis context object
release redis context object.
redisFreeCommand
syntax: hiredis.redisFreeCommand(cmd)
Parameters:
- cmd - return value of redisFormatCommandArgv & redisFormatCommand
release cmd string memory.
redisGetFromPool
syntax: redisCtx, errstr = hiredis.redisGetFromPool(key)
Parameters:
- key - string key
Get redis context from the connection pool based on key.
This function returns redisCtx on success, or returns nil and a string describing the error otherwise.
redisGetReply
syntax: reply, errstr = hiredis.redisGetReply(redisCtx)
Parameters:
- redisCtx - redis context
this function first checks if there are unconsumed replies to return and returns one if so. Otherwise, it flushes the output buffer to the socket and reads until it has a reply.
This function returns reply on success, or returns nil and a string describing the error otherwise.
redisGetReplyFromReader
syntax: reply, errstr = hiredis.redisGetReplyFromReader(redisCtx)
Parameters:
- redisCtx - redis context
Same as redisGetReply.
This function returns reply on success, or returns nil and a string describing the error otherwise.
redisGetReusedTimes
syntax: num, errstr = hiredis.redisGetReusedTimes(redisCtx)
Parameters:
- redisCtx - redis context
Returns the number of times the current redisCtx has been reused.
This function returns num on success, or returns nil and a string describing the error otherwise.
redisInitOpenSSL
syntax: rc = hiredis.redisInitOpenSSL()
Helper function to initialize the OpenSSL library.
This function always returns 0.
redisInitiateSSLWithContext
syntax: rc, errstr = hiredis.redisInitiateSSLWithContext(redisCtx, redis_ssl_ctx)
Parameters:
- redisCtx - redis context
- redis_ssl_ctx - redis ssl context
Initiate SSL on an existing redisContext.
This is similar to redisInitiateSSL() but does not require the caller to directly interact with OpenSSL, and instead uses a redisSSLContext previously created using redisCreateSSLContext().
This function returns 0 on success, or returns nil and a string describing the error otherwise.
redisPutToPool
syntax: ok, errstr = hiredis.redisPutToPool(redisCtx, pool_name, pool_size, timeout)
Parameters:
- redisCtx - redis context
- pool_name - pool key string
- pool_size - connection pool size
- timeout - how long does it take to time out after being placed in the connection pool
Put redis context in the connection pool.
This function returns true on success, or returns nil and a string describing the error otherwise.
redisSSLContextGetError
syntax: err = hiredis.redisSSLContextGetError(err)
Parameters:
- err - ssl error code
Return the error message corresponding with the specified error code.
redisSetTimeout
syntax: rc = hiredis.redisSetTimeout(redisCtx, timeout)
Parameters:
- redisCtx - redis context
- timeout - command timeout
Set command send and receive timeout values.
This function returns 0 on success.
redisSetTimeouts
syntax: ok = hiredis.redisSetTimeouts(connect_timeout, read_timeout, write_timeout)
Parameters:
- connect_timeout - connect timeout
- read_timeout - read reply timeout
- write_timeout - send command timeout
Set connect/read/send timeout.
This function returns true on success.
Installation
You need to configure the lua_package_path directive to add the path of your lua-resty-hiredis source tree to ngx_lua’s LUA_PATH search path, as in
# nginx.conf
http {
lua_package_path "/path/to/lua-resty-hiredis/lib/?.lua;;";
...
}
Ensure that the system account running your Nginx ‘‘worker’’ processes have
enough permission to read the .lua file.
TODO
Copyright and License
Copyright (C) 2022 by OpenResty Inc. All rights reserved.
License: Proprietary.