python-ddd-framework 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

python_ddd_framework/redis/cache.py

@@ -0,0 +1,243 @@
+"""类型化 Redis Provider；序列化错误与业务 factory 不进入故障隐藏边界。"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Awaitable, Callable, Iterable
+from functools import partial
+from typing import Generic, TypeVar
+
+from pydantic import TypeAdapter
+from redis.exceptions import RedisError
+
+from ..caching import DistributedCacheEntryOptions, DistributedCacheError, DistributedCacheOptions
+from ..caching.naming import _cache_name
+from ..caching.unit_of_work import _CachePending, _pending
+from ..options import Options
+from ..unit_of_work import UnitOfWorkManager
+from .cache_scripts import _READ, _WRITE
+from .options import RedisOptions
+from .runtime import _RedisClientOwner
+
+_T = TypeVar("_T")
+
+
+class RedisDistributedCache(Generic[_T]):
+    def __init__(
+        self,
+        value_type: type[_T],
+        client: _RedisClientOwner,
+        options: Options[RedisOptions],
+        cache_options: Options[DistributedCacheOptions],
+        manager: UnitOfWorkManager,
+    ) -> None:
+        self._client = client.client
+        self._name = _cache_name(value_type)
+        self._prefix = options.value.key_prefix
+        self._options = cache_options.value
+        self._manager = manager
+        self._adapter: TypeAdapter[_T] = TypeAdapter(value_type)
+
+    def _key(self, key: str) -> str:
+        if not isinstance(key, str) or not key or key != key.strip() or len(key) > 512:
+            raise ValueError(
+                "cache key must be a nonempty trimmed string of at most 512 characters"
+            )
+        # 长度前缀明确隔开 Host/type/caller 三个片段，调用 key 可包含冒号而不串缓存。
+        return f"{len(self._prefix)}:{self._prefix}:{len(self._name)}:{self._name}:{key}"
+
+    def _state(self, consider_uow: bool) -> _CachePending | None:
+        if not consider_uow:
+            return None
+        work = self._manager.current
+        return _pending(work) if work is not None else None
+
+    async def _access(
+        self,
+        operation: str,
+        hide_errors: bool | None,
+        call: Callable[[], Awaitable[object]],
+    ) -> object:
+        try:
+            return await call()
+        except RedisError as error:
+            if self._options.hide_errors if hide_errors is None else hide_errors:
+                return None
+            raise DistributedCacheError(
+                operation=operation, cache=self._name, error_type=type(error).__name__
+            ) from None
+
+    async def _read(self, redis_key: str, hide_errors: bool | None) -> bytes | None:
+        payload = await self._access(
+            "get", hide_errors, partial(self._client.eval, _READ, 1, redis_key)
+        )
+        if payload is not None and not isinstance(payload, bytes):
+            raise TypeError("Redis cache returned a non-bytes payload")
+        return payload
+
+    async def get(
+        self, key: str, *, hide_errors: bool | None = None, consider_uow: bool = False
+    ) -> _T | None:
+        redis_key = self._key(key)
+        state = self._state(consider_uow)
+        payload = (
+            state.writes[redis_key][0]
+            if state is not None and redis_key in state.writes
+            else await self._read(redis_key, hide_errors)
+        )
+        return None if payload is None else self._adapter.validate_json(payload, strict=True)
+
+    async def get_many(
+        self, keys: Iterable[str], *, hide_errors: bool | None = None, consider_uow: bool = False
+    ) -> list[tuple[str, _T | None]]:
+        keys = list(keys)
+        for key in keys:
+            self._key(key)
+        return [
+            (key, await self.get(key, hide_errors=hide_errors, consider_uow=consider_uow))
+            for key in keys
+        ]
+
+    async def get_or_add(
+        self,
+        key: str,
+        factory: Callable[[], Awaitable[_T | None]],
+        *,
+        options_factory: Callable[[], DistributedCacheEntryOptions] | None = None,
+        hide_errors: bool | None = None,
+        consider_uow: bool = False,
+    ) -> _T | None:
+        value = await self.get(key, hide_errors=hide_errors, consider_uow=consider_uow)
+        if value is not None:
+            return value
+        value = await factory()
+        if value is not None:
+            await self.set(
+                key,
+                value,
+                options=options_factory() if options_factory else None,
+                hide_errors=hide_errors,
+                consider_uow=consider_uow,
+            )
+        return value
+
+    async def get_or_add_many(
+        self,
+        keys: Iterable[str],
+        factory: Callable[[list[str]], Awaitable[Iterable[tuple[str, _T]]]],
+        *,
+        options_factory: Callable[[], DistributedCacheEntryOptions] | None = None,
+        hide_errors: bool | None = None,
+        consider_uow: bool = False,
+    ) -> list[tuple[str, _T | None]]:
+        found = await self.get_many(keys, hide_errors=hide_errors, consider_uow=consider_uow)
+        missing = list(dict.fromkeys(key for key, value in found if value is None))
+        if not missing:
+            return found
+        values: dict[str, _T] = {}
+        for key, value in await factory(missing):
+            if key not in missing or key in values:
+                raise ValueError("factory must return unique keys from the requested missing keys")
+            values[key] = value
+        await self.set_many(
+            values.items(),
+            options=options_factory() if options_factory else None,
+            hide_errors=hide_errors,
+            consider_uow=consider_uow,
+        )
+        return [(key, values.get(key, value)) for key, value in found]
+
+    def _expiration(self, options: DistributedCacheEntryOptions | None) -> tuple[int, int, int]:
+        selected = self._options.default_entry_options if options is None else options
+        if not isinstance(selected, DistributedCacheEntryOptions):
+            raise TypeError("options must be DistributedCacheEntryOptions")
+        return (
+            math.ceil(selected.absolute_expiration.timestamp() * 1000)
+            if selected.absolute_expiration is not None
+            else 0,
+            math.ceil(selected.absolute_expiration_relative_to_now.total_seconds() * 1000)
+            if selected.absolute_expiration_relative_to_now is not None
+            else 0,
+            math.ceil(selected.sliding_expiration.total_seconds() * 1000)
+            if selected.sliding_expiration is not None
+            else 0,
+        )
+
+    async def _write(
+        self,
+        redis_key: str,
+        payload: bytes,
+        expiration: tuple[int, int, int],
+        hide_errors: bool | None,
+    ) -> None:
+        await self._access(
+            "set",
+            hide_errors,
+            partial(self._client.eval, _WRITE, 1, redis_key, payload, *expiration),
+        )
+
+    async def set(
+        self,
+        key: str,
+        value: _T,
+        *,
+        options: DistributedCacheEntryOptions | None = None,
+        hide_errors: bool | None = None,
+        consider_uow: bool = False,
+    ) -> None:
+        await self.set_many(
+            [(key, value)], options=options, hide_errors=hide_errors, consider_uow=consider_uow
+        )
+
+    async def set_many(
+        self,
+        items: Iterable[tuple[str, _T]],
+        *,
+        options: DistributedCacheEntryOptions | None = None,
+        hide_errors: bool | None = None,
+        consider_uow: bool = False,
+    ) -> None:
+        expiration = self._expiration(options)
+        # 全部输入先校验/序列化，再做写入；mutable value 不泄漏到待提交快照。
+        encoded = [
+            (
+                self._key(key),
+                self._adapter.dump_json(self._adapter.validate_python(value, strict=True)),
+            )
+            for key, value in items
+        ]
+        state = self._state(consider_uow)
+        for redis_key, payload in encoded:
+            apply = partial(self._write, redis_key, payload, expiration, hide_errors)
+            if state is None:
+                await apply()
+            else:
+                state.writes[redis_key] = (payload, apply)
+
+    async def remove(
+        self, key: str, *, hide_errors: bool | None = None, consider_uow: bool = False
+    ) -> None:
+        await self.remove_many([key], hide_errors=hide_errors, consider_uow=consider_uow)
+
+    async def _remove(self, redis_key: str, hide_errors: bool | None) -> None:
+        await self._access("remove", hide_errors, partial(self._client.delete, redis_key))
+
+    async def remove_many(
+        self, keys: Iterable[str], *, hide_errors: bool | None = None, consider_uow: bool = False
+    ) -> None:
+        redis_keys = [self._key(key) for key in keys]
+        state = self._state(consider_uow)
+        for redis_key in redis_keys:
+            apply = partial(self._remove, redis_key, hide_errors)
+            if state is None:
+                await apply()
+            else:
+                state.writes[redis_key] = (None, apply)
+
+    async def refresh(self, key: str, *, hide_errors: bool | None = None) -> None:
+        await self._read(self._key(key), hide_errors)
+
+    async def refresh_many(self, keys: Iterable[str], *, hide_errors: bool | None = None) -> None:
+        redis_keys = [self._key(key) for key in keys]
+        for redis_key in redis_keys:
+            await self._read(redis_key, hide_errors)

python_ddd_framework/redis/cache_scripts.py

@@ -0,0 +1,40 @@
+"""单 key 的值、截止时间与续期在 Redis 内原子处理；不用客户端调度器。"""
+
+_WRITE = """
+local time = redis.call('TIME')
+local now = time[1] * 1000 + math.floor(time[2] / 1000)
+local absolute = tonumber(ARGV[2])
+local relative = tonumber(ARGV[3])
+local sliding = tonumber(ARGV[4])
+if relative > 0 and (absolute == 0 or now + relative < absolute) then
+    absolute = now + relative
+end
+local deadline = absolute
+if sliding > 0 and (deadline == 0 or now + sliding < deadline) then
+    deadline = now + sliding
+end
+redis.call('DEL', KEYS[1])
+if deadline > 0 and deadline <= now then return 0 end
+redis.call('HSET', KEYS[1], 'value', ARGV[1], 'absolute', absolute, 'sliding', sliding)
+if deadline > 0 then redis.call('PEXPIREAT', KEYS[1], deadline) end
+return 1
+"""
+
+_READ = """
+local entry = redis.call('HMGET', KEYS[1], 'value', 'absolute', 'sliding')
+if not entry[1] then return false end
+local time = redis.call('TIME')
+local now = time[1] * 1000 + math.floor(time[2] / 1000)
+local absolute = tonumber(entry[2])
+local sliding = tonumber(entry[3])
+if absolute > 0 and absolute <= now then
+    redis.call('DEL', KEYS[1])
+    return false
+end
+if sliding > 0 then
+    local deadline = now + sliding
+    if absolute > 0 and absolute < deadline then deadline = absolute end
+    redis.call('PEXPIREAT', KEYS[1], deadline)
+end
+return entry[1]
+"""

python_ddd_framework/redis/distributed_lock.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 from collections.abc import AsyncIterator, Awaitable
 from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from datetime import timedelta
 from typing import TypeVar, cast
 from uuid import uuid4
 
@@ -33,13 +34,20 @@ class RedisDistributedLock:
         self._options = options.value
         self._prefix = redis_options.value.key_prefix
 
-    def acquire(self, key: str, /) -> AbstractAsyncContextManager[bool]:
+    def acquire(
+        self, key: str, *, wait_timeout: timedelta | None = None
+    ) -> 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")
+        if wait_timeout is not None and (
+            not isinstance(wait_timeout, timedelta) or wait_timeout < timedelta(0)
+        ):
+            raise ValueError("wait_timeout must be a non-negative timedelta or None")
+        wait = self._options.wait_timeout if wait_timeout is None else wait_timeout
         native = self._client.lock(
             f"{self._prefix}:locks:{key}",
             timeout=self._options.lease_timeout.total_seconds(),
-            blocking_timeout=self._options.wait_timeout.total_seconds(),
+            blocking_timeout=wait.total_seconds(),
             thread_local=False,
             lock_class=_LeaseLock,
         )

python_ddd_framework/redis/module.py

@@ -2,15 +2,24 @@
 
 from __future__ import annotations
 
+from typing import TypeVar
+
 from dishka import Provider, Scope
 
 from ..caching import DistributedCache
+from ..caching.module import CachingModule
 from ..distributed_lock import DistributedLock, DistributedLockOptions
 from ..lifecycle import ConfigureContext, InitializeContext
 from ..modularity import AppModule
+from .cache import RedisDistributedCache
 from .distributed_lock import RedisDistributedLock
 from .options import RedisOptions
-from .runtime import RedisDistributedCache, _redis_client, _RedisClientOwner
+from .runtime import _redis_client, _RedisClientOwner
+
+_T = TypeVar("_T")
+# Dishka 的开放泛型契约与实现必须使用同一个类型变量；闭合由原生 registry 完成。
+_CacheImplementation = RedisDistributedCache[_T]
+_CacheContract = DistributedCache[_T]
 
 
 class RedisConnectionModule(AppModule):
@@ -24,13 +33,13 @@ class RedisConnectionModule(AppModule):
 
 
 class RedisModule(AppModule):
-    dependencies = (RedisConnectionModule,)
+    dependencies = (RedisConnectionModule, CachingModule)
 
     def configure(self, context: ConfigureContext) -> None:
         provider = Provider()
         provider.provide(
-            RedisDistributedCache,
-            provides=DistributedCache,
+            _CacheImplementation,
+            provides=_CacheContract,
             scope=Scope.APP,
         )
         context.services.contribute(provider, reason="Redis typed distributed cache")

python_ddd_framework/redis/notifications.py

@@ -2,16 +2,19 @@
 
 from dishka import Provider, Scope
 
+from ..hosted_services.declarations import HostedServices
+from ..hosted_services.module import HostedServicesModule
 from ..lifecycle import ConfigureContext
 from ..modularity import AppModule
 from ..notifications import Notifications
+from ..notifications.module import NotificationsModule
 from .module import RedisConnectionModule
 from .notification_runtime import NotificationOptions, RedisNotifications
 
 
 class RedisNotificationsModule(AppModule):
-    dependencies = (RedisConnectionModule,)
-    hosted_services = (RedisNotifications,)
+    dependencies = (RedisConnectionModule, NotificationsModule, HostedServicesModule)
+    hosted_services = HostedServices((RedisNotifications,))
 
     def configure(self, context: ConfigureContext) -> None:
         context.configure(NotificationOptions, section="notifications")

python_ddd_framework/redis/runtime.py

@@ -2,15 +2,12 @@
 
 from __future__ import annotations
 
-import math
 from collections.abc import AsyncIterator
-from typing import Any
 
-from pydantic import ValidationError
 from redis.asyncio import Redis
 from redis.exceptions import RedisError
 
-from ..caching import CacheCatalog, CacheDefinition, DistributedCacheError
+from ..caching import DistributedCacheError
 from ..options import Options
 from .options import RedisOptions
 
@@ -39,78 +36,3 @@ async def _redis_client(options: Options[RedisOptions]) -> AsyncIterator[_RedisC
         yield owner
     finally:
         await client.aclose()
-
-
-class RedisDistributedCache:
-    __slots__ = ("_catalog", "_client", "_prefix")
-
-    def __init__(
-        self,
-        client: _RedisClientOwner,
-        catalog: CacheCatalog,
-        options: Options[RedisOptions],
-    ) -> None:
-        self._client = client.client
-        self._catalog = catalog
-        self._prefix = options.value.key_prefix
-
-    async def get(self, definition: CacheDefinition[Any], key: str) -> Any | None:
-        redis_key = self._key(definition, key)
-        try:
-            payload = await self._client.get(redis_key)
-            return None if payload is None else definition._deserialize(payload)
-        except (RedisError, TypeError, ValueError, ValidationError) as original_error:
-            raise DistributedCacheError(
-                operation="get",
-                cache=definition.name,
-                error_type=type(original_error).__name__,
-            ) from None
-
-    async def set(
-        self,
-        definition: CacheDefinition[Any],
-        key: str,
-        value: Any,
-    ) -> None:
-        redis_key = self._key(definition, key)
-        try:
-            payload = definition._serialize(value)
-            await self._client.set(redis_key, payload, ex=math.ceil(definition.ttl.total_seconds()))
-        except (RedisError, TypeError, ValueError, ValidationError) as original_error:
-            raise DistributedCacheError(
-                operation="set",
-                cache=definition.name,
-                error_type=type(original_error).__name__,
-            ) from None
-
-    async def remove(self, definition: CacheDefinition[Any], key: str) -> None:
-        redis_key = self._key(definition, key)
-        try:
-            await self._client.delete(redis_key)
-        except RedisError as original_error:
-            raise DistributedCacheError(
-                operation="remove",
-                cache=definition.name,
-                error_type=type(original_error).__name__,
-            ) from None
-
-    def _key(self, definition: CacheDefinition[Any], key: str) -> str:
-        if not self._catalog.owns(definition):
-            raise DistributedCacheError(
-                operation="key",
-                cache=definition.name,
-                error_type="ForeignCacheDefinition",
-            )
-        if (
-            not isinstance(key, str)
-            or not key
-            or key != key.strip()
-            or any(character.isspace() for character in key)
-            or len(key) > 512
-        ):
-            raise DistributedCacheError(
-                operation="key",
-                cache=definition.name,
-                error_type="InvalidCacheKey",
-            )
-        return f"{self._prefix}:{definition.name}:{key}"

python_ddd_framework/seeding/__init__.py

@@ -0,0 +1,13 @@
+"""按正式模块依赖启用的数据初始化能力。"""
+
+from .contracts import DataSeedContributor, DataSeedError, DataSeedRegistration
+from .module import DataSeedingModule
+from .runtime import DataSeeder
+
+__all__ = (
+    "DataSeedContributor",
+    "DataSeedError",
+    "DataSeedRegistration",
+    "DataSeeder",
+    "DataSeedingModule",
+)

python_ddd_framework/seeding/contracts.py

@@ -0,0 +1,45 @@
+"""数据初始化的独立契约；业务幂等性归贡献者，事务和执行顺序归框架。"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import ClassVar
+
+from dishka import Scope
+
+from ..errors.base import FrameworkError
+from ..modularity import ModuleKey, ModuleRef, ModuleRequirement
+
+
+class DataSeedContributor(ABC):
+    _fixed_service_scope: ClassVar[Scope] = Scope.ACTION
+    __data_seeding_module__ = ModuleRequirement(
+        ModuleRef("python_ddd_framework.seeding.module:DataSeedingModule")
+    )
+
+    @abstractmethod
+    async def seed(self) -> None:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True, slots=True)
+class DataSeedRegistration:
+    service: type[DataSeedContributor]
+    implementation: type[DataSeedContributor]
+    owner: ModuleKey
+
+
+class DataSeedError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        completed: tuple[type[DataSeedContributor], ...],
+        failed: type[DataSeedContributor],
+        original_error: BaseException,
+    ) -> None:
+        self.completed = completed
+        self.failed = failed
+        self.original_error = original_error
+        super().__init__(
+            f"Data seed contributor {failed.__module__}.{failed.__qualname__} failed after "
+            f"{len(completed)} completed contributor(s): {type(original_error).__name__}"
+        )

