socar-api 0.6.0__py3-none-any.whl

api_frame/cache.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""Unified cache decorator / middleware for api_frame resources.
+
+Usage::
+
+    # Decorator form (recommended)
+    @cached(prefix='cars', ttl=300)
+    class Cars(BaseResource):
+        ...
+
+    # Class-attribute form (alternative)
+    class Cars(BaseResource):
+        cache_prefix = 'cars'
+        cache_ttl = 300
+        ...
+
+The cache uses a Cache-Aside pattern: check cache → hit → return;
+miss → call original → store result → return.
+"""
+
+from __future__ import annotations
+
+import functools
+import hashlib
+import json
+import logging
+import time
+from collections.abc import Callable
+from typing import Any, Protocol
+
+from fastapi import Request
+
+from api_frame.responses import JsonapiResponse
+
+logger = logging.getLogger(__name__)
+
+# ── Cache Backend Protocol ──────────────────────────────────────────────────
+
+
+class CacheBackend(Protocol):
+    """Pluggable cache storage protocol.
+
+    Projects implement this protocol and register it via
+    ``api_frame.cache.set_default_backend(backend)``.
+    """
+
+    async def get(self, key: str) -> Any | None:
+        """Return cached value or ``None``."""
+        ...
+
+    async def set(self, key: str, value: Any, ttl: int) -> None:
+        """Store *value* for *ttl* seconds."""
+        ...
+
+    async def delete(self, key: str) -> None:
+        """Remove *key* from cache."""
+        ...
+
+
+class _NullBackend:
+    """Fallback backend that never caches (safe default)."""
+
+    async def get(self, key: str) -> None:
+        return None
+
+    async def set(self, key: str, value: Any, ttl: int) -> None:
+        pass
+
+    async def delete(self, key: str) -> None:
+        pass
+
+
+_default_backend: CacheBackend = _NullBackend()
+
+
+def set_default_backend(backend: CacheBackend) -> None:
+    """Set the global default cache backend.
+
+    Called once during application startup::
+
+        set_default_backend(RedisCacheBackend(host='...', port=6379))
+    """
+    global _default_backend
+    _default_backend = backend
+
+
+def get_default_backend() -> CacheBackend:
+    """Return the current default cache backend."""
+    return _default_backend
+
+
+# ── Version / Invalidation Hook ────────────────────────────────────────────
+
+_version_hook: Callable[[str], str] | None = None
+"""Optional hook that returns a cache-busting version string for a prefix.
+
+Signature: ``version_hook(prefix: str) -> str``
+Return ``""`` (or the same value across restarts) to keep cache alive.
+Return a new value to invalidate all keys under that prefix.
+"""
+
+
+def set_version_hook(hook: Callable[[str], str]) -> None:
+    """Register a cache version hook."""
+    global _version_hook
+    _version_hook = hook
+
+
+# ── Key construction ───────────────────────────────────────────────────────
+
+
+def _make_cache_key(prefix: str, request: Request) -> str:
+    """Build a deterministic cache key from URL + query params.
+
+    Format: ``{prefix}:{sha256_of_url}``
+    """
+    url = str(request.url)
+    url_hash = hashlib.sha256(url.encode()).hexdigest()[:16]
+    return f"{prefix}:{url_hash}"
+
+
+# ── The @cached decorator ──────────────────────────────────────────────────
+
+
+CACHE_PREFIX_ATTR = "_cache_prefix"
+CACHE_TTL_ATTR = "_cache_ttl"
+CACHE_BACKEND_ATTR = "_cache_backend"
+
+
+def cached(
+    prefix: str = "",
+    ttl: int | None = None,
+    backend: CacheBackend | None = None,
+) -> Callable[[type], type]:
+    """Class decorator: enable Cache-Aside for all GET/GETS routes.
+
+    Parameters
+    ----------
+    prefix : str
+        Cache key prefix.  Falls back to ``cls.cache_prefix`` if set.
+    ttl : int
+        Time-to-live in seconds (default 300).
+    backend : CacheBackend | None
+        Backend override.  Uses ``get_default_backend()`` when ``None``.
+    """
+
+    def decorator(cls: type) -> type:
+        _prefix = prefix or getattr(cls, "cache_prefix", cls.__name__.lower())
+        _ttl = ttl if ttl is not None else getattr(cls, "cache_ttl", 300)
+        _backend = backend if backend is not None else getattr(cls, "_cache_backend", None)
+
+        setattr(cls, CACHE_PREFIX_ATTR, _prefix)
+        setattr(cls, CACHE_TTL_ATTR, _ttl)
+        if _backend is not None:
+            setattr(cls, CACHE_BACKEND_ATTR, _backend)
+
+        # Only wrap handle_request if it exists (real Resource classes)
+        if not hasattr(cls, "handle_request"):
+            return cls
+
+        # Wrap handle_request if not already wrapped
+        original_handle_request = cls.handle_request
+
+        @functools.wraps(original_handle_request)
+        async def cached_handle_request(
+            handler_response: str,
+            handler_data: str,
+            *args: Any,
+            **kwargs: Any,
+        ) -> JsonapiResponse:
+            # Only cache GET requests
+            request: Request | None = kwargs.get("request")
+            if request is None:
+                return await original_handle_request(handler_response, handler_data, *args, **kwargs)
+
+            # Cache only GET (not POST/PATCH/DELETE)
+            if request.method not in ("GET",):
+                # Invalidate on write
+                _backend = getattr(cls, CACHE_BACKEND_ATTR, None) or get_default_backend()
+                if not isinstance(_backend, _NullBackend):
+                    # Best-effort invalidate: delete exact-match key
+                    key = _make_cache_key(getattr(cls, CACHE_PREFIX_ATTR, ""), request)
+                    try:
+                        await _backend.delete(key)
+                    except Exception:
+                        logger.warning("Cache invalidation failed for key %s", key, exc_info=True)
+                return await original_handle_request(handler_response, handler_data, *args, **kwargs)
+
+            prefix_key = getattr(cls, CACHE_PREFIX_ATTR, "")
+            ttl_val = getattr(cls, CACHE_TTL_ATTR, 300)
+            active_backend = getattr(cls, CACHE_BACKEND_ATTR, None) or get_default_backend()
+
+            # Build key with optional version
+            key = _make_cache_key(prefix_key, request)
+            if _version_hook is not None:
+                ver = _version_hook(prefix_key)
+                if ver:
+                    key = f"{key}:v{ver}"
+
+            # Try cache
+            try:
+                cached_data = await active_backend.get(key)
+            except Exception:
+                cached_data = None
+
+            if cached_data is not None:
+                logger.debug("Cache HIT  %s", key)
+                return JsonapiResponse(content=cached_data)
+
+            logger.debug("Cache MISS %s", key)
+
+            # Cache miss → call original
+            response = await original_handle_request(handler_response, handler_data, *args, **kwargs)
+
+            # Store result
+            if response is not None:
+                try:
+                    if hasattr(response, "body") and response.body:
+                        data = json.loads(response.body.decode())
+                    else:
+                        data = response
+                    await active_backend.set(key, data, ttl_val)
+                except Exception:
+                    logger.warning("Cache store failed for key %s", key, exc_info=True)
+
+            return response
+
+        cls.handle_request = cached_handle_request  # type: ignore[assignment]
+        return cls
+
+    return decorator
+
+
+# ── Simple in-memory backend (for testing / single-instance) ───────────────
+
+
+class MemoryBackend:
+    """In-memory cache backend.  Not distributed; use only for testing or single-worker deployments."""
+
+    def __init__(self) -> None:
+        self._store: dict[str, Any] = {}
+        self._ttls: dict[str, float] = {}
+
+    async def get(self, key: str) -> Any | None:
+        expiry = self._ttls.get(key)
+        if expiry is not None and time.monotonic() > expiry:
+            self._store.pop(key, None)
+            self._ttls.pop(key, None)
+            return None
+        return self._store.get(key)
+
+    async def set(self, key: str, value: Any, ttl: int) -> None:
+        self._store[key] = value
+        self._ttls[key] = time.monotonic() + ttl
+
+    async def delete(self, key: str) -> None:
+        self._store.pop(key, None)
+        self._ttls.pop(key, None)

api_frame/exception.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+
+"""
+http错误处理
+"""
+
+import json
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+from fastapi import Request, status
+from fastapi.exceptions import HTTPException, RequestValidationError
+
+from api_frame.jsonapi import ErrorModel, ErrorResponse
+from api_frame.responses import JsonapiResponse
+
+
+class JsonapiException(HTTPException):
+    """
+    jsonapi错误类
+     Args:
+        status_code: 错误http code
+        detail: 错误详情
+        errors: 错误列表
+
+    """
+
+    def __init__(
+        self, status_code: int, detail: str = None, title: str = None, errors: list[ErrorModel] = None, body: Any = None
+    ) -> None:
+        super().__init__(status_code, detail=detail)
+        self.errors = errors or []
+        self.body = body
+        self.errors.append(ErrorModel(detail=detail, status=str(status_code), title=title))
+
+
+class AuthError(JsonapiException):
+    """HTTP 401 error,没有认证权限"""
+
+    status_code: int = status.HTTP_401_UNAUTHORIZED
+    title: str = "没有认证权限"
+
+    def __init__(self, status_code: int = None, detail: str = None, title: str = None, body: Any = None) -> None:
+        super().__init__(
+            status_code if status_code is not None else self.status_code,
+            title=title if title is not None else self.title,
+            detail=detail,
+            errors=None,
+            body=body,
+        )
+
+
+class ResourceDuplicate(JsonapiException):
+    """HTTP 409 error,资源已存在"""
+
+    status_code: int = status.HTTP_409_CONFLICT
+    title: str = "资源重复创建"
+
+    def __init__(self, status_code: int = None, detail: str = None, title: str = None, body: Any = None) -> None:
+        super().__init__(
+            status_code if status_code is not None else self.status_code,
+            title=title if title is not None else self.title,
+            detail=detail,
+            errors=None,
+            body=body,
+        )
+
+
+class ResourceNotFound(JsonapiException):
+    """HTTP 404 error,资源不存在"""
+
+    status_code: int = status.HTTP_404_NOT_FOUND
+    title: str = "资源不存在"
+
+    def __init__(self, status_code: int = None, detail: str = None, title: str = None, body: Any = None) -> None:
+        super().__init__(
+            status_code if status_code is not None else self.status_code,
+            title=title if title is not None else self.title,
+            detail=detail,
+            errors=None,
+            body=body,
+        )
+
+
+class QureyError(JsonapiException):
+    """HTTP 400 error,查询参数错误"""
+
+    status_code: int = status.HTTP_400_BAD_REQUEST
+    title: str = "查询参数错误"
+
+    def __init__(self, status_code: int = None, detail: str = None, title: str = None, body: Any = None) -> None:
+        super().__init__(
+            status_code if status_code is not None else self.status_code,
+            title=title if title is not None else self.title,
+            detail=detail,
+            errors=None,
+            body=body,
+        )
+
+
+def _extract_request_context(request: Request, body: Any = None) -> dict:
+    """Extract common request context for error logging."""
+    if request.headers.get("X-Real-IP"):
+        client_ip = request.headers.get("X-Real-IP")
+    else:
+        client_ip = request.client.host
+    if not body:
+        if hasattr(request, "_json"):
+            body = request._json
+        if hasattr(request, "_form") and request._form:
+            for item, value in request._form.multi_items():
+                if item == "data":
+                    body = json.loads(value)
+    return {
+        "RequestMethod": request.method,
+        "url": str(request.url),
+        "UserAgent": request.headers.get("user-agent"),
+        "IP": client_ip,
+        "TokenPrefix": (request.headers.get("authorization", "")[:16] + "...")
+        if request.headers.get("authorization")
+        else None,
+        "RequestBody": body,
+    }
+
+
+
+def _loc_to_json_pointer(loc):
+    """将 Pydantic loc 元组转为 JSON Pointer。
+
+    ("body", "data", "attributes", "title") → "/data/attributes/title"
+    """
+    if not loc:
+        return ""
+    parts = [str(p) for p in loc if str(p) != "body"]
+    if not parts:
+        return ""
+    return "/" + "/".join(parts)
+
+
+def serialize_error(exc: BaseException, request: Request, msg: dict = None) -> JsonapiResponse:
+    """JSON:API 格式的错误序列化。
+    错误处理，将所有错误类型转成json:api，
+    JsonapiException: 预判规范内的错误，返给前端
+    HTTPException: http错误，日志记录
+    RequestValidationError，ValidationError：pydantic的验证错误，数据不合规范，记录日志
+    对pydantic的验证错误做了处理。detail中指明了验证错误的具体字段和错误原因
+    Args:
+        exc: 处理对象
+        request: Request
+        msg: 日志信息
+    Returns:JsonapiResponse
+
+    """
+    body = None
+    if isinstance(exc, JsonapiException):
+        status_code = exc.status_code
+        errors = exc.errors
+        body = exc.body
+    elif isinstance(exc, HTTPException):
+        status_code = exc.status_code
+        errors = [ErrorModel(status=str(status_code), detail=exc.detail, meta={"headers": exc.headers})]
+    elif isinstance(exc, RequestValidationError):
+        status_code = status.HTTP_422_UNPROCESSABLE_CONTENT
+        errors = [
+            ErrorModel(
+                detail=error.get("msg"),
+                title=error.get("type"),
+                status=str(status_code),
+                source={
+                    "pointer": _loc_to_json_pointer(error.get("loc")),
+                },
+            )
+            for error in exc.errors()
+        ]
+        body = exc.body
+    else:
+        status_code = status.HTTP_500_INTERNAL_SERVER_ERROR
+        errors = [ErrorModel(status=str(status_code), detail="Internal server error")]
+    error_body = ErrorResponse(errors=errors)
+
+    if not msg:
+        msg = _extract_request_context(request, body)
+        msg["ResponseStatusCode"] = status_code
+
+    if status_code == status.HTTP_500_INTERNAL_SERVER_ERROR:
+        logger.error(msg, exc_info=exc)
+    else:
+        logger.warning(msg, exc_info=exc)
+
+    return JsonapiResponse(status_code=status_code, content=error_body.model_dump())

api_frame/field.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+
+"""
+字段
+"""
+
+from typing import Any
+
+from pydantic.fields import FieldInfo
+
+
+class Field(FieldInfo):
+    """模型默认字段属性， 提供额外信息。
+    与pydantic的field相比，增加了:
+        onlyread: 标明此字段是否只读
+        onlywrite：标明此字段是否只写
+        inmany: 在资源列表中是否显示。=true显示
+        ishide: 是否不在schema模型中隐藏。例如用户id,在响应模型中不需要，只在接口和数据库交互时使用。可置ishide=true
+        isrel: 是否作为关系，默认否
+    """
+
+    def __init__(self, default: Any = None, **kwargs: Any):
+        # 在调用 super().__init__() 前弹出自定义元数据 — pydantic v2 FieldInfo
+        # only accepts known parameters; unknown ones would raise TypeError
+        self.onlyread = kwargs.pop("onlyread", False)
+        self.inmany = kwargs.pop("inmany", True)
+        self.onlywrite = kwargs.pop("onlywrite", False)
+        self.ishide = kwargs.pop("ishide", False)
+        self.isrel = kwargs.pop("isrel", False)
+        self.mapping = kwargs.pop("mapping", None)
+
+        # pydantic v2 中 'pattern' 存储在 metadata 中，不作为公共属性暴露。
+        # 这里显式保存以便 Email/URL 等子类能对外暴露。
+        self._saved_pattern = kwargs.get("pattern")
+
+        super().__init__(default=default, **kwargs)
+
+
+class Email(Field):
+    """
+    邮箱
+    """
+
+    def __init__(self, default: Any = None, **kwargs: Any):
+        kwargs["pattern"] = r"(^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$)"
+        super().__init__(default=default, **kwargs)
+
+    @property
+    def pattern(self):
+        return self._saved_pattern
+
+
+class URL(Field):
+    """
+    url
+    """
+
+    def __init__(self, default: Any = None, **kwargs: Any):
+        kwargs["pattern"] = r"^https?:/{2}\w.+$"
+        super().__init__(default=default, **kwargs)
+
+    @property
+    def pattern(self):
+        return self._saved_pattern
+
+
+class Phone(Field):
+    pass