@opengroundplan/core 0.1.1

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

@@ -0,0 +1,119 @@
+using StackExchange.Redis;
+
+namespace {{ solutionName | dot }}.Cache.Redis;
+
+/// <summary>The only place a Redis or TTL default may appear. Nothing else reads the environment for caching.</summary>
+public sealed record CacheOptions
+{
+    private const string Prefix = "{{ redisEnvPrefix }}";
+
+    /// <summary>Redis protocol default, not a tunable — the host port lives in the URL.</summary>
+    private const int DefaultRedisPort = 6379;
+
+    // Typed defaults. Change a value here or in the environment, never at a call site.
+    public bool Enabled { get; init; } = true;
+    public string Url { get; init; } = "redis://127.0.0.1:{{ redisPort }}/0";
+    public string KeyPrefix { get; init; } = "{{ solutionName | kebab }}";
+    public int ConnectTimeoutMs { get; init; } = 5_000;
+    public int CommandTimeoutMs { get; init; } = 2_000;
+    public int MaxReconnectAttempts { get; init; } = 10;
+    public int MemoryMaxEntries { get; init; } = 10_000;
+
+    /// <summary>Applied when a caller passes no TTL.</summary>
+    public int DefaultTtlSeconds { get; init; } = {{ cacheDefaultTtlSeconds }};
+    public int ShortTtlSeconds { get; init; } = {{ cacheShortTtlSeconds }};
+    public int LongTtlSeconds { get; init; } = {{ cacheLongTtlSeconds }};
+
+    public TimeSpan DefaultTtl => TimeSpan.FromSeconds(DefaultTtlSeconds);
+    public TimeSpan ShortTtl => TimeSpan.FromSeconds(ShortTtlSeconds);
+    public TimeSpan LongTtl => TimeSpan.FromSeconds(LongTtlSeconds);
+
+    /// <summary>
+    /// Reads <c>{{ redisEnvPrefix }}_*</c>. Env-based so the wrapper stays free of a hosting
+    /// dependency; an ASP.NET host may bind its own configuration onto this record instead.
+    /// </summary>
+    public static CacheOptions FromEnvironment()
+    {
+        var defaults = new CacheOptions();
+        return defaults with
+        {
+            Enabled = Bool("ENABLED", defaults.Enabled),
+            Url = Raw("URL") ?? defaults.Url,
+            KeyPrefix = Raw("KEY_PREFIX") ?? defaults.KeyPrefix,
+            ConnectTimeoutMs = Int("CONNECT_TIMEOUT_MS", defaults.ConnectTimeoutMs),
+            CommandTimeoutMs = Int("COMMAND_TIMEOUT_MS", defaults.CommandTimeoutMs),
+            MaxReconnectAttempts = Int("MAX_RECONNECT_ATTEMPTS", defaults.MaxReconnectAttempts),
+            MemoryMaxEntries = Int("MEMORY_MAX_ENTRIES", defaults.MemoryMaxEntries),
+            DefaultTtlSeconds = Int("TTL_DEFAULT_SECONDS", defaults.DefaultTtlSeconds),
+            ShortTtlSeconds = Int("TTL_SHORT_SECONDS", defaults.ShortTtlSeconds),
+            LongTtlSeconds = Int("TTL_LONG_SECONDS", defaults.LongTtlSeconds),
+        };
+    }
+
+    /// <summary>
+    /// StackExchange.Redis takes its own configuration string, so the URL every other stack
+    /// uses is translated here rather than duplicated as separate host/port/password settings.
+    /// </summary>
+    public ConfigurationOptions ToConfiguration()
+    {
+        var uri = new Uri(Url);
+        var configuration = new ConfigurationOptions
+        {
+            EndPoints = { { uri.Host, uri.IsDefaultPort ? DefaultRedisPort : uri.Port } },
+            Ssl = uri.Scheme.Equals("rediss", StringComparison.OrdinalIgnoreCase),
+            ConnectTimeout = ConnectTimeoutMs,
+            SyncTimeout = CommandTimeoutMs,
+            AsyncTimeout = CommandTimeoutMs,
+            ConnectRetry = MaxReconnectAttempts,
+            // Reconnect in the background instead of throwing when Redis is briefly unavailable.
+            AbortOnConnectFail = false,
+        };
+
+        var credentials = uri.UserInfo.Split(':', 2);
+        if (credentials.Length == 2)
+        {
+            if (credentials[0].Length > 0)
+            {
+                configuration.User = Uri.UnescapeDataString(credentials[0]);
+            }
+            configuration.Password = Uri.UnescapeDataString(credentials[1]);
+        }
+        else if (credentials.Length == 1 && credentials[0].Length > 0)
+        {
+            configuration.Password = Uri.UnescapeDataString(credentials[0]);
+        }
+
+        var path = uri.AbsolutePath.Trim('/');
+        if (path.Length > 0 && int.TryParse(path, out var database))
+        {
+            configuration.DefaultDatabase = database;
+        }
+
+        return configuration;
+    }
+
+    private static string? Raw(string key)
+    {
+        var value = Environment.GetEnvironmentVariable($"{Prefix}_{key}");
+        return string.IsNullOrWhiteSpace(value) ? null : value.Trim();
+    }
+
+    private static int Int(string key, int fallback)
+    {
+        var value = Raw(key);
+        if (value is null)
+        {
+            return fallback;
+        }
+        // Fail at startup rather than hand a bad value to a driver.
+        return int.TryParse(value, out var parsed) && parsed >= 0
+            ? parsed
+            : throw new ArgumentException($"{Prefix}_{key} must be a non-negative integer, got \"{value}\"");
+    }
+
+    private static bool Bool(string key, bool fallback)
+    {
+        var value = Raw(key)?.ToLowerInvariant();
+        return value is null ? fallback : value is "1" or "true" or "yes" or "on";
+    }
+}

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