python_ddd_framework/seeding/module.py

@@ -0,0 +1,73 @@
+"""Seed 发现与最终绑定归所属能力；Domain 不必依赖应用服务组合。"""
+
+from dishka import DEFAULT_COMPONENT, DependencyKey, Scope
+
+from ..errors import InvalidConventionDefinitionError
+from ..invocation.interception import InvocationEntry
+from ..invocation.module import InvocationModule
+from ..lifecycle import ConfigureContext
+from ..modularity import AppModule, ModuleKey
+from ..modularity.discovery import _is_concrete_implementation
+from ..services.composition import (
+    ServiceBindingContext,
+    ServiceComposition,
+    ServiceConvention,
+    ServiceDiscoveryContext,
+)
+from ..services.convention_contracts import ConventionDiscoveryKind, _ServiceDefinition
+from ..unit_of_work.module import UnitOfWorkModule
+from .contracts import DataSeedContributor, DataSeedRegistration
+
+
+class DataSeedingModule(AppModule):
+    dependencies = (UnitOfWorkModule,)
+    registrations: tuple[DataSeedRegistration, ...]
+
+    def __init__(self) -> None:
+        self._discoveries: dict[tuple[ModuleKey, type[DataSeedContributor]], None] = {}
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.services.add_composition(
+            ServiceComposition(discover=self._discover, bind=self._bind)
+        )
+
+    def _discover(self, context: ServiceDiscoveryContext) -> None:
+        for discovery in context.discoveries:
+            candidate = discovery.candidate
+            if not issubclass(candidate, DataSeedContributor) or not _is_concrete_implementation(
+                candidate
+            ):
+                continue
+            self._discoveries[discovery.owner, candidate] = None
+            context.conventions[discovery.owner, candidate] = ServiceConvention(
+                _ServiceDefinition(provides=candidate, scope=Scope.ACTION),
+                ConventionDiscoveryKind.FRAMEWORK_MARKER,
+                "DataSeedContributor declaration",
+            )
+
+    def _bind(self, context: ServiceBindingContext) -> None:
+        registrations = []
+        invocation = context.modules.instance(InvocationModule)
+        for owner, service in self._discoveries:
+            factory = context.arbitration.single_factory(DependencyKey(service, DEFAULT_COMPONENT))
+            if (
+                factory is None
+                or factory.scope is not Scope.ACTION
+                or not isinstance(factory.source, type)
+                or not issubclass(factory.source, DataSeedContributor)
+            ):
+                raise InvalidConventionDefinitionError(
+                    symbol=service.__qualname__,
+                    reason="seed requires a single ACTION-scoped DataSeedContributor class binding",
+                )
+            # 以正式仲裁结果的实现 owner 选择模块闭包，不能继续执行已被替换的扫描类型。
+            implementation_owner = next(
+                draft.contribution.owner
+                for draft in context.arbitration.drafts
+                if draft.factory is factory
+            )
+            registrations.append(
+                DataSeedRegistration(service, factory.source, implementation_owner)
+            )
+            invocation.entries.append(InvocationEntry(service, "seed", owner, 0))
+        self.registrations = tuple(registrations)

