core-framework 0.3.0__py3-none-any.whl

core_framework/domains/moderation/service.py

@@ -0,0 +1,334 @@
+import asyncio
+from collections import defaultdict
+from datetime import datetime, timedelta, timezone
+from typing import Any, Final
+
+from core_framework.domains.moderation.enums import (
+    AppealDecision,
+    ModerationActionType,
+    ReportCategory,
+    RestrictionCategory,
+)
+from core_framework.domains.moderation.exceptions import SelfReportException
+from core_framework.domains.moderation.models import (
+    Appeal,
+    InternalNote,
+    ModerationAction,
+    Report,
+    RestrictionHistory,
+    UserModeration,
+    UserRestriction,
+)
+from core_framework.domains.moderation.repository import ModerationRepository
+
+
+class ModerationService:
+    DEFAULT_BAN_EXPIRATION_DAYS: Final[int] = 4000
+    DEFAULT_MUTE_EXPIRATION_DAYS: Final[int] = 7
+    USER_DETAIL_NOTES_LIMIT: Final[int] = 5
+
+    def __init__(self, repository: ModerationRepository):
+        self.repository = repository
+
+    # Restrictions
+    async def ban_user(self, *, actor_id: str, user_id: str, reason: str, category: RestrictionCategory) -> None:
+        expires_at = datetime.now(timezone.utc) + timedelta(days=self.DEFAULT_BAN_EXPIRATION_DAYS)
+        await self.repository.upsert_ban_state(
+            actor_id=actor_id,
+            user_id=user_id,
+            reason=reason,
+            category=category,
+            expires_at=expires_at,
+        )
+
+    async def mute_user(self, *, actor_id: str, user_id: str, reason: str, category: RestrictionCategory) -> None:
+        expires_at = datetime.now(timezone.utc) + timedelta(days=self.DEFAULT_MUTE_EXPIRATION_DAYS)
+        await self.repository.upsert_mute_state(
+            actor_id=actor_id,
+            user_id=user_id,
+            reason=reason,
+            category=category,
+            expires_at=expires_at,
+        )
+
+    async def warn_user(self, *, actor_id: str, user_id: str, reason: str, category: RestrictionCategory) -> None:
+        await self.repository.upsert_warn_state(actor_id=actor_id, user_id=user_id, reason=reason, category=category)
+
+    async def clear_user_restriction(self, *, actor_id: str, user_id: str) -> None:
+        await self.repository.delete_user_restriction(actor_id=actor_id, user_id=user_id)
+
+    async def retrieve_expired_mute_user_ids(self) -> list[str]:
+        return await self.repository.select_expired_mute_user_ids()
+
+    # Reports
+    async def add_user_report(self, *, reporter_id: str, target_id: str, category: ReportCategory, reason: str) -> None:
+        if reporter_id == target_id:
+            raise SelfReportException()
+
+        await self.repository.insert_user_report(
+            reporter_id=reporter_id,
+            target_id=target_id,
+            category=category,
+            reason=reason,
+        )
+
+    async def retrieve_user_reports(
+        self,
+        *,
+        reporter_id: str | None,
+        target_id: str | None,
+        cursor: datetime,
+        limit: int,
+    ) -> list[Report]:
+        return await self.repository.select_user_reports(
+            reporter_id=reporter_id,
+            target_id=target_id,
+            cursor=cursor,
+            limit=limit,
+        )
+
+    async def remove_user_report(self, *, report_id: int) -> None:
+        await self.repository.delete_user_report_by_id(report_id=report_id)
+
+    async def remove_user_report_by_reporter(self, *, reporter_id: str, target_id: str) -> None:
+        await self.repository.delete_user_report_by_reporter_and_target(
+            reporter_id=reporter_id,
+            target_id=target_id,
+        )
+
+    async def add_post_report(
+        self,
+        *,
+        reporter_id: str,
+        target_id: str,
+        category: ReportCategory,
+        reason: str,
+    ) -> None:
+        await self.repository.insert_post_report(
+            reporter_id=reporter_id,
+            target_id=target_id,
+            category=category,
+            reason=reason,
+        )
+
+    async def retrieve_post_reports(
+        self,
+        *,
+        reporter_id: str | None,
+        target_id: str | None,
+        cursor: datetime,
+        limit: int,
+    ) -> list[Report]:
+        return await self.repository.select_post_reports(
+            reporter_id=reporter_id,
+            target_id=target_id,
+            cursor=cursor,
+            limit=limit,
+        )
+
+    async def retrieve_comment_reports(
+        self,
+        *,
+        reporter_id: str | None,
+        target_id: str | None,
+        cursor: datetime,
+        limit: int,
+    ) -> list[Report]:
+        return await self.repository.select_comment_reports(
+            reporter_id=reporter_id,
+            target_id=target_id,
+            cursor=cursor,
+            limit=limit,
+        )
+
+    async def retrieve_post_report_count(self, *, post_id: str) -> int:
+        return await self.repository.select_post_report_count(post_id=post_id)
+
+    async def retrieve_comment_report_count(self, *, comment_id: str) -> int:
+        return await self.repository.select_comment_report_count(comment_id=comment_id)
+
+    async def remove_post_report(self, *, report_id: int) -> None:
+        await self.repository.delete_post_report_by_id(report_id=report_id)
+
+    async def remove_comment_report(self, *, report_id: int) -> None:
+        await self.repository.delete_comment_report_by_id(report_id=report_id)
+
+    async def remove_post_report_by_reporter(self, *, reporter_id: str, target_id: str) -> None:
+        await self.repository.delete_post_report_by_reporter_and_target(
+            reporter_id=reporter_id,
+            target_id=target_id,
+        )
+
+    async def remove_post_reports_by_target_id(self, *, target_id: str) -> None:
+        await self.repository.delete_post_reports_by_target_id(target_id=target_id)
+
+    async def retrieve_post_ids_reported_by_user(self, *, reporter_id: str, post_ids: set[str]) -> frozenset[str]:
+        ids = await self.repository.select_post_ids_reported_by_user(reporter_id=reporter_id, post_ids=post_ids)
+        return frozenset(ids)
+
+    async def retrieve_comment_ids_reported_by_user(self, *, reporter_id: str, comment_ids: set[str]) -> frozenset[str]:
+        ids = await self.repository.select_comment_ids_reported_by_user(
+            reporter_id=reporter_id, comment_ids=comment_ids
+        )
+        return frozenset(ids)
+
+    async def add_comment_report(
+        self,
+        *,
+        reporter_id: str,
+        target_id: str,
+        category: ReportCategory,
+        reason: str,
+    ) -> None:
+        await self.repository.insert_comment_report(
+            reporter_id=reporter_id,
+            target_id=target_id,
+            category=category,
+            reason=reason,
+        )
+
+    async def remove_comment_report_by_reporter(self, *, reporter_id: str, target_id: str) -> None:
+        await self.repository.delete_comment_report_by_reporter_and_target(
+            reporter_id=reporter_id,
+            target_id=target_id,
+        )
+
+    async def remove_comment_reports_by_target_ids(self, *, target_ids: set[str]) -> None:
+        await self.repository.delete_comment_reports_by_target_ids(target_ids=target_ids)
+
+    # Appeals
+    async def add_appeal(self, *, user_id: str, justification: str) -> None:
+        await self.repository.insert_appeal(user_id=user_id, justification=justification)
+
+    async def decide_appeal(self, *, actor_id: str, appeal_id: int, decision: AppealDecision, reason: str) -> Appeal:
+        await self.repository.update_appeal_decision(
+            actor_id=actor_id,
+            appeal_id=appeal_id,
+            decision=decision,
+            reason=reason,
+        )
+        return await self.repository.select_appeal_strong(appeal_id=appeal_id)
+
+    async def retrieve_appeals(self, *, status: AppealDecision | None, cursor: datetime, limit: int) -> list[Appeal]:
+        return await self.repository.select_appeals(status=status, cursor=cursor, limit=limit)
+
+    async def retrieve_appeals_of_user(
+        self,
+        *,
+        user_id: str,
+        status: AppealDecision | None,
+        cursor: datetime,
+        limit: int,
+    ) -> list[Appeal]:
+        return await self.repository.select_appeals(user_id=user_id, status=status, cursor=cursor, limit=limit)
+
+    async def remove_current_appeal_of_user(self, *, user_id: str) -> None:
+        await self.repository.delete_current_appeal_of_user(user_id=user_id)
+
+    # Internal Notes
+    async def add_internal_note(
+        self,
+        *,
+        actor_id: str,
+        target_user_id: str,
+        content: str,
+    ) -> InternalNote:
+        return await self.repository.insert_internal_note(
+            actor_id=actor_id,
+            target_user_id=target_user_id,
+            content=content,
+        )
+
+    async def retrieve_internal_note_strong(self, *, note_id: int, target_user_id: str) -> InternalNote | None:
+        return await self.repository.select_internal_note_by_id_strong(
+            note_id=note_id,
+            target_user_id=target_user_id,
+        )
+
+    async def retrieve_internal_notes(self, *, target_user_id: str) -> list[InternalNote]:
+        return await self.repository.select_internal_notes(target_user_id=target_user_id)
+
+    async def retrieve_internal_notes_paginated(
+        self,
+        *,
+        target_user_id: str,
+        cursor: datetime,
+        limit: int,
+    ) -> list[InternalNote]:
+        return await self.repository.select_internal_notes_paginated(
+            target_user_id=target_user_id,
+            cursor=cursor,
+            limit=limit,
+        )
+
+    async def remove_internal_note(self, *, note_id: int, target_user_id: str) -> None:
+        await self.repository.delete_internal_note(note_id=note_id, target_user_id=target_user_id)
+
+    # User Moderation
+    async def retrieve_user_restriction(self, *, user_id: str) -> UserRestriction:
+        mapping = await self.repository.select_user_restriction_mapping(user_ids={user_id})
+        return mapping.get(user_id, UserRestriction.DEFAULT)
+
+    async def retrieve_user_restriction_strong(self, *, user_id: str) -> UserRestriction:
+        mapping = await self.repository.select_user_restriction_mapping_strong(user_ids={user_id})
+        return mapping.get(user_id, UserRestriction.DEFAULT)
+
+    async def retrieve_user_moderation_mapping(self, *, user_ids: set[str]) -> defaultdict[str, UserModeration]:
+        user_restriction_mapping = await self.repository.select_user_restriction_mapping(user_ids=user_ids)
+        result: defaultdict[str, UserModeration] = defaultdict(lambda: UserModeration.DEFAULT)
+        for user_id, restriction in user_restriction_mapping.items():
+            result[user_id] = UserModeration(restriction=restriction, notes=())
+        return result
+
+    async def retrieve_user_moderation_for_detail(self, *, user_id: str) -> UserModeration:
+        far_future = datetime(3000, 1, 1, tzinfo=timezone.utc)
+        async with asyncio.TaskGroup() as tg:
+            restriction_task = tg.create_task(self.repository.select_user_restriction_mapping(user_ids={user_id}))
+            notes_task = tg.create_task(
+                self.repository.select_internal_notes_paginated(
+                    target_user_id=user_id,
+                    cursor=far_future,
+                    limit=self.USER_DETAIL_NOTES_LIMIT,
+                )
+            )
+        restriction_mapping = restriction_task.result()
+        notes = notes_task.result()
+        restriction = restriction_mapping.get(user_id, UserRestriction.DEFAULT)
+        return UserModeration(restriction=restriction, notes=tuple(notes))
+
+    async def remove_user(self, *, user_id: str) -> None:
+        await self.repository.delete_user(user_id=user_id)
+
+    async def retrieve_restriction_history(
+        self,
+        *,
+        user_id: str,
+        cursor: datetime,
+        limit: int,
+    ) -> list[RestrictionHistory]:
+        return await self.repository.select_restriction_history(user_id=user_id, cursor=cursor, limit=limit)
+
+    # Moderation Actions
+    async def retrieve_moderation_actions_strong(
+        self, *, actor_id: str, cursor: datetime, limit: int
+    ) -> list[ModerationAction]:
+        return await self.repository.select_moderation_actions_strong(
+            actor_id=actor_id,
+            cursor=cursor,
+            limit=limit,
+        )
+
+    async def record_moderation_action(
+        self,
+        *,
+        actor_id: str,
+        action_type: ModerationActionType,
+        target_user_id: str | None = None,
+        action_metadata: dict[str, Any] | None = None,
+    ) -> None:
+        await self.repository.insert_moderation_action(
+            actor_id=actor_id,
+            action_type=action_type,
+            target_user_id=target_user_id,
+            action_metadata=action_metadata,
+        )

