summercms/modules/cooler/README.md

cooler

Cache drivers and shared counters for SummerCMS: memory and Redis caches with a key prefix and TTLs, and a Redis-backed rate-limit store.

import "git.golem15.com/golem15/summercms/modules/cooler"

Name: The cool box you bring to the beach; it keeps things fresh and at hand for everyone in the group.

Overview

cooler holds the state that several application instances share. Its first piece is a Redis-backed rate-limit store: with http.rate_limit.store: redis, the serve command of surf calls cooler.Install, which builds a Redis client from redis.url, and publishes the store so the throttle middleware counts in Redis instead of in the process. Two instances behind one load balancer then enforce one limit together. It is the counterpart of Laravel's Redis cache store behind RateLimiter and the throttle middleware.

Role in the framework

A service module on backpack and compass, below surf: surf imports cooler, never the reverse. cooler.RateLimitStore has the method set of surf.Store (through cooler.Attempter), so surf takes no Redis dependency and cooler imports neither surf nor cabana. The framework wires cooler at boot; applications import nothing.

Use cases:

• Keep throttle limits exact when an application runs as several instances behind a load balancer.
• Share one Redis connection setting (redis.url) between the framework services that need Redis.

Features

• cooler.Install reads http.rate_limit.store (memory, the default, or redis). With redis it builds the client from redis.url and pings it within cooler.PingTimeout (3 s).
• Start-up never fails because Redis is down: an unanswered ping is one warning that names the endpoint (host and port, never the URL), and the limiter counts per instance until Redis answers. A missing or malformed redis.url, or an unknown store name, fails start-up with an error that names the key and never contains the URL or its password.
• cooler.RateLimitStore runs one atomic Lua script per attempt with the semantics of surf.MemoryStore: the first attempt opens the window, a denied attempt does not increment, the window never extends, and the retry time is what is left of the window. Redis keeps the clock, so instance clock skew does not matter.
• Each attempt is bounded by cooler.AttemptTimeout (500 ms). When Redis fails, the attempt is counted in the fallback store surf passes in (a per-instance surf.MemoryStore) and a warning is logged at most once per minute.
• Keys carry a per-application prefix: cache.prefix, or by default app.name lower-cased with every run of other characters than a-z and 0-9 replaced by _, then : (summer: when app.name is empty). Rate-limit keys are <prefix>rl:<key>.
• cooler.OpenRedis accepts redis://, rediss:// (TLS) and unix:// URLs, does not dial at construction, and skips the CLIENT SETINFO and maintenance-notification handshakes.
• Only serve installs cooler: route:list and surf.Assemble in tests keep the in-process store and never dial Redis.

Usage

Select the shared store in the application's config and keep the URL, which may carry a password, in the environment (SUMMER_REDIS__URL):

# config/http.yaml
rate_limit:
  store: redis

# config/redis.yaml (or SUMMER_REDIS__URL=redis://:secret@10.0.0.7:6379/0)
url: redis://10.0.0.7:6379/0

Nothing else changes: routes keep throttle:60,1 or throttle:<bucket>, and serve publishes the Redis store before it builds the router.

A tool outside serve can use the store directly:

package blog

import (
	"context"
	"time"

	"git.golem15.com/golem15/summercms/modules/backpack"
	"git.golem15.com/golem15/summercms/modules/cooler"
)

// AllowExport admits five exports a minute per user across all instances.
func AllowExport(ctx context.Context, app *backpack.App, fallback cooler.Attempter, userKey string) (bool, error) {
	client, err := cooler.OpenRedis(ctx, app.Config.String(cooler.RedisURLKey))
	if err != nil {
		return false, err
	}
	defer client.Close()
	store := cooler.NewRateLimitStore(client, "acme:", fallback)
	allowed, _, _ := store.Attempt("export|"+userKey, 5, time.Minute)
	return allowed, nil
}

API reference

Identifier	Description
cooler.Install	Reads cooler's config, opens and pings Redis when a Redis store is selected, and returns a cooler.Handle. Called by surf's serve.
cooler.Handle	What cooler.Install set up.
cooler.Handle.Close	Closes the Redis client cooler.Install opened, if any.
cooler.Handle.RateLimitRedis	Reports whether http.rate_limit.store selects the Redis store.
cooler.Handle.RateLimitStore	Returns the Redis rate-limit store with the given fallback, or the fallback itself when Redis is not selected.
cooler.Attempter	One atomic fixed-window admission; the method set of surf.Store.
cooler.RateLimitStore	Redis fixed-window store shared by all instances, with a fallback while Redis fails.
cooler.NewRateLimitStore	Builds a cooler.RateLimitStore from a go-redis client, a key prefix and a fallback.
cooler.RateLimitStore.Attempt	Admits and counts one request in one Lua script; falls back on a Redis error.
cooler.OpenRedis	Builds a go-redis client from a redis://, rediss:// or unix:// URL without dialing; errors never contain the URL.
cooler.RedisURLKey	redis.url.
cooler.RateLimitStoreKey	http.rate_limit.store.
cooler.CachePrefixKey	cache.prefix.
cooler.PingTimeout	Bound of the start-up ping (3 s).
cooler.AttemptTimeout	Bound of one rate-limit attempt on Redis (500 ms).

Configuration

cooler.Install reads these keys from the app's compass config:

Key	Default	Controls
http.rate_limit.store	memory	Where throttle counters live: memory (per instance) or redis (shared). Any other value fails at boot. Environment: SUMMER_HTTP__RATE_LIMIT__STORE.
redis.url	none	Redis URL (redis://, rediss:// or unix://). Required when a Redis store is selected; keep it in the environment when it carries a password. Environment: SUMMER_REDIS__URL.
cache.prefix	from app.name	Prefix of every cooler key. Environment: SUMMER_CACHE__PREFIX.

Dependencies

• SummerCMS modules: backpack, compass.
• Third-party: github.com/redis/go-redis/v9 (Redis client).
• Standard library: context, errors, fmt, log/slog, strings, sync, time.

Testing

go test ./modules/cooler/...

The smoke tests need no external services. The cross-instance rate-limit test lives in surf (go test ./modules/surf -run TestRateLimitAcrossInstancesSmoke), starts a Redis container through testcontainers-go and needs Docker; -short skips it.