@opengroundplan/core 0.1.1

package/templates/layers/cache-redis/files/src/__solutionName.snake__/cache/settings.py

@@ -0,0 +1,82 @@
+"""The only place a Redis or TTL default may appear.
+
+Every other cache module reads this table; a URL or a literal TTL at a call site is a bug.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+_PREFIX = "{{ redisEnvPrefix }}"
+
+_TRUE = {"1", "true", "yes", "on"}
+
+
+def _raw(key: str) -> str | None:
+    value = os.environ.get(f"{_PREFIX}_{key}")
+    return value.strip() if value and value.strip() else None
+
+
+def _int(key: str, fallback: int) -> int:
+    value = _raw(key)
+    if value is None:
+        return fallback
+    try:
+        parsed = int(value)
+    except ValueError as exc:  # fail at startup rather than hand junk to a driver
+        raise ValueError(f"{_PREFIX}_{key} must be an integer, got {value!r}") from exc
+    if parsed < 0:
+        raise ValueError(f"{_PREFIX}_{key} must be non-negative, got {parsed}")
+    return parsed
+
+
+def _bool(key: str, fallback: bool) -> bool:
+    value = _raw(key)
+    return fallback if value is None else value.lower() in _TRUE
+
+
+@dataclass(frozen=True, slots=True)
+class TtlSeconds:
+    """Named TTL profiles so call sites reference an intent, not a number."""
+
+    default: int = {{ cacheDefaultTtlSeconds }}
+    short: int = {{ cacheShortTtlSeconds }}
+    long: int = {{ cacheLongTtlSeconds }}
+
+
+@dataclass(frozen=True, slots=True)
+class CacheSettings:
+    """Typed defaults. Change a value here or in the environment, never at a call site."""
+
+    enabled: bool = True
+    url: str = "redis://127.0.0.1:{{ redisPort }}/0"
+    key_prefix: str = "{{ solutionName | kebab }}"
+    connect_timeout_ms: int = 5_000
+    command_timeout_ms: int = 2_000
+    max_reconnect_attempts: int = 10
+    memory_max_entries: int = 10_000
+    ttl: TtlSeconds = field(default_factory=TtlSeconds)
+
+    @property
+    def uses_tls(self) -> bool:
+        """TLS follows the URL scheme, never a separate flag that can disagree with it."""
+        return self.url.startswith("rediss://")
+
+
+def load_cache_settings() -> CacheSettings:
+    defaults = CacheSettings()
+    return CacheSettings(
+        enabled=_bool("ENABLED", defaults.enabled),
+        url=_raw("URL") or defaults.url,
+        key_prefix=_raw("KEY_PREFIX") or defaults.key_prefix,
+        connect_timeout_ms=_int("CONNECT_TIMEOUT_MS", defaults.connect_timeout_ms),
+        command_timeout_ms=_int("COMMAND_TIMEOUT_MS", defaults.command_timeout_ms),
+        max_reconnect_attempts=_int("MAX_RECONNECT_ATTEMPTS", defaults.max_reconnect_attempts),
+        memory_max_entries=_int("MEMORY_MAX_ENTRIES", defaults.memory_max_entries),
+        ttl=TtlSeconds(
+            default=_int("TTL_DEFAULT_SECONDS", defaults.ttl.default),
+            short=_int("TTL_SHORT_SECONDS", defaults.ttl.short),
+            long=_int("TTL_LONG_SECONDS", defaults.ttl.long),
+        ),
+    )

package/templates/layers/cache-redis/files/src/__solutionName.snake__/cache/store.py

@@ -0,0 +1,113 @@
+"""The cache seam plus the fallback implementation.
+
+Callers depend on ``CacheStore`` only, so Redis can be swapped for the in-process store in a
+test without touching a call site.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections import OrderedDict
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from .keys import build_key, namespace_prefix
+from .settings import CacheSettings
+
+Loader = Callable[[], Awaitable[Any]]
+
+
+class CacheStore(Protocol):
+    """Every method is async so the Redis and memory stores stay interchangeable."""
+
+    async def get(self, namespace: str, key_id: str) -> Any | None:
+        """Return ``None`` on a miss — a miss is never an error."""
+        ...
+
+    async def set(
+        self, namespace: str, key_id: str, value: Any, ttl_seconds: int | None = None
+    ) -> None:
+        """``ttl_seconds=0`` stores without expiry; ``None`` uses the default profile."""
+        ...
+
+    async def delete(self, namespace: str, key_id: str) -> bool: ...
+
+    async def get_or_set(
+        self, namespace: str, key_id: str, load: Loader, ttl_seconds: int | None = None
+    ) -> Any:
+        """Read-through: ``load`` runs only on a miss and its result is cached."""
+        ...
+
+    async def invalidate_namespace(self, namespace: str) -> int: ...
+
+    async def ping(self) -> bool: ...
+
+    async def close(self) -> None: ...
+
+
+@dataclass(slots=True)
+class _Entry:
+    value: str
+    expires_at: float | None
+
+
+class MemoryCacheStore:
+    """Process-local fallback, bounded by ``memory_max_entries``.
+
+    An unbounded dict behind a cache API is a memory leak waiting for production.
+    """
+
+    def __init__(self, settings: CacheSettings) -> None:
+        self._settings = settings
+        self._entries: OrderedDict[str, _Entry] = OrderedDict()
+
+    async def get(self, namespace: str, key_id: str) -> Any | None:
+        key = build_key(self._settings.key_prefix, namespace, key_id)
+        entry = self._entries.get(key)
+        if entry is None:
+            return None
+        if entry.expires_at is not None and entry.expires_at <= time.monotonic():
+            del self._entries[key]
+            return None
+        return json.loads(entry.value)
+
+    async def set(
+        self, namespace: str, key_id: str, value: Any, ttl_seconds: int | None = None
+    ) -> None:
+        ttl = self._settings.ttl.default if ttl_seconds is None else ttl_seconds
+        key = build_key(self._settings.key_prefix, namespace, key_id)
+        if key not in self._entries and len(self._entries) >= self._settings.memory_max_entries:
+            self._entries.popitem(last=False)  # drop the oldest write
+        self._entries[key] = _Entry(
+            value=json.dumps(value),
+            expires_at=time.monotonic() + ttl if ttl > 0 else None,
+        )
+
+    async def delete(self, namespace: str, key_id: str) -> bool:
+        key = build_key(self._settings.key_prefix, namespace, key_id)
+        return self._entries.pop(key, None) is not None
+
+    async def get_or_set(
+        self, namespace: str, key_id: str, load: Loader, ttl_seconds: int | None = None
+    ) -> Any:
+        hit = await self.get(namespace, key_id)
+        if hit is not None:
+            return hit
+        value = await load()
+        await self.set(namespace, key_id, value, ttl_seconds)
+        return value
+
+    async def invalidate_namespace(self, namespace: str) -> int:
+        prefix = namespace_prefix(self._settings.key_prefix, namespace)
+        doomed = [key for key in self._entries if key.startswith(prefix)]
+        for key in doomed:
+            del self._entries[key]
+        return len(doomed)
+
+    async def ping(self) -> bool:
+        return True
+
+    async def close(self) -> None:
+        self._entries.clear()

