Merge branch 'release/0.10'

.gitignore

@@ -1,2 +1,3 @@
 t/servroot/
 t/error.log
+luacov.*

.luacov

@@ -0,0 +1,5 @@
+modules = {
+    ["resty.qless"] = "lib/resty/qless.lua",
+    ["resty.qless.*"] = "lib",
+    ["resty.qless.reserver.*"] = "lib",
+}

Makefile

@@ -7,7 +7,7 @@ INSTALL ?= install
 TEST_FILE ?= t
 
 TEST_REDIS_PORT ?= 6379
-TEST_REDIS_DATABASE ?= 1
+TEST_REDIS_DATABASE ?= 6
 
 REDIS_CLI	:= redis-cli -p $(TEST_REDIS_PORT) -n $(TEST_REDIS_DATABASE)
 
@@ -20,7 +20,10 @@ install: all
 			$(INSTALL) lib/resty/qless/*.lua $(DESTDIR)/$(LUA_LIB_DIR)/resty/qless/
 
 test: all
+		util/lua-releng
 		-@echo "Flushing Redis DB"
 		@$(REDIS_CLI) flushdb
+		@rm -f luacov.stats.out
 		PATH=$(OPENRESTY_PREFIX)/nginx/sbin:$$PATH TEST_REDIS_DATABASE=$(TEST_REDIS_DATABASE) TEST_REDIS_PORT=$(TEST_REDIS_PORT) TEST_NGINX_NO_SHUFFLE=1 prove -I../test-nginx/lib -r $(TEST_FILE)
-		#util/lua-releng
+		@luacov
+		@tail -14 luacov.report.out

README.md

@@ -21,7 +21,7 @@ Requirements
 
 * Redis >= 2.8.x
 * OpenResty >= 1.9.x
-* [lua-resty-redis-connector](https://github.com/pintsized/lua-resty-redis-connector) >= 0.03
+* [lua-resty-redis-connector](https://github.com/pintsized/lua-resty-redis-connector) >= 0.04
 
 
 Philosophy and Nomenclature
@@ -72,24 +72,44 @@ Features
   completed, failed, put, popped, etc. Use these events to get notified of
   progress on jobs you're interested in.
 
-Enqueing Jobs
+Connecting
 =============
 First things first, require `resty.qless` and create a client, specifying your Redis connection details.
 
 ```lua
-local resty_qless = require "resty.qless"
-
--- Default parameters shown below.
-local qless = resty_qless.new({
-    -- host = "127.0.0.1",
-    -- port = 6379,
-    -- connect_timeout = 100,
-    -- read_timeout = 5000,
-    -- keepalive_timeout = nil,
-    -- keepalive_poolsize = nil,
+local qless = require("resty.qless").new({
+    host = "127.0.0.1",
+    port = 6379,
+})
+```
+
+Parameters passed to `new` are forwarded to [lua-resty-redis-connector](https://github.com/pintsized/lua-resty-redis-connector). Please review the documentation there for connection options, including how to use Redis Sentinel etc.
+
+Additionally, if your application has a Redis connection that you wish to reuse, there are two ways you can integrate this:
+
+1) Using an already established connection directly
+
+```lua
+local qless = require("resty.qless").new({
+    redis_client = my_redis,
+})
+```
+
+2) Providing callbacks for connecting and closing the connection
+
+```lua
+local qless = require("resty.qless").new({
+    get_redis_client = my_connection_callback,
+    close_redis_client = my_close_callback,
 })
 ```
 
+When finished with Qless, you should call `qless:set_keepalive()` which will attempt to put Redis back on the keepalive pool, either using settings you provide directly, or via parameters sent to `lua-resty-redis-connector`, or by calling your `close_redis_client` callback.
+
+
+Enqueing Jobs
+=============
+
 Jobs themselves are modules, which must be loadable via `require` and provide a `perform` function, which accepts a single `job` argument.
 
 

dist.ini

@@ -7,4 +7,4 @@ lib_dir=lib
 doc_dir=lib
 repo_link=https://github.com/pintsized/lua-resty-qless
 main_module=lib/resty/qless.lua
-requires=luajit, openresty/lua-resty-redis, pintsized/lua-resty-redis-connector >= 0.03
+requires=luajit, openresty/lua-resty-redis, pintsized/lua-resty-redis-connector >= 0.04

lib/resty/qless.lua

@@ -1,5 +1,4 @@
 local ffi = require "ffi"
-local redis_mod = require "resty.redis"
 local redis_connector = require "resty.redis.connector"
 local cjson = require "cjson"
 
@@ -59,10 +58,19 @@ local function gethostname()
 end
 
 
-local DEFAULT_REDIS_PARAMS = {
-    host = "127.0.0.1",
-    port = 6379,
-}
+--  1)  if `params.redis_client` exists and is not an empty table, return this
+--      pre-connected redis_client
+--  2) if `params.get_redis_client` exists and is a function, call this function
+--      to return a connected redis instance.
+--
+--  Otherwise lua-resty-redis-connector is used to create a new connection.
+local function get_existing_redis_connection(params)
+    if params.redis_client and next(params.redis_client) then
+        return params.redis_client
+    elseif type(params.get_redis_client) == "function" then
+        return params.get_redis_client()
+    end
+end
 
 
 -- Jobs, to be accessed via qless.jobs.
@@ -190,25 +198,24 @@ local _events_mt = { __index = _events }
 
 
 function _events.new(params)
-    local redis, err
+    -- First try to pull an existing connection from the params
+    local redis = get_existing_redis_connection(params)
 
-    if not params then params = {} end
-    setmetatable(params, { __index = DEFAULT_REDIS_PARAMS })
+    -- If not, use redis connector to create one
+    local rc
+    if not redis then
+        local err
+        rc, err = redis_connector.new(params)
+        if not rc then return nil, err end
 
-    if params.redis_client then
-        redis = params.redis_client
-    else
-        local rc = redis_connector.new()
-        redis, err = rc:connect(params)
+        redis, err = rc:connect()
+        if not redis then return nil, err end
     end
 
-    if not redis then
-        return nil, err
-    else
-        return setmetatable({
-            redis = redis,
-        }, _events_mt)
-    end
+    return setmetatable({
+        redis = redis,
+        redis_connector = rc,
+    }, _events_mt)
 end
 
 
@@ -238,49 +245,43 @@ end
 
 
 local _M = {
-    _VERSION = '0.09',
+    _VERSION = '0.10',
 }
 
 local mt = { __index = _M }
 
 
-function _M.new(params, options)
-    local redis, err
+function _M.new(params)
+    -- First try to pull an existing connection from the params
+    local redis = get_existing_redis_connection(params)
 
-    if params.redis_client then
-        redis = params.redis_client
-    else
-        local rc = redis_connector.new()
-        if options then
-            if options.connect_timeout then
-                rc:set_connect_timeout(options.connect_timeout)
-            end
-            if options.read_timeout then
-                rc:set_read_timeout(options.read_timeout)
-            end
-            if options.connection_options then
-                rc:set_connection_options(options.connection_options)
-            end
-        end
+    -- If not, use redis connector to create one
+    local rc
+    if not redis then
+        local err
+        rc, err = redis_connector.new(params)
+        if not rc then return nil, err end
 
-        redis, err = rc:connect(params)
+        redis, err = rc:connect()
+        if not redis then return nil, err end
     end
 
-    if not redis then
-        return nil, err
-    else
-        local self = setmetatable({
-            redis = redis,
-            worker_name = gethostname() .. "-nginx-" .. ngx_worker_pid() .. "-" .. ngx_worker_id(),
-            luascript = qless_luascript.new("qless", redis),
-        }, mt)
+    local worker_name = gethostname() .. "-nginx-" ..
+        tostring(ngx_worker_pid()) .. "-" .. tostring(ngx_worker_id())
 
-        self.workers = _workers.new(self)
-        self.queues = _queues.new(self)
-        self.jobs = _jobs.new(self)
+    local self = setmetatable({
+        params = params,
+        redis = redis,
+        redis_connector = rc,
+        worker_name = worker_name,
+        luascript = qless_luascript.new("qless", redis),
+    }, mt)
 
-        return self
-    end
+    self.workers = _workers.new(self)
+    self.queues = _queues.new(self)
+    self.jobs = _jobs.new(self)
+
+    return self
 end
 
 
@@ -289,9 +290,36 @@ function _M.events(params)
 end
 
 
-function _M.redis_close(self)
-    self.redis:set_keepalive()
+local function set_keepalive(self, keepalive_timeout, keepalive_poolsize)
+    local redis = self.redis
+    if not redis or not redis.set_keepalive then
+        return nil, "redis is not connected"
+    end
+
+    local params = self.params
+
+    -- If we're given params, close the redis connection directly
+    if keepalive_timeout or keepalive_poolsize then
+        return redis:set_keepalive(
+            keepalive_timeout,
+            keepalive_poolsize
+        )
+    elseif params.close_redis_client and
+        type(params.close_redis_client == "function") then
+
+        -- Use the callback given to us
+        return params.close_redis_client(redis)
+    elseif self.redis_connector then
+        -- Use redis connector keepalive params (or defaults)
+        return self.redis_connector:set_keepalive(redis)
+    else
+        -- Just use system defaults
+        return redis:set_keepalive()
+    end
 end
+_M.set_keepalive = set_keepalive
+_events.set_keepalive = set_keepalive
+_M.redis_close = set_keepalive  -- maintain backwards compatability
 
 
 function _M.generate_jid(self)

lib/resty/qless/job.lua

@@ -10,7 +10,7 @@ local cjson_decode = cjson.decode
 
 
 local _M = {
-    _VERSION = '0.09',
+    _VERSION = '0.10',
 }
 
 local mt = {

lib/resty/qless/luascript.lua

@@ -12,7 +12,7 @@ local io_open = io.open
 
 
 local _M = {
-    _VERSION = '0.09',
+    _VERSION = '0.10',
 }
 
 local mt = { __index = _M }

lib/resty/qless/queue.lua

@@ -48,7 +48,7 @@ end
 
 
 local _M = {
-    _VERSION = '0.09',
+    _VERSION = '0.10',
 }
 
 

lib/resty/qless/recurring_job.lua

@@ -10,7 +10,7 @@ local cjson_decode = cjson.decode
 
 
 local _M = {
-    _VERSION = '0.09',
+    _VERSION = '0.10',
 }
 
 local mt = {

lib/resty/qless/reserver/ordered.lua

@@ -4,7 +4,7 @@ local ngx_ERR = ngx.ERR
 local ngx_INFO = ngx.INFO
 
 local _M = {
-    _VERSION = '0.09',
+    _VERSION = '0.10',
 }
 
 local mt = { __index = _M }

lib/resty/qless/reserver/round_robin.lua

@@ -4,7 +4,7 @@ local ngx_ERR = ngx.ERR
 local ngx_INFO = ngx.INFO
 
 local _M = {
-    _VERSION = '0.09',
+    _VERSION = '0.10',
 }
 
 local mt = { __index = _M }

lib/resty/qless/reserver/shuffled_round_robin.lua

@@ -5,7 +5,7 @@ local math_random = math.random
 local math_randomseed = math.randomseed
 
 local _M = {
-    _VERSION = '0.09',
+    _VERSION = '0.10',
 }
 
 local mt = { __index = _M }