core-framework 0.3.0__py3-none-any.whl

core_framework/api/users/authenticated/router.py

@@ -0,0 +1,244 @@
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, Query, Request, status
+
+from core_framework.api.dependencies import RequiredFirebaseUser, RequiredUserID, check_not_banned
+from core_framework.api.users.authenticated.schemas import (
+    AccountResponse,
+    AccountUpdateRequest,
+    AppealRequest,
+    BlockedUserResponse,
+    MyAppealsResponse,
+    PreferencesResponse,
+    PreferencesUpdateRequest,
+    ProfileResponse,
+    ProfileUpdateRequest,
+    UserReportRequest,
+)
+from core_framework.api.users.shared.schemas import validate_user_id
+from core_framework.application.users.authenticated_service import (
+    add_appeal,
+    add_user_report,
+    block_user,
+    cancel_account_deletion,
+    change_my_account,
+    change_my_preferences,
+    change_my_profile,
+    delete_my_current_appeal,
+    remove_user_report,
+    retrieve_my_account,
+    retrieve_my_appeals,
+    retrieve_my_blocked_users,
+    retrieve_my_preferences,
+    retrieve_my_profile,
+    schedule_account_deletion,
+    unblock_user,
+)
+from core_framework.core.pagination import (
+    PaginationCursorType,
+    PaginationResponse,
+    TokenCursorQueryParams,
+    paginate_cursor,
+)
+from core_framework.domains.moderation import AppealDecision
+
+router = APIRouter(
+    prefix="/users",
+    tags=["users - authenticated"],
+)
+
+
+@router.get(
+    "/me/blocks",
+    response_model=PaginationResponse[BlockedUserResponse],
+    dependencies=[Depends(check_not_banned)],
+)
+async def get_my_blocked_users(
+    request: Request,
+    user_id: RequiredUserID,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+) -> Any:
+    blocked_users = await retrieve_my_blocked_users(
+        user_id=user_id.root, created_at=pagination_params.cursor, limit=pagination_params.limit
+    )
+    return paginate_cursor(
+        request,
+        blocked_users,
+        pagination_params.limit,
+        PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.get(
+    "/me/preferences",
+    response_model=PreferencesResponse,
+    dependencies=[Depends(check_not_banned)],
+)
+async def get_my_preferences(user_id: RequiredUserID) -> Any:
+    return await retrieve_my_preferences(user_id=user_id.root)
+
+
+@router.patch(
+    "/me/preferences",
+    response_model=PreferencesResponse,
+    dependencies=[Depends(check_not_banned)],
+)
+async def patch_my_preferences(user_id: RequiredUserID, update_request: PreferencesUpdateRequest) -> Any:
+    validated_update_request = update_request.model_dump(mode="json", exclude_unset=True)
+    return await change_my_preferences(user_id=user_id.root, validated_update_request=validated_update_request)
+
+
+@router.get(
+    "/me/profile",
+    response_model=ProfileResponse,
+    dependencies=[Depends(check_not_banned)],
+)
+async def get_my_profile(user_id: RequiredUserID) -> Any:
+    return await retrieve_my_profile(user_id=user_id.root)
+
+
+@router.patch(
+    "/me/profile",
+    response_model=ProfileResponse,
+    dependencies=[Depends(check_not_banned)],
+)
+async def patch_my_profile(user_id: RequiredUserID, update_request: ProfileUpdateRequest) -> Any:
+    validated_update_request = update_request.model_dump(mode="json", exclude_unset=True)
+    return await change_my_profile(user_id=user_id.root, validated_update_request=validated_update_request)
+
+
+@router.get(
+    "/me/account",
+    response_model=AccountResponse,
+    dependencies=[Depends(check_not_banned)],
+)
+async def get_my_account(firebase_user: RequiredFirebaseUser) -> Any:
+    return await retrieve_my_account(
+        user_id=firebase_user.user_id.root,
+        email=firebase_user.email,
+        email_verified=firebase_user.email_verified,
+    )
+
+
+@router.patch(
+    "/me/account",
+    response_model=AccountResponse,
+    dependencies=[Depends(check_not_banned)],
+)
+async def patch_my_account(
+    firebase_user: RequiredFirebaseUser,
+    update_request: AccountUpdateRequest,
+) -> Any:
+    validated_update_request = update_request.model_dump(mode="json", exclude_unset=True)
+    await change_my_account(user_id=firebase_user.user_id.root, validated_update_request=validated_update_request)
+    return await retrieve_my_account(
+        user_id=firebase_user.user_id.root,
+        email=firebase_user.email,
+        email_verified=firebase_user.email_verified,
+    )
+
+
+@router.put(
+    "/me/account/deletion",
+    status_code=status.HTTP_204_NO_CONTENT,
+    dependencies=[Depends(check_not_banned)],
+)
+async def put_my_account_deletion(user_id: RequiredUserID) -> None:
+    await schedule_account_deletion(user_id=user_id.root)
+
+
+@router.delete(
+    "/me/account/deletion",
+    status_code=status.HTTP_204_NO_CONTENT,
+    dependencies=[Depends(check_not_banned)],
+)
+async def delete_my_account_deletion(user_id: RequiredUserID) -> None:
+    await cancel_account_deletion(user_id=user_id.root)
+
+
+@router.get("/me/appeals", response_model=PaginationResponse[MyAppealsResponse])
+async def get_my_appeals(
+    request: Request,
+    user_id: RequiredUserID,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+    status: Annotated[AppealDecision | None, Query()] = None,
+) -> Any:
+    appeals = await retrieve_my_appeals(
+        user_id=user_id.root,
+        status=status,
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+    )
+    return paginate_cursor(
+        request,
+        appeals,
+        pagination_params.limit,
+        PaginationCursorType.UPDATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.post("/me/appeals", status_code=status.HTTP_204_NO_CONTENT)
+async def post_my_appeals(user_id: RequiredUserID, appeal_request: AppealRequest) -> None:
+    await add_appeal(user_id=user_id.root, justification=appeal_request.justification)
+
+
+@router.delete("/me/appeals", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_my_appeal(user_id: RequiredUserID) -> None:
+    await delete_my_current_appeal(user_id=user_id.root)
+
+
+@router.put(
+    "/{user_id}/block",
+    status_code=status.HTTP_204_NO_CONTENT,
+    dependencies=[Depends(check_not_banned)],
+)
+async def put_block_user(requester_id: RequiredUserID, user_id: str) -> None:
+    validated_target_user_id = validate_user_id(user_id=user_id)
+    await block_user(user_id=requester_id.root, target_user_id=validated_target_user_id.root)
+
+
+@router.delete(
+    "/{user_id}/block",
+    status_code=status.HTTP_204_NO_CONTENT,
+    dependencies=[Depends(check_not_banned)],
+)
+async def delete_block_user(requester_id: RequiredUserID, user_id: str) -> None:
+    validated_target_user_id = validate_user_id(user_id=user_id)
+    await unblock_user(user_id=requester_id.root, target_user_id=validated_target_user_id.root)
+
+
+@router.post(
+    "/{user_id}/report",
+    status_code=status.HTTP_204_NO_CONTENT,
+    dependencies=[Depends(check_not_banned)],
+)
+async def post_user_report(
+    requester_id: RequiredUserID,
+    user_id: str,
+    report_request: UserReportRequest,
+) -> None:
+    validated_target_user_id = validate_user_id(user_id=user_id)
+    await add_user_report(
+        reporter_id=requester_id.root,
+        target_id=validated_target_user_id.root,
+        category=report_request.category,
+        reason=report_request.reason,
+    )
+
+
+@router.delete(
+    "/{user_id}/report",
+    status_code=status.HTTP_204_NO_CONTENT,
+    dependencies=[Depends(check_not_banned)],
+)
+async def delete_user_report(
+    requester_id: RequiredUserID,
+    user_id: str,
+) -> None:
+    validated_target_user_id = validate_user_id(user_id=user_id)
+    await remove_user_report(
+        reporter_id=requester_id.root,
+        target_id=validated_target_user_id.root,
+    )

core_framework/api/users/authenticated/schemas.py

@@ -0,0 +1,81 @@
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import BaseModel, EmailStr, Field
+from ulid import ULID
+
+from core_framework.api.schemas import BasePatchRequest
+from core_framework.api.users.shared.schemas import (
+    AvatarMixin,
+    BannerMixin,
+    Bio,
+    DisplayName,
+    UserID,
+    Username,
+    UserReference,
+    UserStatus,
+)
+from core_framework.domains.moderation import AppealDecision, ReportCategory
+from core_framework.domains.user import ProfileVisibility, Theme
+
+
+class BlockedUserResponse(BaseModel):
+    user_id: UserID
+    username: Username
+
+
+class ProfileResponse(AvatarMixin, BannerMixin):
+    display_name: DisplayName | None
+    bio: Bio | None
+    status: UserStatus | None
+    social_links: dict[str, str]
+    profile_visibility: ProfileVisibility
+
+
+class AccountResponse(BaseModel):
+    username: Username
+    email: EmailStr
+    email_verified: bool
+    deletion_scheduled_for: datetime | None
+
+
+class AccountUpdateRequest(BasePatchRequest):
+    username: Username | None = None
+
+
+class ProfileUpdateRequest(BasePatchRequest):
+    display_name: DisplayName | None = None
+    avatar_id: ULID | None = None
+    banner_id: ULID | None = None
+    bio: Bio | None = None
+    status: UserStatus | None = None
+    social_links: dict[str, str] | None = None
+    profile_visibility: ProfileVisibility | None = None
+
+
+class UserReportRequest(BaseModel):
+    category: ReportCategory
+    reason: Annotated[str, Field(default="", max_length=250)]
+
+
+class AppealRequest(BaseModel):
+    justification: Annotated[str, Field(..., min_length=50, max_length=1000)]
+
+
+class MyAppealsResponse(BaseModel):
+    justification: str
+    reviewer: UserReference | None
+    decision_reason: str | None
+    status: AppealDecision
+    created_at: datetime
+    updated_at: datetime
+
+
+class PreferencesResponse(BaseModel):
+    theme: Theme
+    language: str
+
+
+class PreferencesUpdateRequest(BasePatchRequest):
+    theme: Theme | None = None
+    language: Annotated[str | None, Field(default=None, max_length=10)]

core_framework/api/users/public/router.py

@@ -0,0 +1,25 @@
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Query
+from fastapi.exceptions import RequestValidationError
+from pydantic import ValidationError
+
+from core_framework.api.users.public.schemas import UsernameExistsResponse
+from core_framework.api.users.shared.schemas import Username
+from core_framework.application.users.public_service import is_username_available
+
+router = APIRouter(
+    prefix="/users",
+    tags=["users - public"],
+)
+
+
+@router.get("/usernames/exists", response_model=UsernameExistsResponse)
+async def get_username_exists(username: Annotated[str, Query()]) -> Any:
+    try:
+        validated_username = Username(
+            root=username
+        )  # Note: Workaround for Pydantic's lack of support for Root Model in Query parameters
+    except ValidationError as e:
+        raise RequestValidationError(e.errors()) from e
+    return {"status": "available" if await is_username_available(username=validated_username.root) else "taken"}

core_framework/api/users/public/schemas.py

@@ -0,0 +1,7 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class UsernameExistsResponse(BaseModel):
+    status: Literal["available", "taken"]

core_framework/api/users/router.py

@@ -0,0 +1,9 @@
+from fastapi import APIRouter
+
+from core_framework.api.users.authenticated.router import router as authenticated_router
+from core_framework.api.users.public.router import router as public_router
+
+router = APIRouter()
+
+router.include_router(public_router)
+router.include_router(authenticated_router)

core_framework/api/users/shared/schemas.py

@@ -0,0 +1,174 @@
+from typing import Annotated
+
+from fastapi.exceptions import RequestValidationError
+from pydantic import (
+    BaseModel,
+    Field,
+    HttpUrl,
+    RootModel,
+    TypeAdapter,
+    ValidationError,
+    computed_field,
+    field_validator,
+)
+
+_http_url_adapter = TypeAdapter(HttpUrl)
+_avatar_default_url: str | None = None
+_avatar_base_url: str | None = None
+_avatar_extension: str | None = None
+_banner_default_url: str | None = None
+_banner_base_url: str | None = None
+_banner_extension: str | None = None
+
+
+def configure_user_media_urls(
+    *,
+    avatar_default_url: str,
+    avatar_base_url: str,
+    avatar_extension: str,
+    banner_default_url: str,
+    banner_base_url: str,
+    banner_extension: str,
+) -> None:
+    global _avatar_default_url, _avatar_base_url, _avatar_extension
+    global _banner_default_url, _banner_base_url, _banner_extension
+    _avatar_default_url = avatar_default_url
+    _avatar_base_url = avatar_base_url.rstrip("/")
+    _avatar_extension = avatar_extension
+    _banner_default_url = banner_default_url
+    _banner_base_url = banner_base_url.rstrip("/")
+    _banner_extension = banner_extension
+
+
+def _get_user_media_urls() -> dict[str, str]:
+    if (
+        _avatar_default_url is not None
+        and _avatar_base_url is not None
+        and _avatar_extension is not None
+        and _banner_default_url is not None
+        and _banner_base_url is not None
+        and _banner_extension is not None
+    ):
+        return {
+            "avatar_default_url": _avatar_default_url,
+            "avatar_base_url": _avatar_base_url,
+            "avatar_extension": _avatar_extension,
+            "banner_default_url": _banner_default_url,
+            "banner_base_url": _banner_base_url,
+            "banner_extension": _banner_extension,
+        }
+    msg = "User media URLs are not configured. Call configure_user_media_urls() during application bootstrap."
+    raise RuntimeError(msg)
+
+
+class UserID(RootModel[str]):
+    root: Annotated[
+        str,
+        Field(
+            description="The ID of the user",
+            min_length=1,
+            max_length=128,
+        ),
+    ]
+
+
+class Username(RootModel[str]):
+    root: Annotated[
+        str,
+        Field(
+            description="The username of the user",
+            min_length=1,
+            max_length=50,
+        ),
+    ]
+
+    @field_validator("root", mode="after")
+    @classmethod
+    def no_whitespace(cls, v: str) -> str:
+        if any(ch.isspace() for ch in v):
+            raise ValueError("Username must not contain whitespace")
+        return v
+
+
+class Bio(RootModel[str]):
+    root: Annotated[
+        str,
+        Field(
+            description="User profile bio",
+            max_length=500,
+        ),
+    ]
+
+
+class UserStatus(RootModel[str]):
+    root: Annotated[
+        str,
+        Field(
+            description="User status (e.g. away, online)",
+            max_length=150,
+        ),
+    ]
+
+
+class DisplayName(RootModel[str]):
+    root: Annotated[
+        str,
+        Field(
+            description="The display name of the user",
+            min_length=1,
+            max_length=100,
+        ),
+    ]
+
+
+class AvatarMixin(BaseModel):
+    avatar_id: Annotated[str | None, Field(exclude=True)]
+
+    @computed_field
+    @property
+    def avatar(self) -> HttpUrl:
+        url_string = _construct_avatar_url(avatar_id=self.avatar_id)
+        return _http_url_adapter.validate_python(url_string)
+
+
+class BannerMixin(BaseModel):
+    banner_id: Annotated[str | None, Field(exclude=True)]
+
+    @computed_field
+    @property
+    def banner(self) -> HttpUrl:
+        url_string = _construct_banner_url(banner_id=self.banner_id)
+        return _http_url_adapter.validate_python(url_string)
+
+
+class UserReference(BaseModel):
+    user_id: UserID
+    username: Username
+    display_name: DisplayName | None = None
+
+
+def validate_user_id(*, user_id: str) -> UserID:
+    try:
+        return UserID(root=user_id)  # Note: Workaround for Pydantic's lack of support for Root Model in Path parameters
+    except ValidationError as e:
+        raise RequestValidationError(e.errors()) from e
+
+
+def validate_optional_user_id(*, user_id: str | None) -> UserID | None:
+    if user_id is None:
+        return None
+    return validate_user_id(user_id=user_id)
+
+
+def _construct_avatar_url(*, avatar_id: str | None) -> str:
+    media_urls = _get_user_media_urls()
+    if avatar_id is None:
+        return media_urls["avatar_default_url"]
+    return f"{media_urls['avatar_base_url']}/{avatar_id}.{media_urls['avatar_extension']}"
+
+
+def _construct_banner_url(*, banner_id: str | None) -> str:
+    media_urls = _get_user_media_urls()
+    if banner_id is None:
+        return media_urls["banner_default_url"]
+    return f"{media_urls['banner_base_url']}/{banner_id}.{media_urls['banner_extension']}"

core_framework/application/auth/access_service.py

@@ -0,0 +1,26 @@
+import asyncio
+
+import core_framework.domains.moderation.dependencies as moderation_deps
+import core_framework.domains.user.dependencies as user_deps
+from core_framework.application.auth.models import UserDetail
+from core_framework.application.shared.enums import RedisKeys
+from core_framework.core.cache import cache
+from core_framework.domains.user import UserIdentity
+
+
+@cache(
+    resource_name=RedisKeys.USER_DETAIL,
+    ttl=86_400,  # 1 day
+    skip_if=lambda r: r.identity == UserIdentity.DEFAULT,
+)
+async def get_user_detail(*, user_id: str) -> UserDetail:
+    async with asyncio.TaskGroup() as tg:
+        identity_task = tg.create_task(user_deps.user_service.retrieve_user_identity_mapping(user_ids={user_id}))
+        moderation_task = tg.create_task(
+            moderation_deps.moderation_service.retrieve_user_moderation_mapping(user_ids={user_id})
+        )
+
+    return UserDetail(
+        identity=identity_task.result()[user_id],
+        moderation=moderation_task.result()[user_id],
+    )

core_framework/application/auth/auth_service.py

@@ -0,0 +1,10 @@
+import core_framework.core as core_fw
+import core_framework.domains.user.dependencies as user_deps
+from core_framework.application.shared.enums import RedisKeys
+from core_framework.domains.user import CreatedUser
+
+
+async def register_user(*, user_id: str) -> CreatedUser:
+    created_user = await user_deps.user_service.add_user(user_id=user_id)
+    await core_fw.redis_cache.sadd(RedisKeys.TAKEN_USERNAMES, created_user.username)
+    return created_user

core_framework/application/auth/models.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+from core_framework.domains.moderation import UserModeration
+from core_framework.domains.user import UserIdentity
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UserDetail:
+    identity: UserIdentity
+    moderation: UserModeration

core_framework/application/bootstrap.py

@@ -0,0 +1,19 @@
+from core_framework.core.cache import configure_cache
+from core_framework.core.runtime import CoreRuntime
+from core_framework.domains.comment.dependencies import configure_comment_dependencies
+from core_framework.domains.moderation.dependencies import configure_moderation_dependencies
+from core_framework.domains.post.dependencies import configure_post_dependencies
+from core_framework.domains.user.dependencies import configure_user_dependencies
+
+
+def configure_application_dependencies(runtime: CoreRuntime) -> None:
+    configure_cache(redis_cache=runtime.redis_cache)
+    configure_comment_dependencies(runtime)
+    configure_moderation_dependencies(runtime)
+    configure_post_dependencies(runtime)
+    configure_user_dependencies(runtime)
+
+    # alru_cache on user id set must not survive a rebound UserService instance
+    from core_framework.application.users.admin_service import retrieve_admin_user_ids
+
+    retrieve_admin_user_ids.cache_clear()