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

python_ddd_framework/identity/management.py

@@ -0,0 +1,166 @@
+"""Identity 管理用例；持久化并发与事务由 repository/UoW 负责。"""
+
+from __future__ import annotations
+
+from uuid import UUID, uuid4
+
+from ..application_services import (
+    ApplicationService,
+    PagedResult,
+    PagedResultRequestDto,
+    application_service,
+)
+from ..authorization import (
+    PermissionCatalog,
+    PermissionName,
+    authorize,
+)
+from .contracts import (
+    IDENTITY_ROLES_MANAGE,
+    IDENTITY_USERS_MANAGE,
+    CreateRoleCommand,
+    CreateUserCommand,
+    IdentityConcurrencyCommand,
+    IdentityManagementApplicationService,
+    IdentityRepository,
+    IdentityRole,
+    IdentityUser,
+    RolePermissionsView,
+    RoleView,
+    SetPasswordCommand,
+    SetRolePermissionsCommand,
+    SetUserActiveCommand,
+    SetUserRolesCommand,
+    UpdateRoleCommand,
+    UpdateUserCommand,
+    UserRolesView,
+    UserView,
+    _normalize_name,
+)
+from .errors import (
+    IdentityConflictError,
+    IdentityResourceNotFoundError,
+)
+from .passwords import PasswordHasher
+
+
+@application_service(provides=IdentityManagementApplicationService)
+class DefaultIdentityManagementApplicationService(ApplicationService):
+    def __init__(
+        self,
+        repository: IdentityRepository,
+        passwords: PasswordHasher,
+        permissions: PermissionCatalog,
+    ) -> None:
+        self._repository = repository
+        self._passwords = passwords
+        self._permissions = permissions
+
+    @authorize(IDENTITY_USERS_MANAGE)
+    async def create_user(self, command: CreateUserCommand) -> UserView:
+        normalized = _normalize_name(command.username, role="username")
+        if await self._repository.find_user_by_normalized_username(normalized) is not None:
+            raise IdentityConflictError(resource="user")
+        user = IdentityUser(
+            user_id=uuid4(),
+            username=command.username.strip(),
+            normalized_username=normalized,
+            password_hash=await self._passwords.hash(command.password.get_secret_value()),
+            is_active=True,
+            failed_access_count=0,
+            lockout_end=None,
+            permission_version=0,
+            extra_properties=command.extra_properties,
+        )
+        await self._repository.create_user(user)
+        return UserView(
+            user_id=user.user_id,
+            username=user.username,
+            is_active=user.is_active,
+            role_ids=(),
+            extra_properties=user.extra_properties,
+            concurrency_version=user.concurrency_version,
+        )
+
+    @authorize(IDENTITY_USERS_MANAGE)
+    async def get_users(self, query: PagedResultRequestDto) -> PagedResult[UserView]:
+        return await self._repository.list_users(query)
+
+    @authorize(IDENTITY_USERS_MANAGE)
+    async def get_user(self, user_id: UUID) -> UserView:
+        return await self._repository.get_user_view(user_id)
+
+    @authorize(IDENTITY_USERS_MANAGE)
+    async def update_user(self, user_id: UUID, command: UpdateUserCommand) -> UserView:
+        return await self._repository.update_user(user_id, command)
+
+    @authorize(IDENTITY_USERS_MANAGE)
+    async def set_user_active(self, user_id: UUID, command: SetUserActiveCommand) -> UserView:
+        return await self._repository.set_user_active(user_id, command)
+
+    @authorize(IDENTITY_USERS_MANAGE)
+    async def delete_user(self, user_id: UUID, command: IdentityConcurrencyCommand) -> None:
+        await self._repository.delete_user(user_id, command.concurrency_version)
+
+    @authorize(IDENTITY_USERS_MANAGE)
+    async def set_password(self, user_id: UUID, command: SetPasswordCommand) -> None:
+        password_hash = await self._passwords.hash(command.new_password.get_secret_value())
+        await self._repository.set_password(user_id, password_hash, command.concurrency_version)
+
+    @authorize(IDENTITY_ROLES_MANAGE)
+    async def create_role(self, command: CreateRoleCommand) -> RoleView:
+        normalized = _normalize_name(command.name, role="role name")
+        if await self._repository.find_role_by_normalized_name(normalized) is not None:
+            raise IdentityConflictError(resource="role")
+        role = IdentityRole(uuid4(), command.name.strip(), normalized, 0)
+        await self._repository.create_role(role)
+        return RoleView(role.role_id, role.name, (), role.concurrency_version)
+
+    @authorize(IDENTITY_ROLES_MANAGE)
+    async def get_roles(self, query: PagedResultRequestDto) -> PagedResult[RoleView]:
+        return await self._repository.list_roles(query)
+
+    @authorize(IDENTITY_ROLES_MANAGE)
+    async def get_role(self, role_id: UUID) -> RoleView:
+        return await self._repository.get_role(role_id)
+
+    @authorize(IDENTITY_ROLES_MANAGE)
+    async def update_role(self, role_id: UUID, command: UpdateRoleCommand) -> RoleView:
+        return await self._repository.update_role(role_id, command)
+
+    @authorize(IDENTITY_ROLES_MANAGE)
+    async def delete_role(self, role_id: UUID, command: IdentityConcurrencyCommand) -> None:
+        await self._repository.delete_role(role_id, command.concurrency_version)
+
+    @authorize(IDENTITY_USERS_MANAGE, IDENTITY_ROLES_MANAGE)
+    async def get_user_roles(self, user_id: UUID) -> UserRolesView:
+        user = await self._repository.get_user_view(user_id)
+        return UserRolesView(role_ids=user.role_ids, concurrency_version=user.concurrency_version)
+
+    @authorize(IDENTITY_ROLES_MANAGE)
+    async def get_role_permissions(self, role_id: UUID) -> RolePermissionsView:
+        role = await self._repository.get_role(role_id)
+        return RolePermissionsView(
+            permissions=role.permissions, concurrency_version=role.concurrency_version
+        )
+
+    @authorize(IDENTITY_USERS_MANAGE, IDENTITY_ROLES_MANAGE)
+    async def set_user_roles(self, user_id: UUID, command: SetUserRolesCommand) -> UserRolesView:
+        role_ids = tuple(dict.fromkeys(command.role_ids))
+        return await self._repository.set_user_roles(user_id, role_ids, command.concurrency_version)
+
+    @authorize(IDENTITY_ROLES_MANAGE)
+    async def set_role_permissions(
+        self, role_id: UUID, command: SetRolePermissionsCommand
+    ) -> RolePermissionsView:
+        names = tuple(PermissionName(item) for item in command.permissions)
+        if len(set(names)) != len(names):
+            raise IdentityConflictError(resource="role permission")
+        unknown = tuple(item for item in names if item not in self._permissions)
+        if unknown:
+            raise IdentityResourceNotFoundError(resource="permission")
+        return await self._repository.set_role_permissions(
+            role_id,
+            tuple(item.value for item in names),
+            command.concurrency_version,
+        )

