python-platform 0.1.1__py3-none-any.whl

python_platform/realtime/messages.py

@@ -0,0 +1,113 @@
+"""Provider-neutral realtime wire envelope 与 JSON boundary。"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from types import MappingProxyType
+from typing import Final, Literal
+from uuid import UUID, uuid4
+
+from ..invocation.contracts import _is_safe_correlation_id
+
+_MESSAGE_TYPE_PATTERN = re.compile(r"^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*\.v[1-9][0-9]*$")
+_REALTIME_SCHEMA_VERSION: Final = 1
+
+
+@dataclass(frozen=True, slots=True)
+class RealtimeEnvelope:
+    """不可变、可序列化且不携带 transport/provider object 的消息。"""
+
+    message_type: str
+    correlation_id: str
+    payload: Mapping[str, object]
+    schema_version: Literal[1] = _REALTIME_SCHEMA_VERSION
+    message_id: UUID = field(default_factory=uuid4)
+    occurred_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+    def __post_init__(self) -> None:
+        if self.schema_version != _REALTIME_SCHEMA_VERSION:
+            raise ValueError(f"realtime schema_version must be {_REALTIME_SCHEMA_VERSION}")
+        if not isinstance(self.message_id, UUID):
+            raise TypeError("realtime message_id must be UUID")
+        if (
+            not isinstance(self.message_type, str)
+            or _MESSAGE_TYPE_PATTERN.fullmatch(self.message_type) is None
+        ):
+            raise ValueError("realtime message_type must be a versioned dotted name")
+        if not _is_safe_correlation_id(self.correlation_id):
+            raise ValueError("realtime correlation_id must be a safe non-empty identifier")
+        if not isinstance(self.occurred_at, datetime) or self.occurred_at.utcoffset() is None:
+            raise ValueError("realtime occurred_at must be timezone-aware")
+        if self.occurred_at.utcoffset() != UTC.utcoffset(self.occurred_at):
+            raise ValueError("realtime occurred_at must be UTC")
+        if not isinstance(self.payload, Mapping):
+            raise TypeError("realtime payload must be a JSON object")
+        frozen = _freeze_json_mapping(self.payload, active=set())
+        object.__setattr__(self, "payload", frozen)
+
+
+def _encode_envelope(envelope: RealtimeEnvelope) -> str:
+    occurred_at = envelope.occurred_at.isoformat().replace("+00:00", "Z")
+    wire = {
+        "schema_version": envelope.schema_version,
+        "message_id": str(envelope.message_id),
+        "message_type": envelope.message_type,
+        "occurred_at": occurred_at,
+        "correlation_id": envelope.correlation_id,
+        "payload": _thaw_json_value(envelope.payload),
+    }
+    return json.dumps(wire, ensure_ascii=False, allow_nan=False, separators=(",", ":"))
+
+
+def _freeze_json_mapping(
+    value: Mapping[str, object],
+    *,
+    active: set[int],
+) -> Mapping[str, object]:
+    identity = id(value)
+    if identity in active:
+        raise ValueError("realtime payload cannot contain cycles")
+    active.add(identity)
+    try:
+        frozen: dict[str, object] = {}
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise TypeError("realtime payload object keys must be strings")
+            frozen[key] = _freeze_json_value(item, active=active)
+        return MappingProxyType(frozen)
+    finally:
+        active.remove(identity)
+
+
+def _freeze_json_value(value: object, *, active: set[int]) -> object:
+    if value is None or isinstance(value, (str, bool, int)):
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError("realtime payload numbers must be finite")
+        return value
+    if isinstance(value, Mapping):
+        return _freeze_json_mapping(value, active=active)
+    if isinstance(value, (list, tuple)):
+        identity = id(value)
+        if identity in active:
+            raise ValueError("realtime payload cannot contain cycles")
+        active.add(identity)
+        try:
+            return tuple(_freeze_json_value(item, active=active) for item in value)
+        finally:
+            active.remove(identity)
+    raise TypeError("realtime payload contains a non-JSON value")
+
+
+def _thaw_json_value(value: object) -> object:
+    if isinstance(value, Mapping):
+        return {key: _thaw_json_value(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        return [_thaw_json_value(item) for item in value]
+    return value

python_platform/redis/__init__.py

@@ -0,0 +1,6 @@
+"""Optional Redis distributed cache provider。"""
+
+from .module import RedisConnectionModule, RedisDistributedLockModule, RedisModule
+from .options import RedisOptions
+
+__all__ = ("RedisConnectionModule", "RedisDistributedLockModule", "RedisModule", "RedisOptions")

python_platform/redis/distributed_lock.py

@@ -0,0 +1,212 @@
+"""原生 Redis Lock 的接线与每次获取独立的业务取消／资源 owner。"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Awaitable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from typing import TypeVar, cast
+from uuid import uuid4
+
+from anyio import CancelScope
+from redis.exceptions import LockNotOwnedError
+
+from ..distributed_lock import DistributedLockError, DistributedLockOptions
+from ..options import Options
+from .lease_lock import _LeaseLock
+from .options import RedisOptions
+from .runtime import _RedisClientOwner
+
+_T = TypeVar("_T")
+
+
+class RedisDistributedLock:
+    """APP 服务只持有连接和冻结配置；可变租约不在不同获取之间共享。"""
+
+    def __init__(
+        self,
+        client: _RedisClientOwner,
+        options: Options[DistributedLockOptions],
+        redis_options: Options[RedisOptions],
+    ) -> None:
+        self._client = client.client
+        self._options = options.value
+        self._prefix = redis_options.value.key_prefix
+
+    def acquire(self, key: str, /) -> AbstractAsyncContextManager[bool]:
+        if not isinstance(key, str) or not key or key != key.strip():
+            raise ValueError("Distributed lock key must be a nonempty trimmed string")
+        native = self._client.lock(
+            f"{self._prefix}:locks:{key}",
+            timeout=self._options.lease_timeout.total_seconds(),
+            blocking_timeout=self._options.wait_timeout.total_seconds(),
+            thread_local=False,
+            lock_class=_LeaseLock,
+        )
+        return _RedisLockLease(key, cast(_LeaseLock, native), self._options).hold()
+
+
+class _RedisLockLease:
+    def __init__(self, key: str, native: _LeaseLock, options: DistributedLockOptions) -> None:
+        self._key = key
+        self._lock = native
+        self._options = options
+        self._stop = asyncio.Event()
+        self._active = False
+        self._lease_errors: list[BaseException] = []
+        self._cancellation: asyncio.CancelledError | None = None
+
+    @asynccontextmanager
+    async def hold(self) -> AsyncIterator[bool]:
+        # 显式 token 仍交给原生 Lua 仲裁；响应丢失时也只能条件释放本次 token，不能 DEL key。
+        token = uuid4().hex.encode()
+        try:
+            acquired = await self._wait_owned(
+                asyncio.ensure_future(cast(Awaitable[bool], self._lock.acquire(token=token)))
+            )
+            if acquired and asyncio.get_running_loop().time() >= self._lock.deadline:
+                raise TimeoutError("Acquire response arrived after the conservative lease deadline")
+        except BaseException as error:
+            failures = [self._native_error("acquire", error)]
+            try:
+                await self._wait_owned(asyncio.create_task(self._lock.do_release(token)))
+            except LockNotOwnedError:
+                # 获取未成功或响应不确定时，无本次 token 是合法结果；原始失败仍然传播。
+                pass
+            except BaseException as cleanup_error:
+                failures.append(self._native_error("release", cleanup_error))
+            failure = _lock_failure(failures, self._cancellation)
+            raise failure from failure.__cause__
+
+        if not acquired:
+            self._raise_failures(None, [])
+            yield False
+            return
+
+        body_error: BaseException | None = None
+        failures = []
+        renewal: asyncio.Task[None] | None = None
+        try:
+            self._raise_failures(None, [])
+            # 上下文进入、业务与退出属于同一 task；业务自身的 shield / 线程等待保持原生语义。
+            with CancelScope() as scope:
+                self._active = True
+                renewal = asyncio.create_task(
+                    self._renew(scope), name="python-platform-lock-renewal"
+                )
+                try:
+                    yield True
+                except BaseException as error:
+                    body_error = error
+                    raise
+        except BaseException as error:
+            body_error = error
+        finally:
+            # body 的 finally 已退出，才停续租并释放锁。I/O 尚未结束时不与 release 并发。
+            self._active = False
+            self._stop.set()
+            if renewal is not None:
+                await self._wait_owned(renewal)
+            failures.extend(self._lease_errors)
+            try:
+                await self._wait_owned(asyncio.create_task(self._lock.release()))
+            except BaseException as cleanup_error:
+                failures.append(self._native_error("release", cleanup_error))
+        self._raise_failures(body_error, failures)
+
+    async def _renew(self, scope: CancelScope) -> None:
+        interval = self._options.renewal_interval.total_seconds()
+        loop = asyncio.get_running_loop()
+        try:
+            while True:
+                deadline = self._lock.deadline
+                delay = max(0, min(self._lock.lease_started + interval, deadline) - loop.time())
+                if self._stop.is_set():
+                    return
+                try:
+                    await asyncio.wait_for(self._stop.wait(), delay)
+                    return
+                except TimeoutError:
+                    pass
+                remaining = deadline - loop.time()
+                if remaining <= 0:
+                    raise TimeoutError("Lease expired before renewal")
+                request = asyncio.ensure_future(self._lock.reacquire())
+                done, _ = await asyncio.wait((request,), timeout=remaining)
+                if not done or loop.time() >= deadline:
+                    # 旧截止时间不能被迟到的成功响应延长。先撤销业务许可，再等 I/O 收口；
+                    # 不 cancel 请求后立即 release，避免旧续租与 Token 释放并发。
+                    self._fail_lease(scope, TimeoutError("Renewal exceeded the lease deadline"))
+                    try:
+                        await request
+                    except BaseException as error:
+                        self._fail_lease(scope, error)
+                    return
+                request.result()
+        except BaseException as error:
+            self._fail_lease(scope, error)
+
+    def _fail_lease(self, scope: CancelScope, error: BaseException) -> None:
+        self._lease_errors.append(self._native_error("renew", error))
+        if self._active:
+            scope.cancel()
+
+    async def _wait_owned(self, future: asyncio.Future[_T]) -> _T:
+        # caller 取消不能遗弃正在获取／释放的原生 I/O。记录取消，确定 Token 结果并清理后再传播。
+        try:
+            return await asyncio.shield(future)
+        except asyncio.CancelledError as cancellation:
+            if self._cancellation is None:
+                self._cancellation = cancellation
+        # 外层 AnyIO level cancellation 会在每次 await 重发；捕获后必须 shield 收尾，
+        # 否则 asyncio.shield 的反复等待会形成忙循环。raw task.cancel 仍被记录并等待。
+        with CancelScope(shield=True):
+            while not future.done():
+                try:
+                    await asyncio.shield(future)
+                except asyncio.CancelledError:
+                    # 首次取消已保存；再次 raw cancel 也不能遗弃这个 I/O owner。
+                    continue
+        return future.result()
+
+    def _native_error(self, operation: str, error: BaseException) -> BaseException:
+        if not isinstance(error, Exception):
+            return error
+        failure = DistributedLockError(
+            key=self._key, operation=operation, error_type=type(error).__name__
+        )
+        failure.__cause__ = error
+        return failure
+
+    def _raise_failures(
+        self, body_error: BaseException | None, failures: list[BaseException]
+    ) -> None:
+        cancellation = self._cancellation
+        if isinstance(body_error, asyncio.CancelledError):
+            cancellation = body_error
+        elif body_error is not None:
+            if not failures:
+                if cancellation is None:
+                    # 成功清理时保持业务异常原有 cause，不用 from None 覆盖调用者的诊断链。
+                    raise body_error
+                raise _lock_failure([body_error, cancellation])
+            failures.insert(0, body_error)
+        if failures:
+            raise _lock_failure(failures, cancellation)
+        if cancellation is not None:
+            raise cancellation
+
+
+def _lock_failure(
+    failures: list[BaseException], cancellation: asyncio.CancelledError | None = None
+) -> BaseException:
+    if cancellation is not None:
+        # 取消放在聚合 cause，原生 I/O 的 cause 留在各失败上，避免相互覆盖。
+        group = BaseExceptionGroup("Distributed lock operation and cleanup failed", tuple(failures))
+        group.__cause__ = cancellation
+        return group
+    return (
+        failures[0]
+        if len(failures) == 1
+        else BaseExceptionGroup("Distributed lock operation and cleanup failed", tuple(failures))
+    )

