Merge branch 'release/0.04'

Author: pintsized

.gitignore

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

.luacov

@@ -0,0 +1,4 @@
+modules = {
+    ["resty.redis.connector"] = "lib/resty/redis/connector.lua",
+    ["resty.redis.sentinel"] = "lib/resty/redis/sentinel.lua",
+}

Makefile

@@ -1,6 +1,6 @@
 SHELL := /bin/bash # Cheat by using bash :)
 
-OPENRESTY_PREFIX    = /usr/local/openresty-debug
+OPENRESTY_PREFIX    = /usr/local/openresty
 
 TEST_FILE          ?= t
 SENTINEL_TEST_FILE ?= $(TEST_FILE)/sentinel
@@ -141,8 +141,11 @@ check_ports:
 	@$(foreach port,$(REDIS_PORTS),! lsof -i :$(port) &&) true 2>&1 > /dev/null
 
 test_redis: flush_db
-	$(TEST_REDIS_VARS) $(PROVE) $(TEST_FILE)
 	util/lua-releng
+	@rm -f luacov.stats.out
+	$(TEST_REDIS_VARS) $(PROVE) $(TEST_FILE)
+	@luacov
+	@tail -7 luacov.report.out
 
 test_leak: flush_db
 	$(TEST_REDIS_VARS) TEST_NGINX_CHECK_LEAK=1 $(PROVE) $(TEST_FILE)

README.md

@@ -1,43 +1,88 @@
 # lua-resty-redis-connector
 