package/templates/layers/cache-redis/files/src/cache/index.ts

@@ -0,0 +1,54 @@
+/**
+ * The cache entry point. Import `getCache()` — never a concrete store — so disabling the
+ * cache in the environment is enough to run the app without Redis.
+ *
+ *   const user = await (await getCache()).getOrSet('user', id, () => loadUser(id));
+ */
+import { RedisCacheStore } from './redis.js';
+import { loadCacheSettings } from './settings.js';
+import { MemoryCacheStore } from './store.js';
+import type { CacheSettings } from './settings.js';
+import type { CacheStore } from './store.js';
+
+export type { CacheStore } from './store.js';
+export type { CacheSettings, CacheTtlSeconds } from './settings.js';
+export { MemoryCacheStore } from './store.js';
+export { RedisCacheStore } from './redis.js';
+export { buildKey, namespacePattern } from './keys.js';
+export { loadCacheSettings } from './settings.js';
+
+let settings: CacheSettings | undefined;
+let instance: CacheStore | undefined;
+
+export function cacheSettings(): CacheSettings {
+  settings ??= loadCacheSettings();
+  return settings;
+}
+
+/** Named TTL profiles, so call sites reference an intent instead of a number. */
+export const ttl = {
+  short: (): number => cacheSettings().ttlSeconds.short,
+  default: (): number => cacheSettings().ttlSeconds.default,
+  long: (): number => cacheSettings().ttlSeconds.long,
+  /** Store without expiry — use only for data invalidated explicitly. */
+  forever: (): number => 0,
+} as const;
+
+/** One connection per process; the first call connects, later calls reuse it. */
+export async function getCache(): Promise<CacheStore> {
+  if (instance !== undefined) return instance;
+  const resolved = cacheSettings();
+  const store = resolved.enabled
+    ? new RedisCacheStore(resolved)
+    : new MemoryCacheStore(resolved);
+  if (store instanceof RedisCacheStore) await store.connect();
+  instance = store;
+  return instance;
+}
+
+/** Call on shutdown so the process can exit; safe to call when no cache was created. */
+export async function closeCache(): Promise<void> {
+  await instance?.close();
+  instance = undefined;
+  settings = undefined;
+}

