fastapi-forge-cli 0.1.0__py3-none-any.whl

fastapi_forge/templates/with_rbac/app/api/v1/roles/router.py

@@ -0,0 +1,169 @@
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.v1.schema import DeleteNoteRequest
+from app.api.v1.roles.schema import AssignRoleRequest, RoleCreate, RoleUpdate
+from app.api.v1.roles.service import RoleService
+from app.core.dependencies import (
+    get_async_db,
+    get_current_user_payload,
+    require_any_permission,
+)
+from app.helper.pagination_helper import PaginationParams
+from app.core.responses import paginated_response, success_response
+
+router = APIRouter()
+
+_role_read = Depends(require_any_permission("admin:write", "roles:read"))
+_role_create = Depends(require_any_permission("admin:write", "roles:create"))
+_role_update = Depends(require_any_permission("admin:write", "roles:update"))
+_role_soft_delete = Depends(require_any_permission("admin:write", "roles:soft_delete"))
+_role_hard_delete = Depends(require_any_permission("admin:write", "roles:hard_delete"))
+
+
+@router.get("", dependencies=[_role_read])
+async def list_roles(
+    pagination: PaginationParams = Depends(),
+    db: AsyncSession = Depends(get_async_db),
+    active_only: bool = Query(False, alias="activeOnly"),
+):
+    svc = RoleService(db)
+    data, total = await svc.list_roles(
+        pagination.page,
+        pagination.page_size,
+        pagination.pagination,
+        pagination.search,
+        pagination.sort_by,
+        pagination.sort_order,
+        active_only,
+    )
+    items = [item.model_dump() for item in data]
+    if not pagination.pagination:
+        return success_response(data=items)
+    return paginated_response(
+        items,
+        total,
+        pagination.page,
+        pagination.page_size,
+    )
+
+
+@router.get("/deleted", dependencies=[_role_read], summary="List soft-deleted roles")
+async def list_deleted_roles(
+    pagination: PaginationParams = Depends(),
+    db: AsyncSession = Depends(get_async_db),
+):
+    svc = RoleService(db)
+    data, total = await svc.list_deleted_roles(
+        pagination.page,
+        pagination.page_size,
+        pagination.pagination,
+        pagination.search,
+        pagination.sort_by,
+        pagination.sort_order,
+    )
+    items = [item.model_dump() for item in data]
+    if not pagination.pagination:
+        return success_response(data=items)
+    return paginated_response(items, total, pagination.page, pagination.page_size)
+
+
+@router.post("", dependencies=[_role_create])
+async def create_role(
+    body: RoleCreate,
+    db: AsyncSession = Depends(get_async_db),
+    payload: dict = Depends(get_current_user_payload),
+):
+    svc = RoleService(db)
+    role = await svc.create_role(body, payload.get("role"))
+    return success_response(
+        data=role.model_dump(exclude_none=True),
+        message="Role created",
+    )
+
+
+@router.post("/assign", dependencies=[_role_update], summary="Assign a role to a user")
+async def assign_role(
+    body: AssignRoleRequest,
+    db: AsyncSession = Depends(get_async_db),
+    payload: dict = Depends(get_current_user_payload),
+):
+    svc = RoleService(db)
+    await svc.assign_role(body.user_id, body.role_id, payload.get("role"))
+    return success_response(message="Role assigned to user")
+
+
+@router.get("/below", dependencies=[_role_read], summary="List roles below current role")
+async def list_roles_below_current(
+    db: AsyncSession = Depends(get_async_db),
+    payload: dict = Depends(get_current_user_payload),
+):
+    svc = RoleService(db)
+    roles = await svc.list_roles_below_current(payload.get("role"))
+    return success_response(data=[role.model_dump(exclude_none=True) for role in roles])
+
+
+@router.get("/tree", dependencies=[_role_read], summary="Get role tree below current role")
+async def get_role_tree(
+    db: AsyncSession = Depends(get_async_db),
+    payload: dict = Depends(get_current_user_payload),
+):
+    svc = RoleService(db)
+    tree = await svc.role_tree_below_current(payload.get("role"))
+    return success_response(data=[node.model_dump(exclude_none=True) for node in tree])
+
+
+@router.get("/{role_id}", dependencies=[_role_read], summary="Get a role")
+async def get_role(role_id: UUID, db: AsyncSession = Depends(get_async_db)):
+    svc = RoleService(db)
+    role = await svc.get_role(role_id)
+    return success_response(data=role.model_dump(exclude_none=True))
+
+
+@router.patch("/{role_id}", dependencies=[_role_update], summary="Update a role")
+async def update_role(
+    role_id: UUID,
+    body: RoleUpdate,
+    db: AsyncSession = Depends(get_async_db),
+    payload: dict = Depends(get_current_user_payload),
+):
+    svc = RoleService(db)
+    role = await svc.update_role(role_id, body, payload.get("role"))
+    return success_response(
+        data=role.model_dump(exclude_none=True),
+        message="Role updated",
+    )
+
+
+@router.delete(
+    "/{role_id}",
+    dependencies=[_role_soft_delete],
+    summary="Soft delete a role",
+)
+async def soft_delete_role(
+    role_id: UUID,
+    body: DeleteNoteRequest,
+    db: AsyncSession = Depends(get_async_db),
+    payload: dict = Depends(get_current_user_payload),
+):
+    svc = RoleService(db)
+    await svc.soft_delete_role(role_id, body.note, payload.get("role"))
+    return success_response(message="Role soft deleted")
+
+
+@router.delete(
+    "/{role_id}/hard",
+    dependencies=[_role_hard_delete],
+    summary="Hard delete a role",
+)
+async def hard_delete_role(
+    role_id: UUID,
+    body: DeleteNoteRequest,
+    db: AsyncSession = Depends(get_async_db),
+    payload: dict = Depends(get_current_user_payload),
+):
+    svc = RoleService(db)
+    await svc.hard_delete_role(role_id, body.note, payload.get("role"))
+    return success_response(message="Role hard deleted")

