cacheadapters

README

Golang Cache Adapters

A set of Cache Adapters for various distributed systems (like Redis) written in Go.

Supported CacheAdapter implementations

• Redis -> using github.com/gomodule/redigo

Library reference

Just check the GoDocs

Install

Just use the standard way

go get github.com/tryvium-travels/golang-cache-adapters

or use go modules, it should take care of this automagically.

Usage

The CacheAdapter interface offers 2 main ways to access a cache: Get and Set methods. You can also use InTransaction function when you need to perform multiple operations in the same session.

You can use Delete and SetTTL functions as well. For more info, check the docs.

This example creates a new RedisAdapter and uses it, but you can replace it with any of the other supported Adapters.

package cacheadapters_test

import (
	"log"
	"time"

	"github.com/gomodule/redigo/redis"
	cacheadapters "github.com/tryvium-travels/golang-cache-adapters"
	rediscacheadapters "github.com/tryvium-travels/golang-cache-adapters/redis"
)

func main() {
	redisURI := "rediss://my-redis-instance-uri:port"

	myRedisPool := &redis.Pool{
		Dial: func() (redis.Conn, error) {
			// obtain a redis connection, there
			// are plenty of ways to do that.
			return redis.DialURL(redisURI)
		},
	}

	exampleTTL := time.Hour

	adapter, err := rediscacheadapters.New(myRedisPool, exampleTTL)
	if err != nil {
		// remember to check for errors
		log.Fatalf("Adapter initialization error: %s", err)
	}

	type exampleStruct struct {
		Value string
	}

	exampleKey := "a:redis:key"

	var exampleValue exampleStruct
	err = adapter.Get(exampleKey, &exampleValue)
	if err != nil {
		// remember to check for errors
		log.Fatalf("adapter.Get error: %s", err)
	}

	exampleKey = "another:redis:key"

	// nil TTL represents the default value put in the New function
	err = adapter.Set(exampleKey, exampleValue, nil)
	if err != nil {
		// remember to check for errors
		log.Fatalf("adapter.Get error: %s", err)
	}

	results := []interface{}{
		&exampleValue,
		nil,
	}

	// use InTransaction when you need to perform multiple operations
	// in the same session.
	err = adapter.InTransaction(func(session cacheadapters.CacheSessionAdapter) error {
		err = adapter.Get(exampleKey, nil)
		if err != nil {
			return err
		}

		exampleValue.Value = "2"

		err = session.Set(exampleKey, exampleValue, nil)
		if err != nil {
			return err
		}

		return nil
	}, results)
}

Contributing

First of all, thank you!

To contribute to our project:

1. Open an Issue signaling bugs or proposals using the provided templates
2. If you are going to add a new adapter, please stick to the NAMING CONVENTION for branch, package, folder, file and adapter names.
3. We require a total test coverage (100%) if we are going to accept a new adapter, we can help you if you have any difficulties to achieve that.
4. Please be polite in issue and PR discussions and do not offend other people.

Naming Convention

The following naming convention applies if you want to contribute:

1. Branch name should follow the following form

   adapters/{{ADAPTER_NAME}}-#{{GITHUB_ISSUE_ID}}

   Example branch name: adapters/redis-#1

2. If you add a new adapter:

   The name of the folder must match the lowercase adapter name (e.g. redis/mongodb/memcached)

   We strongly suggest you to create an adapter and a session_adapter go file, although it is not required.

   Example file names:

   redis_adapter.go and redis_session_adapter.go

   Example test file names:

   redis_adapter_test.go and redis_session_adapter_test.go.

   There must also be test files with 100% test coverage.

Documentation

Index

• Constants
• Variables
• type CacheAdapter
• type CacheSessionAdapter
• type InTransactionFunc

Constants

const TTLExpired time.Duration = 0

Variables

var (
	//ErrInvalidConnection will come out if you try to use an invalid connection in a session.
	ErrInvalidConnection = fmt.Errorf("cannot use an invalid connection")
	// ErrNotFound will come out if a key is not found in the cache.
	ErrNotFound = fmt.Errorf("the value tried to get has not been found, check if it may be expired")
	// ErrGetRequiresObjectReference will come out if a nil object
	// reference is passed in a Get operation.
	ErrGetRequiresObjectReference = fmt.Errorf("in Get operations it is mandatory to provide a non-nil object reference to store the result in, nil found")
	// ErrInTransactionObjectReferencesLengthMismatch will come out
	// if there is a mismatch in number of commands in the transaction
	// and the length of the object references array.
	ErrInTransactionObjectReferencesLengthMismatch = fmt.Errorf("in InTransactions you must provide an array of reference objects with length equal to the number of commands you call in the transaction")
	// ErrInTransactionMarshalValue will come out if a nil object value is parsed
	// from the cache transaction and at the same index of reference objects you
	// are expecting to put a value.
	ErrInTransactionMarshalValue = fmt.Errorf("in InTransaction you must provide an array that matches nil return values from cache into your reference objects array")
	// ErrNoNestedTransactions will come out if you try to call session.Intransaction inside
	// a transactionFunc.
	ErrNoNestedTransactions = fmt.Errorf("you cannot nest multiple InTransaction calls")
	// ErrInvalidTTL will come out if you try to set a zero-or-negative
	// TTL in a Set operation.
	ErrInvalidTTL = fmt.Errorf("cannot provide a negative TTL to Set operations")
)

Types

type CacheAdapter

type CacheAdapter interface {
	// OpenSession opens a new Cache Session.
	OpenSession() (CacheSessionAdapter, error)
	// contains filtered or unexported methods
}

CacheAdapter represents a Cache Mechanism abstraction.

type CacheSessionAdapter

type CacheSessionAdapter interface {
	// Close closes the Cache Session.
	Close() error
	// contains filtered or unexported methods
}

CacheSessionAdapter represents a Cache Session Mechanism abstraction.

type InTransactionFunc

type InTransactionFunc func(adapter CacheSessionAdapter) error

InTransactionFunc is a function executed inside an InTransaction calls of CacheAdapter and CacheSessionAdapter objects.