core-framework 0.3.0__py3-none-any.whl

core_framework/core/pagination.py

@@ -0,0 +1,203 @@
+from collections.abc import Mapping, Sequence
+from datetime import datetime, timezone
+from enum import StrEnum
+from functools import cached_property
+from typing import Annotated, Any, Final, Literal, TypedDict
+
+from fastapi import HTTPException, Query, Request
+from itsdangerous import BadSignature, URLSafeSerializer
+from pydantic import BaseModel, ConfigDict, field_validator
+
+DEFAULT_LIMIT: Final[int] = 10
+MAX_LIMIT: Final[int] = 100
+DEFAULT_CURSOR: Final[datetime] = datetime(3000, 1, 1, 0, 0)
+DEFAULT_OFFSET: Final[int] = 0
+DEFAULT_MAX_ITEMS: Final[int] = 10_000
+_configured_secret_key: str | None = None
+
+
+class PaginationCursorType(StrEnum):
+    CREATED_AT = "created_at"
+    UPDATED_AT = "updated_at"
+    SIGNUP_AT = "signup_at"
+
+
+class PaginationResult[T](TypedDict):
+    items: Sequence[T]
+    next_page_href: str | None
+
+
+class PaginationResponse[T](BaseModel):
+    items: list[T]
+    next_page_href: str | None
+
+
+def configure_pagination(*, secret_key: str) -> None:
+    global _configured_secret_key
+    _configured_secret_key = secret_key
+
+
+def _build_token_serializer(secret_key: str) -> URLSafeSerializer:
+    return URLSafeSerializer(secret_key, salt="pagination")
+
+
+def _get_token_serializer() -> URLSafeSerializer:
+    if _configured_secret_key is None:
+        msg = "Pagination is not configured. Call configure_pagination() during application bootstrap."
+        raise RuntimeError(msg)
+    return _build_token_serializer(_configured_secret_key)
+
+
+def _cursor_to_utc_iso(cursor: datetime) -> str:
+    """Serialize cursor as UTC ISO 8601 with full resolution (including microseconds)."""
+    if cursor.tzinfo is None:
+        utc = cursor.replace(tzinfo=timezone.utc)
+    else:
+        utc = cursor.astimezone(timezone.utc)
+    return utc.isoformat()
+
+
+def _parse_cursor_payload(raw: object) -> datetime:
+    """Decode cursor from token payload (UTC ISO 8601 string)."""
+    if not isinstance(raw, str):
+        msg = f"Invalid cursor type in page token: {type(raw).__name__}"
+        raise TypeError(msg)
+    parsed = datetime.fromisoformat(raw)
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def _decode_page_token(token: str | None) -> tuple[datetime, int]:
+    if token is None:
+        return DEFAULT_CURSOR, 0
+
+    try:
+        data = _get_token_serializer().loads(token)
+        cursor = _parse_cursor_payload(data["c"])
+        retrieved = data["r"]
+        return cursor, retrieved
+    except (BadSignature, KeyError, TypeError, ValueError) as e:
+        raise HTTPException(status_code=400, detail="Invalid page token") from e
+
+
+def _encode_page_token(cursor: datetime, retrieved: int) -> str:
+    return _get_token_serializer().dumps({"c": _cursor_to_utc_iso(cursor), "r": retrieved})
+
+
+class _BaseLimitParams(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    limit: Annotated[int, Query(ge=DEFAULT_LIMIT, le=MAX_LIMIT)] = DEFAULT_LIMIT
+
+    @field_validator("limit", mode="after")
+    @classmethod
+    def increment_limit(cls, v: int) -> int:
+        return v + 1
+
+
+class TokenCursorQueryParams(_BaseLimitParams):
+    page_token: Annotated[str | None, Query()] = None
+
+    @cached_property
+    def _decoded(self) -> tuple[datetime, int]:
+        return _decode_page_token(self.page_token)
+
+    @property
+    def cursor(self) -> datetime:
+        return self._decoded[0]
+
+    @property
+    def retrieved(self) -> int:
+        return self._decoded[1]
+
+
+class OffsetQueryParams(_BaseLimitParams):
+    offset: Annotated[int, Query(ge=DEFAULT_OFFSET)] = DEFAULT_OFFSET
+
+
+def paginate_cursor[T](
+    request: Request,
+    items: Sequence[T],
+    limit: int,
+    cursor_field: PaginationCursorType,
+    retrieved: int = 0,
+    max_items: int = DEFAULT_MAX_ITEMS,
+) -> PaginationResult[T]:
+    """Paginate items using cursor-based pagination with signed tokens."""
+    return _paginate(request, items, limit, "cursor", cursor_field, retrieved, max_items)
+
+
+def paginate_offset[T](
+    request: Request,
+    items: Sequence[T],
+    limit: int,
+    retrieved: int = 0,
+    max_items: int | None = None,
+) -> PaginationResult[T]:
+    """Paginate items using offset-based pagination."""
+    return _paginate(request, items, limit, "offset", retrieved=retrieved, max_items=max_items)
+
+
+def _get_field(obj: Any, field: str) -> Any:
+    if isinstance(obj, Mapping):
+        return obj.get(field)
+    return getattr(obj, field, None)
+
+
+def _paginate[T](
+    request: Request,
+    items: Sequence[T],
+    limit: int,
+    pagination_type: Literal["offset", "cursor"],
+    cursor_field: PaginationCursorType | None = None,
+    retrieved: int = 0,
+    max_items: int | None = None,
+) -> PaginationResult[T]:
+    page_size = limit - 1
+
+    last_page = len(items) <= page_size
+    if last_page:
+        return {"items": items, "next_page_href": None}
+
+    # Check if we've reached max_items limit
+    new_retrieved = retrieved + page_size
+    if max_items is not None and new_retrieved >= max_items:
+        return {"items": items[:page_size], "next_page_href": None}
+
+    match pagination_type:
+        case "offset":
+            current_offset = int(request.query_params.get("offset", "0"))
+            next_offset = current_offset + page_size
+
+            next_url = request.url.include_query_params(
+                limit=page_size,
+                offset=next_offset,
+            )
+
+        case "cursor":
+            if cursor_field is None:  # pragma: no cover
+                raise ValueError("cursor_field is required for cursor pagination")
+
+            cursor = _get_field(items[-1], cursor_field.value)
+
+            if cursor is None:
+                raise ValueError(f"No cursor found in field: {cursor_field.value}")
+
+            if not isinstance(cursor, datetime):
+                raise TypeError(f"Cursor field {cursor_field.value!r} must be datetime, got {type(cursor).__name__}")
+
+            # Generate signed token with cursor and retrieved count
+            token = _encode_page_token(cursor, new_retrieved)
+
+            # Build URL with token (remove old page_token param, add new token)
+            base_url = request.url.remove_query_params(["page_token"])
+            next_url = base_url.include_query_params(
+                limit=page_size,
+                page_token=token,
+            )
+
+    return {
+        "items": items[:page_size],
+        "next_page_href": f"{next_url.path}?{next_url.query}" if next_url.query else next_url.path,
+    }

core_framework/core/redis.py

@@ -0,0 +1,135 @@
+from collections.abc import AsyncIterator
+from types import TracebackType
+from typing import Final, Self
+
+from redis.asyncio import Redis
+from redis.exceptions import RedisError
+from saq.queue.redis import RedisQueue as BaseRedisQueue
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
+
+REDIS_NOT_CONNECTED_MSG: Final[str] = "Redis is not connected"
+REDIS_ALREADY_CONNECTED_MSG: Final[str] = "Redis is already connected"
+
+
+class RedisQueue:
+    __slots__ = ("_queue", "_host", "_port", "_database")
+
+    def __init__(self, host: str, port: int, database: int) -> None:
+        self._queue: BaseRedisQueue | None = None
+        self._host = host
+        self._port = port
+        self._database = database
+
+    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((RedisError, OSError)),
+    )
+    async def connect(self) -> Self:
+        if self._queue is not None:
+            raise RuntimeError(REDIS_ALREADY_CONNECTED_MSG)
+
+        self._queue = BaseRedisQueue.from_url(f"redis://{self._host}:{self._port}/{self._database}")
+        return self
+
+    async def disconnect(self) -> None:
+        if self._queue is None:
+            return
+
+        await self._queue.disconnect()
+        self._queue = None
+
+    @property
+    def redis_queue(self) -> BaseRedisQueue:
+        if self._queue is None:
+            raise RuntimeError(REDIS_NOT_CONNECTED_MSG)
+
+        return self._queue
+
+
+class RedisCache:
+    __slots__ = ("_client", "_host", "_port", "_database")
+
+    def __init__(self, host: str, port: int, database: int) -> None:
+        self._client: Redis | None = None
+        self._host = host
+        self._port = port
+        self._database = database
+
+    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((RedisError, OSError)),
+    )
+    async def connect(self) -> Self:
+        if self._client is not None:
+            raise RuntimeError(REDIS_ALREADY_CONNECTED_MSG)
+
+        self._client = Redis(
+            host=self._host,
+            port=self._port,
+            db=self._database,
+        )
+        await self._client.ping()
+        return self
+
+    async def disconnect(self) -> None:
+        if self._client is None:
+            return
+
+        try:
+            await self._client.aclose()
+        finally:
+            self._client = None
+
+    @property
+    def client(self) -> Redis:
+        if self._client is None:
+            raise RuntimeError(REDIS_NOT_CONNECTED_MSG)
+
+        return self._client
+
+    async def ping(self) -> bool:
+        return await self.client.ping()
+
+    async def get(self, key: bytes) -> bytes | None:
+        return await self.client.get(key)
+
+    async def set(self, key: bytes, value: bytes, ex: int) -> None:
+        await self.client.set(key, value, ex=ex)
+
+    async def scan_iter(self, match: bytes, count: int) -> AsyncIterator[bytes]:
+        async for key in self.client.scan_iter(match=match, count=count):
+            yield key
+
+    async def sadd(self, key: str, *values: str) -> int:
+        return await self.client.sadd(key, *values)  # type: ignore[assignment]
+
+    async def sismember(self, key: str, value: str) -> bool:
+        result: int = await self.client.sismember(key, value)  # type: ignore[assignment]
+        return bool(result)
+
+    async def unlink(self, *keys: bytes) -> None:
+        await self.client.unlink(*keys)

