core-framework 0.3.0__py3-none-any.whl

core_framework/application/users/authenticated_service.py

@@ -0,0 +1,179 @@
+from asyncio import TaskGroup
+from datetime import datetime
+from typing import Any
+
+import core_framework.core as core_fw
+import core_framework.domains.comment.dependencies as comment_deps
+import core_framework.domains.moderation.dependencies as moderation_deps
+import core_framework.domains.post.dependencies as post_deps
+import core_framework.domains.user.dependencies as user_deps
+from core_framework.application.shared.enums import RedisKeys
+from core_framework.core.cache import invalidate_cache
+from core_framework.domains.moderation import AppealDecision, ReportCategory
+from core_framework.domains.user import BlockedUser, Preferences, Profile
+
+USER_DETAIL_PROFILE_FIELDS = frozenset({"display_name", "avatar_id", "banner_id"})
+
+
+# User Blocks
+async def retrieve_my_blocked_users(*, user_id: str, created_at: datetime, limit: int) -> list[BlockedUser]:
+    return await user_deps.user_service.retrieve_blocked_users(
+        blocker_id=user_id,
+        created_at=created_at,
+        limit=limit,
+    )
+
+
+async def block_user(*, user_id: str, target_user_id: str) -> None:
+    await user_deps.user_service.block_user(user_id=user_id, target_user_id=target_user_id)
+    async with TaskGroup() as tg:
+        tg.create_task(
+            post_deps.post_service.add_user_block_lookup(
+                blocker_id=user_id,
+                blocked_id=target_user_id,
+            )
+        )
+        tg.create_task(
+            comment_deps.comment_service.add_user_block_lookup(
+                blocker_id=user_id,
+                blocked_id=target_user_id,
+            )
+        )
+
+
+async def unblock_user(*, user_id: str, target_user_id: str) -> None:
+    await user_deps.user_service.unblock_user(user_id=user_id, target_user_id=target_user_id)
+    async with TaskGroup() as tg:
+        tg.create_task(
+            post_deps.post_service.remove_user_block_lookup(
+                blocker_id=user_id,
+                blocked_id=target_user_id,
+            )
+        )
+        tg.create_task(
+            comment_deps.comment_service.remove_user_block_lookup(
+                blocker_id=user_id,
+                blocked_id=target_user_id,
+            )
+        )
+
+
+# Preferences
+async def retrieve_my_preferences(*, user_id: str) -> Preferences:
+    return await user_deps.user_service.retrieve_preferences(user_id=user_id)
+
+
+async def change_my_preferences(*, user_id: str, validated_update_request: dict[str, Any]) -> Preferences:
+    await user_deps.user_service.change_preferences(
+        user_id=user_id,
+        validated_update_request=validated_update_request,
+    )
+    return await user_deps.user_service.retrieve_preferences_strong(user_id=user_id)
+
+
+# Profile
+async def retrieve_my_profile(*, user_id: str) -> Profile:
+    return await user_deps.user_service.retrieve_profile(user_id=user_id)
+
+
+async def change_my_profile(*, user_id: str, validated_update_request: dict[str, Any]) -> Profile:
+    await user_deps.user_service.change_profile(
+        actor_id=user_id,
+        user_id=user_id,
+        validated_update_request=validated_update_request,
+    )
+    if USER_DETAIL_PROFILE_FIELDS.intersection(validated_update_request):
+        await invalidate_cache(RedisKeys.USER_DETAIL, user_id=user_id)
+    return await user_deps.user_service.retrieve_profile_strong(user_id=user_id)
+
+
+# Account
+async def retrieve_my_account(*, user_id: str, email: str, email_verified: bool) -> dict[str, Any]:
+    user_identity = await user_deps.user_service.retrieve_user_identity(user_id=user_id)
+    deletion_scheduled_for = await user_deps.user_service.retrieve_user_deletion_scheduled_for(user_id=user_id)
+
+    return {
+        "username": user_identity.username,
+        "email": email,
+        "email_verified": email_verified,
+        "deletion_scheduled_for": deletion_scheduled_for,
+    }
+
+
+async def change_my_account(*, user_id: str, validated_update_request: dict[str, Any]) -> None:
+    await user_deps.user_service.change_account(
+        actor_id=user_id,
+        user_id=user_id,
+        validated_update_request=validated_update_request,
+    )
+    if (new_username := validated_update_request.get("username")) is not None:
+        await core_fw.redis_cache.sadd(RedisKeys.TAKEN_USERNAMES, new_username)
+    await invalidate_cache(RedisKeys.USER_DETAIL, user_id=user_id)
+
+
+async def schedule_account_deletion(*, user_id: str) -> None:
+    await user_deps.user_service.schedule_account_deletion(user_id=user_id)
+
+
+async def cancel_account_deletion(*, user_id: str) -> None:
+    await user_deps.user_service.cancel_account_deletion(user_id=user_id)
+
+
+# Reports
+async def add_user_report(*, reporter_id: str, target_id: str, category: ReportCategory, reason: str) -> None:
+    await moderation_deps.moderation_service.add_user_report(
+        reporter_id=reporter_id,
+        target_id=target_id,
+        category=category,
+        reason=reason,
+    )
+
+
+async def remove_user_report(*, reporter_id: str, target_id: str) -> None:
+    await moderation_deps.moderation_service.remove_user_report_by_reporter(
+        reporter_id=reporter_id,
+        target_id=target_id,
+    )
+
+
+# Appeals
+async def add_appeal(*, user_id: str, justification: str) -> None:
+    await moderation_deps.moderation_service.add_appeal(user_id=user_id, justification=justification)
+
+
+async def retrieve_my_appeals(
+    *,
+    user_id: str,
+    status: AppealDecision | None,
+    cursor: datetime,
+    limit: int,
+) -> list[dict[str, Any]]:
+    raw_appeals = await moderation_deps.moderation_service.retrieve_appeals_of_user(
+        user_id=user_id,
+        status=status,
+        cursor=cursor,
+        limit=limit,
+    )
+    user_ids = {appeal.reviewer_id for appeal in raw_appeals if appeal.reviewer_id is not None}
+    user_identity_mapping = await user_deps.user_service.retrieve_user_identity_mapping(user_ids=user_ids)
+    return [
+        {
+            "justification": appeal.justification,
+            "reviewer": {
+                "user_id": appeal.reviewer_id,
+                "username": user_identity_mapping[appeal.reviewer_id].username,
+                "display_name": user_identity_mapping[appeal.reviewer_id].display_name,
+            }
+            if appeal.reviewer_id is not None
+            else None,
+            "decision_reason": appeal.decision_reason,
+            "status": appeal.status,
+            "created_at": appeal.created_at,
+            "updated_at": appeal.updated_at,
+        }
+        for appeal in raw_appeals
+    ]
+
+
+async def delete_my_current_appeal(*, user_id: str) -> None:
+    await moderation_deps.moderation_service.remove_current_appeal_of_user(user_id=user_id)