python_platform/redis/lease_lock.py

@@ -0,0 +1,36 @@
+"""redis-py 原生扩展点：记录成功请求的起点，不接管重试或 Token Lua。"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Literal
+
+from redis.asyncio.lock import Lock
+
+
+class _LeaseLock(Lock):
+    _lease_started: float
+
+    @property
+    def lease_started(self) -> float:
+        return self._lease_started
+
+    @property
+    def deadline(self) -> float:
+        # 与原生 SET PX / reacquire Lua 使用的毫秒截断保持一致。
+        assert self.timeout is not None
+        return self._lease_started + int(self.timeout * 1000) / 1000
+
+    async def do_acquire(self, token: str | bytes) -> bool:
+        started = asyncio.get_running_loop().time()
+        acquired = await super().do_acquire(token)
+        if acquired:
+            # 竞争失败及原生 retry sleep 不消耗下一次成功获取的租期。
+            self._lease_started = started
+        return acquired
+
+    async def do_reacquire(self) -> Literal[True]:
+        started = asyncio.get_running_loop().time()
+        result = await super().do_reacquire()
+        self._lease_started = started
+        return result

python_platform/redis/module.py

@@ -0,0 +1,50 @@
+"""Host 显式选择的 Redis Module。"""
+
+from __future__ import annotations
+
+from dishka import Provider, Scope
+
+from ..caching import DistributedCache
+from ..distributed_lock import DistributedLock, DistributedLockOptions
+from ..lifecycle import ConfigureContext, InitializeContext
+from ..modularity import AppModule
+from .distributed_lock import RedisDistributedLock
+from .options import RedisOptions
+from .runtime import RedisDistributedCache, _redis_client, _RedisClientOwner
+
+
+class RedisConnectionModule(AppModule):
+    """共享原生连接生命周期；缓存和通知自行决定连接故障的业务语义。"""
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure(RedisOptions, section="redis", secret_paths=frozenset({"url"}))
+        provider = Provider()
+        provider.provide(_redis_client, provides=_RedisClientOwner, scope=Scope.APP)
+        context.services.contribute(provider, reason="Application Redis connection")
+
+
+class RedisModule(AppModule):
+    dependencies = (RedisConnectionModule,)
+
+    def configure(self, context: ConfigureContext) -> None:
+        provider = Provider()
+        provider.provide(
+            RedisDistributedCache,
+            provides=DistributedCache,
+            scope=Scope.APP,
+        )
+        context.services.contribute(provider, reason="Redis typed distributed cache")
+
+    async def initialize(self, context: InitializeContext) -> None:
+        client = await context.container.get(_RedisClientOwner)
+        await client.ping()
+
+
+class RedisDistributedLockModule(AppModule):
+    dependencies = (RedisConnectionModule,)
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure(DistributedLockOptions, section="distributed_lock")
+        provider = Provider()
+        provider.provide(RedisDistributedLock, provides=DistributedLock, scope=Scope.APP)
+        context.services.contribute(provider, reason="Redis renewable distributed lock")

python_platform/redis/notification_runtime.py

@@ -0,0 +1,182 @@
+"""原生 Redis Pub/Sub 的 typed 边界与 Application-owned 接收生命周期。"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager, suppress
+from dataclasses import dataclass
+from typing import Any, ClassVar, TypeVar, cast
+
+from pydantic import ConfigDict, Field
+from redis.exceptions import RedisError
+
+from ..application_services.invocation import _InvocationRuntime
+from ..hosted_services import HostedService, HostedServiceContext
+from ..lifecycle import ShutdownReason
+from ..notifications import (
+    NotificationCatalog,
+    NotificationDefinition,
+    NotificationDefinitionError,
+    NotificationPayloadError,
+    NotificationPublishStatus,
+)
+from ..observability.context import capture_trace_context, invocation_span
+from ..options import BaseOptions, Options
+from .options import RedisOptions
+from .runtime import _RedisClientOwner
+
+_T = TypeVar("_T")
+_LOGGER = logging.getLogger(__name__)
+
+
+class NotificationOptions(BaseOptions):
+    model_config = ConfigDict(extra="forbid")
+
+    max_message_bytes: int = Field(default=65536, ge=1)
+    reconnect_interval_seconds: float = Field(default=1.0, gt=0)
+    publish_timeout_seconds: float = Field(default=5.0, gt=0)
+
+
+@dataclass(frozen=True, slots=True)
+class _Subscriber:
+    handler: Callable[[Any], Awaitable[None]]
+    on_reconnect: Callable[[], None] | None
+
+
+class RedisNotifications(HostedService):
+    run_in_background_processes: ClassVar[bool] = True
+
+    def __init__(
+        self,
+        client: _RedisClientOwner,
+        catalog: NotificationCatalog,
+        options: Options[NotificationOptions],
+        redis_options: Options[RedisOptions],
+        runtime: _InvocationRuntime,
+    ) -> None:
+        self._client = client.client
+        self._catalog = catalog
+        self._options = options.value
+        self._runtime = runtime
+        self._channels = {
+            f"{redis_options.value.key_prefix}:notifications:{definition.name}": definition
+            for definition in catalog.definitions
+        }
+        self._prefix = f"{redis_options.value.key_prefix}:notifications:"
+        self._subscribers: dict[str, dict[object, _Subscriber]] = {
+            channel: {} for channel in self._channels
+        }
+        self._connected: set[str] = set()
+        self._outage_reported = False
+        self._task: asyncio.Task[None] | None = None
+
+    async def start(self, context: HostedServiceContext) -> None:
+        self._task = asyncio.create_task(self._listen(), name=context.name)
+        # 接收/重连由组件拥有；启动完成不等同于 Redis 订阅已确认。
+
+    async def stop(self, reason: ShutdownReason) -> None:
+        task = self._task
+        if task is not None:
+            task.cancel()
+            with suppress(asyncio.CancelledError):
+                await task
+        self._connected.clear()
+
+    async def publish(
+        self, definition: NotificationDefinition[_T], payload: _T
+    ) -> NotificationPublishStatus:
+        self._catalog.require_owned(definition)
+        with invocation_span(self._runtime.tracer, f"publish {definition.name}"):
+            encoded = definition._encode(payload, capture_trace_context(self._runtime.tracer))
+            if len(encoded) > self._options.max_message_bytes:
+                raise NotificationPayloadError("Notification exceeds configured message size")
+            try:
+                await asyncio.wait_for(
+                    self._client.publish(self._prefix + definition.name, encoded),
+                    timeout=self._options.publish_timeout_seconds,
+                )
+            except (TimeoutError, RedisError):
+                self._report_outage()
+                return NotificationPublishStatus.UNAVAILABLE
+        return NotificationPublishStatus.PUBLISHED
+
+    @asynccontextmanager
+    async def subscribe(
+        self,
+        definition: NotificationDefinition[_T],
+        handler: Callable[[_T], Awaitable[None]],
+        *,
+        on_reconnect: Callable[[], None] | None = None,
+    ) -> AsyncIterator[None]:
+        self._catalog.require_owned(definition)
+        if not callable(handler) or (on_reconnect is not None and not callable(on_reconnect)):
+            raise NotificationDefinitionError("Notification callbacks must be callable")
+        channel = self._prefix + definition.name
+        token = object()
+        subscriber = _Subscriber(cast(Callable[[Any], Awaitable[None]], handler), on_reconnect)
+        self._subscribers[channel][token] = subscriber
+        try:
+            if channel in self._connected and on_reconnect is not None:
+                on_reconnect()
+            yield
+        finally:
+            self._subscribers[channel].pop(token)
+
+    async def _listen(self) -> None:
+        if not self._channels:
+            await asyncio.Future[None]()
+        while True:
+            try:
+                async with self._client.pubsub() as pubsub:
+                    await pubsub.subscribe(*self._channels)
+                    while True:
+                        message = await pubsub.get_message(
+                            ignore_subscribe_messages=False, timeout=1
+                        )
+                        if message is not None:
+                            await self._receive(message)
+            except RedisError:
+                self._connected.clear()
+                self._report_outage()
+                await asyncio.sleep(self._options.reconnect_interval_seconds)
+
+    async def _receive(self, message: dict[str, Any]) -> None:
+        channel = message["channel"].decode("utf-8")
+        if message["type"] == "subscribe":
+            self._connected.add(channel)
+            self._outage_reported = False
+            for subscriber in tuple(self._subscribers[channel].values()):
+                if subscriber.on_reconnect is not None:
+                    try:
+                        subscriber.on_reconnect()
+                    except Exception as error:
+                        _LOGGER.error(
+                            "Notification reconnect handler failed: %s", type(error).__name__
+                        )
+        elif message["type"] == "message":
+            await self._deliver(channel, message["data"])
+
+    async def _deliver(self, channel: str, encoded: bytes) -> None:
+        definition = self._channels[channel]
+        try:
+            if len(encoded) > self._options.max_message_bytes:
+                raise NotificationPayloadError("Notification exceeds configured message size")
+            payload, carrier = definition._decode(encoded)
+        except NotificationPayloadError:
+            _LOGGER.warning("Invalid notification envelope ignored")
+            return
+        with invocation_span(self._runtime.tracer, f"receive {definition.name}", carrier=carrier):
+            for token, subscriber in tuple(self._subscribers[channel].items()):
+                if token not in self._subscribers[channel]:
+                    continue
+                try:
+                    await subscriber.handler(payload)
+                except Exception as error:
+                    _LOGGER.error("Notification handler failed: %s", type(error).__name__)
+
+    def _report_outage(self) -> None:
+        if not self._outage_reported:
+            _LOGGER.warning("Redis notifications temporarily unavailable")
+            self._outage_reported = True

