@opengroundplan/core 0.1.1

package/templates/layers/cache-redis/files/go.mod

@@ -0,0 +1 @@
+require github.com/redis/go-redis/v9 v9.21.0

package/templates/layers/cache-redis/files/internal/cache/cache.go

@@ -0,0 +1,127 @@
+package cache
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"strings"
+	"time"
+)
+
+// separator is the Redis key convention, not a tunable.
+const separator = ":"
+
+// TTL sentinels. A caller says what it means; the number lives in Config.
+const (
+	// DefaultTTL asks the store to apply the configured default profile.
+	DefaultTTL time.Duration = -1
+	// NoExpiry stores the entry until it is invalidated explicitly.
+	NoExpiry time.Duration = 0
+)
+
+// Whitespace breaks the wire protocol; glob characters would make invalidation over-match.
+var illegalSegment = regexp.MustCompile(`[\s*?\[\]]`)
+
+// Cache is the seam every caller depends on, so Redis can be swapped for the in-process
+// store in a test without touching a call site. Values are opaque bytes here; the generic
+// helpers below add typing.
+type Cache interface {
+	Get(ctx context.Context, namespace, id string) ([]byte, bool, error)
+	Set(ctx context.Context, namespace, id string, payload []byte, ttl time.Duration) error
+	Delete(ctx context.Context, namespace, id string) (bool, error)
+	InvalidateNamespace(ctx context.Context, namespace string) (int, error)
+	Ping(ctx context.Context) error
+	Close() error
+}
+
+// New returns the Redis store, or the bounded in-process store when the cache is disabled.
+func New(cfg Config) (Cache, error) {
+	if !cfg.Enabled {
+		return NewMemory(cfg), nil
+	}
+	return NewRedis(cfg)
+}
+
+// BuildKey lays out `<prefix>:<namespace>:<id>` so invalidation and the SCAN pattern can
+// never drift apart.
+func BuildKey(prefix, namespace, id string) (string, error) {
+	segments := make([]string, 0, 3)
+	for _, segment := range []string{prefix, namespace, id} {
+		if segment == "" {
+			continue
+		}
+		if illegalSegment.MatchString(segment) {
+			return "", fmt.Errorf("cache: key segment %q contains whitespace or a glob character", segment)
+		}
+		segments = append(segments, segment)
+	}
+	if len(segments) < 2 {
+		return "", fmt.Errorf("cache: key needs at least a namespace and an id")
+	}
+	return strings.Join(segments, separator), nil
+}
+
+// NamespacePrefix is every key in one namespace, without the trailing glob.
+func NamespacePrefix(prefix, namespace string) (string, error) {
+	key, err := BuildKey(prefix, namespace, "sentinel")
+	if err != nil {
+		return "", err
+	}
+	return strings.TrimSuffix(key, "sentinel"), nil
+}
+
+// Get decodes a cached value. The bool reports a hit; a miss is never an error.
+func Get[T any](ctx context.Context, c Cache, namespace, id string) (T, bool, error) {
+	var value T
+	payload, found, err := c.Get(ctx, namespace, id)
+	if err != nil || !found {
+		return value, false, err
+	}
+	if err := json.Unmarshal(payload, &value); err != nil {
+		// A value we cannot decode is poison; drop it so the next read is a clean miss.
+		_, _ = c.Delete(ctx, namespace, id)
+		return value, false, nil
+	}
+	return value, true, nil
+}
+
+// Set encodes and stores a value. Pass DefaultTTL unless the call site has a real reason.
+func Set[T any](ctx context.Context, c Cache, namespace, id string, value T, ttl time.Duration) error {
+	payload, err := json.Marshal(value)
+	if err != nil {
+		return fmt.Errorf("cache: encode %s/%s: %w", namespace, id, err)
+	}
+	return c.Set(ctx, namespace, id, payload, ttl)
+}
+
+// GetOrSet is read-through: load runs only on a miss, and its result is cached.
+func GetOrSet[T any](
+	ctx context.Context,
+	c Cache,
+	namespace, id string,
+	ttl time.Duration,
+	load func(context.Context) (T, error),
+) (T, error) {
+	if value, found, err := Get[T](ctx, c, namespace, id); err == nil && found {
+		return value, nil
+	}
+	value, err := load(ctx)
+	if err != nil {
+		return value, err
+	}
+	// A cache write failure must not fail the request the value was loaded for.
+	_ = Set(ctx, c, namespace, id, value, ttl)
+	return value, nil
+}
+
+// resolveTTL turns the sentinels into the duration the driver receives.
+func (c Config) resolveTTL(ttl time.Duration) time.Duration {
+	if ttl == DefaultTTL {
+		return c.DefaultTTL
+	}
+	if ttl < 0 {
+		return NoExpiry
+	}
+	return ttl
+}