package/templates/layers/cache-redis/files/src/cache/keys.ts

@@ -0,0 +1,28 @@
+/**
+ * Key layout: `<prefix>:<namespace>:<id>`. Every implementation builds keys through here so
+ * namespace invalidation and the Redis SCAN pattern can never drift apart.
+ */
+
+/** Redis convention, not a tunable. */
+const SEPARATOR = ':';
+
+/** Whitespace breaks the wire protocol; glob characters would make invalidation over-match. */
+const ILLEGAL = /[\s*?[\]]/;
+
+export function buildKey(prefix: string, namespace: string, id: string): string {
+  const segments = [prefix, namespace, id].filter((segment) => segment.length > 0);
+  for (const segment of segments) {
+    if (ILLEGAL.test(segment)) {
+      throw new Error(`cache key segment "${segment}" contains whitespace or a glob character`);
+    }
+  }
+  if (segments.length < 2) throw new Error('cache key needs at least a namespace and an id');
+  return segments.join(SEPARATOR);
+}
+
+/** SCAN pattern matching every key in one namespace. */
+export function namespacePattern(prefix: string, namespace: string): string {
+  const base = [prefix, namespace].filter((segment) => segment.length > 0).join(SEPARATOR);
+  if (ILLEGAL.test(base)) throw new Error(`cache namespace "${namespace}" is not a valid key segment`);
+  return `${base}${SEPARATOR}*`;
+}

package/templates/layers/cache-redis/files/src/cache/redis.ts