@@ -0,0 +1,16 @@
+namespace {{ solutionName | dot }}.Cache.Redis;
+
+/// <summary>
+/// The one place a store is constructed. Resolve <see cref="ICacheStore"/> through here — never
+/// a concrete type — so disabling the cache in the environment is enough to run without Redis.
+/// </summary>
+public static class CacheStoreFactory
+{
+    public static async Task<ICacheStore> CreateAsync(CacheOptions? options = null)
+    {
+        var resolved = options ?? CacheOptions.FromEnvironment();
+        return resolved.Enabled
+            ? await RedisCacheStore.ConnectAsync(resolved).ConfigureAwait(false)
+            : new MemoryCacheStore(resolved);
+    }
+}

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

@@ -0,0 +1,37 @@
+namespace {{ solutionName | dot }}.Cache.Redis;
+
+/// <summary>A lookup outcome. <c>Found</c> is the only reliable hit test once <c>T</c> may be a value type.</summary>
+public readonly record struct CacheResult<T>(bool Found, T? Value);
+
+/// <summary>
+/// The cache seam. Callers depend on this only, so Redis can be swapped for the in-process
+/// store in a test without touching a call site.
+/// </summary>
+/// <remarks>
+/// No <see cref="CancellationToken"/> on the store methods: StackExchange.Redis has no
+/// per-command cancellation, and an ignored token is worse than an absent one. Command
+/// deadlines come from <see cref="CacheOptions.CommandTimeoutMs"/>.
+/// </remarks>
+public interface ICacheStore : IAsyncDisposable
+{
+    /// <summary>A miss is never an error; it returns <c>Found = false</c>.</summary>
+    Task<CacheResult<T>> TryGetAsync<T>(string scope, string id);
+
+    /// <summary><see cref="TimeSpan.Zero"/> stores without expiry; <c>null</c> uses the default profile.</summary>
+    Task SetAsync<T>(string scope, string id, T value, TimeSpan? ttl = null);
+
+    Task<bool> DeleteAsync(string scope, string id);
+
+    /// <summary>Read-through: <paramref name="load"/> runs only on a miss and its result is cached.</summary>
+    Task<T> GetOrSetAsync<T>(
+        string scope,
+        string id,
+        Func<CancellationToken, Task<T>> load,
+        TimeSpan? ttl = null,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>Drops every key in the namespace and returns how many were removed.</summary>
+    Task<int> InvalidateNamespaceAsync(string scope);
+
+    Task<bool> PingAsync();
+}

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

@@ -0,0 +1,129 @@
+using System.Text.Json;
+
+namespace {{ solutionName | dot }}.Cache.Redis;
+
+/// <summary>
+/// Process-local fallback used when the cache is disabled. Bounded by
+/// <see cref="CacheOptions.MemoryMaxEntries"/> — an unbounded dictionary behind a cache API
+/// is a memory leak waiting for production.
+/// </summary>
+public sealed class MemoryCacheStore : ICacheStore
+{
+    private static readonly JsonSerializerOptions Json = new(JsonSerializerDefaults.Web);
+
+    private readonly CacheOptions _options;
+    private readonly object _gate = new();
+    private readonly Dictionary<string, Entry> _entries = [];
+    private readonly Queue<string> _order = new(); // insertion order, oldest first
+
+    public MemoryCacheStore(CacheOptions options) => _options = options;
+
+    public Task<CacheResult<T>> TryGetAsync<T>(string scope, string id)
+    {
+        var key = CacheKey.Build(_options.KeyPrefix, scope, id);
+        lock (_gate)
+        {
+            if (!_entries.TryGetValue(key, out var entry))
+            {
+                return Task.FromResult(new CacheResult<T>(false, default));
+            }
+            if (entry.ExpiresAt is { } expiry && expiry <= DateTimeOffset.UtcNow)
+            {
+                _entries.Remove(key);
+                return Task.FromResult(new CacheResult<T>(false, default));
+            }
+            return Task.FromResult(new CacheResult<T>(true, JsonSerializer.Deserialize<T>(entry.Payload, Json)));
+        }
+    }
+
+    public Task SetAsync<T>(string scope, string id, T value, TimeSpan? ttl = null)
+    {
+        var key = CacheKey.Build(_options.KeyPrefix, scope, id);
+        var expiry = ttl ?? _options.DefaultTtl;
+        var entry = new Entry(
+            JsonSerializer.Serialize(value, Json),
+            expiry > TimeSpan.Zero ? DateTimeOffset.UtcNow.Add(expiry) : null);
+
+        lock (_gate)
+        {
+            if (!_entries.ContainsKey(key))
+            {
+                EvictIfFull();
+                _order.Enqueue(key);
+            }
+            _entries[key] = entry;
+        }
+        return Task.CompletedTask;
+    }
+
+    public Task<bool> DeleteAsync(string scope, string id)
+    {
+        var key = CacheKey.Build(_options.KeyPrefix, scope, id);
+        lock (_gate)
+        {
+            return Task.FromResult(_entries.Remove(key));
+        }
+    }
+
+    public async Task<T> GetOrSetAsync<T>(
+        string scope,
+        string id,
+        Func<CancellationToken, Task<T>> load,
+        TimeSpan? ttl = null,
+        CancellationToken cancellationToken = default)
+    {
+        var hit = await TryGetAsync<T>(scope, id).ConfigureAwait(false);
+        if (hit.Found)
+        {
+            return hit.Value!;
+        }
+
+        var value = await load(cancellationToken).ConfigureAwait(false);
+        await SetAsync(scope, id, value, ttl).ConfigureAwait(false);
+        return value;
+    }
+
+    public Task<int> InvalidateNamespaceAsync(string scope)
+    {
+        var prefix = CacheKey.NamespacePrefix(_options.KeyPrefix, scope);
+        lock (_gate)
+        {
+            var doomed = _entries.Keys.Where(key => key.StartsWith(prefix, StringComparison.Ordinal)).ToArray();
+            foreach (var key in doomed)
+            {
+                _entries.Remove(key);
+            }
+            return Task.FromResult(doomed.Length);
+        }
+    }
+
+    public Task<bool> PingAsync() => Task.FromResult(true);
+
+    public ValueTask DisposeAsync()
+    {
+        lock (_gate)
+        {
+            _entries.Clear();
+            _order.Clear();
+        }
+        return ValueTask.CompletedTask;
+    }
+
+    // Callers hold the lock.
+    private void EvictIfFull()
+    {
+        if (_options.MemoryMaxEntries <= 0 || _entries.Count < _options.MemoryMaxEntries)
+        {
+            return;
+        }
+        while (_order.TryDequeue(out var oldest))
+        {
+            if (_entries.Remove(oldest))
+            {
+                return;
+            }
+        }
+    }
+
+    private sealed record Entry(string Payload, DateTimeOffset? ExpiresAt);
+}

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

@@ -0,0 +1,139 @@
+using System.Text.Json;
+using StackExchange.Redis;
+
+namespace {{ solutionName | dot }}.Cache.Redis;
+
+/// <summary>
+/// Typed wrapper over StackExchange.Redis. Values cross the wire as JSON and keys are
+/// namespaced; timeouts and retries come from <see cref="CacheOptions"/>.
+/// </summary>
+public sealed class RedisCacheStore : ICacheStore
+{
+    /// <summary>SCAN page size: a throughput/latency trade-off internal to invalidation, not a setting.</summary>
+    private const int ScanPageSize = 250;
+
+    private static readonly JsonSerializerOptions Json = new(JsonSerializerDefaults.Web);
+
+    private readonly CacheOptions _options;
+    private readonly IConnectionMultiplexer _multiplexer;
+    private readonly IDatabase _database;
+
+    private RedisCacheStore(CacheOptions options, IConnectionMultiplexer multiplexer)
+    {
+        _options = options;
+        _multiplexer = multiplexer;
+        _database = multiplexer.GetDatabase();
+    }
+
+    public static async Task<RedisCacheStore> ConnectAsync(CacheOptions options)
+    {
+        var multiplexer = await ConnectionMultiplexer
+            .ConnectAsync(options.ToConfiguration())
+            .ConfigureAwait(false);
+        return new RedisCacheStore(options, multiplexer);
+    }
+
+    public async Task<CacheResult<T>> TryGetAsync<T>(string scope, string id)
+    {
+        var key = CacheKey.Build(_options.KeyPrefix, scope, id);
+        var payload = await _database.StringGetAsync(key).ConfigureAwait(false);
+        if (!payload.HasValue)
+        {
+            return new CacheResult<T>(false, default);
+        }
+
+        var json = payload.ToString();
+        try
+        {
+            return new CacheResult<T>(true, JsonSerializer.Deserialize<T>(json, Json));
+        }
+        catch (JsonException)
+        {
+            // A value we cannot decode is poison; drop it so the next read is a clean miss.
+            await _database.KeyDeleteAsync(key).ConfigureAwait(false);
+            return new CacheResult<T>(false, default);
+        }
+    }
+
+    public async Task SetAsync<T>(string scope, string id, T value, TimeSpan? ttl = null)
+    {
+        var key = CacheKey.Build(_options.KeyPrefix, scope, id);
+        var payload = JsonSerializer.Serialize(value, Json);
+        var requested = ttl ?? _options.DefaultTtl;
+        // Expiration.Default writes no TTL — the StackExchange.Redis 3.x spelling of "no expiry".
+        var expiry = requested > TimeSpan.Zero ? new Expiration(requested) : Expiration.Default;
+        await _database.StringSetAsync(key, payload, expiry).ConfigureAwait(false);
+    }
+
+    public async Task<bool> DeleteAsync(string scope, string id)
+    {
+        var key = CacheKey.Build(_options.KeyPrefix, scope, id);
+        return await _database.KeyDeleteAsync(key).ConfigureAwait(false);
+    }
+
+    public async Task<T> GetOrSetAsync<T>(
+        string scope,
+        string id,
+        Func<CancellationToken, Task<T>> load,
+        TimeSpan? ttl = null,
+        CancellationToken cancellationToken = default)
+    {
+        var hit = await TryGetAsync<T>(scope, id).ConfigureAwait(false);
+        if (hit.Found)
+        {
+            return hit.Value!;
+        }
+
+        var value = await load(cancellationToken).ConfigureAwait(false);
+        await SetAsync(scope, id, value, ttl).ConfigureAwait(false);
+        return value;
+    }
+
+    /// <summary>Iterates with SCAN, never KEYS: KEYS blocks the server on a large keyspace.</summary>
+    public async Task<int> InvalidateNamespaceAsync(string scope)
+    {
+        var pattern = CacheKey.NamespacePattern(_options.KeyPrefix, scope);
+        var removed = 0;
+        var batch = new List<RedisKey>(ScanPageSize);
+
+        foreach (var endpoint in _multiplexer.GetEndPoints())
+        {
+            var server = _multiplexer.GetServer(endpoint);
+            if (server.IsReplica)
+            {
+                continue;
+            }
+
+            await foreach (var key in server.KeysAsync(_database.Database, pattern, ScanPageSize).ConfigureAwait(false))
+            {
+                batch.Add(key);
+                if (batch.Count < ScanPageSize)
+                {
+                    continue;
+                }
+                removed += (int)await _database.KeyDeleteAsync(batch.ToArray()).ConfigureAwait(false);
+                batch.Clear();
+            }
+
+            if (batch.Count > 0)
+            {
+                removed += (int)await _database.KeyDeleteAsync(batch.ToArray()).ConfigureAwait(false);
+                batch.Clear();
+            }
+        }
+
+        return removed;
+    }
+
+    public async Task<bool> PingAsync()
+    {
+        var latency = await _database.PingAsync().ConfigureAwait(false);
+        return latency >= TimeSpan.Zero;
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        await _multiplexer.CloseAsync().ConfigureAwait(false);
+        _multiplexer.Dispose();
+    }
+}

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

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Cache.Redis</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Cache.Redis</AssemblyName>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <LangVersion>latest</LangVersion>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);CS1591</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="StackExchange.Redis" />
+  </ItemGroup>
+
+</Project>

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