python_platform/redis/notifications.py

@@ -0,0 +1,25 @@
+"""Host 按需启用 Redis 通知；复用原生 Hosted Service 监督。"""
+
+from dishka import Provider, Scope
+
+from ..lifecycle import ConfigureContext
+from ..modularity import AppModule
+from ..notifications import Notifications
+from .module import RedisConnectionModule
+from .notification_runtime import NotificationOptions, RedisNotifications
+
+
+class RedisNotificationsModule(AppModule):
+    dependencies = (RedisConnectionModule,)
+    hosted_services = (RedisNotifications,)
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure(NotificationOptions, section="notifications")
+        provider = Provider()
+        provider.provide(_notifications, provides=Notifications, scope=Scope.APP)
+        context.services.contribute(provider, reason="Redis typed Pub/Sub")
+
+
+def _notifications(runtime: RedisNotifications) -> Notifications:
+    # 正式 catalog 只接纳 provide；同一实例承担通知契约与 Hosted Service 生命周期。
+    return runtime

python_platform/redis/options.py

@@ -0,0 +1,35 @@
+"""Redis connection 与统一 key prefix Options。"""
+
+from __future__ import annotations
+
+from pydantic import SecretStr, field_validator
+
+from ..options import BaseOptions
+
+
+class RedisOptions(BaseOptions):
+    url: SecretStr
+    key_prefix: str = "python-platform"
+
+    @field_validator("url")
+    @classmethod
+    def _validate_url(cls, value: SecretStr) -> SecretStr:
+        raw = value.get_secret_value()
+        scheme, separator, remainder = raw.partition("://")
+        if scheme not in {"redis", "rediss"} or not separator or not remainder:
+            raise ValueError("Redis URL must use redis:// or rediss://")
+        return value
+
+    @field_validator("key_prefix")
+    @classmethod
+    def _validate_key_prefix(cls, value: str) -> str:
+        if (
+            not value
+            or value != value.strip()
+            or value.startswith(":")
+            or value.endswith(":")
+            or "::" in value
+            or len(value) > 128
+        ):
+            raise ValueError("Redis key_prefix must be a trimmed identifier")
+        return value