package/templates/layers/cache-redis/files/internal/cache/cache_test.go

@@ -0,0 +1,113 @@
+package cache
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// testConfig avoids reading the environment so the contract tests are hermetic.
+func testConfig() Config {
+	return Config{
+		KeyPrefix:        "app",
+		MemoryMaxEntries: 100,
+		DefaultTTL:       time.Minute,
+	}
+}
+
+func TestBuildKey(t *testing.T) {
+	key, err := BuildKey("app", "user", "42")
+	if err != nil {
+		t.Fatalf("BuildKey: %v", err)
+	}
+	if key != "app:user:42" {
+		t.Fatalf("got %q, want app:user:42", key)
+	}
+}
+
+func TestBuildKeyRejectsUnsafeSegments(t *testing.T) {
+	for _, bad := range []string{"with space", "glob*", "brack[et]"} {
+		if _, err := BuildKey("app", "user", bad); err == nil {
+			t.Fatalf("BuildKey(%q) should have failed", bad)
+		}
+	}
+}
+
+func TestMemoryRoundTrip(t *testing.T) {
+	ctx := context.Background()
+	store := NewMemory(testConfig())
+
+	if _, found, err := Get[string](ctx, store, "user", "1"); err != nil || found {
+		t.Fatalf("empty store: found=%v err=%v", found, err)
+	}
+	if err := Set(ctx, store, "user", "1", "Ada", DefaultTTL); err != nil {
+		t.Fatalf("Set: %v", err)
+	}
+	value, found, err := Get[string](ctx, store, "user", "1")
+	if err != nil || !found || value != "Ada" {
+		t.Fatalf("got %q found=%v err=%v", value, found, err)
+	}
+}
+
+func TestMemoryExpires(t *testing.T) {
+	ctx := context.Background()
+	store := NewMemory(testConfig())
+
+	if err := Set(ctx, store, "user", "1", "Ada", time.Nanosecond); err != nil {
+		t.Fatalf("Set: %v", err)
+	}
+	time.Sleep(time.Millisecond)
+	if _, found, _ := Get[string](ctx, store, "user", "1"); found {
+		t.Fatal("expired entry should read as a miss")
+	}
+}
+
+func TestGetOrSetLoadsOnce(t *testing.T) {
+	ctx := context.Background()
+	store := NewMemory(testConfig())
+	calls := 0
+	load := func(context.Context) (int, error) {
+		calls++
+		return 7, nil
+	}
+
+	for range 2 {
+		value, err := GetOrSet(ctx, store, "count", "1", DefaultTTL, load)
+		if err != nil || value != 7 {
+			t.Fatalf("got %d err=%v", value, err)
+		}
+	}
+	if calls != 1 {
+		t.Fatalf("loader ran %d times, want 1", calls)
+	}
+}
+
+func TestInvalidateNamespace(t *testing.T) {
+	ctx := context.Background()
+	store := NewMemory(testConfig())
+	_ = Set(ctx, store, "user", "1", "a", DefaultTTL)
+	_ = Set(ctx, store, "user", "2", "b", DefaultTTL)
+	_ = Set(ctx, store, "order", "1", "c", DefaultTTL)
+
+	removed, err := store.InvalidateNamespace(ctx, "user")
+	if err != nil || removed != 2 {
+		t.Fatalf("removed %d err=%v", removed, err)
+	}
+	if _, found, _ := Get[string](ctx, store, "order", "1"); !found {
+		t.Fatal("other namespaces must survive")
+	}
+}
+
+func TestMemoryIsBounded(t *testing.T) {
+	ctx := context.Background()
+	cfg := testConfig()
+	cfg.MemoryMaxEntries = 2
+	store := NewMemory(cfg)
+
+	for _, id := range []string{"1", "2", "3"} {
+		_ = Set(ctx, store, "user", id, id, DefaultTTL)
+	}
+	if _, found, _ := Get[string](ctx, store, "user", "1"); found {
+		t.Fatal("oldest entry should have been evicted")
+	}
+}

package/templates/layers/cache-redis/files/internal/cache/config.go