@@ -0,0 +1,67 @@
+"""The cache entry point.
+
+Import ``get_cache()`` — never a concrete store — so disabling the cache in the environment
+is enough to run the app without Redis::
+
+    from {{ solutionName | snake }}.cache.api import get_cache
+
+    cache = await get_cache()
+    user = await cache.get_or_set("user", user_id, lambda: load_user(user_id))
+
+The package deliberately ships no ``__init__.py``: it is a PEP 420 namespace package, which
+keeps the public surface in one importable module.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from .keys import build_key, namespace_pattern
+from .settings import CacheSettings, TtlSeconds, load_cache_settings
+from .store import CacheStore, MemoryCacheStore
+
+__all__ = [
+    "CacheSettings",
+    "CacheStore",
+    "MemoryCacheStore",
+    "TtlSeconds",
+    "build_key",
+    "cache_settings",
+    "close_cache",
+    "get_cache",
+    "load_cache_settings",
+    "namespace_pattern",
+]
+
+_instance: CacheStore | None = None
+
+
+@lru_cache
+def cache_settings() -> CacheSettings:
+    """Cached so the environment is read once and every caller shares one instance."""
+    return load_cache_settings()
+
+
+async def get_cache() -> CacheStore:
+    """One client per process; the first call builds it, later calls reuse it."""
+    global _instance
+    if _instance is not None:
+        return _instance
+    settings = cache_settings()
+    if settings.enabled:
+        # Imported lazily so a disabled cache needs no redis package installed.
+        from .redis_store import RedisCacheStore
+
+        _instance = RedisCacheStore(settings)
+    else:
+        _instance = MemoryCacheStore(settings)
+    return _instance
+
+
+async def close_cache() -> None:
+    """Call on shutdown; safe when no cache was ever created."""
+    global _instance
+    if _instance is not None:
+        await _instance.close()
+        _instance = None
+    cache_settings.cache_clear()

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

@@ -0,0 +1,39 @@
+"""Key layout: ``<prefix>:<namespace>:<id>``.
+
+Every implementation builds keys here so namespace invalidation and the Redis SCAN pattern
+can never drift apart.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Redis convention, not a tunable.
+SEPARATOR = ":"
+
+# Whitespace breaks the wire protocol; glob characters would make invalidation over-match.
+_ILLEGAL = re.compile(r"[\s*?\[\]]")
+
+
+def build_key(prefix: str, namespace: str, key_id: str) -> str:
+    segments = [segment for segment in (prefix, namespace, key_id) if segment]
+    if len(segments) < 2:
+        raise ValueError("cache key needs at least a namespace and an id")
+    for segment in segments:
+        if _ILLEGAL.search(segment):
+            raise ValueError(
+                f"cache key segment {segment!r} contains whitespace or a glob character"
+            )
+    return SEPARATOR.join(segments)
+
+
+def namespace_prefix(prefix: str, namespace: str) -> str:
+    base = SEPARATOR.join(segment for segment in (prefix, namespace) if segment)
+    if _ILLEGAL.search(base):
+        raise ValueError(f"cache namespace {namespace!r} is not a valid key segment")
+    return f"{base}{SEPARATOR}"
+
+
+def namespace_pattern(prefix: str, namespace: str) -> str:
+    """SCAN pattern matching every key in one namespace."""
+    return f"{namespace_prefix(prefix, namespace)}*"

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