-Connection utilities for [lua-resty-redis](https://github.com/openresty/lua-resty-redis), making
-it easy and reliable to connect to Redis hosts, either directly or via
-[Redis Sentinel](http://redis.io/topics/sentinel).
+Connection utilities for [lua-resty-redis](https://github.com/openresty/lua-resty-redis), making it easy and reliable to connect to Redis hosts, either directly or via [Redis Sentinel](http://redis.io/topics/sentinel).
 
 
 ## Synopsis
 
+Quick and simple authenticated connection on localhost to DB 2:
+
 ```lua
-local redis_connector = require "resty.redis.connector"
-local rc = redis_connector.new()
+local redis, err = require("resty.redis.connector").new({
+    url = "redis://PASSWORD@127.0.0.1:6379/2",
+}):connect()
+```
 
-local redis, err = rc:connect{ url = "redis://PASSWORD@127.0.0.1:6379/2" }
+More verbose configuration, with timeouts and a default password:
 
--- or...
+```lua
+local rc = require("resty.redis.connector").new({
+    connect_timeout = 50,
+    read_timeout = 5000,
+    keepalive_timeout = 30000,
+    password = "mypass",
+})
 
-local redis, err = rc:connect{
+local redis, err = rc:connect({
+    url = "redis://127.0.0.1:6379/2",
+})
+
+-- ...
+
+local ok, err = rc:set_keepalive(redis)  -- uses keepalive params
+```
+
+Keep all config in a table, to easily create / close connections as needed:
+
+```lua
+local rc = require("resty.redis.connector").new({
+    connect_timeout = 50,
+    read_timeout = 5000,
+    keepalive_timeout = 30000,
+    
     host = "127.0.0.1",
     port = 6379,
     db = 2,
-    password = "PASSWORD",
-}
+    password = "mypass",
+})
+
+local redis, err = rc:connect()
 
-if not redis then
-    ngx.log(ngx.ERR, err)
-end
+-- ...
+
+local ok, err = rc:set_keepalive(redis)
 ```
 
+`connect` can be used to override defaults given in `new`
+
+
+```lua
+local rc = require("resty.redis.connector").new({
+    host = "127.0.0.1",
+    port = 6379,
+    db = 2,
+})
+
+local redis, err = rc:connect({
+    db = 5,
+})
+```
+
+
 ## DSN format
 
-The [connect](#connect) method accepts a single table of named arguments. If the `url` field is
-present then it will be parsed, overriding values supplied in the parameters table.
+If the `params.url` field is present then it will be parsed, overriding values supplied in the parameters table.
+
+### Direct Redis connections
 
 The format for connecting directly to Redis is:
 
 `redis://PASSWORD@HOST:PORT/DB`
 
 The `PASSWORD` and `DB` fields are optional, all other components are required.
 
+### Connections via Redis Sentinel
+
 When connecting via Redis Sentinel, the format is as follows:
 
 `sentinel://PASSWORD@MASTER_NAME:ROLE/DB`
@@ -48,53 +93,50 @@ Again, `PASSWORD` and `DB` are optional. `ROLE` must be any of `m`, `s` or `a`,
 * `s`: slave
 * `a`: any (first tries the master, but will failover to a slave if required)
 
+A table of `sentinels` must also be supplied. e.g.
 
-## Parameters
+```lua
+local redis, err = rc:connect{
+    url = "sentinel://mymaster:a/2",
+    sentinels = {
+        { host = "127.0.0.1", port = 26379" },
+    }
+}
+```
 
-The [connect](#connect) method expects the following field values, either by falling back to
-defaults, populating the fields by parsing the DSN, or being specified directly.
 
-The defaults are as follows:
+## Default Parameters
 
 
 ```lua
 {
+    connect_timeout = 100,
+    read_timeout = 1000,
+    connection_options = {}, -- pool, etc
+    keepalive_timeout = 60000,
+    keepalive_poolsize = 30,
+    
     host = "127.0.0.1",
     port = "6379",
-    path = nil, -- unix socket path, e.g. /tmp/redis.sock
+    path = "",  -- unix socket path, e.g. /tmp/redis.sock
     password = "",
     db = 0,
+    
     master_name = "mymaster",
-    role = "master", -- master | slave | any
-    sentinels = nil,
-}
-```
-
-Note that if `sentinel://` is supplied as the `url` parameter, a table of `sentinels` must also
-be supplied. e.g.
-
-```lua
-local redis, err = rc:connect{
-    url = "sentinel://mymaster:a/2",
-    sentinels = {
-        { host = "127.0.0.1", port = 26379" },
-    }
+    role = "master",  -- master | slave | any
+    sentinels = {},
 }
 ```
 
 
 ## API
 
 * [new](#new)
-* [set_connect_timeout](#set_connect_timeout)
-* [set_read_timeout](#set_read_timeout)
-* [set_connection_options](#set_connection_options)
 * [connect](#connect)
 * [Utilities](#utilities)
     * [connect_via_sentinel](#connect_via_sentinel)
     * [try_hosts](#try_hosts)
     * [connect_to_host](#connect_to_host)
-* [Sentinel Utilities](#sentinel-utilities)
     * [sentinel.get_master](#sentinelget_master)
     * [sentinel.get_slaves](#sentinelget_slaves)
 
@@ -106,38 +148,18 @@ local redis, err = rc:connect{
 Creates the Redis Connector object. In case of failures, returns `nil` and a string describing the error.
 
 
-### set_connect_timeout
-
-`syntax: rc:set_connect_timeout(100)`
-
-Sets the cosocket connection timeout, in ms.
-
-
-
-### set_read_timeout
-
-`syntax: rc:set_read_timeout(500)`
-
-Sets the cosocket read timeout, in ms.
-
-
-### set_connection_options
-
-`syntax: rc:set_connection_options({ pool = params.host .. ":" .. params.port .. "/" .. params.db })`
-
-Sets the connection options table, as supplied to [tcpsock:connect](https://github.com/openresty/lua-nginx-module#tcpsockconnect)
-method.
-
-
 ### connect
 
 `syntax: redis, err = rc:connect(params)`
 
-Attempts to create a connection, according to the [params](#parameters) supplied.
+Attempts to create a connection, according to the [params](#parameters) supplied. If a connection cannot be made, returns `nil` and a string describing the reason.
 
 
 ## Utilities
 
+The following methods are not typically needed, but may be useful if a custom interface is required.
+
+
 ### connect_via_sentinel
 
 `syntax: redis, err = rc:connect_via_sentinel(params)`
@@ -160,8 +182,6 @@ Tries the hosts supplied in order and returns the first successful connection.
 Attempts to connect to the supplied `host`.
 
 
-## Sentinel Utilities
-
 ### sentinel.get_master
 
 `syntax: master, err = sentinel.get_master(sentinel, master_name)`
@@ -176,11 +196,6 @@ Given a connected Sentinel instance and a master name, will return the current m
 Given a connected Sentinel instance and a master name, will return a list of registered slave Redis instances.
 
 
-## TODO
-
-* Redis Cluster support.
-
-
 # Author
 
 James Hurst <james@pintsized.co.uk>