fastapi_forge/templates/with_rbac/app/api/v1/roles/schema.py

@@ -0,0 +1,51 @@
+from typing import List, Optional
+from uuid import UUID
+
+from pydantic import Field
+
+from app.utils.casing import CamelModel
+
+
+class RoleCreate(CamelModel):
+    name: str = Field(..., min_length=2, max_length=100)
+    description: Optional[str] = None
+    is_active: bool = True
+    parent_role_id: Optional[UUID] = None
+    permission_ids: List[UUID] = []
+
+
+class RoleUpdate(CamelModel):
+    name: Optional[str] = Field(default=None, min_length=2, max_length=100)
+    description: Optional[str] = None
+    is_active: Optional[bool] = None
+    parent_role_id: Optional[UUID] = None
+    permission_ids: Optional[List[UUID]] = None
+
+
+class Permission(CamelModel):
+    id: UUID
+    code: str
+
+
+class RoleBase(CamelModel):
+    id: str
+    name: str
+    description: Optional[str] = None
+    is_active: bool
+    parent_role_id: Optional[str] = None
+    is_deleted: bool = False
+    deleted_at: Optional[str] = None
+    deletion_note: Optional[str] = None
+
+
+class RoleResponse(RoleBase):
+    permissions: list[Permission]
+
+
+class RoleTreeNode(RoleBase):
+    children: list["RoleTreeNode"] = Field(default_factory=list)
+
+
+class AssignRoleRequest(CamelModel):
+    user_id: UUID
+    role_id: UUID

fastapi_forge/templates/with_rbac/app/api/v1/roles/service.py