core_framework/core/runtime.py

@@ -0,0 +1,66 @@
+from dataclasses import dataclass
+from typing import Any
+
+from core_framework.core.database import Postgres
+from core_framework.core.http_client import HttpClient
+from core_framework.core.redis import RedisCache, RedisQueue
+from core_framework.core.settings import Settings
+
+
+@dataclass(slots=True)
+class CoreRuntime:
+    settings: Settings
+    write_postgres: Postgres
+    read_postgres: Postgres
+    redis_queue: RedisQueue
+    redis_cache: RedisCache
+    general_http_client: HttpClient
+
+
+class _UnconfiguredDependencyProxy:
+    __slots__ = ("dependency_name",)
+
+    def __init__(self, dependency_name: str) -> None:
+        self.dependency_name = dependency_name
+
+    def __getattr__(self, _: str) -> Any:
+        msg = (
+            f"{self.dependency_name} is not configured. "
+            "Build the app via init_app(), create_task_worker(), or call the relevant "
+            "configure_*() bootstrap helper before use."
+        )
+        raise RuntimeError(msg)
+
+
+def unconfigured_dependency(dependency_name: str) -> Any:
+    return _UnconfiguredDependencyProxy(dependency_name)
+
+
+def build_core_runtime(settings: Settings) -> CoreRuntime:
+    return CoreRuntime(
+        settings=settings,
+        write_postgres=Postgres(
+            database_url=settings.write_postgres.postgres_url,
+            min_connections=settings.write_postgres.min_connections,
+            max_connections=settings.write_postgres.max_connections,
+        ),
+        read_postgres=Postgres(
+            database_url=settings.read_postgres.postgres_url,
+            min_connections=settings.read_postgres.min_connections,
+            max_connections=settings.read_postgres.max_connections,
+        ),
+        redis_queue=RedisQueue(
+            host=settings.redis.host,
+            port=settings.redis.port,
+            database=settings.redis.queue_db,
+        ),
+        redis_cache=RedisCache(
+            host=settings.redis.host,
+            port=settings.redis.port,
+            database=settings.redis.cache_db,
+        ),
+        general_http_client=HttpClient(
+            timeout=settings.http_client.timeout_config,
+            limits=settings.http_client.limit_config,
+        ),
+    )

