cache

README

Cache

The Cache package in Go provides a unified, portable API for managing caches, enabling developers to write cache-related code once and transition seamlessly between different cache drivers with minimal reconfiguration. This approach simplifies both local testing and deployment to different environments.

Installation

go get -u github.com/bartventer/gocache

Supported Cache Implementations

Name	Author	Docs
Redis	go-redis/redis
Redis Cluster	go-redis/redis
Memcache	bradfitz/gomemcache
RAM Cache (in-memory)	bartventer/gocache

Note: More coming soon!

See the Contributing section if you would like to add a new cache implementation.

Usage

To use a cache implementation, import the relevant driver package and use the OpenCache function to create a new cache. The cache package will automatically use the correct cache driver based on the URL scheme. Each driver also provides a constructor function for manual initialization.

Redis

The redis package provides a Redis cache driver using the go-redis/redis client.

import (
    "context"
    "log"

    cache "github.com/bartventer/gocache"
    _ "github.com/bartventer/gocache/redis"
)

func main() {
    ctx := context.Background()
    urlStr := "redis://localhost:7000?maxretries=5&minretrybackoff=1s"
    c, err := cache.OpenCache(ctx, urlStr)
    if err != nil {
        log.Fatalf("Failed to initialize cache: %v", err)
    }
    // ... use c with the cache.Cache interface
}

Redis Constructor

You can create a Redis cache with redis.New:

import (
    "context"

    "github.com/bartventer/gocache/redis"
)

func main() {
    ctx := context.Background()
    c := redis.New(ctx, &redis.Options{
        RedisOptions: &redis.RedisOptions{
            Addr: "localhost:7000",
            MaxRetries: 5,
            MinRetryBackoff: 1 * time.Second,
        },
    })
    // ... use c with the cache.Cache interface
}

Redis Cluster

The rediscluster package provides a Redis Cluster cache driver using the go-redis/redis client.

import (
    "context"
    "log"

    cache "github.com/bartventer/gocache"
    _ "github.com/bartventer/gocache/rediscluster"
)

func main() {
    ctx := context.Background()
    urlStr := "rediscluster://localhost:7000,localhost:7001,localhost:7002?maxretries=5&minretrybackoff=1s"
    c, err := cache.OpenCache(ctx, urlStr)
    if err != nil {
        log.Fatalf("Failed to initialize cache: %v", err)
    }
    // ... use c with the cache.Cache interface
}

Redis Cluster Constructor

You can create a Redis Cluster cache with rediscluster.New:

import (
    "context"

    "github.com/bartventer/gocache/rediscluster"
)

func main() {
    ctx := context.Background()
    c := rediscluster.New(ctx, &rediscluster.Options{
        ClusterOptions: &rediscluster.ClusterOptions{
            Addrs: []string{"localhost:7000", "localhost:7001", "localhost:7002"},
            MaxRetries: 5,
            MinRetryBackoff: 1 * time.Second,
        },
    })
    // ... use c with the cache.Cache interface
}

Memcache

The memcache package provides a Memcache cache driver using the bradfitz/gomemcache client.

import (
    "context"
    "log"

    cache "github.com/bartventer/gocache"
    _ "github.com/bartventer/gocache/memcache"
)

func main() {
    ctx := context.Background()
    urlStr := "memcache://localhost:11211"
    c, err := cache.OpenCache(ctx, urlStr)
    if err != nil {
        log.Fatalf("Failed to initialize cache: %v", err)
    }
    // ... use c with the cache.Cache interface
}

Memcache Constructor

You can create a Memcache cache with memcache.New:

import (
    "context"

    "github.com/bartventer/gocache/memcache"
)

func main() {
    ctx := context.Background()
    c := memcache.New(ctx, &memcache.Options{
        Addrs: []string{"localhost:11211"},
    })
    // ... use c with the cache.Cache interface
}

RAM Cache (in-memory)

The ramcache package provides an in-memory cache driver using a map.

import (
    "context"
    "log"

    cache "github.com/bartventer/gocache"
    _ "github.com/bartventer/gocache/ramcache"
)

func main() {
    ctx := context.Background()
    urlStr := "ramcache://?cleanupinterval=1m"
    c, err := cache.OpenCache(ctx, urlStr)
    if err != nil {
        log.Fatalf("Failed to initialize cache: %v", err)
    }
    // ... use c with the cache.Cache interface
}

RAM Cache Constructor

You can create a RAM cache with ramcache.New:

import (
    "context"

    "github.com/bartventer/gocache/ramcache"
)

func main() {
    ctx := context.Background()
    c := ramcache.New(ctx, &ramcache.Options{
        CleanupInterval: 1 * time.Minute,
    })
    // ... use c with the cache.Cache interface
}

Contributing

All contributions are welcome! See the Contributing Guide for more details.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Documentation

Overview

Package cache offers a library for managing caches in a unified manner in Go.

This package enables developers to transition between various cache implementations (such as Redis, Redis Cluster, Memcache, etc.) by altering the URL scheme. This is achieved by offering consistent, idiomatic interfaces for common operations.

Central to this package are "portable types", built atop service-specific drivers for supported cache services. For instance, cache.Cache portable type instances can be created using redis.OpenCache, memcache.OpenCache, or any other supported driver. This allows the cache.Cache to be used across your application without concern for the underlying implementation.

URL Format

The cache package uses URLs to specify cache implementations. The URL scheme is used to determine the cache implementation to use. The URL format is:

scheme://<host>:<port>[?query]

The scheme is used to determine the cache implementation. The host and port are used to connect to the cache service. The optional query parameters can be used to configure the cache implementation. Each cache implementation supports different query parameters.