@@ -0,0 +1,110 @@
+// Package cache is the caching seam: one config table, a Redis client wrapper, and an
+// in-process fallback that satisfies the same interface.
+package cache
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Prefixed so several services can share one environment without colliding.
+const envPrefix = "{{ redisEnvPrefix }}_"
+
+// Config is the fully resolved cache settings for one process.
+type Config struct {
+	Enabled          bool
+	URL              string
+	KeyPrefix        string
+	ConnectTimeout   time.Duration
+	CommandTimeout   time.Duration
+	MaxRetries       int
+	MemoryMaxEntries int
+	DefaultTTL       time.Duration
+	ShortTTL         time.Duration
+	LongTTL          time.Duration
+}
+
+// defaults is the single source of truth for every tunable. Add a knob here first; the
+// environment only ever overrides a key that already exists in this table.
+var defaults = map[string]string{
+	"ENABLED":                "true",
+	"URL":                    "redis://127.0.0.1:{{ redisPort }}/0",
+	"KEY_PREFIX":             "{{ solutionName | kebab }}",
+	"CONNECT_TIMEOUT_MS":     "5000",
+	"COMMAND_TIMEOUT_MS":     "2000",
+	"MAX_RECONNECT_ATTEMPTS": "10",
+	"MEMORY_MAX_ENTRIES":     "10000",
+	"TTL_DEFAULT_SECONDS":    "{{ cacheDefaultTtlSeconds }}",
+	"TTL_SHORT_SECONDS":      "{{ cacheShortTtlSeconds }}",
+	"TTL_LONG_SECONDS":       "{{ cacheLongTtlSeconds }}",
+}
+
+// Load reads the environment once at startup and reports every bad value at once.
+func Load() (Config, error) {
+	r := &reader{}
+	cfg := Config{
+		Enabled:          r.boolean("ENABLED"),
+		URL:              r.str("URL"),
+		KeyPrefix:        r.str("KEY_PREFIX"),
+		ConnectTimeout:   r.millis("CONNECT_TIMEOUT_MS"),
+		CommandTimeout:   r.millis("COMMAND_TIMEOUT_MS"),
+		MaxRetries:       r.intVal("MAX_RECONNECT_ATTEMPTS"),
+		MemoryMaxEntries: r.intVal("MEMORY_MAX_ENTRIES"),
+		DefaultTTL:       r.seconds("TTL_DEFAULT_SECONDS"),
+		ShortTTL:         r.seconds("TTL_SHORT_SECONDS"),
+		LongTTL:          r.seconds("TTL_LONG_SECONDS"),
+	}
+	if len(r.errs) > 0 {
+		return Config{}, errors.Join(r.errs...)
+	}
+	return cfg, nil
+}
+
+// UsesTLS follows the URL scheme, never a separate flag that can disagree with it.
+func (c Config) UsesTLS() bool { return strings.HasPrefix(c.URL, "rediss://") }
+
+type reader struct {
+	errs []error
+}
+
+func (r *reader) str(key string) string {
+	def, declared := defaults[key]
+	if !declared {
+		r.errs = append(r.errs, fmt.Errorf("cache: no default declared for %q", key))
+		return ""
+	}
+	if v, found := os.LookupEnv(envPrefix + key); found && strings.TrimSpace(v) != "" {
+		return strings.TrimSpace(v)
+	}
+	return def
+}
+
+func (r *reader) intVal(key string) int {
+	raw := r.str(key)
+	v, err := strconv.Atoi(raw)
+	if err != nil || v < 0 {
+		r.errs = append(r.errs, fmt.Errorf("cache: %s%s must be a non-negative integer, got %q", envPrefix, key, raw))
+	}
+	return v
+}
+
+func (r *reader) boolean(key string) bool {
+	switch strings.ToLower(r.str(key)) {
+	case "1", "true", "yes", "on":
+		return true
+	default:
+		return false
+	}
+}
+
+func (r *reader) millis(key string) time.Duration {
+	return time.Duration(r.intVal(key)) * time.Millisecond
+}
+
+func (r *reader) seconds(key string) time.Duration {
+	return time.Duration(r.intVal(key)) * time.Second
+}

package/templates/layers/cache-redis/files/internal/cache/memory.go