@@ -0,0 +1,319 @@
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.v1.permissions.repository import PermissionRepository
+from app.api.v1.roles.repository import RoleAssignmentRepository, RoleRepository
+from app.core.exceptions import (
+    ConflictException,
+    ForbiddenException,
+    NotFoundException,
+    ValidationException,
+)
+from app.db.models.permission import Role
+
+from .schema import (
+    RoleCreate,
+    RoleResponse,
+    RoleUpdate,
+    Permission as PermissionSchema,
+    RoleTreeNode,
+    RoleBase,
+)
+
+ROOT_ROLE_NAME = "SUPER ADMIN"
+
+
+class RoleService:
+    def __init__(self, session: AsyncSession):
+        self.session = session
+        self.roles = RoleRepository(session)
+        self.assignments = RoleAssignmentRepository(session)
+        self.permissions = PermissionRepository(session)
+
+    async def list_roles(
+        self,
+        page: int,
+        page_size: int,
+        pagination: bool = True,
+        search: str | None = None,
+        sort_by: str | None = None,
+        sort_order: str | None = None,
+        active_only: bool = True,
+    ) -> tuple[list[RoleResponse], int]:
+        items, total = await self.roles.get_active(
+            page, page_size, pagination, search, sort_by, sort_order, active_only
+        )
+        return [self._role_response(item) for item in items], total
+
+    async def list_roles_below_current(self, current_role_name: str | None):
+        current_role = await self._current_role(current_role_name)
+        roles = await self.roles.list_active_with_permissions()
+        descendants = await self._descendant_roles(current_role, roles)
+        return [self._role_tree_response(role) for role in descendants]
+
+    async def role_tree_below_current(self, current_role_name: str | None):
+        current_role = await self._current_role(current_role_name)
+        roles = await self.roles.list_active_with_permissions()
+        descendants = await self._descendant_roles(current_role, roles)
+        allowed_ids = {role.id for role in descendants}
+        children_by_parent = {}
+        for role in descendants:
+            children_by_parent.setdefault(role.parent_role_id, []).append(role)
+
+        def build_node(role) -> RoleTreeNode:
+            response = self._role_tree_response(role)
+            return RoleTreeNode(
+                **response.model_dump(),
+                children=[
+                    build_node(child)
+                    for child in children_by_parent.get(role.id, [])
+                    if child.id in allowed_ids
+                ],
+            )
+
+        roots = [
+            role
+            for role in descendants
+            if role.parent_role_id not in allowed_ids
+            or role.parent_role_id == current_role.id
+        ]
+        return [build_node(role) for role in roots]
+
+    async def list_deleted_roles(
+        self,
+        page: int,
+        page_size: int,
+        pagination: bool = True,
+        search: str | None = None,
+        sort_by: str | None = None,
+        sort_order: str | None = None,
+    ) -> tuple[list[RoleResponse], int]:
+        items, total = await self.roles.get_deleted(
+            page=page,
+            page_size=page_size,
+            pagination=pagination,
+            search=search,
+            search_columns=[Role.name, Role.description],
+            sort_by=sort_by,
+            sort_order=sort_order,
+        )
+        return [self._role_response(item) for item in items], total
+
+    async def create_role(
+        self,
+        data: RoleCreate,
+        current_role_name: str | None = None,
+    ) -> RoleResponse:
+        current_role = await self._current_role(current_role_name)
+        if await self.roles.exists("name", data.name):
+            raise ConflictException(f"Role '{data.name}' already exists")
+
+        permissions = await self._resolve_permissions(data.permission_ids)
+        parent = await self._resolve_parent_role(data.parent_role_id, current_role)
+
+        role = await self.roles.create(
+            {
+                "name": data.name,
+                "description": data.description,
+                "is_active": data.is_active,
+                "parent_role_id": parent.id,
+            }
+        )
+        role.permissions = permissions
+        await self.session.flush()
+        return self._role_response(role)
+
+    async def get_role(self, role_id: UUID) -> RoleResponse:
+        role = await self.roles.get_with_permissions(role_id)
+        if not role:
+            raise NotFoundException("Role", role_id)
+        return self._role_response(role)
+
+    async def update_role(
+        self,
+        role_id: UUID,
+        data: RoleUpdate,
+        current_role_name: str | None = None,
+    ) -> RoleResponse:
+        current_role = await self._current_role(current_role_name)
+        role = await self.roles.get_with_permissions(role_id)
+        if not role:
+            raise NotFoundException("Role", role_id)
+        await self._require_manage_role(current_role, role)
+
+        values = data.model_dump(exclude_unset=True)
+        if "name" in values and await self.roles.exists_for_other_role(
+            "name",
+            values["name"],
+            role_id,
+        ):
+            raise ConflictException(f"Role '{values['name']}' already exists")
+
+        permission_ids = values.pop("permission_ids", None)
+        if "parent_role_id" in values:
+            parent_role_id = values.pop("parent_role_id")
+            parent = await self._resolve_parent_role(parent_role_id, current_role)
+            if await self.roles.would_create_cycle(role_id, parent.id):
+                raise ValidationException("Role parent cannot create a cycle")
+            role.parent_role_id = parent.id
+        for key, value in values.items():
+            setattr(role, key, value)
+        if permission_ids is not None:
+            role.permissions = await self._resolve_permissions(permission_ids)
+
+        self.session.add(role)
+        await self.session.flush()
+        return self._role_response(role)
+
+    async def assign_role(
+        self,
+        user_id: UUID,
+        role_id: UUID,
+        current_role_name: str | None = None,
+    ) -> None:
+        current_role = await self._current_role(current_role_name)
+        user = await self.assignments.get_user(user_id)
+        if not user:
+            raise NotFoundException("User", user_id)
+        role = await self.assignments.get_role(role_id)
+        if not role:
+            raise NotFoundException("Role", role_id)
+        target_role = self.assignments.get_role_from_user(user)
+        if target_role:
+            await self._require_manage_role(current_role, target_role)
+        await self._require_manage_role(current_role, role)
+        duplicates = self._role_extra_permission_duplicates(
+            role,
+            user.extra_permissions,
+        )
+        if duplicates:
+            raise ValidationException(
+                "Permission(s) already assigned to role: "
+                + ", ".join(sorted(permission.code for permission in duplicates))
+            )
+        user.roles = [role]
+        await self.session.flush()
+
+    async def soft_delete_role(
+        self,
+        role_id: UUID,
+        note: str,
+        current_role_name: str | None = None,
+    ) -> None:
+        current_role = await self._current_role(current_role_name)
+        role = await self.roles.get_by_id(role_id)
+        if not role:
+            raise NotFoundException("Role", role_id)
+        await self._require_manage_role(current_role, role)
+        if await self.roles.has_active_children(role_id):
+            raise ValidationException("Role has active child roles")
+        await self.roles.soft_delete(role, note)
+
+    async def hard_delete_role(
+        self,
+        role_id: UUID,
+        note: str,
+        current_role_name: str | None = None,
+    ) -> None:
+        current_role = await self._current_role(current_role_name)
+        role = await self.roles.get_by_id(role_id, include_deleted=True)
+        if not role:
+            raise NotFoundException("Role", role_id)
+        await self._require_manage_role(current_role, role)
+        if await self.roles.has_active_children(role_id):
+            raise ValidationException("Role has active child roles")
+        await self.roles.hard_delete(role, note)
+
+    def _role_response(self, role) -> RoleResponse:
+        return RoleResponse(
+            id=str(role.id),
+            name=role.name,
+            description=role.description,
+            is_active=role.is_active,
+            parent_role_id=str(role.parent_role_id) if role.parent_role_id else None,
+            is_deleted=role.is_deleted,
+            deleted_at=role.deleted_at.isoformat() if role.deleted_at else None,
+            deletion_note=role.deletion_note,
+            permissions=[
+                PermissionSchema(id=permission.id, code=permission.code)
+                for permission in role.permissions
+                if not permission.is_deleted and permission.is_active
+            ],
+        )
+
+    def _role_tree_response(self, role) -> RoleBase:
+        return RoleBase(
+            id=str(role.id),
+            name=role.name,
+            description=role.description,
+            is_active=role.is_active,
+            parent_role_id=str(role.parent_role_id) if role.parent_role_id else None,
+            is_deleted=role.is_deleted,
+            deleted_at=role.deleted_at.isoformat() if role.deleted_at else None,
+            deletion_note=role.deletion_note,
+        )
+
+    def _role_extra_permission_duplicates(self, role, extra_permissions: list) -> list:
+        role_permission_ids = {
+            permission.id
+            for permission in role.permissions
+            if not permission.is_deleted and permission.is_active
+        }
+        return [
+            permission
+            for permission in extra_permissions
+            if permission.id in role_permission_ids
+            and not permission.is_deleted
+            and permission.is_active
+        ]
+
+    async def _resolve_permissions(self, permission_ids: list[UUID]) -> list:
+        permissions = []
+        for permission_id in list(dict.fromkeys(permission_ids)):
+            permission = await self.permissions.get_active_by_id(permission_id)
+            if not permission:
+                raise NotFoundException("Permission", permission_id)
+            permissions.append(permission)
+        return permissions
+
+    async def _current_role(self, role_name: str | None) -> Role:
+        if not role_name:
+            raise ForbiddenException("Current user role is required")
+        role = await self.roles.get_by_name_with_permissions(role_name)
+        if not role:
+            raise ForbiddenException("Current user role is invalid")
+        return role
+
+    async def _resolve_parent_role(
+        self,
+        parent_role_id: UUID | None,
+        current_role: Role,
+    ) -> Role:
+        if parent_role_id is None:
+            return current_role
+        parent = await self.roles.get_with_permissions(parent_role_id)
+        if not parent or not parent.is_active:
+            raise NotFoundException("Parent role", parent_role_id)
+        if parent.id != current_role.id:
+            await self._require_manage_role(current_role, parent)
+        return parent
+
+    async def _require_manage_role(self, current_role: Role, target_role: Role) -> None:
+        if current_role.name.upper() == ROOT_ROLE_NAME:
+            if target_role.id == current_role.id:
+                raise ForbiddenException("You cannot manage your own role")
+            return
+        if not await self.roles.is_descendant(target_role.id, current_role.id):
+            raise ForbiddenException("You cannot manage this role")
+
+    async def _descendant_roles(
+        self, current_role: Role, roles: list[Role]
+    ) -> list[Role]:
+        if current_role.name.upper() == ROOT_ROLE_NAME:
+            return [role for role in roles if role.id != current_role.id]
+        descendants = []
+        for role in roles:
+            if await self.roles.is_descendant(role.id, current_role.id):
+                descendants.append(role)
+        return descendants

fastapi_forge/templates/with_rbac/app/api/v1/schema.py

@@ -0,0 +1,7 @@
+from pydantic import Field
+
+from app.utils.casing import CamelModel
+
+
+class DeleteNoteRequest(CamelModel):
+    note: str = Field(..., min_length=3, max_length=1000)

fastapi_forge/templates/with_rbac/app/api/v1/users/__init__.py

@@ -0,0 +1 @@
+