core_framework/application/users/public_service.py

@@ -0,0 +1,7 @@
+import core_framework.core as core_fw
+from core_framework.application.shared.enums import RedisKeys
+
+
+async def is_username_available(*, username: str) -> bool:
+    is_taken = await core_fw.redis_cache.sismember(RedisKeys.TAKEN_USERNAMES, username)
+    return not is_taken

core_framework/application/users/scheduled_service.py

@@ -0,0 +1,5 @@
+import core_framework.domains.user.dependencies as user_deps
+
+
+async def retrieve_expired_user_deletions() -> list[str]:
+    return await user_deps.user_service.retrieve_expired_user_deletions()

core_framework/bundled_alembic.py

@@ -0,0 +1,57 @@
+"""Locate Alembic migration trees shipped with the ``core_framework`` package."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import core_framework
+
+
+def bundled_alembic_root() -> Path:
+    """Root directory containing ``extension/``, ``user/``, … (each with ``alembic.ini``).
+
+    Resolves to:
+
+    - ``site-packages/core_framework/alembic`` when installed from a wheel (bundled copy).
+    - The repository ``alembic/`` directory when developing this project from a checkout
+      (no ``core_framework/alembic`` in the working tree).
+    """
+
+    pkg = Path(core_framework.__file__).resolve().parent
+    bundled = pkg / "alembic"
+    if bundled.is_dir():
+        return bundled
+    legacy = pkg.parent / "alembic"
+    if legacy.is_dir():
+        return legacy
+    msg = (
+        f"could not find Alembic trees: expected {bundled} or {legacy}. "
+        "Install core-framework from a wheel or use a full repository checkout."
+    )
+    raise FileNotFoundError(msg)
+
+
+# Order matches production deploy (``.github/workflows/_deploy.yml``).
+ALEMBIC_DOMAINS: tuple[str, ...] = (
+    "extension",
+    "user",
+    "moderation",
+    "post",
+    "comment",
+)
+
+
+def alembic_ini_path(domain: str) -> Path:
+    """Return the path to ``<domain>/alembic.ini`` under :func:`bundled_alembic_root`."""
+
+    p = bundled_alembic_root() / domain / "alembic.ini"
+    if not p.is_file():
+        msg = f"no alembic.ini for domain {domain!r} under {bundled_alembic_root()}"
+        raise FileNotFoundError(msg)
+    return p
+
+
+def iter_alembic_ini_paths() -> tuple[Path, ...]:
+    """``alembic.ini`` paths in deploy order."""
+
+    return tuple(alembic_ini_path(d) for d in ALEMBIC_DOMAINS)

core_framework/core/__init__.py

@@ -0,0 +1,37 @@
+from core_framework.core.exception_handlers import setup_exception_handlers
+from core_framework.core.logging import setup_logging
+from core_framework.core.middleware import setup_middleware
+from core_framework.core.observability import setup_observability
+from core_framework.core.runtime import CoreRuntime, unconfigured_dependency
+from core_framework.core.settings import load_default_settings
+
+settings = load_default_settings()
+write_postgres = unconfigured_dependency("Postgres")
+read_postgres = unconfigured_dependency("Postgres")
+redis_queue = unconfigured_dependency("RedisQueue")
+redis_cache = unconfigured_dependency("RedisCache")
+general_http_client = unconfigured_dependency("HttpClient")
+
+
+def configure_core_runtime(core_runtime: CoreRuntime) -> None:
+    global write_postgres, read_postgres, redis_queue, redis_cache, general_http_client
+    write_postgres = core_runtime.write_postgres
+    read_postgres = core_runtime.read_postgres
+    redis_queue = core_runtime.redis_queue
+    redis_cache = core_runtime.redis_cache
+    general_http_client = core_runtime.general_http_client
+
+
+__all__ = [
+    "write_postgres",
+    "read_postgres",
+    "settings",
+    "redis_queue",
+    "redis_cache",
+    "general_http_client",
+    "configure_core_runtime",
+    "setup_logging",
+    "setup_middleware",
+    "setup_observability",
+    "setup_exception_handlers",
+]

core_framework/core/cache.py

@@ -0,0 +1,234 @@
+import inspect
+import random
+from collections.abc import Awaitable, Callable
+from dataclasses import is_dataclass
+from functools import wraps
+from typing import Any, Final, get_type_hints
+
+import orjson
+from loguru import logger
+from mashumaro.codecs.orjson import ORJSONDecoder
+
+from core_framework.core.redis import RedisCache
+
+CACHE_SCAN_COUNT: Final[int] = 2000
+CACHE_BATCH_SIZE: Final[int] = 2000
+DEFAULT_CACHE_TTL: Final[int] = 60 * 60 * 24 * 30  # 30 days
+_configured_redis_cache: RedisCache | None = None
+
+ALLOWED_CACHE_TYPES: Final[tuple[type, ...]] = (str, int, float, bool, type(None))
+
+# orjson only supports 64-bit integers
+_MIN_INT64: Final[int] = -(2**63)
+_MAX_INT64: Final[int] = 2**63 - 1
+
+type CacheValue = str | int | float | bool | None
+
+
+def configure_cache(*, redis_cache: RedisCache) -> None:
+    global _configured_redis_cache
+    _configured_redis_cache = redis_cache
+
+
+def _get_redis_cache() -> RedisCache:
+    if _configured_redis_cache is not None:
+        return _configured_redis_cache
+
+    msg = "Cache is not configured. Call configure_cache() during application bootstrap."
+    raise RuntimeError(msg)
+
+
+def _ensure_cacheable(value: object) -> None:
+    if not isinstance(value, ALLOWED_CACHE_TYPES):
+        raise ValueError(f"Value is not a cache primitive: {value}")
+
+    # Validate integer range for orjson compatibility
+    if isinstance(value, int):
+        if value < _MIN_INT64 or value > _MAX_INT64:
+            raise ValueError(f"Integer {value} exceeds 64-bit range ({_MIN_INT64} to {_MAX_INT64})")
+
+
+def _stable_serialize(value: CacheValue) -> bytes:
+    _ensure_cacheable(value)
+    return orjson.dumps(value)
+
+
+def _generate_cache_key(resource_name: str, **kwargs: CacheValue) -> bytes:
+    if not resource_name:
+        raise ValueError("resource_name cannot be empty")
+
+    segments: list[bytes] = [resource_name.encode()]
+
+    for k, v in sorted(kwargs.items()):
+        segments.append(k.encode() + b"=" + _stable_serialize(v))
+
+    return b":".join(segments)
+
+
+def _generate_cache_pattern(resource_name: str, **kwargs: CacheValue) -> bytes:
+    if not resource_name:
+        raise ValueError("resource_name cannot be empty")
+
+    segments: list[bytes] = [resource_name.encode()]
+
+    for k, v in sorted(kwargs.items()):
+        if v is None:
+            segments.append(k.encode() + b"=*")
+        else:
+            segments.append(k.encode() + b"=" + _stable_serialize(v))
+
+    return b":*".join(segments) + b"*"
+
+
+async def _invalidate_cache_by_pattern(pattern: bytes) -> None:
+    to_delete: list[bytes] = []
+    redis_cache = _get_redis_cache()
+
+    async for key in redis_cache.scan_iter(
+        match=pattern,
+        count=CACHE_SCAN_COUNT,
+    ):
+        to_delete.append(key)
+
+        if len(to_delete) >= CACHE_BATCH_SIZE:
+            await redis_cache.unlink(*to_delete)
+            to_delete.clear()
+
+    if to_delete:
+        await redis_cache.unlink(*to_delete)
+
+
+async def invalidate_cache(resource_name: str, **kwargs: CacheValue) -> None:
+    pattern = _generate_cache_pattern(resource_name, **kwargs)
+    await _invalidate_cache_by_pattern(pattern)
+
+
+def cache(
+    *,
+    resource_name: str,
+    ttl: int = DEFAULT_CACHE_TTL,
+    skip_if: Callable[[Any], bool] | None = None,
+) -> Callable[[Callable[..., Awaitable[Any]]], Callable[..., Awaitable[Any]]]:
+    def wrapper(func: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
+        if ttl <= 0:
+            raise ValueError("ttl must be positive")
+
+        sig = inspect.signature(func)
+
+        # Validate that function only accepts keyword arguments
+        # Allow: keyword-only parameters (*, x: int) or **kwargs
+        # Reject: positional parameters (x: int) or *args
+        func_name = getattr(func, "__name__", "<unknown>")
+        for param_name, param in sig.parameters.items():
+            if param.kind == inspect.Parameter.VAR_POSITIONAL:
+                raise ValueError(
+                    f"Function {func_name} has *{param_name} which is not supported. "
+                    "Cached functions must use only keyword arguments (no *args)."
+                )
+            if param.kind == inspect.Parameter.VAR_KEYWORD:
+                # **kwargs is allowed
+                continue
+            if param.kind == inspect.Parameter.POSITIONAL_ONLY:
+                raise ValueError(
+                    f"Function {func_name} has positional-only parameter {param_name} which is not supported. "
+                    "Cached functions must use only keyword arguments."
+                )
+            if param.kind == inspect.Parameter.POSITIONAL_OR_KEYWORD:
+                # Allow self/cls for methods, but reject other positional-or-keyword params
+                if param_name not in {"self", "cls"}:
+                    raise ValueError(
+                        f"Function {func_name} has positional parameter {param_name} which is not supported. "
+                        f"Cached functions must use only keyword arguments (use *, {param_name}... for keyword-only)."
+                    )
+            # KEYWORD_ONLY is allowed (parameters after * or *args)
+
+        first_param = next(iter(sig.parameters.values()), None)
+        ignore_first = first_param is not None and first_param.name in {
+            "self",
+            "cls",
+        }
+
+        return_type = get_type_hints(func).get("return")
+        decoder: ORJSONDecoder | None = None
+        if return_type is not None and is_dataclass(return_type):
+            decoder = ORJSONDecoder(return_type)
+
+        @wraps(func)
+        async def inner(*args: Any, **kwargs: Any) -> Any:
+            # Reject positional arguments (except self/cls for methods)
+            # Only kwargs are allowed for cache key generation
+            if ignore_first:
+                # For methods, allow self/cls as first positional arg
+                if len(args) > 1:
+                    raise TypeError(
+                        f"{func_name}() does not accept positional arguments (except self/cls). "
+                        "Cached functions must be called with keyword arguments only."
+                    )
+            else:
+                # For regular functions, no positional args allowed
+                if args:
+                    raise TypeError(
+                        f"{func_name}() does not accept positional arguments. "
+                        "Cached functions must be called with keyword arguments only."
+                    )
+
+            # Remove self/cls from kwargs if present (for methods)
+            key_kwargs = dict(kwargs)
+            if ignore_first and first_param is not None:
+                fp_name = first_param.name
+                if fp_name in key_kwargs:
+                    del key_kwargs[fp_name]
+
+            cache_key = _generate_cache_key(resource_name, **key_kwargs)
+            redis_cache = _get_redis_cache()
+
+            try:
+                cached_bytes = await redis_cache.get(cache_key)
+            except Exception as e:
+                logger.error(f"Failed to get cache for key: {cache_key}: {e}")
+                cached_bytes = None
+
+            if cached_bytes is not None:
+                try:
+                    if decoder:
+                        return decoder.decode(cached_bytes)
+                    return orjson.loads(cached_bytes)
+                except Exception:
+                    logger.error(f"Failed to decode JSON for key: {cache_key}")
+                    # No need to unlink - the cache will be overwritten after fetching from DB
+
+            result = await func(*args, **kwargs)
+
+            if skip_if is not None and skip_if(result):
+                return result
+
+            try:
+                payload = orjson.dumps(result)
+                # Apply 5% jitter with minimum of 1 second to prevent cache stampede
+                # Ensure jitter never exceeds base TTL to avoid negative/zero results
+                jitter = min(max(1, int(ttl * 0.05)), ttl // 2)
+                ttl_jittered = ttl + random.randint(-jitter, jitter)
+
+                await redis_cache.set(cache_key, payload, ex=ttl_jittered)
+            except TypeError as exc:
+                raise ValueError(f"Value is not JSON serializable for key: {cache_key}") from exc
+            except Exception as e:
+                logger.warning(f"Failed to cache result for key {cache_key}: {e}")
+
+            return result
+
+        return inner
+
+    return wrapper
+
+
+if __name__ == "__main__":  # pragma: no cover
+    print(
+        _generate_cache_key(
+            "user_cache",
+            user_id=1,
+            series_id="SDFAZV45SOLDFDF534",
+            date="2025-01-01",
+        )
+    )
+    print(_generate_cache_pattern("user_cache", user_id=1, series_id="SDFAZV45SOLDFDF534"))

core_framework/core/context.py

@@ -0,0 +1,14 @@
+from contextvars import ContextVar
+
+user_id: ContextVar[str | None] = ContextVar[str | None]("user_id", default=None)
+user_ip: ContextVar[str | None] = ContextVar[str | None]("user_ip", default=None)
+client_ip: ContextVar[str | None] = ContextVar[str | None]("client_ip", default=None)
+request_id: ContextVar[str | None] = ContextVar[str | None]("request_id", default=None)
+
+
+REQUEST_CONTEXTVARS: list[ContextVar[str | None]] = [
+    user_id,
+    user_ip,
+    client_ip,
+    request_id,
+]

core_framework/core/database.py

@@ -0,0 +1,111 @@
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from types import TracebackType
+from typing import Any, Final, Self
+
+import asyncpg
+import orjson
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
+
+DB_NOT_CONNECTED_MSG: Final[str] = "Database is not connected"
+DB_ALREADY_CONNECTED_MSG: Final[str] = "Database is already connected"
+
+
+class Postgres:
+    __slots__ = ("_pool", "_database_url", "_min_connections", "_max_connections")
+
+    def __init__(
+        self,
+        database_url: str,
+        min_connections: int,
+        max_connections: int,
+    ) -> None:
+        self._pool: asyncpg.Pool | None = None
+        self._database_url = database_url
+        self._min_connections = min_connections
+        self._max_connections = max_connections
+
+    async def __aenter__(self) -> Self:
+        return await self.connect()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.disconnect()
+
+    @retry(
+        stop=stop_after_attempt(10),
+        wait=wait_exponential(multiplier=2, min=2, max=30),
+        retry=retry_if_exception_type((asyncpg.PostgresConnectionError, OSError)),
+    )
+    async def connect(self) -> Self:
+        if self._pool is not None:
+            raise RuntimeError(DB_ALREADY_CONNECTED_MSG)
+
+        self._pool = await asyncpg.create_pool(
+            self._database_url,
+            min_size=self._min_connections,
+            max_size=self._max_connections,
+            init=self.init_connection,
+            server_settings={
+                "search_path": "extension, public",
+            },
+        )
+        return self
+
+    async def disconnect(self) -> None:
+        if self._pool is None:
+            return
+
+        await self._pool.close()
+        self._pool = None
+
+    @asynccontextmanager
+    async def get_connection(self) -> AsyncGenerator[asyncpg.Connection]:
+        if self._pool is None:
+            raise RuntimeError(DB_NOT_CONNECTED_MSG)
+
+        async with self._pool.acquire() as connection:
+            yield connection
+
+    @asynccontextmanager
+    async def get_transaction_with_actor_id(self, actor_id: str | None) -> AsyncGenerator[asyncpg.Connection]:
+        if self._pool is None:
+            raise RuntimeError(DB_NOT_CONNECTED_MSG)
+
+        async with self._pool.acquire() as connection:
+            async with connection.transaction():
+                if actor_id is not None:
+                    try:
+                        await connection.execute("select set_config('app.actor_id', $1, true)", actor_id)
+                    except asyncpg.PostgresError:
+                        pass  # Actor ID is optional - transaction proceeds without it
+                yield connection
+
+    @asynccontextmanager
+    async def get_transaction(self) -> AsyncGenerator[asyncpg.Connection]:
+        if self._pool is None:
+            raise RuntimeError(DB_NOT_CONNECTED_MSG)
+
+        async with self._pool.acquire() as connection:
+            async with connection.transaction():
+                yield connection
+
+    @staticmethod
+    def orjson_dump_str(value: Any) -> str:
+        return orjson.dumps(value).decode()
+
+    @staticmethod
+    def orjson_load_str(value: str) -> Any:
+        return orjson.loads(value)
+
+    async def init_connection(self, connection: asyncpg.Connection) -> None:
+        await connection.set_type_codec(
+            "jsonb",
+            encoder=self.orjson_dump_str,
+            decoder=self.orjson_load_str,
+            schema="pg_catalog",
+        )

core_framework/core/exception_handlers/__init__.py

@@ -0,0 +1,3 @@
+from core_framework.core.exception_handlers.setup import setup_exception_handlers
+
+__all__ = ["setup_exception_handlers"]