core_framework/domains/post/README.md

@@ -0,0 +1,182 @@
+# Post Domain
+
+## Scope
+
+Owns post content lifecycle, audience visibility rules, media attachments, post likes, hashtags, mentions, and engagement analytics. Provides the authoritative source for post existence and current content state.
+
+## Owns
+
+### Post Content
+
+- Post creation, retrieval, editing, and deletion state
+- Author-owned content fields (body and optional metadata)
+- Post timestamps (created/updated/edited)
+- Edit limit (max 5 edits) and `edited_count` for author capability display; retrieval responses include `author_context` (can_edit, can_delete) when viewer is author—see `docs/flows/posts/author_context.md`
+
+### Post Visibility State
+
+- Audience visibility state of a post (public, followers, private, unlisted)
+- Soft-delete state for post lifecycle management
+- Readability/editability rules based on state
+
+### Media Attachments
+
+- Post-linked media metadata for images and videos
+- Attachment ordering and per-post attachment limits
+- Media state lifecycle (processing, ready, failed, removed)
+
+### Post Likes
+
+- User-to-post like relationships
+- Idempotent like/unlike behavior as relationship state
+- Aggregate like counts derived from post_like rows
+
+### Hashtags and Discovery
+
+- Hashtag extraction and canonicalization from post content
+- Hashtag-to-post indexing for discovery and retrieval
+- Search/discovery query support over post content and hashtags
+
+### Mentions
+
+- Mention extraction from post content (e.g., @username)
+- Mention-to-post mapping for retrieval and mention inbox use cases
+- Mention events for downstream notification workflows
+
+### Engagement Analytics
+
+- Post engagement counters and derived analytics (views, likes, comments, reports)
+- View tracking records and aggregation strategy for post metrics
+- Retrieval of post-level metrics for authors and admins
+
+## Does Not Own
+
+- User identity, authentication, or profile data
+- User relationship graph (follows/friends/blocks)
+- Post reports (owned by moderation domain; moderation is the policy enforcement system)
+- Enforcement decisions (ban/mute/warn) and appeal lifecycle - owned by moderation domain
+- Notification delivery mechanisms (domain may emit mention events, but delivery is external)
+- Feed ranking, recommendation, or timeline assembly in API layer
+
+## User removal and redacted authors (design)
+
+When an account is removed, **authored posts are not hard-deleted**: **retain** `posts.id`, **redact** content to an agreed placeholder, and set **`author_id`** to the same **sentinel** used for redacted comments (see `docs/flows/users/user_removal.md`). **Post reports and post likes** are kept; **`reporter_id` / `liker_id` are not rewritten** to the sentinel. Public post **GET** responses set **`engagement_allowed`** to `false` for redacted-author posts so clients can hide like/report actions; **write** endpoints do not enforce that flag.
+
+## Hard delete post (design)
+
+**Hard delete** is a separate operation from user removal. For `DELETE /admin/posts/{post_id}` the **target is physical removal** of the `posts` row and **all post-domain rows** that reference that `post_id` (e.g. `post_likes`, `post_stats`, `post_attachments`, `post_hashtags`, `post_mentions`, `post_views`), plus **cross-domain cleanup**: every comment on that post (full subtree), their likes/stats/attachments/dirty markers, and **moderation** `post_reports` and the relevant `comment_reports`.
+
+Authoritative checklist and HTTP flow notes: `docs/flows/posts/admin_posts.md` (Hard delete post). Keep repository and application delete paths aligned with that contract whenever hard-delete behavior changes.
+
+## Invariants
+
+- A post has exactly one author_id
+- A post in deleted state is not editable
+- Attachments are immutable once published on an active post
+- Attachment type must be image or video
+- A user can like a given post at most once
+- Post visibility must be one of (public, followers, private, unlisted)
+- A user can be mentioned at most once per post
+- Engagement counters are non-negative
+- Domain stores only IDs for external entities (no cross-domain foreign keys)
+- Post reads/writes only touch the post schema
+
+## Feed Visibility Filtering Rules
+
+- Post domain may keep local lookup mirrors for cross-domain visibility checks:
+  - `user_restrictions_lookup` (restricted authors: muted/banned)
+  - `user_blocks_lookup` (directed block edge: blocker -> blocked)
+- For viewer `A` and post author `B`, hide the post when either:
+  - `A` has blocked `B` (exists in `user_blocks_lookup`)
+  - `B` is restricted as muted/banned (exists in `user_restrictions_lookup`)
+- Special rule: if viewer `A` is muted, `A` can still see their own posts.
+- These lookup tables are mirrors for read-time filtering only; source-of-truth remains outside post domain.
+
+## Lookup Sync Contract
+
+- Source-of-truth for restriction state is the moderation domain.
+- Source-of-truth for user-to-user blocks is the user domain.
+- Post domain mirrors (`user_restrictions_lookup`, `user_blocks_lookup`) exist only to support read-time filtering.
+- Sync operations should be idempotent and safe to run repeatedly.
+- No-op moderation operations (for example, banning an already banned user or clearing an already active user)
+  should still reconcile post-domain lookup rows to heal prior cross-domain partial failures.
+
+## Persistence Model
+
+### Tables
+
+#### posts
+
+- Canonical post record (author_id, content, visibility/state, timestamps)
+- Supports soft deletion and edit tracking
+- Indexed for recent-first listing and author timeline queries
+
+#### post_likes
+
+- Tracks user likes on posts as a relationship table
+- Stores liker_id, post_id, and created_at
+- One row per (liker_id, post_id) pair to enforce idempotent likes
+
+#### post_stats
+
+- Denormalized engagement counters per post
+- Stores post_id, like_count, comment_count, view_count, report_count, view_count_aggregated_at, timestamps
+- like_count, comment_count, report_count from post_likes, comments, moderation domain post_reports; view_count from incremental aggregation of post_views
+- One row per post; created when post is created
+- Aggregated periodically by background worker (every 15 min); see `docs/flows/posts/post_stats_aggregation.md`
+
+#### post_attachments
+
+- Tracks media attached to posts (image/video)
+- Stores post_id, media_id/storage_key, media_type, order_index, and processing status
+- Supports deterministic ordering for multi-attachment posts
+
+#### post_hashtags
+
+- Tracks normalized hashtag labels attached to posts
+- Supports hashtag-based retrieval and discovery
+- One row per (post_id, hashtag) pair
+
+#### post_mentions
+
+- Tracks mentioned users per post
+- Stores post_id, mentioned_user_id, and mention metadata
+- One row per (post_id, mentioned_user_id) pair
+
+#### post_views
+
+- Append-only view events for analytics
+- Stores post_id, token (deduplication), created_at, and request_context (JSONB)
+- request_context holds optional fields: viewer_id, country_code, client_type, browser_name, os_name, referrer
+- Unique (post_id, token) prevents duplicate views per token
+- Used to derive view_count via incremental aggregation (every 15 min). For each affected post, a task also aggregates like/comment counts (from post_likes, comments) and report counts (from moderation domain post_reports)
+
+#### user_restrictions_lookup
+
+- Read-time mirror for restricted users (muted/banned). Source-of-truth: moderation domain.
+- Stores user_id, restriction_type (muted, banned)
+- Used in feed queries to hide posts from restricted authors. Sync operations reconcile from moderation domain; see Lookup Sync Contract above.
+
+#### user_blocks_lookup
+
+- Read-time mirror for user-to-user blocks. Source-of-truth: user domain.
+- Stores blocker_id, blocked_id (directed edge: blocker has blocked blocked)
+- Used in feed queries to hide posts from authors the viewer has blocked. Sync operations reconcile from user domain; see Lookup Sync Contract above.
+
+### Enums
+
+#### post_status
+
+- Lifecycle state of a post (active, deleted)
+
+#### post_visibility
+
+- Post visibility state (public, followers, private, unlisted)
+
+#### post_media_type
+
+- Attachment media type (image, video)
+
+#### post_attachment_status
+
+- Attachment processing lifecycle (processing, ready, failed, removed)