core_framework/core/settings.py

@@ -0,0 +1,189 @@
+from functools import cache
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+from httpx import Limits, Timeout
+from pydantic import BaseModel, Field, HttpUrl, field_validator, model_validator
+from pydantic_core import MultiHostUrl
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    TomlConfigSettingsSource,
+)
+
+
+def get_version() -> str:
+    try:
+        return version("core_framework")
+    except PackageNotFoundError:
+        return "dev"
+
+
+class AvatarConfig(BaseModel):
+    base_url: HttpUrl
+    default_url: HttpUrl
+    extension: str = "webp"
+
+    @field_validator("base_url", mode="before")
+    @classmethod
+    def strip_trailing_slash(cls, v: str) -> str:
+        return v.rstrip("/")
+
+
+class BannerConfig(BaseModel):
+    base_url: HttpUrl
+    default_url: HttpUrl
+    extension: str = "webp"
+
+    @field_validator("base_url", mode="before")
+    @classmethod
+    def strip_trailing_slash(cls, v: str) -> str:
+        return v.rstrip("/")
+
+
+class AppConfig(BaseModel):
+    environment: Literal["local", "development", "production"]
+    debug: bool
+    openapi_url: str
+    allowed_hosts: list[str]
+    secret_key: str
+
+    @property
+    def fastapi_kwargs(self) -> dict[str, Any]:
+        return {
+            "title": "core-framework API",
+            "version": get_version(),
+            "debug": self.debug,
+            "openapi_url": self.openapi_url,
+        }
+
+
+class LoggingConfig(BaseModel):
+    sink: str
+    level: Literal["trace", "debug", "info", "notice", "warn", "warning", "error", "fatal"]
+
+
+class ObservabilityConfig(BaseModel):
+    enabled: bool
+    logfire_token: str
+
+
+class HttpClientConfig(BaseModel):
+    timeout: float
+    max_connections: int
+    max_keepalive_connections: int
+
+    @property
+    def limit_config(self) -> Limits:
+        return Limits(
+            max_connections=self.max_connections,
+            max_keepalive_connections=self.max_keepalive_connections,
+        )
+
+    @property
+    def timeout_config(self) -> Timeout:
+        return Timeout(timeout=self.timeout)
+
+
+class CorsConfig(BaseModel):
+    allow_credentials: bool
+    allowed_origins: list[str]
+    allowed_methods: list[str]
+    allowed_headers: list[str]
+
+
+class PostgresConnectionConfig(BaseModel):
+    host: str
+    port: int
+    user: str
+    password: str
+    db_name: str
+    min_connections: int = 10
+    max_connections: int = 20
+
+    @model_validator(mode="after")
+    def validate_connection_limits(self) -> PostgresConnectionConfig:
+        if self.min_connections > self.max_connections:
+            raise ValueError(f"{self.min_connections=} must be less than {self.max_connections=}")
+        return self
+
+    @property
+    def alembic_postgres_url(self) -> str:
+        return MultiHostUrl.build(
+            scheme="postgresql+asyncpg",
+            host=self.host,
+            port=self.port,
+            username=self.user,
+            password=self.password,
+            path=self.db_name,
+        ).unicode_string()
+
+    @property
+    def postgres_url(self) -> str:
+        return MultiHostUrl.build(
+            scheme="postgresql",
+            host=self.host,
+            port=self.port,
+            username=self.user,
+            password=self.password,
+            path=self.db_name,
+        ).unicode_string()
+
+
+class PostgresSchemasConfig(BaseModel):
+    schema_extension: str
+    schema_user: str
+    schema_moderation: str
+    schema_post: str
+    schema_comment: str
+
+
+class RedisConfig(BaseModel):
+    host: str
+    port: int
+    cache_db: int
+    queue_db: int
+
+    @property
+    def redis_queue_url(self) -> str:
+        return f"redis://{self.host}:{self.port}/{self.queue_db}"
+
+    @property
+    def redis_cache_url(self) -> str:
+        return f"redis://{self.host}:{self.port}/{self.cache_db}"
+
+
+class Settings(BaseSettings):
+    PROJECT_ROOT: Path = Path(__file__).parent.parent.parent
+
+    app: AppConfig
+    logging: LoggingConfig
+    observability: ObservabilityConfig
+    cors: CorsConfig
+    http_client: Annotated[HttpClientConfig, Field(alias="http-client")]
+    write_postgres: PostgresConnectionConfig
+    read_postgres: PostgresConnectionConfig
+    postgres_schemas: PostgresSchemasConfig
+    redis: RedisConfig
+    avatar: AvatarConfig
+    banner: BannerConfig
+
+    model_config = SettingsConfigDict(toml_file="config.toml")
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (TomlConfigSettingsSource(settings_cls),)
+
+
+@cache
+def load_default_settings() -> Settings:
+    return Settings()  # ty: ignore[missing-argument]