core-framework 0.3.0__py3-none-any.whl

core_framework/api/events/router.py

@@ -0,0 +1,39 @@
+from typing import Any
+
+from fastapi import APIRouter, BackgroundTasks, status
+
+from core_framework.api.dependencies import RequestContext
+from core_framework.api.events.schemas import EventRequest, EventTokenResponse
+from core_framework.application.events.event_service import EVENT_HANDLERS
+from core_framework.application.events.event_token import generate_token, verify_token
+from core_framework.application.events.models import Event
+
+router = APIRouter(
+    prefix="/events",
+    tags=["events"],
+)
+
+
+@router.get("/token", response_model=EventTokenResponse)
+async def get_event_token() -> Any:
+    return {"token": generate_token()}
+
+
+@router.post("", status_code=status.HTTP_202_ACCEPTED)
+async def post_events(
+    request_body: EventRequest,
+    background_tasks: BackgroundTasks,
+    request_context: RequestContext,
+) -> None:
+    if not verify_token(request_body.token, event_type=request_body.type):
+        return
+
+    events = [Event(**e.model_dump()) for e in request_body.events]
+    handler = EVENT_HANDLERS.get(request_body.type)
+    if handler:
+        background_tasks.add_task(
+            handler,
+            events=events,
+            token=request_body.token,
+            request_context=request_context,
+        )

core_framework/api/events/schemas.py

@@ -0,0 +1,20 @@
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+from core_framework.application.shared.enums import EventType, SubjectType
+
+
+class EventItem(BaseModel):
+    subject_type: SubjectType
+    subject: Annotated[str, Field(min_length=1, max_length=128)]
+
+
+class EventRequest(BaseModel):
+    type: EventType
+    token: Annotated[str, Field(min_length=1)]
+    events: list[EventItem] = Field(default_factory=list, max_length=100)
+
+
+class EventTokenResponse(BaseModel):
+    token: str

core_framework/api/posts/authenticated/router.py