@@ -0,0 +1,131 @@
+/**
+ * Typed wrapper over node-redis. Values cross the wire as JSON, keys are namespaced, and
+ * every command inherits the configured timeout so a stalled cache cannot stall a request.
+ */
+import { createClient } from 'redis';
+import { buildKey, namespacePattern } from './keys.js';
+import type { CacheStore } from './store.js';
+import type { CacheSettings } from './settings.js';
+
+type RedisClient = ReturnType<typeof createClient>;
+
+/** SCAN page size: a throughput/latency trade-off internal to invalidation, not a setting. */
+const SCAN_COUNT = 250;
+
+export class RedisCacheStore implements CacheStore {
+  private readonly settings: CacheSettings;
+  private readonly client: RedisClient;
+  private connecting: Promise<void> | undefined;
+
+  constructor(settings: CacheSettings, onError: (error: unknown) => void = defaultOnError) {
+    this.settings = settings;
+    this.client = createClient({
+      url: settings.url,
+      socket: {
+        connectTimeout: settings.connectTimeoutMs,
+        reconnectStrategy: (retries: number) =>
+          retries >= settings.maxReconnectAttempts
+            ? new Error(`redis: giving up after ${retries} reconnect attempts`)
+            : Math.min(2 ** retries * 50, 2_000),
+      },
+    });
+    // node-redis emits 'error' on every dropped connection; unhandled, it would kill the process.
+    this.client.on('error', onError);
+  }
+
+  /** Idempotent, so callers can await it on every request without tracking state. */
+  async connect(): Promise<void> {
+    if (this.client.isOpen) return;
+    this.connecting ??= this.client.connect().then(() => undefined);
+    try {
+      await this.connecting;
+    } finally {
+      this.connecting = undefined;
+    }
+  }
+
+  async get<T>(namespace: string, id: string): Promise<T | undefined> {
+    await this.connect();
+    const key = buildKey(this.settings.keyPrefix, namespace, id);
+    const raw = await this.withTimeout(this.client.get(key), 'GET');
+    if (raw === null) return undefined;
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      // A value we cannot parse is poison; drop it so the next read is a clean miss.
+      await this.withTimeout(this.client.del(key), 'DEL');
+      return undefined;
+    }
+  }
+
+  async set<T>(namespace: string, id: string, value: T, ttlSeconds?: number): Promise<void> {
+    await this.connect();
+    const key = buildKey(this.settings.keyPrefix, namespace, id);
+    const payload = JSON.stringify(value);
+    const ttl = ttlSeconds ?? this.settings.ttlSeconds.default;
+    const command = ttl > 0 ? this.client.setEx(key, ttl, payload) : this.client.set(key, payload);
+    await this.withTimeout(command, 'SET');
+  }
+
+  async delete(namespace: string, id: string): Promise<boolean> {
+    await this.connect();
+    const key = buildKey(this.settings.keyPrefix, namespace, id);
+    return (await this.withTimeout(this.client.del(key), 'DEL')) > 0;
+  }
+
+  async getOrSet<T>(
+    namespace: string,
+    id: string,
+    load: () => Promise<T>,
+    ttlSeconds?: number,
+  ): Promise<T> {
+    const hit = await this.get<T>(namespace, id);
+    if (hit !== undefined) return hit;
+    const value = await load();
+    await this.set(namespace, id, value, ttlSeconds);
+    return value;
+  }
+
+  /** SCAN + UNLINK rather than KEYS + DEL: neither call blocks the server on a large keyspace. */
+  async invalidateNamespace(namespace: string): Promise<number> {
+    await this.connect();
+    const match = namespacePattern(this.settings.keyPrefix, namespace);
+    // The cursor is a string on the wire; 64-bit values do not survive a round-trip through Number.
+    let cursor = '0';
+    let removed = 0;
+    do {
+      const page = await this.withTimeout(
+        this.client.scan(cursor, { MATCH: match, COUNT: SCAN_COUNT }),
+        'SCAN',
+      );
+      cursor = String(page.cursor);
+      if (page.keys.length > 0) {
+        removed += await this.withTimeout(this.client.unlink(page.keys), 'UNLINK');
+      }
+    } while (cursor !== '0');
+    return removed;
+  }
+
+  async ping(): Promise<boolean> {
+    await this.connect();
+    return (await this.withTimeout(this.client.ping(), 'PING')) === 'PONG';
+  }
+
+  async close(): Promise<void> {
+    if (this.client.isOpen) await this.client.close();
+  }
+
+  /** node-redis has no per-command deadline, so one is imposed here. */
+  private withTimeout<T>(command: Promise<T>, name: string): Promise<T> {
+    const limit = this.settings.commandTimeoutMs;
+    if (limit <= 0) return command;
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`redis ${name} timed out after ${limit}ms`)), limit);
+      command.then(resolve, reject).finally(() => clearTimeout(timer));
+    });
+  }
+}
+
+function defaultOnError(error: unknown): void {
+  console.error('[cache] redis connection error', error);
+}