python_ddd_framework/identity/module.py

@@ -5,14 +5,17 @@ from __future__ import annotations
 from dishka import Provider, Scope
 
 from ..authorization import AccessTokenAuthenticator, PermissionChecker
+from ..caching.module import CachingModule
+from ..extensions.contracts import ExtensionPoints
 from ..lifecycle import ConfigureContext
-from ..modularity import AppModule
+from ..modularity import AppModule, ModuleRef
+from ..seeding.module import DataSeedingModule
 from .contracts import (
+    IDENTITY_USER_EXTENSION,
     IdentityOptions,
 )
 from .passwords import PasswordHasher
 from .services import (
-    IDENTITY_PERMISSION_CACHE,
     IdentityAuthenticator,
     IdentityPermissionChecker,
 )
@@ -20,13 +23,18 @@ from .tokens import JwtTokenService
 
 
 class IdentityModule(AppModule):
+    extension_points = ExtensionPoints((IDENTITY_USER_EXTENSION,))
+    dependencies = (
+        DataSeedingModule,
+        CachingModule,
+        ModuleRef("python_ddd_framework.application_services.module:ApplicationServicesModule"),
+    )
     scan_packages = (
         "python_ddd_framework.identity.application",
+        "python_ddd_framework.identity.management",
         "python_ddd_framework.identity.permissions",
     )
 