@@ -0,0 +1,85 @@
+"""Typed wrapper over redis-py's asyncio client.
+
+Values cross the wire as JSON, keys are namespaced, and every command inherits the
+configured timeout so a stalled cache cannot stall a request.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from redis.asyncio import Redis
+
+from .keys import build_key, namespace_pattern
+from .settings import CacheSettings
+from .store import Loader
+
+# SCAN page size: a throughput/latency trade-off internal to invalidation, not a setting.
+_SCAN_COUNT = 250
+
+
+class RedisCacheStore:
+    def __init__(self, settings: CacheSettings, client: Redis | None = None) -> None:
+        self._settings = settings
+        self._client = client or Redis.from_url(
+            settings.url,
+            decode_responses=True,
+            socket_connect_timeout=settings.connect_timeout_ms / 1000,
+            socket_timeout=settings.command_timeout_ms / 1000,
+            retry_on_timeout=True,
+            health_check_interval=30,
+        )
+
+    async def get(self, namespace: str, key_id: str) -> Any | None:
+        key = build_key(self._settings.key_prefix, namespace, key_id)
+        raw = await self._client.get(key)
+        if raw is None:
+            return None
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            # A value we cannot parse is poison; drop it so the next read is a clean miss.
+            await self._client.delete(key)
+            return None
+
+    async def set(
+        self, namespace: str, key_id: str, value: Any, ttl_seconds: int | None = None
+    ) -> None:
+        key = build_key(self._settings.key_prefix, namespace, key_id)
+        ttl = self._settings.ttl.default if ttl_seconds is None else ttl_seconds
+        await self._client.set(key, json.dumps(value), ex=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 await self._client.delete(key) > 0
+
+    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:
+        """SCAN + UNLINK, never KEYS + DEL: neither call blocks the server."""
+        pattern = namespace_pattern(self._settings.key_prefix, namespace)
+        removed = 0
+        batch: list[str] = []
+        async for key in self._client.scan_iter(match=pattern, count=_SCAN_COUNT):
+            batch.append(key)
+            if len(batch) >= _SCAN_COUNT:
+                removed += await self._client.unlink(*batch)
+                batch.clear()
+        if batch:
+            removed += await self._client.unlink(*batch)
+        return removed
+
+    async def ping(self) -> bool:
+        return bool(await self._client.ping())
+
+    async def close(self) -> None:
+        await self._client.aclose()