socar-api 0.6.0__py3-none-any.whl

api_frame/__init__.py

@@ -0,0 +1,16 @@
+__version__ = "0.6.0"
+
+from api_frame.auth import Auth  # noqa: F401
+from api_frame.cache import MemoryBackend, cached, set_default_backend, set_version_hook  # noqa: F401
+from api_frame.exception import (  # noqa: F401
+    AuthError,
+    JsonapiException,
+    QureyError,
+    ResourceDuplicate,
+    ResourceNotFound,
+)
+from api_frame.filebase import DownloadFileResource, UploadFileResource  # noqa: F401
+from api_frame.query import ArgParse, Filter, FilterAnd, FilterOr  # noqa: F401
+from api_frame.resource import BaseResource, Resource, UploadFileBaseResource  # noqa: F401
+from api_frame.schema import Relationship, SchemaBase, field_mapping  # noqa: F401
+from api_frame.scope import scope  # noqa: F401

api_frame/atomic.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""Atomic operations module extracted from resource.py.
+
+Provides AtomicOperation dataclass and AtomicExecutor class for
+processing JSON:API atomic operations without mutating the request.
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Literal
+
+logger = logging.getLogger(__name__)
+
+from fastapi import Request
+
+from api_frame.exception import AuthError, JsonapiException, serialize_error
+from api_frame.meta import type_registered_resources
+
+
+@dataclass
+class AtomicOperation:
+    """Represents a single atomic operation.
+
+    Attributes:
+        op: The operation type ('add', 'update', 'remove')
+        target_cls: The target resource class
+        data: Operation data dict (from 'data' field)
+        ref_id: Optional reference id (for 'update' and 'remove')
+    """
+
+    op: Literal["add", "update", "remove"]
+    target_cls: type[Any]
+    data: dict
+    ref_id: str | None = None
+
+
+class AtomicExecutor:
+    """Executes JSON:API atomic operations.
+
+    Processes a list of atomic operations by creating resource instances
+    directly and calling their post/patch/delete methods, without
+    mutating request.scope or request._json on the original request.
+    """
+
+    def __init__(self, request: Request):
+        self.request = request
+
+    async def run(self, operations: list[dict]) -> dict:
+        """Execute a list of atomic operations.
+
+        Args:
+            operations: List of operation dicts from 'atomic:operations'
+
+        Returns:
+            dict with 'atomic:results' key containing operation results
+
+        Raises:
+            JsonapiException: On validation errors
+            AuthError: On permission errors
+        """
+        if not operations:
+            raise JsonapiException(status_code=400, detail="atomic:operations 不能为空")
+
+        # 阶段1：解析并验证所有操作
+        resolved = await self._parse_operations(operations)
+
+        # 阶段2：在共享事务中执行所有操作
+        return await self._execute_operations(resolved)
+
+    async def _parse_operations(self, operations: list[dict]) -> list[tuple]:
+        """Parse and validate all operations.
+
+        Returns list of (op, target_cls, op_data, ref_id) tuples.
+        """
+        op_to_method = {"add": "POST", "update": "PATCH", "remove": "DELETE"}
+        resolved = []
+
+        for op_data in operations:
+            op = op_data.get("op")
+            if op not in ("add", "update", "remove"):
+                raise JsonapiException(status_code=400, detail=f"不支持的操作符: {op}")
+
+            if op == "add":
+                target_type = op_data.get("data", {}).get("type")
+                ref_id = None
+            else:
+                ref = op_data.get("ref", {})
+                target_type = ref.get("type")
+                ref_id = ref.get("id")
+                if not ref_id:
+                    raise JsonapiException(status_code=400, detail="缺少资源 id")
+
+            if not target_type:
+                raise JsonapiException(status_code=400, detail="缺少资源类型 type")
+
+            target_cls = type_registered_resources.get(target_type)
+            if not target_cls:
+                raise JsonapiException(status_code=400, detail=f"资源类型不存在: {target_type}")
+
+            # 检查权限
+            if target_cls.Auth:
+                scope = target_cls.Auth.get_scopes(api_url=target_cls.Meta.link, method=op_to_method[op])
+                if scope is not None:
+                    has_perm = await target_cls.Auth.api_auth(api_url=target_cls.Meta.link, method=op_to_method[op])
+                    if not has_perm:
+                        raise AuthError(detail=f"没有 {op_to_method[op]} {target_type} 的权限")
+
+            resolved.append((op, target_cls, op_data, ref_id))
+
+        return resolved
+
+    async def _execute_operations(self, resolved: list[tuple]) -> dict:
+        """Execute validated operations with shared transaction management."""
+        shared_db = None
+        last_target_cls = None  # 用于异常时的错误处理回退
+        try:
+            # 获取 session 数据源
+            session_source = next((tc for _, tc, _, _ in resolved if tc.session is not None), None)
+
+            if session_source and session_source.session:
+                shared_db = session_source.session.get()
+                try:
+                    shared_db.rollback()
+                except BaseException:
+                    pass
+
+            results = []
+            for op, target_cls, op_data, ref_id in resolved:
+                last_target_cls = target_cls
+                result = await self._execute_single(op, target_cls, op_data, ref_id, shared_db)
+                results.append(
+                    {
+                        "data": {
+                            "type": target_cls.Meta.type_,
+                            "id": result.id if result and hasattr(result, "id") else None,
+                        }
+                    }
+                )
+
+            if shared_db:
+                shared_db.commit()
+
+            return {"atomic:results": results}
+
+        except BaseException as e:
+            if shared_db:
+                shared_db.rollback()
+            if last_target_cls is not None:
+                return await last_target_cls.handle_error(request=self.request, exc=e)
+            return await self._fallback_error(e)
+        finally:
+            if shared_db:
+                shared_db.close()
+
+    async def _execute_single(self, op: str, target_cls: type, op_data: dict, ref_id: str | None, shared_db):
+        """Execute a single atomic operation.
+
+        Creates a resource instance and calls the appropriate handler,
+        without mutating request.scope or request._json.
+        """
+        if op == "add":
+            body = op_data.get("data", {}).copy()
+            resource = target_cls(request=self.request, request_context={"request_body": {"data": body}})
+            # 标记为新增操作
+            resource._atomic_op = "add"
+            resource._atomic_body = body
+            if shared_db:
+                resource.db = shared_db
+            result = await resource.post()
+            if shared_db and resource.db is not shared_db:
+                logger.warning(
+                    "原子操作: %s.post() 内部调用了 connect_data，已自动恢复共享事务", target_cls.Meta.type_
+                )
+                resource.db = shared_db
+
+        elif op == "update":
+            body = op_data.get("data", {}).copy()
+            body["id"] = ref_id
+            body.setdefault("type", target_cls.Meta.type_)
+            resource = target_cls(request=self.request, request_context={"request_body": {"data": body}})
+            # 标记为更新操作
+            resource._atomic_op = "update"
+            resource._atomic_body = body
+            resource._atomic_id = ref_id
+            if shared_db:
+                resource.db = shared_db
+            result = await resource.patch()
+            if shared_db and resource.db is not shared_db:
+                logger.warning(
+                    "原子操作: %s.patch() 内部调用了 connect_data，已自动恢复共享事务", target_cls.Meta.type_
+                )
+                resource.db = shared_db
+
+        else:  # remove
+            resource = target_cls(request=self.request)
+            resource._atomic_op = "remove"
+            resource._atomic_id = ref_id
+            if shared_db:
+                resource.db = shared_db
+            result = await resource.delete()
+            if shared_db and resource.db is not shared_db:
+                logger.warning(
+                    "原子操作: %s.delete() 内部调用了 connect_data，已自动恢复共享事务", target_cls.Meta.type_
+                )
+                resource.db = shared_db
+
+        return result
+
+    async def _fallback_error(self, exc: BaseException) -> dict:
+        """Fallback error handler when target_cls is not available."""
+
+        return serialize_error(request=self.request, exc=exc)