-    cache_definitions = (IDENTITY_PERMISSION_CACHE,)
-
     def configure(self, context: ConfigureContext) -> None:
         context.configure(
             IdentityOptions,

python_ddd_framework/identity/services.py

@@ -9,8 +9,20 @@ from dishka import AsyncContainer
 from dishka.exceptions import NoFactoryError
 from pydantic import BaseModel, ConfigDict
 
-from ..authorization import CurrentUser, PermissionCatalog, PermissionChecker, PermissionName
-from ..caching import CacheDefinition, DistributedCache, DistributedCacheError
+from ..authorization import (
+    AuthorizationOptions,
+    CurrentUser,
+    PermissionCatalog,
+    PermissionChecker,
+    PermissionName,
+)
+from ..caching import (
+    DistributedCache,
+    DistributedCacheEntryOptions,
+    DistributedCacheError,
+    cache_name,
+)
+from ..options import Options
 from .contracts import IdentityAccessStore
 from .errors import InvalidCredentialsError
 from .tokens import JwtTokenService
@@ -18,19 +30,13 @@ from .tokens import JwtTokenService
 _LOGGER = logging.getLogger(__name__)
 
 
+@cache_name("identity.permissions")
 class PermissionCacheEntry(BaseModel):
     model_config = ConfigDict(frozen=True)
 
     permissions: tuple[str, ...]
 
 
-IDENTITY_PERMISSION_CACHE = CacheDefinition(
-    "identity.permissions",
-    PermissionCacheEntry,
-    ttl=timedelta(minutes=5),
-)
-
-
 class IdentityAuthenticator:
     __slots__ = ("_access", "_tokens")
 
@@ -51,31 +57,35 @@ class IdentityAuthenticator:
 
 
 class IdentityPermissionChecker(PermissionChecker):
-    __slots__ = ("_access", "_catalog", "_container")
+    __slots__ = ("_access", "_catalog", "_container", "_options")
 
     def __init__(
         self,
         access: IdentityAccessStore,
         catalog: PermissionCatalog,
         container: AsyncContainer,
+        options: Options[AuthorizationOptions],
     ) -> None:
         self._access = access
         self._catalog = catalog
         self._container = container
+        self._options = options.value
 
     async def is_granted(self, user: CurrentUser, permission: PermissionName) -> bool:
+        if self._options.always_allow:
+            return True
         if not user.is_authenticated or permission not in self._catalog:
             return False
         cache = await self._optional_cache()
         cache_key = _permission_cache_key(user, self._catalog.fingerprint)
         if cache is not None:
             try:
-                cached = await cache.get(IDENTITY_PERMISSION_CACHE, cache_key)
+                cached = await cache.get(cache_key, hide_errors=False)
             except DistributedCacheError:
                 cached = None
                 _LOGGER.warning(
                     "permission cache read failed; falling back to authoritative database",
-                    extra={"cache": IDENTITY_PERMISSION_CACHE.name},
+                    extra={"cache": "identity.permissions"},
                 )
             if cached is not None:
                 return permission.value in cached.permissions
@@ -84,20 +94,23 @@ class IdentityPermissionChecker(PermissionChecker):
         if cache is not None:
             try:
                 await cache.set(
-                    IDENTITY_PERMISSION_CACHE,
                     cache_key,
                     PermissionCacheEntry(permissions=tuple(sorted(permissions))),
+                    options=DistributedCacheEntryOptions(
+                        absolute_expiration_relative_to_now=timedelta(minutes=5)
+                    ),
+                    hide_errors=False,
                 )
             except DistributedCacheError:
                 _LOGGER.warning(
                     "permission cache write failed; database result remains authoritative",
-                    extra={"cache": IDENTITY_PERMISSION_CACHE.name},
+                    extra={"cache": "identity.permissions"},
                 )
         return permission.value in permissions
 
-    async def _optional_cache(self) -> DistributedCache | None:
+    async def _optional_cache(self) -> DistributedCache[PermissionCacheEntry] | None:
         try:
-            return await self._container.get(DistributedCache)
+            return await self._container.get(DistributedCache[PermissionCacheEntry])
         except NoFactoryError:
             return None
 

python_ddd_framework/identity/sqlalchemy/migrations/0003_extra_properties.py

@@ -0,0 +1,26 @@
+"""Identity 拥有基础扩展容器；消费者独立列由自身 revision 管理。"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision = "identity_0003"
+down_revision = "identity_0002"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "identity_users",
+        sa.Column(
+            "extra_properties",
+            postgresql.JSONB(),
+            nullable=False,
+            server_default=sa.text("'{}'::jsonb"),
+        ),
+    )
+
+
+def downgrade() -> None:
+    raise RuntimeError("removing extension data requires an explicit data migration")

python_ddd_framework/identity/sqlalchemy/migrations/0004_concurrency_version.py

@@ -0,0 +1,29 @@
+"""Identity owns edit versions independently of permission cache versions."""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "identity_0004"
+down_revision = "identity_0003"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "identity_users",
+        sa.Column(
+            "concurrency_version", sa.BigInteger(), nullable=False, server_default=sa.text("0")
+        ),
+    )
+    op.add_column(
+        "identity_roles",
+        sa.Column(
+            "concurrency_version", sa.BigInteger(), nullable=False, server_default=sa.text("0")
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("identity_roles", "concurrency_version")
+    op.drop_column("identity_users", "concurrency_version")

python_ddd_framework/identity/sqlalchemy/models.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 from datetime import datetime
+from typing import TYPE_CHECKING
 from uuid import UUID
 
-from sqlalchemy import BigInteger, Boolean, DateTime, ForeignKey, Integer, String, Uuid
+from sqlalchemy import BigInteger, Boolean, DateTime, ForeignKey, Integer, String, Uuid, text
+from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
 from ...sqlalchemy import AuditedEntityMixin
@@ -15,7 +17,7 @@ class IdentityBase(DeclarativeBase):
     pass
 
 
-class UserRow(AuditedEntityMixin, IdentityBase):
+class UserRowValues(AuditedEntityMixin):
     __tablename__ = "identity_users"
 
     user_id: Mapped[UUID] = mapped_column(Uuid, primary_key=True)
@@ -28,6 +30,20 @@ class UserRow(AuditedEntityMixin, IdentityBase):
     failed_access_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
     lockout_end: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
     permission_version: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    concurrency_version: Mapped[int] = mapped_column(
+        BigInteger, nullable=False, default=0, server_default=text("0")
+    )
+    extra_properties: Mapped[dict[str, object]] = mapped_column(
+        JSONB, nullable=False, default=dict, server_default=text("'{}'::jsonb")
+    )
+
+    if TYPE_CHECKING:
+        # 实例由 SQLAlchemy 原生 mapper 的关键字构造器创建。
+        def __init__(self, **values: object) -> None: ...
+
+
+class UserRow(UserRowValues, IdentityBase):
+    """基础 Schema 声明；运行时使用本 Application 从 mixin 生成的 mapper。"""
 
 
 class RoleRow(AuditedEntityMixin, IdentityBase):
@@ -39,6 +55,9 @@ class RoleRow(AuditedEntityMixin, IdentityBase):
         String(120), nullable=False, unique=True, index=True
     )
     permission_version: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    concurrency_version: Mapped[int] = mapped_column(
+        BigInteger, nullable=False, default=0, server_default=text("0")
+    )
 
 
 class UserRoleRow(AuditedEntityMixin, IdentityBase):

python_ddd_framework/identity/sqlalchemy/module.py

@@ -7,22 +7,24 @@ from dishka import Provider, Scope
 from ...lifecycle import ConfigureContext
 from ...modularity import AppModule
 from ...sqlalchemy import (
+    SqlAlchemyExtensionMapping,
     SqlAlchemyModelRegistration,
     SqlAlchemyPersistenceModule,
     contributes_sqlalchemy_models,
 )
 from ..contracts import (
+    IDENTITY_USER_EXTENSION,
     IdentityAccessStore,
     IdentityLoginStore,
     IdentityRepository,
     RefreshSessionStore,
 )
 from ..module import IdentityModule
-from .models import IdentityBase
+from .models import IdentityBase, UserRow, UserRowValues
+from .repository import SqlAlchemyIdentityRepository
 from .stores import (
     SqlAlchemyIdentityAccessStore,
     SqlAlchemyIdentityLoginStore,
-    SqlAlchemyIdentityRepository,
     SqlAlchemyRefreshSessionStore,
 )
 
@@ -32,6 +34,13 @@ from .stores import (
         metadata=IdentityBase.metadata,
         migrations_package="python_ddd_framework.identity.sqlalchemy.migrations",
         branch_label="identity",
+        extension_mappings=(
+            SqlAlchemyExtensionMapping(
+                IDENTITY_USER_EXTENSION,
+                IdentityBase.metadata.tables[UserRow.__tablename__],
+                UserRowValues,
+            ),
+        ),
     )
 )
 class SqlAlchemyIdentityModule(AppModule):