redis.go

/*
Package redis provides a Hord database driver for Redis.

Redis is an open-source, in-memory data structure store that can be used as a database, cache, and message broker. To use this driver, import it as follows:

	import (
	    "github.com/madflojo/hord"
	    "github.com/madflojo/hord/redis"
	)

# Connecting to the Database

Use the Dial() function to create a new client for interacting with Redis.

	var db hord.Database
	db, err := redis.Dial(redis.Config{})
	if err != nil {
	    // Handle connection error
	}

# Initialize database

Hord provides a Setup() function for preparing a database. This function is safe to execute after every Dial().

	err := db.Setup()
	if err != nil {
	    // Handle setup error
	}

# Database Operations

Hord provides a simple abstraction for working with Redis, with easy-to-use methods such as Get() and Set() to read and write values.

	// Connect to the Redis database
	db, err := redis.Dial(redis.Config{})
	if err != nil {
	    // Handle connection error
	}

	err := db.Setup()
	if err != nil {
	    // Handle setup error
	}

	// Set a value
	err = db.Set("key", []byte("value"))
	if err != nil {
	    // Handle error
	}

	// Retrieve a value
	value, err := db.Get("key")
	if err != nil {
	    // Handle error
	}
*/
package redis

import (
	"crypto/tls"
	"fmt"
	"github.com/FZambia/sentinel"
	"github.com/gomodule/redigo/redis"
	"github.com/madflojo/hord"
	"time"
)

// Config provides configuration options for connecting to and controlling the behavior of Redis.
type Config struct {
	// ConnectTimeout is used to specify a global connection timeout value.
	ConnectTimeout time.Duration

	// Database specifies the Redis database to connect to and use. If not set, default is 0.
	Database int

	// IdleTimeout will close idle connections that have remained idle beyond the specified time duration.
	IdleTimeout time.Duration

	// KeepAlive defines the TCP Keep-Alive interval for Redis connections. By default this set to 5 minutes, this
	// setting is useful for detecting TCP sessions that are stale.
	KeepAlive time.Duration

	// MaxActive is the maximum number of connections that can be allocated and used for the Redis connection pool.
	MaxActive int

	// MaxConnLifetime will set a maximum lifespan for connections. This setting will close connections in the pool
	// after the time duration is exceeded, regardless of whether the connection is active or not.
	MaxConnLifetime time.Duration

	// MaxIdle sets the maximum number of idle connections the Redis connection pool will allow.
	MaxIdle int

	// Password specifies the AUTH token to be used for Redis Authentication.
	Password string

	// ReadTimeout is used to specify a global read timeout for each Redis command.
	ReadTimeout time.Duration

	// SentinelConfig is used to configure Sentinel connection details. If not using Redis Sentinel or Discovery
	// Service, leave this blank.
	SentinelConfig SentinelConfig

	// Server specifies the Redis Server to connect to. If using Redis Sentinel or Discovery Service leave this
	// blank.
	Server string

	// SkipTLSVerify will disable the TLS hostname checking. Warning, using this setting opens the risk of
	// man-in-the-middle attacks.
	SkipTLSVerify bool

	// TLSConfig allows users to specify TLS settings for connecting to Redis. This is a standard TLS configuration
	// and can be used to configure 2-way TLS for Redis and Redis Sentinel.
	TLSConfig *tls.Config

	// WriteTimeout is used to specify a global write timeout for each Redis command.
	WriteTimeout time.Duration
}

// SentinelConfig can be used to configure the Redis client to connect using Redis Sentinel or Enterprise Redis
// Discovery Service.
type SentinelConfig struct {
	// Servers is a list of Sentinel servers to connect to and use for master discovery.
	Servers []string

	// Master is the name of the Redis master that the Sentinel Servers monitor.
	Master string
}

// Database is used to interface with Redis. It also satisfies the Hord Database interface.
type Database struct {
	// config holds the initial Redis configuration used to create this Database instance.
	config Config

	// pool is the Redis connection pool
	pool *redis.Pool

	// sentinel holds the Redis sentinel connections
	sentinel *sentinel.Sentinel
}

