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

Pull requests for additional cache implementations are welcome!

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! Open a pull request to request a feature or submit a bug report.

License

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

Acknowledgements

This package has been inspired by and uses similar patterns to those used in Google's Go Cloud Development Kit. Make sure to check it out!

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 OpenCache(ctx context.Context, urlstr string) (Cache, 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 interface {
	// Set sets a key to a value in the cache.
	Set(ctx context.Context, key string, value interface{}, modifiers ...keymod.Mod) error

	// SetWithTTL sets a key to a value in the cache with a time-to-live (TTL).
	SetWithTTL(ctx context.Context, key string, value interface{}, ttl time.Duration, modifiers ...keymod.Mod) error

	// Exists checks if a key exists in the cache.
	Exists(ctx context.Context, key string, modifiers ...keymod.Mod) (bool, error)

	// Count returns the number of keys in the cache matching a pattern.
	Count(ctx context.Context, pattern string, modifiers ...keymod.Mod) (int64, error)

	// Get gets the value of a key from the cache.
	Get(ctx context.Context, key string, modifiers ...keymod.Mod) ([]byte, error)

	// Del deletes a key from the cache.
	Del(ctx context.Context, key string, modifiers ...keymod.Mod) error

	// DelKeys deletes all keys matching a pattern from the cache.
	DelKeys(ctx context.Context, pattern string, modifiers ...keymod.Mod) error

	// Clear clears all keys from the cache.
	Clear(ctx context.Context) error

	// Ping checks if the cache is available.
	Ping(ctx context.Context) error

	// Close closes the cache connection.
	Close() error
}

Cache is an interface that represents a cache. It has methods for setting, getting and deleting keys. Each cache implementation should implement this interface.

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.

type URLOpener

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

URLOpener is an interface for opening caches using URLs.