core-framework 0.3.0__py3-none-any.whl

core_framework/api/admin/users/schemas.py

@@ -0,0 +1,137 @@
+from datetime import datetime
+from typing import Annotated, Literal
+
+from fastapi.exceptions import RequestValidationError
+from pydantic import BaseModel, Field, RootModel, ValidationError
+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 RestrictionCategory, RestrictionType
+from core_framework.domains.user import ProfileVisibility, UserRole
+
+
+class UserSummaryResponse(AvatarMixin):
+    user_id: UserID
+    username: str
+    display_name: DisplayName | None = None
+    role: UserRole
+    created_at: datetime
+
+
+class UserIdentity(AvatarMixin):
+    user_id: UserID
+    username: str
+    display_name: DisplayName | None = None
+    role: UserRole
+    created_at: datetime
+
+
+class UserRestriction(BaseModel):
+    status: RestrictionType
+    category: RestrictionCategory
+    expires_at: datetime | None
+
+
+class InternalNoteRequest(BaseModel):
+    content: Annotated[str, Field(..., min_length=3, max_length=200)]
+
+
+class InternalNoteResponse(BaseModel):
+    id: int
+    content: str
+    created_at: datetime
+
+
+class InternalNoteDetailResponse(BaseModel):
+    id: int
+    content: str
+    created_at: datetime
+    actor: UserReference
+
+
+class UserModeration(BaseModel):
+    restriction: UserRestriction
+    notes: list[InternalNoteResponse]
+
+
+class AdminAccountResponse(BaseModel):
+    user_id: UserID
+    username: str
+    role: UserRole
+    email: str | None = None
+    email_verified: bool
+    deletion_scheduled_for: datetime | None = None
+
+
+class AdminProfileResponse(AvatarMixin, BannerMixin):
+    display_name: DisplayName | None = None
+    bio: Bio | None = None
+    status: UserStatus | None = None
+    social_links: Annotated[dict[str, str], Field(default_factory=dict)]
+    profile_visibility: ProfileVisibility
+
+
+class UserDetailResponse(BaseModel):
+    account: AdminAccountResponse
+    profile: AdminProfileResponse
+    moderation: UserModeration
+
+
+class UserSearchQueryParams(BaseModel):
+    username: Annotated[str | None, Field(default=None, min_length=1, max_length=50)]
+    role: Annotated[UserRole | None, Field(default=None)]
+
+
+class UsernameChangeRequest(BaseModel):
+    username: Username
+
+
+class RoleChangeRequest(BaseModel):
+    role: Literal["member", "moderator"]
+
+
+class AdminProfileUpdateRequest(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 UserChangeHistoryItem(BaseModel):
+    user_id: UserID
+    actor: UserReference | None
+    entity_type: str
+    field: str
+    old_value: str | None
+    new_value: str | None
+    created_at: datetime
+
+
+class NoteID(RootModel[int]):
+    root: Annotated[
+        int,
+        Field(
+            description="The ID of the internal note",
+            ge=1,
+        ),
+    ]
+
+
+def validate_note_id(*, note_id: int) -> NoteID:
+    try:
+        return NoteID(root=note_id)
+    except ValidationError as e:
+        raise RequestValidationError(e.errors()) from e

core_framework/api/auth/router.py

@@ -0,0 +1,21 @@
+from typing import Any
+
+from fastapi import APIRouter, status
+
+from core_framework.api.auth.schemas import CreatedUserResponse
+from core_framework.api.dependencies import RequiredFirebaseUser
+from core_framework.application.auth.auth_service import register_user
+
+router = APIRouter(
+    prefix="/auth",
+    tags=["auth"],
+)
+
+
+@router.post(
+    "/register",
+    status_code=status.HTTP_201_CREATED,
+    response_model=CreatedUserResponse,
+)
+async def post_register(firebase_user: RequiredFirebaseUser) -> Any:
+    return await register_user(user_id=firebase_user.user_id.root)

core_framework/api/auth/schemas.py

@@ -0,0 +1,28 @@
+from typing import Annotated
+
+from pydantic import BaseModel, EmailStr, Field, RootModel
+
+from core_framework.api.users.shared.schemas import UserID, Username
+
+
+class CountryCode(RootModel[str]):
+    root: Annotated[
+        str,
+        Field(
+            description="ISO 3166-1 alpha-2 country code",
+            pattern="^[A-Z]{2}$",
+            examples=["US", "GB"],
+        ),
+    ]
+
+
+class CreatedUserResponse(BaseModel):
+    user_id: UserID
+    username: Username
+
+
+class FirebaseUser(BaseModel):
+    user_id: UserID
+    email: EmailStr
+    email_verified: bool
+    sign_in_provider: str

core_framework/api/comments/authenticated/router.py

@@ -0,0 +1,126 @@
+from fastapi import APIRouter, BackgroundTasks, Depends, status
+from ulid import ULID
+
+from core_framework.api.comments.authenticated.schemas import (
+    CommentReportRequest,
+    CreateCommentRequest,
+    CreateReplyRequest,
+    UpdateCommentRequest,
+)
+from core_framework.api.dependencies import RequiredUserID, check_not_banned
+from core_framework.application.comments.authenticated_service import (
+    add_comment_report,
+    create_comment,
+    create_reply,
+    delete_comment,
+    edit_comment,
+    like_comment,
+    mark_comment_stats_dirty,
+    remove_comment_report,
+    unlike_comment,
+)
+
+router = APIRouter(
+    prefix="/comments",
+    tags=["comments - authenticated"],
+    dependencies=[Depends(check_not_banned)],
+)
+
+
+@router.put("/{comment_id}/like", status_code=status.HTTP_204_NO_CONTENT)
+async def put_comment_like(
+    comment_id: ULID,
+    user_id: RequiredUserID,
+    background_tasks: BackgroundTasks,
+) -> None:
+    await like_comment(comment_id=str(comment_id), user_id=user_id.root)
+    background_tasks.add_task(mark_comment_stats_dirty, comment_id=str(comment_id))
+
+
+@router.delete("/{comment_id}/like", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_comment_like(
+    comment_id: ULID,
+    user_id: RequiredUserID,
+    background_tasks: BackgroundTasks,
+) -> None:
+    await unlike_comment(comment_id=str(comment_id), user_id=user_id.root)
+    background_tasks.add_task(mark_comment_stats_dirty, comment_id=str(comment_id))
+
+
+@router.post("/{comment_id}/report", status_code=status.HTTP_204_NO_CONTENT)
+async def post_comment_report(
+    comment_id: ULID,
+    user_id: RequiredUserID,
+    report_request: CommentReportRequest,
+    background_tasks: BackgroundTasks,
+) -> None:
+    await add_comment_report(
+        reporter_id=user_id.root,
+        comment_id=str(comment_id),
+        category=report_request.category,
+        reason=report_request.reason,
+    )
+    background_tasks.add_task(mark_comment_stats_dirty, comment_id=str(comment_id))
+
+
+@router.delete("/{comment_id}/report", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_comment_report(
+    comment_id: ULID,
+    user_id: RequiredUserID,
+    background_tasks: BackgroundTasks,
+) -> None:
+    await remove_comment_report(reporter_id=user_id.root, comment_id=str(comment_id))
+    background_tasks.add_task(mark_comment_stats_dirty, comment_id=str(comment_id))
+
+
+@router.patch("/{comment_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def patch_comment(
+    comment_id: ULID,
+    user_id: RequiredUserID,
+    request_body: UpdateCommentRequest,
+) -> None:
+    validated_update_request = request_body.model_dump(mode="json", exclude_unset=True)
+    await edit_comment(
+        comment_id=str(comment_id),
+        author_id=user_id.root,
+        validated_update_request=validated_update_request,
+    )
+
+
+@router.delete("/{comment_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_comment_route(
+    comment_id: ULID,
+    user_id: RequiredUserID,
+    background_tasks: BackgroundTasks,
+) -> None:
+    parent_comment_id = await delete_comment(
+        comment_id=str(comment_id),
+        author_id=user_id.root,
+    )
+    if parent_comment_id is not None:
+        background_tasks.add_task(mark_comment_stats_dirty, comment_id=parent_comment_id)
+
+
+@router.post("", status_code=status.HTTP_201_CREATED)
+async def post_comment(user_id: RequiredUserID, request_body: CreateCommentRequest) -> None:
+    await create_comment(
+        author_id=user_id.root,
+        content=request_body.content.root,
+        subject_type=request_body.subject_type,
+        subject_id=request_body.subject_id,
+    )
+
+
+@router.post("/{comment_id}/replies", status_code=status.HTTP_201_CREATED)
+async def post_reply(
+    comment_id: ULID,
+    user_id: RequiredUserID,
+    request_body: CreateReplyRequest,
+    background_tasks: BackgroundTasks,
+) -> None:
+    await create_reply(
+        author_id=user_id.root,
+        content=request_body.content.root,
+        parent_comment_id=str(comment_id),
+    )
+    background_tasks.add_task(mark_comment_stats_dirty, comment_id=str(comment_id))

core_framework/api/comments/authenticated/schemas.py

@@ -0,0 +1,27 @@
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+from core_framework.api.comments.schemas import CommentContent
+from core_framework.api.schemas import BasePatchRequest
+from core_framework.domains.comment import CommentSubjectType
+from core_framework.domains.moderation import ReportCategory
+
+
+class UpdateCommentRequest(BasePatchRequest):
+    content: CommentContent | None = None
+
+
+class CommentReportRequest(BaseModel):
+    category: ReportCategory
+    reason: Annotated[str, Field(default="", max_length=250)]
+
+
+class CreateCommentRequest(BaseModel):
+    content: CommentContent
+    subject_type: CommentSubjectType
+    subject_id: Annotated[str, Field(min_length=1)]
+
+
+class CreateReplyRequest(BaseModel):
+    content: CommentContent

core_framework/api/comments/public/router.py

@@ -0,0 +1,103 @@
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
+from ulid import ULID
+
+from core_framework.api.comments.public.schemas import CommentResponse
+from core_framework.api.dependencies import OptionalUserID
+from core_framework.api.users.shared.schemas import validate_user_id
+from core_framework.application.comments.public_service import (
+    retrieve_comment_by_id,
+    retrieve_comments,
+    retrieve_comments_by_user_id,
+    retrieve_replies,
+)
+from core_framework.core.pagination import (
+    PaginationCursorType,
+    PaginationResponse,
+    TokenCursorQueryParams,
+    paginate_cursor,
+)
+from core_framework.domains.comment import CommentSubjectType
+
+router = APIRouter(
+    prefix="/comments",
+    tags=["comments - public"],
+)
+
+
+@router.get("/users/{user_id}", response_model=PaginationResponse[CommentResponse])
+async def get_comments_by_user_id(
+    user_id: str,
+    request: Request,
+    viewer_id: OptionalUserID,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+) -> Any:
+    validated_user_id = validate_user_id(user_id=user_id)
+    comments = await retrieve_comments_by_user_id(
+        user_id=validated_user_id.root,
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+        viewer_id=viewer_id.root if viewer_id else None,
+    )
+    return paginate_cursor(
+        request=request,
+        items=comments,
+        limit=pagination_params.limit,
+        cursor_field=PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.get("", response_model=PaginationResponse[CommentResponse])
+async def get_comments(
+    request: Request,
+    subject_type: CommentSubjectType,
+    subject_id: Annotated[str, Query(min_length=1)],
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+    viewer_id: OptionalUserID,
+) -> Any:
+    comments = await retrieve_comments(
+        subject_type=subject_type,
+        subject_id=subject_id,
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+        viewer_id=viewer_id.root if viewer_id else None,
+    )
+    return paginate_cursor(
+        request=request,
+        items=comments,
+        limit=pagination_params.limit,
+        cursor_field=PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.get("/{comment_id}/replies", response_model=PaginationResponse[CommentResponse])
+async def get_replies(
+    comment_id: ULID,
+    request: Request,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+    viewer_id: OptionalUserID,
+) -> Any:
+    replies = await retrieve_replies(
+        parent_comment_id=str(comment_id),
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+        viewer_id=viewer_id.root if viewer_id else None,
+    )
+    return paginate_cursor(
+        request=request,
+        items=replies,
+        limit=pagination_params.limit,
+        cursor_field=PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.get("/{comment_id}", response_model=CommentResponse)
+async def get_comment_by_id(comment_id: ULID, viewer_id: OptionalUserID) -> Any:
+    comment = await retrieve_comment_by_id(comment_id=str(comment_id), viewer_id=viewer_id.root if viewer_id else None)
+    if comment is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Comment not found")
+    return comment

core_framework/api/comments/public/schemas.py

@@ -0,0 +1,36 @@
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+from ulid import ULID
+
+from core_framework.api.comments.schemas import CommentContent
+from core_framework.api.users.shared.schemas import UserReference
+
+
+class CommentStatsResponse(BaseModel):
+    like_count: Annotated[int, Field(ge=0)] = 0
+    reply_count: Annotated[int, Field(ge=0)] = 0
+
+
+class CommentViewerContext(BaseModel):
+    is_liked: bool
+    is_reported: bool
+
+
+class AuthorContext(BaseModel):
+    can_edit: bool
+    can_delete: bool
+
+
+class CommentResponse(BaseModel):
+    id: ULID
+    author: UserReference
+    content: CommentContent
+    stats: CommentStatsResponse
+    can_reply: bool
+    engagement_allowed: bool
+    edited_at: datetime | None
+    created_at: datetime
+    viewer_context: CommentViewerContext | None
+    author_context: AuthorContext | None

core_framework/api/comments/router.py

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

core_framework/api/comments/schemas.py

@@ -0,0 +1,17 @@
+from typing import Annotated, Final
+
+from pydantic import Field, RootModel, field_validator
+
+MAX_COMMENT_CONTENT_LENGTH: Final[int] = 5000
+
+
+class CommentContent(RootModel[str]):
+    root: Annotated[str, Field(min_length=1, max_length=MAX_COMMENT_CONTENT_LENGTH)]
+
+    @field_validator("root", mode="after")
+    @classmethod
+    def validate_not_blank(cls, v: str) -> str:
+        s = v.strip()
+        if not s:
+            raise ValueError("Comment content must not be blank")
+        return s

core_framework/api/dependencies.py

@@ -0,0 +1,168 @@
+from typing import Annotated, Any, Final
+
+from async_lru import alru_cache
+from asyncer import asyncify
+from fastapi import Depends, Header, Security
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from firebase_admin import auth
+
+from core_framework.api.auth.schemas import CountryCode, FirebaseUser
+from core_framework.api.users.shared.schemas import UserID
+from core_framework.application.auth.access_service import get_user_detail
+from core_framework.application.auth.models import UserDetail
+from core_framework.application.shared.exceptions import ForbiddenException, UnauthorizedException
+from core_framework.application.shared.user_agent import parse_user_agent
+from core_framework.application.users.admin_service import retrieve_admin_user_ids
+from core_framework.core.context import user_id
+from core_framework.domains.moderation import RestrictionType
+from core_framework.domains.user import UserIdentity
+
+MAX_REFERRER_LENGTH: Final[int] = 512
+
+bearer_scheme = HTTPBearer(auto_error=False)
+
+
+@alru_cache(maxsize=5000, ttl=300)  # ~10MB per worker, 5 minutes TTL
+async def _verify_id_token(token: str) -> dict[str, Any]:
+    return await asyncify(auth.verify_id_token)(token)
+
+
+def _build_firebase_user_from_claims(user_dict: dict[str, Any]) -> FirebaseUser | None:
+    uid = user_dict.get("uid")
+    email = user_dict.get("email")
+    email_verified = user_dict.get("email_verified")
+    firebase_claim = user_dict.get("firebase")
+
+    if not isinstance(uid, str):
+        return None
+    if not isinstance(email, str):
+        return None
+    if not isinstance(email_verified, bool):
+        return None
+    if not isinstance(firebase_claim, dict):
+        return None
+
+    sign_in_provider = firebase_claim.get("sign_in_provider")
+    if not isinstance(sign_in_provider, str):
+        return None
+
+    try:
+        return FirebaseUser(
+            user_id=UserID(uid),
+            email=email,
+            email_verified=email_verified,
+            sign_in_provider=sign_in_provider,
+        )
+    except TypeError, ValueError:
+        return None
+
+
+async def _get_bearer_token(
+    creds: Annotated[HTTPAuthorizationCredentials | None, Security(bearer_scheme)],
+) -> str | None:
+    if not creds:
+        return None
+
+    if creds.scheme.lower() != "bearer":
+        raise UnauthorizedException("Invalid token scheme")
+
+    return creds.credentials
+
+
+async def _get_firebase_user(token: Annotated[str | None, Depends(_get_bearer_token)]) -> FirebaseUser | None:
+    if not token:
+        return None
+
+    try:
+        user_dict = await _verify_id_token(token)
+    except (
+        ValueError,
+        auth.InvalidIdTokenError,
+        auth.ExpiredIdTokenError,
+        auth.RevokedIdTokenError,
+        auth.CertificateFetchError,
+        auth.UserDisabledError,
+    ):
+        return None
+
+    firebase_user = _build_firebase_user_from_claims(user_dict)
+    if firebase_user is None:
+        return None
+
+    user_id.set(firebase_user.user_id.root)
+    return firebase_user
+
+
+async def _get_required_firebase_user(
+    user: Annotated[FirebaseUser | None, Depends(_get_firebase_user)],
+) -> FirebaseUser:
+    if not user:
+        raise UnauthorizedException("Unauthorized")
+    return user
+
+
+async def _get_user_id(user: Annotated[FirebaseUser | None, Depends(_get_firebase_user)]) -> UserID | None:
+    if not user:
+        return None
+    return user.user_id
+
+
+async def _get_required_user_id(user_id: Annotated[UserID | None, Depends(_get_user_id)]) -> UserID:
+    if not user_id:
+        raise UnauthorizedException("Unauthorized")
+    return user_id
+
+
+async def check_admin_role(user_id: Annotated[UserID, Depends(_get_required_user_id)]) -> None:
+    if user_id.root not in await retrieve_admin_user_ids():
+        raise ForbiddenException("Admin access required")
+
+
+async def _get_user_detail(user_id: Annotated[UserID, Depends(_get_required_user_id)]) -> UserDetail:
+    return await get_user_detail(user_id=user_id.root)
+
+
+async def check_not_banned(user_detail: Annotated[UserDetail, Depends(_get_user_detail)]) -> None:
+    if (
+        user_detail.identity == UserIdentity.DEFAULT
+        or user_detail.moderation.restriction.status == RestrictionType.BANNED
+    ):
+        raise ForbiddenException()
+
+
+async def _get_request_context(
+    firebase_user: Annotated[FirebaseUser | None, Depends(_get_firebase_user)],
+    user_agent: Annotated[str | None, Header()] = None,
+    cf_ipcountry: Annotated[CountryCode | None, Header()] = None,
+    referrer: Annotated[str | None, Header(alias="Referer")] = None,
+) -> dict[str, str]:
+    metadata: dict[str, str] = {}
+
+    if firebase_user:
+        metadata["viewer_id"] = firebase_user.user_id.root
+        metadata["provider"] = firebase_user.sign_in_provider
+    if cf_ipcountry:
+        metadata["country_code"] = cf_ipcountry.root
+    if referrer:
+        metadata["referrer"] = referrer[:MAX_REFERRER_LENGTH]
+
+    client_info = parse_user_agent(user_agent)
+    metadata.update(client_info)
+
+    return {k: v for k, v in metadata.items() if v is not None}
+
+
+RequiredFirebaseUser = Annotated[FirebaseUser, Depends(_get_required_firebase_user)]
+OptionalUserID = Annotated[UserID | None, Depends(_get_user_id)]
+RequiredUserID = Annotated[UserID, Depends(_get_required_user_id)]
+RequestContext = Annotated[dict[str, str], Depends(_get_request_context)]
+
+
+__all__ = [
+    "RequestContext",
+    "RequiredFirebaseUser",
+    "OptionalUserID",
+    "RequiredUserID",
+    "check_admin_role",
+    "check_not_banned",
+]