@@ -0,0 +1,83 @@
+from fastapi import APIRouter, Depends, status
+from ulid import ULID
+
+from core_framework.api.dependencies import RequiredUserID, check_not_banned
+from core_framework.api.posts.authenticated.schemas import CreatePostRequest, PostReportRequest, UpdatePostRequest
+from core_framework.application.posts.authenticated_service import (
+    add_post_report,
+    create_post,
+    delete_post,
+    edit_post,
+    like_post,
+    remove_post_report,
+    unlike_post,
+)
+
+router = APIRouter(
+    prefix="/posts",
+    tags=["posts - authenticated"],
+    dependencies=[Depends(check_not_banned)],
+)
+
+
+@router.post("", status_code=status.HTTP_201_CREATED)
+async def post_post(user_id: RequiredUserID, request_body: CreatePostRequest) -> None:
+    await create_post(
+        author_id=user_id.root,
+        content=request_body.content.root,
+        visibility=request_body.visibility,
+        hashtags=[h.root for h in request_body.hashtags],
+    )
+
+
+@router.patch("/{post_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def patch_post(post_id: ULID, user_id: RequiredUserID, request_body: UpdatePostRequest) -> None:
+    validated_update_request = request_body.model_dump(mode="json", exclude_unset=True)
+    await edit_post(
+        post_id=str(post_id),
+        author_id=user_id.root,
+        validated_update_request=validated_update_request,
+    )
+
+
+@router.delete("/{post_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_post_route(post_id: ULID, user_id: RequiredUserID) -> None:
+    await delete_post(
+        post_id=str(post_id),
+        author_id=user_id.root,
+    )
+
+
+@router.put("/{post_id}/like", status_code=status.HTTP_204_NO_CONTENT)
+async def put_post_like(post_id: ULID, user_id: RequiredUserID) -> None:
+    await like_post(post_id=str(post_id), user_id=user_id.root)
+
+
+@router.delete("/{post_id}/like", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_post_like(post_id: ULID, user_id: RequiredUserID) -> None:
+    await unlike_post(post_id=str(post_id), user_id=user_id.root)
+
+
+@router.post("/{post_id}/report", status_code=status.HTTP_204_NO_CONTENT)
+async def post_post_report(
+    post_id: ULID,
+    user_id: RequiredUserID,
+    report_request: PostReportRequest,
+) -> None:
+    await add_post_report(
+        reporter_id=user_id.root,
+        post_id=str(post_id),
+        category=report_request.category,
+        reason=report_request.reason,
+    )
+
+
+@router.delete("/{post_id}/report", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_post_report(
+    post_id: ULID,
+    user_id: RequiredUserID,
+) -> None:
+    await remove_post_report(
+        reporter_id=user_id.root,
+        post_id=str(post_id),
+    )

core_framework/api/posts/authenticated/schemas.py

@@ -0,0 +1,37 @@
+from typing import Annotated
+
+from pydantic import BaseModel, Field, field_validator
+
+from core_framework.api.posts.schemas import MAX_HASHTAGS, Hashtag, PostContent
+from core_framework.api.schemas import BasePatchRequest
+from core_framework.domains.moderation import ReportCategory
+from core_framework.domains.post import PostVisibility
+
+
+class PostReportRequest(BaseModel):
+    category: ReportCategory
+    reason: Annotated[str, Field(default="", max_length=250)]
+
+
+class CreatePostRequest(BaseModel):
+    content: PostContent
+    visibility: PostVisibility = PostVisibility.PUBLIC
+    hashtags: list[Hashtag] = Field(default_factory=list, max_length=MAX_HASHTAGS)
+
+    @field_validator("hashtags", mode="after")
+    @classmethod
+    def deduplicate_hashtags(cls, v: list[Hashtag]) -> list[Hashtag]:
+        return list({h.root: h for h in v}.values())
+
+
+class UpdatePostRequest(BasePatchRequest):
+    content: PostContent | None = None
+    visibility: PostVisibility | None = None
+    hashtags: list[Hashtag] | None = None
+
+    @field_validator("hashtags", mode="after")
+    @classmethod
+    def deduplicate_hashtags(cls, v: list[Hashtag] | None) -> list[Hashtag] | None:
+        if v is None:
+            return None
+        return list({h.root: h for h in v}.values())

core_framework/api/posts/public/router.py

@@ -0,0 +1,100 @@
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from ulid import ULID
+
+from core_framework.api.dependencies import OptionalUserID
+from core_framework.api.posts.public.schemas import PostResponse
+from core_framework.api.posts.schemas import validate_hashtag
+from core_framework.api.users.shared.schemas import validate_user_id
+from core_framework.application.posts.public_service import (
+    retrieve_post_by_id,
+    retrieve_posts,
+    retrieve_posts_by_hashtag,
+    retrieve_posts_by_user_id,
+)
+from core_framework.core.pagination import (
+    PaginationCursorType,
+    PaginationResponse,
+    TokenCursorQueryParams,
+    paginate_cursor,
+)
+
+router = APIRouter(
+    prefix="/posts",
+    tags=["posts - public"],
+)
+
+
+@router.get("", response_model=PaginationResponse[PostResponse])
+async def get_posts(
+    request: Request,
+    viewer_id: OptionalUserID,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+) -> Any:
+    posts = await retrieve_posts(
+        viewer_id=viewer_id.root if viewer_id else None,
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+    )
+    return paginate_cursor(
+        request=request,
+        items=posts,
+        limit=pagination_params.limit,
+        cursor_field=PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.get("/users/{user_id}", response_model=PaginationResponse[PostResponse])
+async def get_posts_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)
+    posts = await retrieve_posts_by_user_id(
+        user_id=validated_user_id.root,
+        viewer_id=viewer_id.root if viewer_id else None,
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+    )
+    return paginate_cursor(
+        request=request,
+        items=posts,
+        limit=pagination_params.limit,
+        cursor_field=PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.get("/hashtags/{hashtag}", response_model=PaginationResponse[PostResponse])
+async def get_posts_by_hashtag(
+    hashtag: str,
+    request: Request,
+    viewer_id: OptionalUserID,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+) -> Any:
+    validated_hashtag = validate_hashtag(hashtag=hashtag)
+    posts = await retrieve_posts_by_hashtag(
+        hashtag=validated_hashtag.root,
+        viewer_id=viewer_id.root if viewer_id else None,
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+    )
+    return paginate_cursor(
+        request=request,
+        items=posts,
+        limit=pagination_params.limit,
+        cursor_field=PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.get("/{post_id}", response_model=PostResponse)
+async def get_post(post_id: ULID, viewer_id: OptionalUserID) -> Any:
+    post = await retrieve_post_by_id(post_id=str(post_id), viewer_id=viewer_id.root if viewer_id else None)
+    if post is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Post not found")
+    return post

core_framework/api/posts/public/schemas.py

@@ -0,0 +1,39 @@
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+from ulid import ULID
+
+from core_framework.api.posts.schemas import Hashtag, PostContent
+from core_framework.api.users.shared.schemas import UserReference
+from core_framework.domains.post import PostVisibility
+
+
+class PostStatsResponse(BaseModel):
+    like_count: Annotated[int, Field(ge=0)] = 0
+    comment_count: Annotated[int, Field(ge=0)] = 0
+    view_count: Annotated[int, Field(ge=0)] = 0
+
+
+class PostViewerContext(BaseModel):
+    is_liked: bool
+    is_reported: bool
+
+
+class AuthorContext(BaseModel):
+    can_edit: bool
+    can_delete: bool
+
+
+class PostResponse(BaseModel):
+    id: ULID
+    author: UserReference
+    content: PostContent
+    hashtags: list[Hashtag]
+    visibility: PostVisibility
+    stats: PostStatsResponse
+    engagement_allowed: bool
+    edited_at: datetime | None
+    created_at: datetime
+    viewer_context: PostViewerContext | None
+    author_context: AuthorContext | None

core_framework/api/posts/router.py

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

core_framework/api/posts/schemas.py

@@ -0,0 +1,39 @@
+from typing import Annotated
+
+from fastapi.exceptions import RequestValidationError
+from pydantic import Field, RootModel, ValidationError, field_validator
+
+MAX_HASHTAGS: int = 10
+MAX_HASHTAG_LENGTH: int = 50
+
+
+class Hashtag(RootModel[str]):
+    root: Annotated[str, Field(max_length=MAX_HASHTAG_LENGTH)]
+
+    @field_validator("root", mode="after")
+    @classmethod
+    def normalize_and_validate(cls, v: str) -> str:
+        s = v.strip().lstrip("#").lower()
+        if not s:
+            raise ValueError("Hashtag must not be blank")
+        if len(s) > MAX_HASHTAG_LENGTH:
+            raise ValueError(f"Hashtag must be at most {MAX_HASHTAG_LENGTH} characters")
+        return s
+
+
+class PostContent(RootModel[str]):
+    root: Annotated[str, Field(min_length=1, max_length=10000)]
+
+    @field_validator("root", mode="after")
+    @classmethod
+    def validate_not_blank(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("Post content must not be blank")
+        return v
+
+
+def validate_hashtag(*, hashtag: str) -> Hashtag:
+    try:
+        return Hashtag(root=hashtag)
+    except ValidationError as e:
+        raise RequestValidationError(e.errors()) from e

core_framework/api/router.py

@@ -0,0 +1,19 @@
+from fastapi import APIRouter
+
+from core_framework.api.admin.router import router as admin_router
+from core_framework.api.auth.router import router as auth_router
+from core_framework.api.comments.router import router as comments_router
+from core_framework.api.events.router import router as events_router
+from core_framework.api.posts.router import router as posts_router
+from core_framework.api.system.router import router as system_router
+from core_framework.api.users.router import router as users_router
+
+router = APIRouter()
+
+router.include_router(admin_router)
+router.include_router(auth_router)
+router.include_router(comments_router)
+router.include_router(events_router)
+router.include_router(posts_router)
+router.include_router(system_router)
+router.include_router(users_router)

core_framework/api/schemas.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel, model_validator
+
+
+class BasePatchRequest(BaseModel):
+    @model_validator(mode="after")
+    def validate_non_empty_patch(self) -> BasePatchRequest:
+        if not self.model_fields_set:
+            raise ValueError("At least one field must be provided for update")
+        return self

core_framework/api/system/router.py

@@ -0,0 +1,108 @@
+from asyncio import TaskGroup
+from typing import Final
+
+from fastapi import APIRouter, Request, Response, status
+
+from core_framework.core.runtime import CoreRuntime
+
+router = APIRouter(
+    tags=["system"],
+)
+
+OK_STATUS: Final[str] = "OK"
+ERROR_STATUS: Final[str] = "ERROR"
+
+
+def _get_runtime(request: Request) -> CoreRuntime:
+    runtime = getattr(request.app.state, "core_runtime", None)
+    if runtime is not None:
+        return runtime
+
+    msg = "Core runtime is not configured on app.state. Build the app via init_app() or assign app.state.core_runtime during bootstrap."
+    raise RuntimeError(msg)
+
+
+async def _probe_write_postgres(runtime: CoreRuntime) -> str:
+    try:
+        async with runtime.write_postgres.get_connection() as connection:
+            await connection.fetchval("select 1")
+    except Exception:
+        return ERROR_STATUS
+    return OK_STATUS
+
+
+async def _probe_read_postgres(runtime: CoreRuntime) -> str:
+    try:
+        async with runtime.read_postgres.get_connection() as connection:
+            await connection.fetchval("select 1")
+    except Exception:
+        return ERROR_STATUS
+    return OK_STATUS
+
+
+async def _probe_redis_cache(runtime: CoreRuntime) -> str:
+    try:
+        await runtime.redis_cache.ping()
+    except Exception:
+        return ERROR_STATUS
+    return OK_STATUS
+
+
+async def _probe_redis_queue(runtime: CoreRuntime) -> str:
+    try:
+        await runtime.redis_queue.redis_queue.version()
+    except Exception:
+        return ERROR_STATUS
+    return OK_STATUS
+
+
+async def _probe_http_client(runtime: CoreRuntime) -> str:
+    try:
+        await runtime.general_http_client.client.get("https://www.google.com/generate_204")
+    except Exception:
+        return ERROR_STATUS
+    return OK_STATUS
+
+
+@router.get("/health")
+async def health_check() -> dict[str, str]:
+    return {"status": OK_STATUS}
+
+
+@router.get("/readiness")
+async def readiness_check(request: Request, response: Response) -> dict[str, str]:
+    runtime = _get_runtime(request)
+
+    async with TaskGroup() as tg:
+        write_task = tg.create_task(_probe_write_postgres(runtime))
+        read_task = tg.create_task(_probe_read_postgres(runtime))
+        cache_task = tg.create_task(_probe_redis_cache(runtime))
+        queue_task = tg.create_task(_probe_redis_queue(runtime))
+        http_task = tg.create_task(_probe_http_client(runtime))
+
+    write_postgres_status = write_task.result()
+    read_postgres_status = read_task.result()
+    redis_cache_status = cache_task.result()
+    redis_queue_status = queue_task.result()
+    http_client_status = http_task.result()
+
+    service_statuses = (
+        write_postgres_status,
+        read_postgres_status,
+        redis_cache_status,
+        redis_queue_status,
+        http_client_status,
+    )
+    app_status = ERROR_STATUS if any(s == ERROR_STATUS for s in service_statuses) else OK_STATUS
+
+    if app_status == ERROR_STATUS:
+        response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
+
+    return {
+        "app_status": app_status,
+        "write_postgres_status": write_postgres_status,
+        "read_postgres_status": read_postgres_status,
+        "redis_cache_status": redis_cache_status,
+        "redis_queue_status": redis_queue_status,
+        "http_client_status": http_client_status,
+    }