@@ -0,0 +1,124 @@
+package cache
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"time"
+)
+
+type entry struct {
+	payload   []byte
+	expiresAt time.Time // zero means no expiry
+}
+
+// Memory is the process-local fallback used when the cache is disabled. Bounded by
+// MemoryMaxEntries — an unbounded map behind a cache API is a memory leak waiting for
+// production.
+type Memory struct {
+	cfg     Config
+	mu      sync.Mutex
+	entries map[string]entry
+	order   []string // insertion order, oldest first
+}
+
+func NewMemory(cfg Config) *Memory {
+	return &Memory{cfg: cfg, entries: make(map[string]entry)}
+}
+
+func (m *Memory) Get(_ context.Context, namespace, id string) ([]byte, bool, error) {
+	key, err := BuildKey(m.cfg.KeyPrefix, namespace, id)
+	if err != nil {
+		return nil, false, err
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	found, ok := m.entries[key]
+	if !ok {
+		return nil, false, nil
+	}
+	if !found.expiresAt.IsZero() && !time.Now().Before(found.expiresAt) {
+		delete(m.entries, key)
+		return nil, false, nil
+	}
+	return found.payload, true, nil
+}
+
+func (m *Memory) Set(_ context.Context, namespace, id string, payload []byte, ttl time.Duration) error {
+	key, err := BuildKey(m.cfg.KeyPrefix, namespace, id)
+	if err != nil {
+		return err
+	}
+	resolved := m.cfg.resolveTTL(ttl)
+
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	if _, exists := m.entries[key]; !exists {
+		m.evictIfFull()
+		m.order = append(m.order, key)
+	}
+	stored := entry{payload: payload}
+	if resolved > 0 {
+		stored.expiresAt = time.Now().Add(resolved)
+	}
+	m.entries[key] = stored
+	return nil
+}
+
+func (m *Memory) Delete(_ context.Context, namespace, id string) (bool, error) {
+	key, err := BuildKey(m.cfg.KeyPrefix, namespace, id)
+	if err != nil {
+		return false, err
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	_, existed := m.entries[key]
+	delete(m.entries, key)
+	return existed, nil
+}
+
+func (m *Memory) InvalidateNamespace(_ context.Context, namespace string) (int, error) {
+	prefix, err := NamespacePrefix(m.cfg.KeyPrefix, namespace)
+	if err != nil {
+		return 0, err
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	removed := 0
+	for key := range m.entries {
+		if strings.HasPrefix(key, prefix) {
+			delete(m.entries, key)
+			removed++
+		}
+	}
+	return removed, nil
+}
+
+func (m *Memory) Ping(context.Context) error { return nil }
+
+func (m *Memory) Close() error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.entries = make(map[string]entry)
+	m.order = nil
+	return nil
+}
+
+// evictIfFull drops the oldest write. Callers hold the lock.
+func (m *Memory) evictIfFull() {
+	if m.cfg.MemoryMaxEntries <= 0 || len(m.entries) < m.cfg.MemoryMaxEntries {
+		return
+	}
+	for len(m.order) > 0 {
+		oldest := m.order[0]
+		m.order = m.order[1:]
+		if _, exists := m.entries[oldest]; exists {
+			delete(m.entries, oldest)
+			return
+		}
+	}
+}

package/templates/layers/cache-redis/files/internal/cache/redis.go

@@ -0,0 +1,108 @@
+package cache
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+)
+
+// scanCount is a throughput/latency trade-off internal to invalidation, not a setting.
+const scanCount = 250
+
+// Redis is the typed client wrapper. Keys are namespaced and every command inherits the
+// configured timeout, so a stalled cache cannot stall a request.
+type Redis struct {
+	cfg    Config
+	client *redis.Client
+}
+
+func NewRedis(cfg Config) (*Redis, error) {
+	options, err := redis.ParseURL(cfg.URL)
+	if err != nil {
+		return nil, fmt.Errorf("cache: invalid %sURL: %w", envPrefix, err)
+	}
+	options.DialTimeout = cfg.ConnectTimeout
+	options.ReadTimeout = cfg.CommandTimeout
+	options.WriteTimeout = cfg.CommandTimeout
+	options.MaxRetries = cfg.MaxRetries
+	return &Redis{cfg: cfg, client: redis.NewClient(options)}, nil
+}
+
+func (r *Redis) Get(ctx context.Context, namespace, id string) ([]byte, bool, error) {
+	key, err := BuildKey(r.cfg.KeyPrefix, namespace, id)
+	if err != nil {
+		return nil, false, err
+	}
+	payload, err := r.client.Get(ctx, key).Bytes()
+	if errors.Is(err, redis.Nil) {
+		return nil, false, nil // a miss is never an error
+	}
+	if err != nil {
+		return nil, false, fmt.Errorf("cache: get %s: %w", key, err)
+	}
+	return payload, true, nil
+}
+
+func (r *Redis) Set(ctx context.Context, namespace, id string, payload []byte, ttl time.Duration) error {
+	key, err := BuildKey(r.cfg.KeyPrefix, namespace, id)
+	if err != nil {
+		return err
+	}
+	// go-redis treats a zero expiration as "no expiry", which matches NoExpiry.
+	if err := r.client.Set(ctx, key, payload, r.cfg.resolveTTL(ttl)).Err(); err != nil {
+		return fmt.Errorf("cache: set %s: %w", key, err)
+	}
+	return nil
+}
+
+func (r *Redis) Delete(ctx context.Context, namespace, id string) (bool, error) {
+	key, err := BuildKey(r.cfg.KeyPrefix, namespace, id)
+	if err != nil {
+		return false, err
+	}
+	removed, err := r.client.Del(ctx, key).Result()
+	if err != nil {
+		return false, fmt.Errorf("cache: delete %s: %w", key, err)
+	}
+	return removed > 0, nil
+}
+
+// InvalidateNamespace uses SCAN + UNLINK, never KEYS + DEL: neither call blocks the server.
+func (r *Redis) InvalidateNamespace(ctx context.Context, namespace string) (int, error) {
+	prefix, err := NamespacePrefix(r.cfg.KeyPrefix, namespace)
+	if err != nil {
+		return 0, err
+	}
+	pattern := prefix + "*"
+	removed := 0
+	var cursor uint64
+	for {
+		keys, next, err := r.client.Scan(ctx, cursor, pattern, scanCount).Result()
+		if err != nil {
+			return removed, fmt.Errorf("cache: scan %s: %w", pattern, err)
+		}
+		if len(keys) > 0 {
+			count, err := r.client.Unlink(ctx, keys...).Result()
+			if err != nil {
+				return removed, fmt.Errorf("cache: unlink %s: %w", pattern, err)
+			}
+			removed += int(count)
+		}
+		cursor = next
+		if cursor == 0 {
+			return removed, nil
+		}
+	}
+}
+
+func (r *Redis) Ping(ctx context.Context) error {
+	if err := r.client.Ping(ctx).Err(); err != nil {
+		return fmt.Errorf("cache: ping: %w", err)
+	}
+	return nil
+}
+
+func (r *Redis) Close() error { return r.client.Close() }

package/templates/layers/cache-redis/files/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "redis": "^6.1.0"
+  }
+}