core_framework/domains/post/__init__.py

@@ -0,0 +1,22 @@
+from core_framework.domains.post.enums import AttachmentType, PostStatus, PostVisibility
+from core_framework.domains.post.exceptions import (
+    BasePostException,
+    EditLimitReachedException,
+    PostNotFoundException,
+    PostUpdateNotFoundException,
+)
+from core_framework.domains.post.models import Post, PostPreview, PostStats, PostWithMetadata
+
+__all__ = [
+    "AttachmentType",
+    "PostStatus",
+    "PostVisibility",
+    "BasePostException",
+    "EditLimitReachedException",
+    "Post",
+    "PostNotFoundException",
+    "PostPreview",
+    "PostStats",
+    "PostUpdateNotFoundException",
+    "PostWithMetadata",
+]

core_framework/domains/post/constants.py

@@ -0,0 +1,3 @@
+from typing import Final
+
+REDACTED_CONTENT_PLACEHOLDER: Final[str] = "<deleted>"

core_framework/domains/post/dependencies.py

@@ -0,0 +1,29 @@
+from core_framework.core.runtime import CoreRuntime, unconfigured_dependency
+from core_framework.domains.post.repository import PostRepository
+from core_framework.domains.post.service import PostService
+
+
+def build_post_repository(runtime: CoreRuntime) -> PostRepository:
+    return PostRepository(runtime.write_postgres, runtime.read_postgres, runtime.write_postgres)
+
+
+def build_post_service(runtime: CoreRuntime) -> PostService:
+    return PostService(build_post_repository(runtime))
+
+
+def configure_post_dependencies(runtime: CoreRuntime) -> None:
+    global post_repository, post_service
+    post_repository = build_post_repository(runtime)
+    post_service = build_post_service(runtime)
+
+
+post_repository = unconfigured_dependency("PostRepository")
+post_service = unconfigured_dependency("PostService")
+
+__all__ = [
+    "build_post_repository",
+    "build_post_service",
+    "configure_post_dependencies",
+    "post_repository",
+    "post_service",
+]

