go-cache

go-cache is a multi-layered caching library that coordinates between a private (in-memory) cache and a shared cache (e.g., Redis).

Cache-Aside Data Flow

When an application requests data via Cache.Get() or Cache.MGet():

1. Local Cache Hit: Data is returned immediately from the private in-memory cache.
2. Local Miss / Shared Hit: If the local cache misses but the shared cache (Redis) hits, the data is fetched from the shared cache and then stored in the local cache for future requests.
3. Total Miss: If both caches miss, the library executes a provided getter function (e.g., a database query). The resulting data is then stored in both the shared cache and the local cache before being returned to the application.

Cache Eviction

When Cache.Del() is called:

1. The key is deleted from the shared cache.
2. The key is deleted from the local cache.
3. A Pub-Sub message is broadcast to other distributed instances to ensure their local caches are also evicted, maintaining consistency across the system.

The GetByFunc() method simplifies the Cache-Aside pattern. You provide a getter function that is automatically executed if the key is missing from both local and shared caches. This function is responsible for refilling the cache.

You can also provide custom MarshalFunc and UnmarshalFunc (e.g., using msgpack) within the Setting to control data serialization.

func ExampleCache_GetByFunc() {
    // Create a cache group named "get-by-func" using only the local cache.
    c := cacheFactory.NewCache([]cache.Setting{
        {
            Prefix: "get-by-func",
            CacheAttributes: map[cache.Type]cache.Attribute{
                cache.LocalCacheType: {TTL: 10 * time.Minute},
            },
            MarshalFunc:   msgpack.Marshal,
            UnmarshalFunc: msgpack.Unmarshal,
        },
    })

    ctx := context.TODO()
    container2 := &Object{}

    // GetByFunc automatically refills the cache if it misses
    err := c.GetByFunc(ctx, "get-by-func", "key2", container2, func() (interface{}, error) {
        // This logic runs on cache miss (e.g., DB query)
        return Object{Str: "value2", Num: 2}, nil
    })
    if err != nil {
        panic("not expected")
    }

    fmt.Println(container2) // Output: &{value2 2}
}

If you need to handle multiple keys at once during a cache miss, you can define an MGetter function in your cache.Setting. The MGetter must return a slice of values where the order of items corresponds to the order of the input keys.

func ExampleService_Create_mGetter() {
    // Create a cache group named "mgetter" using both shared and local caches.
    c := cacheFactory.NewCache([]cache.Setting{
        {
            Prefix: "mgetter",
            CacheAttributes: map[cache.Type]cache.Attribute{
                cache.SharedCacheType: {TTL: time.Hour},
                cache.LocalCacheType:  {TTL: 10 * time.Minute},
            },
            MGetter: func(keys ...string) (interface{}, error) {
                // Refill logic for multiple keys. 
                // Return a slice where order matches 'keys'.
                return []Object{{Str: "value3", Num: 3}}, nil
            },
            MarshalFunc:   cache.Marshal,
            UnmarshalFunc: cache.Unmarshal,
        },
    })

    ctx := context.TODO()
    container3 := &Object{}
    if err := c.Get(ctx, "mgetter", "key3", container3); err != nil {
        panic("not expected")
    }

    fmt.Println(container3) // Output: &{value3 3}
}

You can treat a cache group as a standard key-value store. Use NewCache with a Setting to define a prefix and specific CacheAttributes (like TTL) for different cache types (Local vs Shared).

type Object struct {
    Str string
    Num int
}

func Example_setAndGetPattern() {
    // Create a cache group named "set-and-get" using only the shared cache.
    c := cacheFactory.NewCache([]cache.Setting{
        {
            Prefix: "set-and-get",
            CacheAttributes: map[cache.Type]cache.Attribute{
                cache.SharedCacheType: {TTL: 10 * time.Second},
            },
        },
    })

    ctx := context.TODO()

    // Set the cache
    obj := &Object{Str: "value1", Num: 1}
    if err := c.Set(ctx, "set-and-get", "key", obj); err != nil {
        panic("not expected")
    }

    // Read the cache
    container := &Object{}
    if err := c.Get(ctx, "set-and-get", "key", container); err != nil {
        panic("not expected")
    }
    fmt.Println(container) // Output: &{value1 1}
}

A Setting defines how a specific group of keys (identified by a Prefix) behaves. You can define different Attribute configurations (like TTL) for different Type layers (e.g., LocalCacheType vs SharedCacheType).

Key fields in Setting:

• Prefix: The unique identifier for the cache group.
• CacheAttributes: A map linking Type to Attribute (e.g., TTL).
• MGetter: A MGetterFunc used to reload multiple keys during an MGet cache miss.
• MarshalFunc / UnmarshalFunc: Custom functions for data serialization.

setting := cache.Setting{
    Prefix: "session",
    CacheAttributes: map[cache.Type]cache.Attribute{
        cache.LocalCacheType:  {TTL: time.Minute * 1},
        cache.SharedCacheType: {TTL: time.Hour * 24},
    },
    MGetter: func(keys ...string) (interface{}, error) {
        // Implementation to fetch multiple keys from DB
        return values, nil
    },
}

The Pubsub interface allows you to interact with a message queue for publishing and subscribing to cache events.

• Pub(context context.Context, topic string, message []byte) error: Publishes a byte slice message to a specific topic.
• Sub(context context.Context, topic ...string) <-chan Message: Subscribes to one or more topics and returns a read-only channel of Message objects.
• Close(): Closes the subscription. This should be called if Sub() was used to ensure resources are cleaned up. The implementation should safely handle cases where Sub() was never called.

// Example of using Pubsub
var ps cache.Pubsub

// Subscribing to a topic
msgs := ps.Sub(ctx, "cache-eviction")

// Consuming messages
go func() {
    for msg := range msgs {
        fmt.Printf("Received on %s: %s\n", msg.Topic(), string(msg.Content()))
    }
}()

// Publishing a message
err := ps.Pub(ctx, "cache-eviction", []byte("key-123"))
if err != nil {
    // handle error
}

// Cleanup
ps.Close()