// Dial will establish a Redis connection pool using the configuration provided. It provides back an interface that
// satisfies the hord.Database interface.
func Dial(conf Config) (*Database, error) {
	db := &Database{
		config: conf,
	}

	// Verify that Either Server or Sentinel Servers is set
	if db.config.Server == "" && len(db.config.SentinelConfig.Servers) == 0 {
		return db, fmt.Errorf("must specify either a Redis Server or Sentinel Pool")
	}

	// Setup Redis DailOptions
	opts := []redis.DialOption{}
	opts = append(opts, redis.DialConnectTimeout(db.config.ConnectTimeout))
	opts = append(opts, redis.DialDatabase(db.config.Database))
	opts = append(opts, redis.DialKeepAlive(db.config.KeepAlive))
	opts = append(opts, redis.DialPassword(db.config.Password))
	opts = append(opts, redis.DialReadTimeout(db.config.ReadTimeout))
	opts = append(opts, redis.DialWriteTimeout(db.config.WriteTimeout))
	if db.config.TLSConfig != nil {
		opts = append(opts, redis.DialUseTLS(true), redis.DialTLSConfig(db.config.TLSConfig))
		opts = append(opts, redis.DialTLSSkipVerify(db.config.SkipTLSVerify))
	}

	// If Sentinel is set, let's connect
	if len(db.config.SentinelConfig.Servers) > 0 {
		if db.config.SentinelConfig.Master == "" {
			return nil, fmt.Errorf("if using Sentinel the Redis Master must be defined")
		}
		db.sentinel = &sentinel.Sentinel{
			Addrs:      db.config.SentinelConfig.Servers,
			MasterName: db.config.SentinelConfig.Master,
			Dial: func(addr string) (redis.Conn, error) {
				c, err := redis.Dial("tcp", addr, opts...)
				if err != nil {
					return nil, err
				}
				return c, nil
			},
		}
	}

	// Create a Redis Connection Pool
	db.pool = &redis.Pool{
		IdleTimeout:     db.config.IdleTimeout,
		MaxActive:       db.config.MaxActive,
		MaxConnLifetime: db.config.MaxConnLifetime,
		MaxIdle:         db.config.MaxIdle,
		Wait:            true,
		// Used to create new connections for the pool
		Dial: func() (redis.Conn, error) {
			var err error
			server := db.config.Server
			if db.sentinel != nil {
				server, err = db.sentinel.MasterAddr()
				if err != nil {
					return nil, err
				}
			}
			c, err := redis.Dial("tcp", server, opts...)
			if err != nil {
				return nil, err
			}
			return c, nil
		},
		// Used to Test the provided connection
		TestOnBorrow: func(c redis.Conn, _ time.Time) error {
			if !sentinel.TestRole(c, "master") {
				return fmt.Errorf("server is not a master")
			}
			_, err := c.Do("PING")
			if err != nil {
				return fmt.Errorf("connection is unhealthy, failed ping %s", err)
			}
			return nil
		},
	}

	// Execute HealthCheck to verify connectivity
	err := db.HealthCheck()
	if err != nil {
		return db, fmt.Errorf("connection is unhealthy, failed ping %s", err)
	}

	return db, nil
}

// Setup does nothing with Redis, this is only here to meet interface requirements.
func (db *Database) Setup() error {
	// Execute HealthCheck to verify connectivity
	err := db.HealthCheck()
	if err != nil {
		return fmt.Errorf("connection is unhealthy, failed ping %s", err)
	}
	return nil
}

// Get is called to retrieve data from the database. This function will take in a key and return
// the data or any errors received from querying the database.
func (db *Database) Get(key string) ([]byte, error) {
	if err := hord.ValidKey(key); err != nil {
		return nil, err
	}

	if db == nil || db.pool == nil {
		return nil, hord.ErrNoDial
	}

	c := db.pool.Get()
	defer c.Close()

	d, err := redis.Bytes(c.Do("GET", key))
	if err != nil && err != redis.ErrNil {
		return nil, fmt.Errorf("unable to fetch data from Redis - %s", err)
	}
	if err == redis.ErrNil {
		return []byte(""), hord.ErrNil
	}

	return d, nil
}

// Set is called when data within the database needs to be updated or inserted. This function will
// take the data provided and create an entry within the database using the key as a lookup value.
func (db *Database) Set(key string, data []byte) error {
	if err := hord.ValidKey(key); err != nil {
		return err
	}

	if err := hord.ValidData(data); err != nil {
		return err
	}

	if db == nil || db.pool == nil {
		return hord.ErrNoDial
	}

	c := db.pool.Get()
	defer c.Close()

	_, err := c.Do("SET", key, data)
	if err != nil {
		return fmt.Errorf("unable to write data to Redis - %s", err)
	}

	return nil
}

// Delete is called when data within the database needs to be deleted. This function will delete
// the data stored within the database for the specified key.
func (db *Database) Delete(key string) error {
	if err := hord.ValidKey(key); err != nil {
		return err
	}

	if db == nil || db.pool == nil {
		return hord.ErrNoDial
	}

	c := db.pool.Get()
	defer c.Close()

	_, err := c.Do("DEL", key)
	if err != nil {
		return fmt.Errorf("unable to remove key from Redis - %s", err)
	}

	return nil
}

// Keys is called to retrieve a list of keys stored within the database. This function will query
// the database returning all keys used within the hord database.
func (db *Database) Keys() ([]string, error) {
	if db == nil || db.pool == nil {
		return []string{}, hord.ErrNoDial
	}
	c := db.pool.Get()
	defer c.Close()

	keys, err := redis.Strings(c.Do("KEYS", "*"))
	if err != nil {
		return keys, fmt.Errorf("unable to fetch keys from Redis - %s", err)
	}

	return keys, nil
}

// HealthCheck is used to verify connectivity and health of the database. This function
// simply runs a generic ping against the database. If the ping errors in any fashion this
// function will return an error.
func (db *Database) HealthCheck() error {
	// Return error if pool is not created
	if db == nil || db.pool == nil {
		return hord.ErrNoDial
	}

	c := db.pool.Get()
	defer c.Close()

	_, err := c.Do("PING")
	if err != nil {
		return fmt.Errorf("unable to ping Redis - %s", err)
	}
	return nil
}

// Close will close all connections to Redis and clean up the pool.
func (db *Database) Close() {
	if db == nil || db.pool == nil {
		return
	}
	defer db.pool.Close()
	if db.sentinel != nil {
		defer db.sentinel.Close()
	}
}