core_framework/domains/post/enums.py

@@ -0,0 +1,18 @@
+from enum import StrEnum
+
+
+class PostVisibility(StrEnum):
+    PUBLIC = "public"
+    FOLLOWERS = "followers"
+    PRIVATE = "private"
+    UNLISTED = "unlisted"
+
+
+class AttachmentType(StrEnum):
+    IMAGE = "image"
+    VIDEO = "video"
+
+
+class PostStatus(StrEnum):
+    ACTIVE = "active"
+    DELETED = "deleted"

core_framework/domains/post/exceptions.py

@@ -0,0 +1,21 @@
+class BasePostException(Exception):
+    message: str
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(self.message)
+
+
+class PostUpdateNotFoundException(BasePostException):
+    def __init__(self) -> None:
+        super().__init__("Unable to process request")
+
+
+class EditLimitReachedException(BasePostException):
+    def __init__(self) -> None:
+        super().__init__("Edit limit reached. Maximum edits allowed per post.")
+
+
+class PostNotFoundException(BasePostException):
+    def __init__(self) -> None:
+        super().__init__("Post not found")

core_framework/domains/post/models.py

@@ -0,0 +1,53 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import ClassVar
+
+from core_framework.domains.post.enums import PostStatus, PostVisibility
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Post:
+    id: str
+    author_id: str
+    content: str
+    visibility: PostVisibility
+    edited_count: int
+    edited_at: datetime | None
+    created_at: datetime
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PostWithMetadata:
+    id: str
+    author_id: str
+    content: str
+    visibility: PostVisibility
+    status: PostStatus
+    edited_count: int
+    edited_at: datetime | None
+    created_at: datetime
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PostPreview:
+    id: str
+    author_id: str
+    content: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PostStats:
+    like_count: int
+    comment_count: int
+    view_count: int
+    report_count: int
+
+    DEFAULT: ClassVar[PostStats]
+
+
+PostStats.DEFAULT = PostStats(
+    like_count=0,
+    comment_count=0,
+    view_count=0,
+    report_count=0,
+)