api_frame/auth.py

@@ -0,0 +1,243 @@
+import abc
+import logging
+import math
+
+logger = logging.getLogger(__name__)
+
+from bitarray import bitarray
+from bitarray.util import ba2base, base2ba
+from fastapi import Depends, Request, Security, routing
+from fastapi.dependencies.utils import get_parameterless_sub_dependant
+from fastapi.security import OAuth2PasswordBearer, SecurityScopes
+from pydantic import BaseModel, Field
+from treelib import Node, Tree
+
+from api_frame.exception import QureyError
+from api_frame.meta import registered_resources
+from api_frame.scope import _SCOPE_DECLARATIONS_ATTR, ScopeConfig
+
+
+class ScopeTree:
+    def __init__(self, project_scopes: list[dict]) -> None:
+        self.project_scopes = project_scopes
+        self.scope_dict = {}
+        self.scope_tree = Tree()
+
+        for scope in project_scopes:
+            self.scope_dict[scope["scope"]] = scope["id"]
+            node = Node(data=scope["scope"], tag=scope["name"], identifier=scope["id"])
+            if scope["pid"] is not None:
+                self.scope_tree.add_node(node, parent=scope["pid"])
+            else:
+                self.scope_tree.add_node(node)
+
+    def scopes(self):
+        scopes = {}
+        for scope in self.project_scopes:
+            scopes.update({scope["scope"]: scope["name"]})
+        return scopes
+
+    def sub(self, tag: str) -> list:
+        sub = []
+        nodeid = self.scope_dict[tag]
+        children = self.scope_tree.children(nodeid)
+        for child in children:
+            childlist = self.sub(child.data)
+            sub.append(child.data)
+            sub = sub + childlist
+        return sub
+
+    def children(self, tags: list) -> list:
+        family = []
+        for node in tags:
+            family.append(node)
+            family = family + self.sub(node)
+        family = list(set(family))
+        return family
+
+    def to_base(self, checked: list) -> str:
+        family = []
+        for node in checked:
+            family.append(node)
+            family = family + self.sub(node)
+        family = list(set(family))
+        ba_len = math.ceil(len(self.scope_dict) / 6) * 6
+        ba = bitarray(ba_len)
+        ba.setall(0)
+        for item in self.scope_dict:
+            if item in family:
+                ba[self.scope_dict[item]] = 1
+        return str(ba2base(64, ba))
+
+    def to_sope(self, ba_str: str) -> list:
+        ba = base2ba(64, ba_str)
+        scopes = []
+        for item in self.scope_dict:
+            index = self.scope_dict[item]
+            if index <= len(ba) - 1 and ba[index]:
+                scopes.append(item)
+        return scopes
+
+
+class User(BaseModel):
+    id: str = Field(..., title="id")
+    name: str = Field(None, title="姓名")
+    headimage: str = Field(None, title="头像")
+    token: str = Field(None, title="token")
+    scope: list[str] = Field(None, title="scope")
+
+
+class Auth(metaclass=abc.ABCMeta):
+    """权限验证基类"""
+
+    def __init__(self, cert, token_url: str = None, scopes: list[dict] = None):
+        self.cert = cert
+        self.token_url = token_url
+        self.scope_tree = ScopeTree(scopes)
+        self.user = None
+
+    def _scopes(self) -> dict:
+        # 项目全部的scopes集合
+        return self.scope_tree.scopes()
+
+    def _oauth(self) -> OAuth2PasswordBearer:
+        # 权限依赖
+        oauth2_scheme = OAuth2PasswordBearer(
+            tokenUrl=self.token_url,
+            scopes=self._scopes(),
+        )
+
+        return oauth2_scheme
+
+    def scope(self, ba_str) -> list:
+        """
+        64位的scope字符串转成列表
+        :param ba_str: 64进制字符串
+        :return: token中的scope对应的列表
+        """
+        return self.scope_tree.to_sope(ba_str)
+
+    @abc.abstractmethod
+    async def auth(self, security_scopes: SecurityScopes, token: str) -> User:
+        """子类必须实现，权限验证方法"""
+        raise NotImplementedError
+
+
+class SecurityConfig(Auth):
+    """权限安全配置"""
+
+    def __init__(
+        self,
+        api_scopes: dict,
+        cert: str,
+        token_url: str = None,
+        scopes: list[dict] = None,
+        strict: bool = False,
+    ):
+
+        super().__init__(cert, token_url, scopes)
+        self.api_scopes = api_scopes
+        self.res = None
+        self.strict = strict
+
+    def get_scopes(self, api_url, method):
+        """
+        获取接口方法对应scope
+        Args:
+            api_url: api链接
+            method: 方法
+
+        Returns: scope
+
+        """
+        api = self.api_scopes.get(api_url)
+        if not api:
+            return None
+        scope = api.get(method, None)
+        return scope
+
+    async def api_auth(self, api_url, method) -> bool:
+        api_scope = self.get_scopes(api_url=api_url, method=method)
+        if api_scope is None:
+            return True
+        if not self.user or not self.user.scope:
+            return False
+        return bool(set(api_scope).intersection(set(self.user.scope)))
+
+    def _get_auth(self, res):
+        """
+        生成权限判断函数
+        Args:
+            res: 资源
+
+        Returns:
+
+        """
+
+        async def wrapper(
+            request: Request, security_scopes: SecurityScopes, token: str = Depends(self._oauth())
+        ) -> User:
+            include_param = request.query_params.get("include")
+            if include_param:
+                path_parts = request.scope.get("path").split("/")
+                for include in include_param.split(","):
+                    if include.count(".") == 1:
+                        rel_name, relrel_name = include.split(".")
+                        has_id = "id" in request.path_params
+                        if len(path_parts) >= 2 and has_id and request.path_params.get("id") == path_parts[-2]:
+                            res_temp = res.rel_resources()
+                            last_part = path_parts[-1]
+                            if last_part not in res_temp:
+                                raise QureyError(detail=f"include 参数 {rel_name} 不存在")
+                            rel_res_temp = res_temp[last_part]
+                            rel_resource = registered_resources.get(rel_res_temp.rel_resource)
+                            rels = rel_resource.rel_resources()
+                        else:
+                            rels = res.rel_resources()
+                        if rel_name not in rels:
+                            raise QureyError(detail=f"include 参数 {rel_name} 不存在")
+                        rel_res = rels[rel_name]
+                        rel_resource = registered_resources.get(rel_res.rel_resource)
+                        rel_rels = rel_resource.rel_resources()
+                        if relrel_name not in rel_rels:
+                            raise QureyError(detail=f"include 参数 {relrel_name} 不存在")
+                        relrel_res = registered_resources.get(rel_rels[relrel_name].rel_resource)
+                        scope = self.get_scopes(api_url=relrel_res.Meta.link, method="GET")
+                        await self.auth(security_scopes=SecurityScopes(scopes=scope), token=token)
+
+            user = await self.auth(security_scopes, token)
+            self.user = user
+            return user
+
+        return wrapper
+
+    def run(self, res):
+        # Check if resource class has @scope declarations
+        scope_declarations = getattr(res, _SCOPE_DECLARATIONS_ATTR, None)
+        scope_config = None
+        if scope_declarations:
+            scope_config = ScopeConfig(api_scopes=self.api_scopes)
+
+        for route in res.route.routes:
+            api_url = route.path_format[len(res.prefix) :]
+            method = list(route.methods)[0]
+            if scope_config:
+                scopes = scope_config.get_scopes(res, api_url, method)
+            else:
+                scopes = self.get_scopes(api_url=api_url, method=method)
+            if scopes is not None:
+                if isinstance(route, routing.APIRoute):
+                    route.dependant.dependencies.insert(
+                        0,
+                        get_parameterless_sub_dependant(
+                            depends=Security(self._get_auth(res), scopes=scopes), path=route.path_format
+                        ),
+                    )
+            else:
+                msg = f"接口没有配置权限，请确认接口权限是否公开，不公开请配置权限。接口：{route}"
+                if self.strict:
+                    raise RuntimeError(msg)
+                logger.warning(
+                    "接口没有配置权限，请确认接口权限是否公开，不公开请配置权限。接口：%s", route
+                )
+        return res