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

python_ddd_framework/identity/sqlalchemy/repository.py

@@ -0,0 +1,458 @@
+"""管理仓储加入调用方 UoW；拥有并发写入与实体/有效 ORM 映射。"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import UUID
+
+from sqlalchemy import Select, func, select
+from sqlalchemy.exc import IntegrityError
+
+from ...application_services import PagedResult, PagedResultRequestDto
+from ...domain import OptimisticConcurrencyError
+from ...extensions import ExtensionProperties
+from ...sqlalchemy import SqlAlchemyModelCatalog, SqlAlchemySessionProvider
+from ..contracts import (
+    IDENTITY_USER_EXTENSION,
+    IdentityRole,
+    IdentityUser,
+    RolePermissionsView,
+    RoleView,
+    SetUserActiveCommand,
+    UpdateRoleCommand,
+    UpdateUserCommand,
+    UserRolesView,
+    UserView,
+    _check_version,
+)
+from ..errors import IdentityConflictError, IdentityResourceNotFoundError
+from .models import (
+    RolePermissionRow,
+    RoleRow,
+    UserRoleRow,
+    UserRowValues,
+)
+from .session_security import _lock_identity_user, _revoke_user_sessions
+
+
+class SqlAlchemyIdentityRepository:
+    __slots__ = ("_provider", "_users")
+
+    def __init__(self, provider: SqlAlchemySessionProvider, models: SqlAlchemyModelCatalog) -> None:
+        self._provider = provider
+        self._users = models.extension_model(IDENTITY_USER_EXTENSION, UserRowValues)
+
+    async def find_user_by_normalized_username(
+        self,
+        normalized_username: str,
+    ) -> IdentityUser | None:
+        async with self._provider.operation("find_user_by_normalized_username"):
+            session = await self._provider.get_session()
+            statement = select(self._users.model).where(
+                self._users.model.normalized_username == normalized_username
+            )
+            row = await session.scalar(statement)
+            return None if row is None else _user_value(row, self._users.read(row))
+
+    async def create_user(self, user: IdentityUser) -> None:
+        async with self._provider.operation("create_user", write=True):
+            session = await self._provider.get_session()
+            row = self._users.model(
+                user_id=user.user_id,
+                username=user.username,
+                normalized_username=user.normalized_username,
+                password_hash=user.password_hash,
+                is_active=user.is_active,
+                failed_access_count=user.failed_access_count,
+                lockout_end=user.lockout_end,
+                permission_version=user.permission_version,
+                concurrency_version=user.concurrency_version,
+            )
+            self._users.write(row, user.extra_properties)
+            session.add(row)
+            await self._flush_unique("user")
+
+    async def get_user(self, user_id: UUID) -> IdentityUser:
+        async with self._provider.operation("get_user"):
+            row = await self._require_user(user_id, for_update=False)
+            return _user_value(row, self._users.read(row))
+
+    async def get_user_view(self, user_id: UUID) -> UserView:
+        async with self._provider.operation("get_user_view"):
+            items = await self._read_user_views(
+                select(self._users.model.user_id).where(self._users.model.user_id == user_id)
+            )
+            if not items:
+                raise IdentityResourceNotFoundError(resource="user")
+            return items[0]
+
+    async def _user_view(self, row: UserRowValues) -> UserView:
+        session = await self._provider.get_session()
+        roles = tuple(
+            (
+                await session.scalars(
+                    select(UserRoleRow.role_id)
+                    .where(UserRoleRow.user_id == row.user_id)
+                    .order_by(UserRoleRow.role_id)
+                )
+            ).all()
+        )
+        return UserView(
+            user_id=row.user_id,
+            username=row.username,
+            is_active=row.is_active,
+            role_ids=roles,
+            concurrency_version=row.concurrency_version,
+            extra_properties=self._users.read(row),
+        )
+
+    async def list_users(self, query: PagedResultRequestDto) -> PagedResult[UserView]:
+        async with self._provider.operation("list_users"):
+            session = await self._provider.get_session()
+            total = await session.scalar(select(func.count()).select_from(self._users.model))
+            identifiers = (
+                select(self._users.model.user_id)
+                .order_by(self._users.model.normalized_username, self._users.model.user_id)
+                .offset(query.skip_count)
+                .limit(query.max_result_count)
+            )
+            items = await self._read_user_views(identifiers)
+            return PagedResult[UserView](items=items, total_count=total or 0)
+
+    async def _read_user_views(self, identifiers: Select[tuple[UUID]]) -> list[UserView]:
+        session = await self._provider.get_session()
+        role_ids = (
+            select(func.array_agg(UserRoleRow.role_id))
+            .where(UserRoleRow.user_id == self._users.model.user_id)
+            .correlate(self._users.model)
+            .scalar_subquery()
+        )
+        # 一条 SQL 快照同时读取编辑版本和关系，避免读锁升级与 user gate 形成反向等待。
+        rows = (
+            await session.execute(
+                select(self._users.model, role_ids)
+                .where(self._users.model.user_id.in_(identifiers))
+                .order_by(self._users.model.normalized_username, self._users.model.user_id)
+                .execution_options(populate_existing=True)
+            )
+        ).all()
+        return [
+            UserView(
+                user_id=row.user_id,
+                username=row.username,
+                is_active=row.is_active,
+                role_ids=tuple(sorted(roles or ())),
+                concurrency_version=row.concurrency_version,
+                extra_properties=self._users.read(row),
+            )
+            for row, roles in rows
+        ]
+
+    async def update_user(self, user_id: UUID, command: UpdateUserCommand) -> UserView:
+        async with self._provider.operation("update_user", write=True):
+            row = await self._require_user(user_id, for_update=True)
+            user = _user_value(row, self._users.read(row)).renamed(
+                command.username, command.concurrency_version
+            )
+            row.normalized_username = user.normalized_username
+            row.username = user.username
+            self._users.write(row, command.extra_properties)
+            row.concurrency_version = user.concurrency_version
+            await self._flush_unique("user")
+            return await self._user_view(row)
+
+    async def set_user_active(self, user_id: UUID, command: SetUserActiveCommand) -> UserView:
+        async with self._provider.operation("set_user_active", write=True):
+            session = await self._provider.get_session()
+            row = await self._require_user(user_id, for_update=True)
+            user = _user_value(row, self._users.read(row)).with_active(
+                command.is_active, command.concurrency_version
+            )
+            row.is_active = user.is_active
+            row.concurrency_version = user.concurrency_version
+            if not command.is_active:
+                await _revoke_user_sessions(session, user_id, now=datetime.now(UTC))
+            await session.flush()
+            return await self._user_view(row)
+
+    async def delete_user(self, user_id: UUID, concurrency_version: int) -> None:
+        async with self._provider.operation("delete_user", write=True):
+            session = await self._provider.get_session()
+            row = await self._require_user(user_id, for_update=True)
+            _check_version(row.concurrency_version, concurrency_version)
+            await _revoke_user_sessions(session, user_id, now=datetime.now(UTC))
+            # FK CASCADE 在同一 UoW 内删除该用户的关系和所有 family 历史。
+            await session.delete(row)
+            await session.flush()
+
+    async def set_password(
+        self,
+        user_id: UUID,
+        password_hash: str,
+        concurrency_version: int,
+        *,
+        expected_password_hash: str | None = None,
+    ) -> None:
+        async with self._provider.operation("set_password", write=True):
+            session = await self._provider.get_session()
+            row = await self._require_user(user_id, for_update=True)
+            _check_version(row.concurrency_version, concurrency_version)
+            if expected_password_hash is not None and row.password_hash != expected_password_hash:
+                raise OptimisticConcurrencyError
+            row.password_hash = password_hash
+            row.failed_access_count = 0
+            row.lockout_end = None
+            row.concurrency_version += 1
+            await _revoke_user_sessions(session, user_id, now=datetime.now(UTC))
+            await session.flush()
+
+    async def create_role(self, role: IdentityRole) -> None:
+        async with self._provider.operation("create_role", write=True):
+            session = await self._provider.get_session()
+            session.add(
+                RoleRow(
+                    role_id=role.role_id,
+                    name=role.name,
+                    normalized_name=role.normalized_name,
+                    permission_version=role.permission_version,
+                    concurrency_version=role.concurrency_version,
+                )
+            )
+            await self._flush_unique("role")
+
+    async def find_role_by_normalized_name(self, normalized_name: str) -> IdentityRole | None:
+        async with self._provider.operation("find_role_by_normalized_name"):
+            session = await self._provider.get_session()
+            row = await session.scalar(
+                select(RoleRow).where(RoleRow.normalized_name == normalized_name)
+            )
+            return None if row is None else _role_value(row)
+
+    async def get_role(self, role_id: UUID) -> RoleView:
+        async with self._provider.operation("get_role"):
+            items = await self._read_role_views(
+                select(RoleRow.role_id).where(RoleRow.role_id == role_id)
+            )
+            if not items:
+                raise IdentityResourceNotFoundError(resource="role")
+            return items[0]
+
+    async def _role_view(self, row: RoleRow) -> RoleView:
+        session = await self._provider.get_session()
+        permissions = tuple(
+            (
+                await session.scalars(
+                    select(RolePermissionRow.permission_name)
+                    .where(RolePermissionRow.role_id == row.role_id)
+                    .order_by(RolePermissionRow.permission_name)
+                )
+            ).all()
+        )
+        return RoleView(row.role_id, row.name, permissions, row.concurrency_version)
+
+    async def list_roles(self, query: PagedResultRequestDto) -> PagedResult[RoleView]:
+        async with self._provider.operation("list_roles"):
+            session = await self._provider.get_session()
+            total = await session.scalar(select(func.count()).select_from(RoleRow))
+            identifiers = (
+                select(RoleRow.role_id)
+                .order_by(RoleRow.normalized_name, RoleRow.role_id)
+                .offset(query.skip_count)
+                .limit(query.max_result_count)
+            )
+            items = await self._read_role_views(identifiers)
+            return PagedResult[RoleView](items=items, total_count=total or 0)
+
+    async def _read_role_views(self, identifiers: Select[tuple[UUID]]) -> list[RoleView]:
+        session = await self._provider.get_session()
+        permissions = (
+            select(func.array_agg(RolePermissionRow.permission_name))
+            .where(RolePermissionRow.role_id == RoleRow.role_id)
+            .correlate(RoleRow)
+            .scalar_subquery()
+        )
+        rows = (
+            await session.execute(
+                select(RoleRow, permissions)
+                .where(RoleRow.role_id.in_(identifiers))
+                .order_by(RoleRow.normalized_name, RoleRow.role_id)
+                .execution_options(populate_existing=True)
+            )
+        ).all()
+        return [
+            RoleView(row.role_id, row.name, tuple(sorted(names or ())), row.concurrency_version)
+            for row, names in rows
+        ]
+
+    async def update_role(self, role_id: UUID, command: UpdateRoleCommand) -> RoleView:
+        async with self._provider.operation("update_role", write=True):
+            row = await self._require_role(role_id, for_update=True)
+            role = _role_value(row).renamed(command.name, command.concurrency_version)
+            row.normalized_name = role.normalized_name
+            row.name = role.name
+            row.concurrency_version = role.concurrency_version
+            await self._flush_unique("role")
+            return await self._role_view(row)
+
+    async def delete_role(self, role_id: UUID, concurrency_version: int) -> None:
+        async with self._provider.operation("delete_role", write=True):
+            session = await self._provider.get_session()
+            role = await self._require_role(role_id, for_update=True)
+            _check_version(role.concurrency_version, concurrency_version)
+            user_ids = tuple(
+                (
+                    await session.scalars(
+                        select(UserRoleRow.user_id)
+                        .where(UserRoleRow.role_id == role_id)
+                        .order_by(UserRoleRow.user_id)
+                    )
+                ).all()
+            )
+            # 和分配保持 role -> user 顺序；级联删除也是用户关系的修改，必须推进其版本。
+            for user_id in user_ids:
+                await _lock_identity_user(session, user_id)
+                user = await session.scalar(
+                    select(self._users.model)
+                    .where(self._users.model.user_id == user_id)
+                    .with_for_update()
+                    .execution_options(populate_existing=True)
+                )
+                if user is not None:
+                    user.concurrency_version += 1
+                    user.permission_version += 1
+            await session.delete(role)
+            await session.flush()
+
+    async def set_user_roles(
+        self, user_id: UUID, role_ids: tuple[UUID, ...], concurrency_version: int
+    ) -> UserRolesView:
+        async with self._provider.operation("set_user_roles", write=True):
+            session = await self._provider.get_session()
+            requested = frozenset(role_ids)
+            roles = tuple(
+                (
+                    await session.scalars(
+                        select(RoleRow)
+                        .where(RoleRow.role_id.in_(requested))
+                        .order_by(RoleRow.role_id)
+                        .with_for_update()
+                    )
+                ).all()
+            )
+            if len(roles) != len(requested):
+                raise IdentityResourceNotFoundError(resource="role")
+            user = await self._require_user(user_id, for_update=True)
+            _check_version(user.concurrency_version, concurrency_version)
+            existing = tuple(
+                (
+                    await session.scalars(
+                        select(UserRoleRow).where(UserRoleRow.user_id == user_id).with_for_update()
+                    )
+                ).all()
+            )
+            current = frozenset(item.role_id for item in existing)
+            if current == requested:
+                return UserRolesView(
+                    role_ids=tuple(sorted(current)), concurrency_version=user.concurrency_version
+                )
+            for item in existing:
+                if item.role_id not in requested:
+                    await session.delete(item)
+            for role_id in sorted(requested - current):
+                session.add(UserRoleRow(user_id=user_id, role_id=role_id))
+            user.permission_version += 1
+            user.concurrency_version += 1
+            await session.flush()
+            return UserRolesView(
+                role_ids=tuple(sorted(requested)), concurrency_version=user.concurrency_version
+            )
+
+    async def set_role_permissions(
+        self, role_id: UUID, permissions: tuple[str, ...], concurrency_version: int
+    ) -> RolePermissionsView:
+        async with self._provider.operation("set_role_permissions", write=True):
+            session = await self._provider.get_session()
+            role = await self._require_role(role_id, for_update=True)
+            _check_version(role.concurrency_version, concurrency_version)
+            requested = frozenset(permissions)
+            existing = tuple(
+                (
+                    await session.scalars(
+                        select(RolePermissionRow)
+                        .where(RolePermissionRow.role_id == role_id)
+                        .with_for_update()
+                    )
+                ).all()
+            )
+            current = frozenset(item.permission_name for item in existing)
+            if current == requested:
+                return RolePermissionsView(
+                    permissions=tuple(sorted(current)), concurrency_version=role.concurrency_version
+                )
+            for item in existing:
+                if item.permission_name not in requested:
+                    await session.delete(item)
+            for permission in sorted(requested - current):
+                session.add(RolePermissionRow(role_id=role_id, permission_name=permission))
+            role.permission_version += 1
+            role.concurrency_version += 1
+            await session.flush()
+            return RolePermissionsView(
+                permissions=tuple(sorted(requested)), concurrency_version=role.concurrency_version
+            )
+
+    async def _require_user(self, user_id: UUID, *, for_update: bool) -> UserRowValues:
+        session = await self._provider.get_session()
+        statement = select(self._users.model).where(self._users.model.user_id == user_id)
+        if for_update:
+            await _lock_identity_user(session, user_id)
+            statement = statement.with_for_update()
+        # 写锁后强制刷新 identity map，不拿事务内缓存的旧版本执行并发比较。
+        statement = statement.execution_options(populate_existing=True)
+        row = await session.scalar(statement)
+        if row is None:
+            raise IdentityResourceNotFoundError(resource="user")
+        return row
+
+    async def _require_role(self, role_id: UUID, *, for_update: bool) -> RoleRow:
+        session = await self._provider.get_session()
+        statement = select(RoleRow).where(RoleRow.role_id == role_id)
+        if for_update:
+            statement = statement.with_for_update()
+        statement = statement.execution_options(populate_existing=True)
+        row = await session.scalar(statement)
+        if row is None:
+            raise IdentityResourceNotFoundError(resource="role")
+        return row
+
+    async def _flush_unique(self, resource: str) -> None:
+        session = await self._provider.get_session()
+        try:
+            await session.flush()
+        except IntegrityError:
+            raise IdentityConflictError(resource=resource) from None
+
+
+def _user_value(row: UserRowValues, extra_properties: ExtensionProperties) -> IdentityUser:
+    return IdentityUser(
+        user_id=row.user_id,
+        username=row.username,
+        normalized_username=row.normalized_username,
+        password_hash=row.password_hash,
+        is_active=row.is_active,
+        failed_access_count=row.failed_access_count,
+        lockout_end=row.lockout_end,
+        permission_version=row.permission_version,
+        concurrency_version=row.concurrency_version,
+        extra_properties=extra_properties,
+    )
+
+
+def _role_value(row: RoleRow) -> IdentityRole:
+    return IdentityRole(
+        role_id=row.role_id,
+        name=row.name,
+        normalized_name=row.normalized_name,
+        permission_version=row.permission_version,
+        concurrency_version=row.concurrency_version,
+    )

python_ddd_framework/identity/sqlalchemy/session_security.py

@@ -0,0 +1,88 @@
+"""凭据会话的统一锁序、撤销与期限判断；调用方拥有事务。"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from hashlib import blake2b
+from uuid import UUID
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..contracts import (
+    IdentityOptions,
+)
+from .models import (
+    RefreshSessionRow,
+)
+
+_REFRESH_FAMILY_LOCK_PERSON = b"pyplat.rfam.v1"
+
+
+async def _revoke_family(
+    session: AsyncSession,
+    family_id: UUID,
+    *,
+    now: datetime,
+) -> None:
+    rows = tuple(
+        (
+            await session.scalars(
+                select(RefreshSessionRow)
+                .where(RefreshSessionRow.family_id == family_id)
+                .with_for_update()
+            )
+        ).all()
+    )
+    for row in rows:
+        if row.revoked_at is None:
+            row.revoked_at = now
+
+
+async def _lock_refresh_family(session: AsyncSession, family_id: UUID) -> None:
+    # family 没有可锁的稳定 parent row；transaction advisory lock 在同一短事务内提供
+    # family -> token/family rows 的统一顺序，并随 commit/rollback 自动释放。
+    await session.scalar(select(func.pg_advisory_xact_lock(_refresh_family_lock_key(family_id))))
+
+
+async def _lock_identity_user(session: AsyncSession, user_id: UUID) -> None:
+    # 登录创建新 family 与管理撤销共同持有稳定 user gate，阻止枚举 family 后漏掉新会话。
+    # 所有凭据/family 写入先取得此 gate；family 内仍是 advisory -> refresh rows。
+    digest = blake2b(user_id.bytes, digest_size=8, person=b"pyplat.user.v1").digest()
+    key = int.from_bytes(digest, byteorder="big", signed=True)
+    await session.scalar(select(func.pg_advisory_xact_lock(key)))
+
+
+async def _revoke_user_sessions(session: AsyncSession, user_id: UUID, *, now: datetime) -> None:
+    # 调用方已持有 user gate；family 集合不会在此事务期间增长。
+    families = tuple(
+        (
+            await session.scalars(
+                select(RefreshSessionRow.family_id)
+                .where(RefreshSessionRow.user_id == user_id)
+                .distinct()
+                .order_by(RefreshSessionRow.family_id)
+            )
+        ).all()
+    )
+    for family_id in families:
+        await _lock_refresh_family(session, family_id)
+        await _revoke_family(session, family_id, now=now)
+
+
+def _refresh_family_lock_key(family_id: UUID) -> int:
+    digest = blake2b(
+        family_id.bytes,
+        digest_size=8,
+        person=_REFRESH_FAMILY_LOCK_PERSON,
+    ).digest()
+    return int.from_bytes(digest, byteorder="big", signed=True)
+
+
+def _session_is_active(row: RefreshSessionRow, now: datetime, options: IdentityOptions) -> bool:
+    return (
+        row.revoked_at is None
+        and row.replaced_by_session_id is None
+        and now - row.last_used_at < options.refresh_inactivity_lifetime
+        and now - row.family_created_at < options.refresh_absolute_lifetime
+    )