Usage

To use a cache implementation, import the relevant driver package and use the OpenCache function to create a new cache. The cache package will automatically use the correct cache implementation based on the URL scheme.

import (
    "context"
    "log"

    "github.com/bartventer/gocache"
    // Enable the Redis cache implementation
    _ "github.com/bartventer/gocache/redis"
)

func main() {
    ctx := context.Background()
    urlStr := "redis://localhost:7000?maxretries=5&minretrybackoff=1000"
    c, err := cache.OpenCache(ctx, urlStr)
    if err != nil {
        log.Fatalf("Failed to initialize cache: %v", err)
    }

    // Now you can use c with the cache.Cache interface
    err = c.Set(ctx, "key", "value")
    if err != nil {
        log.Fatalf("Failed to set key: %v", err)
    }

    value, err := c.Get(ctx, "key")
    if err != nil {
        log.Fatalf("Failed to get key: %v", err)
    }

    log.Printf("Value: %s", value)
}

Drivers

For specific URL formats, query parameters, and examples, refer to the documentation of each cache implementation.

Index

• Variables
• func RegisterCache(scheme string, opener URLOpener)
• func ValidateTTL(ttl time.Duration) error
• type Cache
  • func NewCache(driver driver.Cache) *Cache
  • func OpenCache(ctx context.Context, urlstr string) (*Cache, error)
  • func (c *Cache) Clear(ctx context.Context) error
  • func (c *Cache) Close() error
  • func (c *Cache) Count(ctx context.Context, pattern string, modifiers ...keymod.Mod) (int64, error)
  • func (c *Cache) Del(ctx context.Context, key string, modifiers ...keymod.Mod) error
  • func (c *Cache) DelKeys(ctx context.Context, pattern string, modifiers ...keymod.Mod) error
  • func (c *Cache) Exists(ctx context.Context, key string, modifiers ...keymod.Mod) (bool, error)
  • func (c *Cache) Get(ctx context.Context, key string, modifiers ...keymod.Mod) ([]byte, error)
  • func (c *Cache) Ping(ctx context.Context) error
  • func (c *Cache) Set(ctx context.Context, key string, value interface{}, modifiers ...keymod.Mod) error
  • func (c *Cache) SetWithTTL(ctx context.Context, key string, value interface{}, ttl time.Duration, ...) error
• type URLOpener

Variables

var (
	// ErrNoCache is returned when no cache implementation is available.
	ErrNoCache = errors.New("gocache: no cache implementation available")

	// ErrKeyNotFound is returned when a key is not found in the cache.
	ErrKeyNotFound = errors.New("gocache: key not found")

	// ErrPatternMatchingNotSupported is returned when a pattern matching operation is not supported
	// by the cache implementation.
	ErrPatternMatchingNotSupported = errors.New("gocache: pattern matching not supported")

	// ErrInvalidTTL is returned when an invalid TTL is provided.
	ErrInvalidTTL = errors.New("gocache: invalid TTL")
)

Functions

func RegisterCache

func RegisterCache(scheme string, opener URLOpener)

RegisterCache registers a URLOpener for a given scheme. If a URLOpener is already registered for the scheme, it panics.

func ValidateTTL

func ValidateTTL(ttl time.Duration) error

ValidateTTL validates the TTL and returns an error if it's invalid. A TTL is invalid if it's negative.

Types

type Cache

type Cache struct {
	// contains filtered or unexported fields
}

Cache is a portable type that implements driver.Cache.

func NewCache

func NewCache(driver driver.Cache) *Cache

NewCache creates a new Cache using the provided driver. Not intended for direct application use.

func OpenCache

func OpenCache(ctx context.Context, urlstr string) (*Cache, error)

OpenCache opens a Cache for the provided URL string. It returns an error if the URL cannot be parsed, or if no URLOpener is registered for the URL's scheme.

func (*Cache) Clear

func (c *Cache) Clear(ctx context.Context) error

Clear implements driver.Cache.

func (*Cache) Close

func (c *Cache) Close() error

Close implements driver.Cache.

func (*Cache) Count

func (c *Cache) Count(ctx context.Context, pattern string, modifiers ...keymod.Mod) (int64, error)

Count implements driver.Cache.

func (*Cache) Del

func (c *Cache) Del(ctx context.Context, key string, modifiers ...keymod.Mod) error

Del implements driver.Cache.

func (*Cache) DelKeys

func (c *Cache) DelKeys(ctx context.Context, pattern string, modifiers ...keymod.Mod) error

DelKeys implements driver.Cache.

func (*Cache) Exists

func (c *Cache) Exists(ctx context.Context, key string, modifiers ...keymod.Mod) (bool, error)

Exists implements driver.Cache.

func (*Cache) Get

func (c *Cache) Get(ctx context.Context, key string, modifiers ...keymod.Mod) ([]byte, error)

Get implements driver.Cache.

func (*Cache) Ping

func (c *Cache) Ping(ctx context.Context) error

Ping implements driver.Cache.

func (*Cache) Set

func (c *Cache) Set(ctx context.Context, key string, value interface{}, modifiers ...keymod.Mod) error

Set implements driver.Cache.

func (*Cache) SetWithTTL

func (c *Cache) SetWithTTL(ctx context.Context, key string, value interface{}, ttl time.Duration, modifiers ...keymod.Mod) error

SetWithTTL implements driver.Cache.

type URLOpener

type URLOpener interface {
	// OpenCacheURL opens a cache using a URL and options.
	OpenCacheURL(ctx context.Context, u *url.URL) (*Cache, error)
}

URLOpener defines the interface for opening a cache using a URL.