bluto

README

Bluto

Bluto is a golang implementation of Redis client based on Redigo. The client manages a connection pool for each node and uses goroutine to execute as concurrently as possible, leading to its high efficiency and low latency.

Supported:

• Most commands of keys, strings, lists, sets, sorted sets, and hashes.

Documentation

API Reference

Installation

Install Bluto with go tool:

    go get -u github.com/alibaba-go/bluto/...

Usage

To use Redis cluster, you need to import the package and create a new Bluto client with a config:

import "https://github.com/alibaba-go/bluto"

bluto, err := bluto.New(
    &bluto.config{
    Address:              "localhost:6379",
    Password              "password"
    ConnectTimeoutSeconds: 10,
    ReadTimeoutSeconds:    10,
    })

Basic

Bluto gives you a commander by calling Borrow(), an interface to run Redis commands (GET, SELECT, etc.) over a Redis connection pool that simplifies all the pool's management.

RESTRICTION:

• The first argument of the command should be a result.
• All commands should end with Commit().
• Optional arguments are passed as variadic args.

See full redis commands:

bluto.Borrow().Set(&setResult, "key", "value", SetOptionKEEPTTL{}).Commit()
bluto.Borrow().Get(&getResult, "key").Commit()
bluto.Borrow().Incr(&incrResult, "key").Commit()

You can also chain redis commands like this:

bluto.Borrow().Select(&selectResult, 2).Set(&setResult, "key", "value",SetOptionKEEPTTL{}).Incr(&incrResult, "key").Commit()
bluto.Borrow().Select(&selectResult, 2).Get(&getResult, "key").Decr(&decrResult, "key").Del(&delResult, "key").Commit()

Also, you can use Values and Scan to convert replies to multiple values with different types.

Command's Options

You can pass options as variadic args as last arguments. The Option for each command is an interface that is satisfied by defined option structs. You can pass multiple options like this:

bluto.Borrow().Set(&setResult, "key", "value", SetOptionEX{EX:1}, SetOptionNX{}, SetOptionKEEPTTL{}).Commit()

For more advanced examples look at example

Contributing

See CONTRIBUTING.md.

Contact

Bug reports and feature requests are welcome. If you have any question, please email us at rd@alibaba.ir.

License

Released under MIT License

Documentation

Overview

Package bluto is redis library wrapper over redigo which adds type safety, chained commands and managed connection pool which makes it easier for developers to use the library and reduce runtime bugs.

bluto instance is completely thread-safe which means you can pass bluto objects to different goroutines without race condition, it also automatically returns finished connections to connection pool.

pool also supports config for connections like timeout and health-check for better management.

commander is borrowed from bluto instance which can be used to chain multiple commands together and run all of them with commit. This chaining reduces the time when the connection is kept so it improves the pool connection reuse latency.

Example (CommandChain)

package main

import (
	"fmt"
	"log"

	"github.com/alibaba-go/bluto/bluto"
	"github.com/alibaba-go/bluto/commander"
)

func main() {
	bluto, _ := bluto.New(bluto.Config{
		Address:               "localhost:6379",
		ConnectTimeoutSeconds: 10,
		ReadTimeoutSeconds:    10,
	})
	defer bluto.ClosePool()

	key1 := "SomeKey"
	key2 := "Other"
	var selectResult string
	var setResult1 string
	var setResult2 string
	var keysResult []string
	var delResult int
	var getResult1 int
	var getResult2 int
	var flushResult string

	errCmd := bluto.Borrow().
		Select(&selectResult, 0).
		Set(&setResult1, key1, 9, commander.SetOptionNX{}, commander.SetOptionEX{EX: 2}).
		Set(&setResult2, key2, 9).
		Keys(&keysResult, "*Key*").
		Del(&delResult, key1, "NotExistKey").
		Get(&getResult1, key1).
		FlushAll(&flushResult, commander.FlushAllOptionAsync{}).
		Get(&getResult2, key2).
		Commit()
	if errCmd != nil {
		log.Fatal(errCmd)
	}

	fmt.Println(keysResult)

}

Output:

[SomeKey]

Example (Scanner)

package main

import (
	"fmt"
	"log"

	"github.com/alibaba-go/bluto/bluto"
	"github.com/alibaba-go/bluto/commander"
	"github.com/gomodule/redigo/redis"
)

// Fields are the properties of each consumed message
type Fields struct {
	Key string `redis:"Key"`
}

// Message represents each consumed message
type Message struct {
	ID     string
	Fields *Fields
}

// RedisScan is the redis.Scanner interface implementation
func (m *Message) RedisScan(src interface{}) error {

	message, err := redis.Values(src, nil)
	if err != nil {
		return err
	}
	messageID, err := redis.String(message[0], nil)
	if err != nil {
		return err
	}
	m.ID = messageID
	msgFieldDetails, err := redis.Values(message[1], nil)
	if err != nil {
		return err
	}
	var msgField Fields
	err = redis.ScanStruct(msgFieldDetails, &msgField)
	if err != nil {
		return err
	}

	m.Fields = &msgField
	return nil
}

// Stream represents each stream
type Stream struct {
	Name     string
	Messages []*Message
}

// RedisScan is the redis.Scanner interface implementation
func (s *Stream) RedisScan(src interface{}) error {

	stream, err := redis.Values(src, nil)
	if err != nil {
		return err
	}

	name, err := redis.String(stream[0], nil)
	if err != nil {
		return err
	}
	s.Name = name

	messages, err := redis.Values(stream[1], nil)
	if err != nil {
		return err
	}

	for i := range messages {
		message := messages[i]
		msgDetails, err := redis.Values(message, nil)
		if err != nil {
			return err
		}

		msgID, err := redis.String(msgDetails[0], nil)
		if err != nil {
			return err
		}

		msgFieldDetails, err := redis.Values(msgDetails[1], nil)
		if err != nil {
			return err
		}
		var msgField Fields
		err = redis.ScanStruct(msgFieldDetails, &msgField)
		if err != nil {
			return err
		}

		s.Messages = append(s.Messages, &Message{
			ID:     msgID,
			Fields: &msgField,
		})
	}
	return nil
}

func main() {
	bluto, _ := bluto.New(bluto.Config{
		Address:               "localhost:6379",
		ConnectTimeoutSeconds: 10,
		ReadTimeoutSeconds:    10,
	})
	defer bluto.ClosePool()

	groupName := "testGroup"
	consumerName := "testConsumer"
	key := "SomeKey"
	var flushResult string
	var xgroupCreateResult string
	var xaddResult string
	var xreadgroupResult []Stream

	err := bluto.Borrow().FlushAll(&flushResult).Commit()
	if err != nil {
		log.Panic(err)
	}
	err = bluto.Borrow().XGroupCreate(&xgroupCreateResult, "testStream", groupName, "0-0", commander.XGroupCreateOptionMKStream{}).Commit()
	if err != nil {
		log.Panic(err)
	}
	err = bluto.Borrow().XAdd(&xaddResult, "testStream", "*", &Fields{Key: key}).Commit()
	if err != nil {
		log.Panic(err)
	}
	err = bluto.Borrow().XReadGroup(&xreadgroupResult, groupName, consumerName, []string{"testStream"}, []string{">"}).Commit()
	if err != nil {
		log.Panic(err)
	}

	fmt.Println(xreadgroupResult[0].Messages[0].Fields.Key)

}

Output:

SomeKey