redistore

To rotate keys without invalidating existing sessions, provide multiple key pairs to redistore.NewStore. The first pair is used for encoding new sessions, while all provided pairs are attempted for decoding existing sessions.

Key Sizes:

• Authentication key: 32 or 64 bytes (HMAC)
• Encryption key: 16 (AES-128), 24 (AES-192), or 32 bytes (AES-256)

Rotation Process:

1. Add new key pair at the beginning of the slice.
2. Keep old keys for a transition period.
3. Remove old keys once all sessions have been renewed.

Helper Functions:

• KeysFromStrings(keys ...string): Provide keys from strings.
• Keys(keys ...[]byte): Provide keys as byte slices.

// Keys are provided in pairs: authentication key, encryption key
store, err := redistore.NewStore(
    redistore.KeysFromStrings(
        "new-authentication-key", // Used for new sessions
        "new-encryption-key",     // Used for new sessions
        "old-authentication-key", // Tried for decoding
        "old-encryption-key",     // Tried for decoding
    ),
    redistore.WithAddress("tcp", ":6379"),
)

Redistore supports multiple serialization formats via the WithSerializer option.

Gob Serializer (Default)

Uses Go's encoding/gob. Best for complex Go types.

JSON Serializer

Uses encoding/json. Best for cross-language compatibility.

// Using JSON Serializer
store, err := redistore.NewStore(
    redistore.KeysFromStrings("secret-key"),
    redistore.WithAddress("tcp", ":6379"),
    redistore.WithSerializer(redistore.JSONSerializer{}),
)

Custom Serializer

Implement the SessionSerializer interface to use your own logic:

type SessionSerializer interface {
    Serialize(ss *sessions.Session) ([]byte, error)
    Deserialize(d []byte, ss *sessions.Session) error
}

type MySerializer struct{}

func (s MySerializer) Serialize(ss *sessions.Session) ([]byte, error) {
    // implementation
}

func (s MySerializer) Deserialize(d []byte, ss *sessions.Session) error {
    // implementation
}

// Usage
store, err := redistore.NewStore(
    redistore.KeysFromStrings("secret-key"),
    redistore.WithSerializer(MySerializer{}),
)

To get started, create a new store using redistore.NewStore. You must provide encryption/authentication keys and at least one connection option (Address, URL, or Pool).

package main

import (
    "log"
    "net/http"

    "github.com/boj/redistore/v2"
    "github.com/gorilla/sessions"
)

func main() {
    // Create a new store with options
    store, err := redistore.NewStore(
        redistore.KeysFromStrings("secret-key"),
        redistore.WithAddress("tcp", ":6379"),
    )
    if err != nil {
        panic(err)
    }
    defer store.Close()

    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        // Get a session
        session, err := store.Get(r, "session-key")
        if err != nil {
            log.Println(err.Error())
            return
        }

        // Set a value
        session.Values["foo"] = "bar"

        // Save session
        if err = sessions.Save(r, w); err != nil {
            log.Fatalf("Error saving session: %v", err)
        }
    })

    log.Fatal(http.ListenAndServe(":8080", nil))
}

When calling redistore.NewStore, you should check the returned err for two main categories of issues:

1. Configuration Errors: Occur when conflicting options are provided (e.g., providing both WithAddress and WithURL). The error message will indicate that "only one connection option can be specified".
2. Connection Errors: Occur when the provided connection details are invalid or the Redis server is unreachable. The error message will follow the pattern "failed to connect to Redis: ...".

// Example Configuration Error
store, err := redistore.NewStore(
    [][]byte{[]byte("secret-key")},
    redistore.WithAddress("tcp", ":6379"),
    redistore.WithURL("redis://localhost"), // ❌ Error: multiple connection options
)
if err != nil {
    log.Fatal(err)
}

// Example Connection Error
store, err := redistore.NewStore(
    [][]byte{[]byte("secret-key")},
    redistore.WithAddress("tcp", "invalid:9999"),
)
if err != nil {
    // Error: "failed to connect to Redis: ..."
    log.Fatal(err)
}