python_ddd_framework/seeding/runtime.py

@@ -0,0 +1,63 @@
+"""显式 Migration Host 的顺序 Seed；每项复用现有调用管线和独立 UoW。"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+from dishka import Scope
+
+from ..authorization import CurrentUser
+from ..invocation.entrypoints import caller_context, invocation_lease
+from ..invocation.module import InvocationModule
+from ..modularity import AppModule
+from ..modularity.selection import _dependency_keys
+from ..unit_of_work.options import _DEFAULT_CONNECTION_NAME
+from .contracts import DataSeedContributor, DataSeedError
+from .module import DataSeedingModule
+
+if TYPE_CHECKING:
+    from ..application import Application
+
+
+class DataSeeder:
+    __slots__ = ("_application",)
+
+    def __init__(self, application: Application) -> None:
+        self._application = application
+
+    async def seed_all(
+        self, *, module: type[AppModule] | None = None
+    ) -> tuple[type[DataSeedContributor], ...]:
+        application = self._application
+        owners = _dependency_keys(application.modules, module) if module is not None else None
+        registrations = application.modules.instance(DataSeedingModule).registrations
+        invocation = application.modules.instance(InvocationModule)
+        completed: list[type[DataSeedContributor]] = []
+        for registration in registrations:
+            if owners is not None and registration.owner not in owners:
+                continue
+            try:
+                # 每项从 root 新建 REQUEST/ACTION；前项已提交的事务不被后项失败回滚。
+                async with invocation_lease(application):
+                    async with caller_context(application, CurrentUser.anonymous(), str(uuid4())):
+                        async with application._container_for_integration()(
+                            scope=Scope.REQUEST
+                        ) as request:
+                            await invocation.catalog.invoke(
+                                invocation.invocation_runtime,
+                                request,
+                                registration.service,
+                                "seed",
+                                (),
+                                connection_name=_DEFAULT_CONNECTION_NAME,
+                            )
+            except Exception as original_error:
+                # 原生取消不包装；调用管线完成取消/异常清理后，报告实际已完成项。
+                raise DataSeedError(
+                    completed=tuple(completed),
+                    failed=registration.implementation,
+                    original_error=original_error,
+                ) from original_error
+            completed.append(registration.implementation)
+        return tuple(completed)