Redis

Redis (or its open-source fork Valkey) is an in-memory key-value server. Vukem uses it as a shared backend: when your app runs on more than one server, the cache, sessions, queue, rate limits and locks must live somewhere every server can see. One Redis gives you all five. The step-by-step guide at the end starts from zero.

go get github.com/AlexGalhardo/vukem/drivers/redis

rc, err := redis.Open(ctx, os.Getenv("REDIS_URL")) // redis://localhost:6379/0, rediss:// for TLS

app, err := vukem.New(
	vukem.WithCacheStore(rc.CacheStore("cache:")), // also backs locks
	vukem.WithSessionStore(rc.SessionStore("")),   // "session:" keys with TTL
	vukem.WithQueueDriver(rc.Queue(redis.QueueOptions{})),
	// ...
)
app.AddHealthCheck("redis", rc.Ping)

Reading REDIS_URL from the app configuration#

os.Getenv above runs before vukem.New loads .env, .env.local and the sources vukemtest passes. To read the URL from app.Source, use the lazy options: each function runs on the first app.Cache(), app.Sessions() or app.Queue() call, after configuration loaded, and its error is returned by that call (DefaultMiddleware builds sessions at boot, so a bad URL is still a boot error).

var (
	once  sync.Once
	rc    *redis.Client
	rcErr error
)

client := func(app *vukem.App) (*redis.Client, error) {
	once.Do(func() {
		if rc, rcErr = redis.Open(context.Background(), app.Source.Get("REDIS_URL")); rcErr != nil {
			return
		}

		app.AddHealthCheck("redis", rc.Ping)
		app.OnShutdown(func(context.Context) error { return rc.Close() })
	})

	return rc, rcErr
}

app, err := vukem.New(
	vukem.WithCacheStoreFunc(func(app *vukem.App) (cache.Store, error) {
		c, err := client(app)
		if err != nil {
			return nil, err
		}

		return c.CacheStore("cache:"), nil
	}),
	vukem.WithSessionStoreFunc(func(app *vukem.App) (session.Store, error) {
		c, err := client(app)
		if err != nil {
			return nil, err
		}

		return c.SessionStore(""), nil
	}),
	vukem.WithQueueDriverFunc(func(app *vukem.App) (queue.Driver, error) {
		c, err := client(app)
		if err != nil {
			return nil, err
		}

		return c.Queue(redis.QueueOptions{}), nil
	}),
)

The last of WithCacheStore / WithCacheStoreFunc (and likewise for sessions and queues) wins; SetSessionStore from a provider still overrides both. A function that returns nil, nil is an error. A function must not call the accessor it feeds (app.Cache() inside WithCacheStoreFunc, app.Sessions() or DefaultMiddleware inside WithSessionStoreFunc, app.Queue() inside WithQueueDriverFunc): it runs inside that accessor's sync.Once and would deadlock.

• Works with Redis 7+ and Valkey 8+; CI runs the cachetest and queuetest conformance suites on both.
• Open pings the server, so the app does not boot while Redis is down; a malformed URL always fails. redis.OpenLazy(url) only parses the URL and connects on first use, so the process starts and rc.Ping reports the outage in a readiness check (app.AddHealthCheck). go-redis retries a failed command 3 times with backoff, so that Ping takes seconds while Redis is down; for a fast readiness answer set ?dial_timeout=1s&max_retries=-1 on the URL (or use a separate client with those options for the check).
• redis.New(client) wraps an existing go-redis client (Cluster, Sentinel, custom options); rc.Redis() returns it.

Step by step: sessions and cache on Redis#

services:
  redis:
    image: redis:7.4
    ports: ["6379:6379"]

docker compose up -d redis

go get github.com/AlexGalhardo/vukem/drivers/redis

REDIS_URL=redis://localhost:6379/0

rc, err := redis.Open(ctx, os.Getenv("REDIS_URL")) // fails when Redis is down
if err != nil {
	return nil, err
}

app, err := vukem.New(
	vukem.WithCacheStore(rc.CacheStore("myapp:cache:")),
	vukem.WithSessionStore(rc.SessionStore("myapp:session:")),
	// ...
)
if err != nil {
	return nil, err
}

app.AddHealthCheck("redis", rc.Ping)
app.OnShutdown(func(context.Context) error { return rc.Close() })

RATE_LIMIT_STORE=cache   # limiters count in app.Cache(), now Redis

vukem serve
curl -s -c jar.txt http://localhost:3000/ > /dev/null   # creates a session
docker compose exec redis redis-cli --scan --pattern 'myapp:*'
curl -s 'http://localhost:3000/up?checks=1'               # "redis" is reported

Pub/sub#

msgs, err := rc.Subscribe(ctx, "orders") // the channel closes when ctx ends
if err != nil {
	return err
}

go func() {
	for b := range msgs {
		log.Printf("order event: %s", b)
	}
}()

err = rc.Publish(ctx, "orders", []byte(`{"id":42}`))

Pub/sub is fire-and-forget: subscribers that are offline miss messages. Use the queue for work that must not be lost.

Pitfalls#

• One Redis, several apps. Give every store its own prefix per app (myapp:cache:, myapp:session:), or two apps read each other's keys.
• Eviction policies. A Redis configured with maxmemory-policy allkeys-lru may evict sessions and queued jobs under memory pressure. Use noeviction (or volatile-lru) for a Redis that holds sessions or queues, or run a separate one for the cache.
• os.Getenv before .env loads. The eager form reads the process environment only; use the lazy With...Func options to read app.Source.
• Slow readiness checks while Redis is down. go-redis retries; add ?dial_timeout=1s&max_retries=-1 to the URL used by the health check.
• Persistence. A default Redis may lose recent writes on restart. Queues and sessions need AOF or RDB persistence enabled (managed Redis usually has it).

Security notes#

• Never expose Redis to the internet. Bind it to a private network, require a password (redis://:password@host:6379/0) and use rediss:// (TLS) across networks.
• Keep the password in an environment variable, never in code or in a committed .env.
• Sessions in Redis hold only session data; still, anyone with Redis access can read or forge sessions, so treat Redis credentials like database credentials.