package/templates/layers/cache-redis/files/src/cache/settings.ts

@@ -0,0 +1,86 @@
+/**
+ * The only place a Redis or TTL default may appear. Every other cache module reads these
+ * settings — a URL or a literal TTL written at a call site is a bug.
+ */
+
+export interface CacheTtlSeconds {
+  /** Applied by `set` when the caller passes no TTL. */
+  default: number;
+  short: number;
+  long: number;
+}
+
+export interface CacheSettings {
+  enabled: boolean;
+  url: string;
+  keyPrefix: string;
+  connectTimeoutMs: number;
+  commandTimeoutMs: number;
+  maxReconnectAttempts: number;
+  memoryMaxEntries: number;
+  ttlSeconds: CacheTtlSeconds;
+}
+
+const PREFIX = '{{ redisEnvPrefix }}';
+
+/** Typed defaults. Change a value here or in the environment, never at a call site. */
+const defaults: CacheSettings = {
+  enabled: true,
+  url: 'redis://127.0.0.1:{{ redisPort }}/0',
+  keyPrefix: '{{ solutionName | kebab }}',
+  connectTimeoutMs: 5_000,
+  commandTimeoutMs: 2_000,
+  maxReconnectAttempts: 10,
+  memoryMaxEntries: 10_000,
+  ttlSeconds: {
+    default: {{ cacheDefaultTtlSeconds }},
+    short: {{ cacheShortTtlSeconds }},
+    long: {{ cacheLongTtlSeconds }},
+  },
+};
+
+type Env = Record<string, string | undefined>;
+
+function read(env: Env, key: string): string | undefined {
+  const value = env[`${PREFIX}_${key}`];
+  return value === undefined || value.trim() === '' ? undefined : value.trim();
+}
+
+function integer(env: Env, key: string, fallback: number): number {
+  const raw = read(env, key);
+  if (raw === undefined) return fallback;
+  const parsed = Number(raw);
+  // Fail at startup rather than hand NaN to a driver or an expiry.
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${PREFIX}_${key} must be a non-negative integer, got "${raw}"`);
+  }
+  return parsed;
+}
+
+function boolean(env: Env, key: string, fallback: boolean): boolean {
+  const raw = read(env, key)?.toLowerCase();
+  if (raw === undefined) return fallback;
+  return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+}
+
+export function loadCacheSettings(env: Env = process.env): CacheSettings {
+  return {
+    enabled: boolean(env, 'ENABLED', defaults.enabled),
+    url: read(env, 'URL') ?? defaults.url,
+    keyPrefix: read(env, 'KEY_PREFIX') ?? defaults.keyPrefix,
+    connectTimeoutMs: integer(env, 'CONNECT_TIMEOUT_MS', defaults.connectTimeoutMs),
+    commandTimeoutMs: integer(env, 'COMMAND_TIMEOUT_MS', defaults.commandTimeoutMs),
+    maxReconnectAttempts: integer(env, 'MAX_RECONNECT_ATTEMPTS', defaults.maxReconnectAttempts),
+    memoryMaxEntries: integer(env, 'MEMORY_MAX_ENTRIES', defaults.memoryMaxEntries),
+    ttlSeconds: {
+      default: integer(env, 'TTL_DEFAULT_SECONDS', defaults.ttlSeconds.default),
+      short: integer(env, 'TTL_SHORT_SECONDS', defaults.ttlSeconds.short),
+      long: integer(env, 'TTL_LONG_SECONDS', defaults.ttlSeconds.long),
+    },
+  };
+}
+
+/** TLS is decided by the URL scheme, never by a separate flag that can disagree with it. */
+export function isTls(url: string): boolean {
+  return url.startsWith('rediss://');
+}

package/templates/layers/cache-redis/files/src/cache/store.ts

@@ -0,0 +1,98 @@
+/**
+ * The cache seam plus the fallback implementation. Callers depend on `CacheStore` only, so
+ * Redis can be swapped for the in-process store in a test without touching a call site.
+ */
+import { buildKey, namespacePattern } from './keys.js';
+import type { CacheSettings } from './settings.js';
+
+export interface CacheStore {
+  /** Resolves to `undefined` on a miss — a miss is never an error. */
+  get<T>(namespace: string, id: string): Promise<T | undefined>;
+  /** `ttlSeconds` of 0 stores the entry without expiry; omit it to use the default profile. */
+  set<T>(namespace: string, id: string, value: T, ttlSeconds?: number): Promise<void>;
+  delete(namespace: string, id: string): Promise<boolean>;
+  /** Read-through: `load` runs only on a miss, and its result is cached before returning. */
+  getOrSet<T>(namespace: string, id: string, load: () => Promise<T>, ttlSeconds?: number): Promise<T>;
+  /** Drops every key in the namespace and returns how many were removed. */
+  invalidateNamespace(namespace: string): Promise<number>;
+  ping(): Promise<boolean>;
+  close(): Promise<void>;
+}
+
+interface Entry {
+  value: string;
+  /** Epoch millis, or undefined for no expiry. */
+  expiresAt: number | undefined;
+}
+
+/**
+ * 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.
+ */
+export class MemoryCacheStore implements CacheStore {
+  private readonly entries = new Map<string, Entry>();
+  private readonly settings: CacheSettings;
+
+  constructor(settings: CacheSettings) {
+    this.settings = settings;
+  }
+
+  async get<T>(namespace: string, id: string): Promise<T | undefined> {
+    const key = buildKey(this.settings.keyPrefix, namespace, id);
+    const entry = this.entries.get(key);
+    if (entry === undefined) return undefined;
+    if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {
+      this.entries.delete(key);
+      return undefined;
+    }
+    return JSON.parse(entry.value) as T;
+  }
+
+  async set<T>(namespace: string, id: string, value: T, ttlSeconds?: number): Promise<void> {
+    const ttl = ttlSeconds ?? this.settings.ttlSeconds.default;
+    const key = buildKey(this.settings.keyPrefix, namespace, id);
+    // Map preserves insertion order, so the first key is the oldest write.
+    if (!this.entries.has(key) && this.entries.size >= this.settings.memoryMaxEntries) {
+      const oldest = this.entries.keys().next();
+      if (!oldest.done) this.entries.delete(oldest.value);
+    }
+    this.entries.set(key, {
+      value: JSON.stringify(value),
+      expiresAt: ttl > 0 ? Date.now() + ttl * 1000 : undefined,
+    });
+  }
+
+  async delete(namespace: string, id: string): Promise<boolean> {
+    return this.entries.delete(buildKey(this.settings.keyPrefix, namespace, id));
+  }
+
+  async getOrSet<T>(
+    namespace: string,
+    id: string,
+    load: () => Promise<T>,
+    ttlSeconds?: number,
+  ): Promise<T> {
+    const hit = await this.get<T>(namespace, id);
+    if (hit !== undefined) return hit;
+    const value = await load();
+    await this.set(namespace, id, value, ttlSeconds);
+    return value;
+  }
+
+  async invalidateNamespace(namespace: string): Promise<number> {
+    const prefix = namespacePattern(this.settings.keyPrefix, namespace).slice(0, -1);
+    let removed = 0;
+    for (const key of [...this.entries.keys()]) {
+      if (key.startsWith(prefix) && this.entries.delete(key)) removed += 1;
+    }
+    return removed;
+  }
+
+  async ping(): Promise<boolean> {
+    return true;
+  }
+
+  async close(): Promise<void> {
+    this.entries.clear();
+  }
+}