labull-framework 0.1.0__py3-none-any.whl

labull_framework/magic_block/dispatch.py

@@ -0,0 +1,314 @@
+"""
+块后端的**唯一请求入口**：`/bx/<uuid>/<类名>.<方法名>`，一律 POST。
+
+🔴 七步的**顺序就是判据**：CSRF（中间件已做，不豁免）→ 身份（401）→ 块存在且启用
+   （不存在 404 / 停用 403 + 原因）→ 路由名（404，**列出这一块真实有的全部路由名**）→
+   权限（Django 的 `has_perm`；没声明 permission ⇒ 只要登录）→ 读 body → 执行（软超时 504）。
+🔴 `ctx` 的构造**只在这里**（`build_context()`），5 个键；`user` **只从 `request.user` 来**。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+from typing import Any
+
+from django.db import close_old_connections
+from django.http import HttpRequest, HttpResponse
+
+from ..env import BLOCK_CONFIG_PREFIX
+from ..jsonio import NO_IDENTITY_MESSAGE, problem
+from .registry import REGISTRY
+from .sdk import (
+    MAX_BODY_BYTES,
+    ROUTE_TIMEOUT_SECONDS,
+    BlockCtx,
+    BlockUser,
+    MagicBackendHTTPError,
+    block_json,
+    errors,
+)
+
+logger = logging.getLogger('labull_framework.magic_block')
+
+
+class _Timeout(MagicBackendHTTPError):
+    """软超时（504）。
+
+    ⚠️ 它刻意**不在 `errors` 里**：那六个是块作者的书写契约（作者写不出 504 的 handler），
+       这一条是分发器自己的语义。
+    """
+
+    status = 504
+
+#: 一律 POST：路径是对的、动词不对 ⇒ **405**（不是 404，报文要说清这一点）。
+ALLOWED_METHOD = 'POST'
+
+#: 正文一次读多少（分块读、边读边数）。
+_CHUNK = 64 * 1024
+
+
+# ──────────────────────────── 正文 ────────────────────────────
+
+
+def _is_json(content_type: str) -> bool:
+    """这次请求的正文是不是 JSON。
+
+    🔴 **没写 `Content-Type` 也当 JSON**：页面上那些 `fetch` 常常这么发，
+       当文件字节会让 handler 收到一堆字节而不是参数（最难查的一种"参数全丢"）。
+    """
+    essence = (content_type or '').split(';')[0].strip().lower()
+    return essence in ('', 'application/json') or essence.endswith('+json')
+
+
+def read_call_body(request: HttpRequest) -> Any:
+    """拿到这一条调用的 `params`。
+
+    · JSON（`application/json` / `+json` / **没写**）⇒ 解成 `dict`；解不开就 400 并带原文，
+      **绝不静默当空对象**（静默的后果是参数全丢，比报错难查得多）；
+      顶层不是对象（数组 / 数字 / null）⇒ 包成 `{'body': 原值}`（params 是不是 dict 对作者恒定）。
+    · 其它 `Content-Type` ⇒ **原样回 bytes**（块前端传文件走这条）。
+
+    🔴 **不用 `request.body`**：那会先撞上 Django 的 `DATA_UPLOAD_MAX_MEMORY_SIZE`（默认 2.5 MB），
+       超了抛的是与"太大"无关的错。这里分块读、**边读边数**（`Content-Length` 客户端可以伪造）。
+    """
+    length = request.META.get('CONTENT_LENGTH') or ''
+    try:
+        declared = int(str(length).strip())
+    except (TypeError, ValueError):
+        declared = 0
+    if declared > MAX_BODY_BYTES:
+        raise errors.BadRequest(_too_large(declared))
+
+    chunks: list[bytes] = []
+    total = 0
+    while True:
+        chunk = request.read(_CHUNK)
+        if not chunk:
+            break
+        total += len(chunk)
+        if total > MAX_BODY_BYTES:
+            raise errors.BadRequest(_too_large(total))
+        chunks.append(chunk)
+    raw = b''.join(chunks)
+
+    if not _is_json(request.META.get('CONTENT_TYPE', '')):
+        return raw
+    text = raw.decode('utf-8', errors='replace').strip()
+    if not text:
+        # 空正文 = 一次"没有参数"的合法调用。
+        return {}
+    try:
+        parsed = json.loads(text)
+    except ValueError as exc:
+        raise errors.BadRequest(f'请求正文不是合法 JSON（{exc}）：请把参数作为 JSON 放进正文') from exc
+    return parsed if isinstance(parsed, dict) else {'body': parsed}
+
+
+def _too_large(size: int) -> str:
+    """正文太大的那句话（提前拦与边读边数给的是同一句）。"""
+    return (
+        f'请求正文太大：至少 {size} 字节，上限是 {MAX_BODY_BYTES} 字节（{MAX_BODY_BYTES // 1024 // 1024} MiB）'
+    )
+
+
+# ──────────────────────────── ctx 的构造（唯一一处） ────────────────────────────
+
+
+def _names(values: Any) -> tuple[str, ...]:
+    """Django 的取值集合（组 / 权限）→ 名字元组（`.values_list` 回的是元组，别的形状一律当空）。"""
+    out: list[str] = []
+    for item in values or ():
+        text = str(item)
+        if text and text not in out:
+            out.append(text)
+    return tuple(out)
+
+
+def user_of(user: Any) -> BlockUser:
+    """`request.user` → `BlockUser`（**认人只认会话**，绝不从 body 取）。
+
+    🔴 `get_all_permissions()` 回的**就是** `app_label.codename` 那种字符串（Django 原生：
+       直接权限与组权限已经合在一起了），所以这里只做去重与排序，不自己拼。
+    🔴 匿名用户也映射得出来：块里的判据不用先判空。
+    """
+    if user is None or not getattr(user, 'is_authenticated', False):
+        return BlockUser(id='', username='', work_id='', name='', is_staff=False)
+    return BlockUser(
+        id=str(user.pk or ''),
+        username=str(getattr(user, 'get_username', lambda: '')() or ''),
+        work_id=str(getattr(user, 'work_id', '') or ''),
+        name=str(getattr(user, 'name', '') or ''),
+        is_staff=bool(getattr(user, 'is_staff', False)),
+        groups=_names(user.groups.values_list('name', flat=True)),
+        permissions=_names(sorted(user.get_all_permissions())),
+    )
+
+
+def block_config() -> dict[str, str]:
+    """`ctx.config` —— 环境里**带前缀**的那些（剥掉前缀当键）。
+
+    🔴 前缀那一个字面量**只有一处**（`env.BLOCK_CONFIG_PREFIX`）：两处各写一份，
+       漂了就是"配了却读不到"（而块作者只会以为自己写错了键名）。
+    🔴 **白名单不是黑名单**：里面有数据库连接串与登录密钥，漏出去任何一条都等于把信任链交出去，
+       而块代码是运行时加载的数据（作者随时改、保存即生效）。
+    🔴 **没配的键不存在**（不造空串）：配成空串照给（那是一次明确的配置动作）。
+    """
+    out: dict[str, str] = {}
+    for name, value in os.environ.items():
+        if not name.startswith(BLOCK_CONFIG_PREFIX):
+            continue
+        key = name[len(BLOCK_CONFIG_PREFIX):]
+        if key:
+            out[key] = str(value)
+    return out
+
+
+def build_context(request: HttpRequest, block: Any) -> BlockCtx:
+    """组装交给 handler 的 `ctx`（**4 个键，见 `sdk.CTX_KEYS`**）。
+
+    🔴 构造只在这一处：多一个键就是给块代码多一样能力（而契约、文档、校验三边都要跟着改）。
+    """
+    return BlockCtx(
+        user=user_of(getattr(request, 'user', None)),
+        config=block_config(),
+        request=request,
+        block={
+            'id': block.id,
+            'module': block.module or '',
+            'name': block.name or '',
+            'brief': block.brief or '',
+        },
+    )
+
+
+# ──────────────────────────── 执行（软超时） ────────────────────────────
+
+
+def run_with_timeout(handler: Any, ctx: BlockCtx, params: Any) -> Any:
+    """跑一条 handler，最多等 `ROUTE_TIMEOUT_SECONDS` 秒。
+
+    🔴 **超时只回话、不停别人**（Python 杀不掉正在跑的线程）：请求方立刻收到 504，
+       handler 继续在后台跑完、结果被丢掉。报文必须说清这一点 —— 否则调用方会以为可以安全重试。
+    🔴 工作线程第一件事与 finally 都 `close_old_connections()`：Django 的数据库连接是线程局部的。
+    """
+    outcome: dict[str, Any] = {}
+
+    def work() -> None:
+        close_old_connections()
+        try:
+            outcome['value'] = handler(ctx, params)
+        except BaseException as exc:  # noqa: BLE001 —— 原样带回主线程去分类
+            outcome['error'] = exc
+        finally:
+            close_old_connections()
+
+    worker = threading.Thread(target=work, name='labull-block-call', daemon=True)
+    worker.start()
+    worker.join(ROUTE_TIMEOUT_SECONDS)
+    if worker.is_alive():
+        raise _Timeout(
+            f'调用超时（超过 {ROUTE_TIMEOUT_SECONDS} 秒）：这次请求不再等下去，但那个方法**还在后台跑**'
+            '（Python 停不掉正在跑的线程）—— 所以别把它当"没执行"直接重试；'
+            '长时间任务请改成"先落状态、再异步处理"的形态'
+        )
+    if 'error' in outcome:
+        raise outcome['error']
+    return outcome.get('value')
+
+
+# ──────────────────────────── 一次调用的完整流程 ────────────────────────────
+
+
+def call_route(request: HttpRequest, uuid: str, route: str) -> tuple[int, Any]:
+    """按顺序处理一条块调用，返回 `(状态码, 要回的内容)`（**不抛**：401 / 403 / 404 都是有语义的答复）。"""
+    # ② 身份：只认会话（`AuthenticationMiddleware` 挂的 `request.user`）。
+    #    🔴 不看 `Authorization` 头：Django 侧的身份只有一个来源，两个来源就是两个真源。
+    user = getattr(request, 'user', None)
+    if user is None or not getattr(user, 'is_authenticated', False):
+        return 401, {'message': NO_IDENTITY_MESSAGE}
+
+    # ③ 块存在且启用。🔴 停用要**明确拒绝**（403 + 原因），不装成"没有这个块"。
+    from ..models import MagicBlock
+
+    if not uuid:
+        return 404, {'message': '路径里没有块的 uuid：要写成 /bx/<uuid>/<类名>.<方法名>'}
+    row = (
+        MagicBlock.objects.filter(id=uuid)
+        .only('id', 'module', 'name', 'brief', 'enabled', 'disabled_reason')
+        .first()
+    )
+    if row is None:
+        return 404, {'message': f'没有这个块：{uuid}'}
+    if row.enabled is False:
+        return 403, {
+            'message': f'这个块已停用：{row.disabled_reason or "体检没通过"}'
+            '（管理员在管理台点一次校验、改好之后会自动恢复启用）'
+        }
+
+    # ④ 路由表：版本对不上就在这一步重新编译（**"保存即生效"落在这里**）。
+    try:
+        backend = REGISTRY.get(uuid)
+    except LookupError:
+        return 404, {'message': f'没有这个块：{uuid}'}
+    except Exception as exc:  # noqa: BLE001 —— 读库 / 编译出岔子要说清是哪一步
+        return 500, {'message': f'读这个块的后端代码失败：{exc}'}
+
+    names = backend.route_names()
+    known = ' / '.join(names) if names else '（没有带 @MagicBackendAPI 的方法）'
+    if '.' not in str(route or ''):
+        return 404, {
+            'message': f'路由名要写成「类名.方法名」（例如 Customer.create），收到的是：{route or "（空）"}；'
+            f'这个块有：{known}'
+        }
+    compiled = backend.routes.get(route)
+    if compiled is None:
+        # 🔴 必须列出这一块真实有的**全部**路由名：客户端那侧没有名字白名单，写错名字的反馈全靠这句。
+        return 404, {'message': f'没有这个接口：{route}；这个块有：{known}'}
+
+    # ⑤ 权限：没声明 ⇒ 只要登录；声明了就走 Django 的 `has_perm`（组与权限是框架的事）。
+    if compiled.permission and not user.has_perm(compiled.permission):
+        return 403, {'message': f'没有权限调用 {route}：这条接口要 {compiled.permission}'}
+
+    # ⑥ 正文只在这里读一次。
+    try:
+        params = read_call_body(request)
+    except MagicBackendHTTPError as exc:
+        return exc.status, {'message': str(exc)}
+
+    # ⑦ 执行。
+    ctx = build_context(request, row)
+    try:
+        value = run_with_timeout(compiled.handler, ctx, params)
+    except MagicBackendHTTPError as exc:
+        return exc.status, {'message': str(exc)}
+    except Exception as exc:  # noqa: BLE001 —— 块自己的 bug 一律 500，原文照带
+        return 500, {'message': f'{type(exc).__name__}：{exc}'}
+
+    try:
+        text = block_json(value)
+    except MagicBackendHTTPError as exc:
+        return exc.status, {'message': str(exc)}
+    # 🔴 正文已经是编好的 JSON 文本（日期 / 金额已转成字符串）：交给出口时**原样**当正文 ——
+    #    再让 Django 编一遍，那一步就整个被绕过去了。
+    return 200, text
+
+
+def block_dispatch_view(request: HttpRequest, uuid: str, route: str) -> HttpResponse:
+    """`/bx/<uuid>/<类名>.<方法名>` —— 一律 POST。
+
+    🔴 **CSRF 由中间件做**（这条路由不豁免）：这里没有、也不该有第二道 CSRF 判据。
+    """
+    if request.method != ALLOWED_METHOD:
+        return problem(f'块后端只认 {ALLOWED_METHOD}（参数放进 JSON 正文）', 405)
+    status, payload = call_route(request, uuid, route)
+    if status == 200:
+        # 🔴 正文已经是编好的 JSON 文本：**原样**当正文（再编一遍就绕过 `block_json` 的编码规则）。
+        return HttpResponse(str(payload), content_type='application/json; charset=utf-8')
+    # 🔴 出错一律走 `problem()`：线格式只有一种（`{statusCode, message}`）——
+    #    两处各拼一份的下场是前端要按两种形状判错。
+    message = payload.get('message') if isinstance(payload, dict) else str(payload)
+    logger.warning('[magic-block] /bx/%s/%s → %s：%s', uuid, route, status, message)
+    return problem(str(message or ''), status)