package/templates/layers/cache-redis/files/pyproject.toml

@@ -0,0 +1,2 @@
+[project]
+dependencies = ["redis>=8.0.1"]

package/templates/layers/cache-redis/files/src/__solutionName.dot__.Cache.Redis/CacheKey.cs

@@ -0,0 +1,44 @@
+using System.Buffers;
+
+namespace {{ solutionName | dot }}.Cache.Redis;
+
+/// <summary>
+/// Key layout: <c>&lt;prefix&gt;:&lt;namespace&gt;:&lt;id&gt;</c>. Every implementation builds keys
+/// here so namespace invalidation and the Redis SCAN pattern can never drift apart.
+/// </summary>
+public static class CacheKey
+{
+    /// <summary>Redis convention, not a tunable.</summary>
+    public const string Separator = ":";
+
+    // Whitespace breaks the wire protocol; glob characters would make invalidation over-match.
+    private static readonly SearchValues<char> Illegal = SearchValues.Create(" \t\n\r*?[]");
+
+    public static string Build(string prefix, string scope, string id)
+    {
+        var segments = new[] { prefix, scope, id }.Where(s => !string.IsNullOrEmpty(s)).ToArray();
+        if (segments.Length < 2)
+        {
+            throw new ArgumentException("cache key needs at least a namespace and an id");
+        }
+        foreach (var segment in segments)
+        {
+            if (segment.AsSpan().IndexOfAny(Illegal) >= 0)
+            {
+                throw new ArgumentException($"cache key segment \"{segment}\" contains whitespace or a glob character");
+            }
+        }
+        return string.Join(Separator, segments);
+    }
+
+    /// <summary>Every key in one namespace, without the trailing glob.</summary>
+    public static string NamespacePrefix(string prefix, string scope)
+    {
+        var key = Build(prefix, scope, "sentinel");
+        return key[..^"sentinel".Length];
+    }
+
+    /// <summary>SCAN pattern matching every key in one namespace.</summary>
+    public static string NamespacePattern(string prefix, string scope) =>
+        NamespacePrefix(prefix, scope) + "*";
+}