labull-framework 1.0.2__tar.gz → 1.0.4__tar.gz

{labull_framework-1.0.2/labull_framework.egg-info → labull_framework-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labull-framework
-Version: 1.0.2
+Version: 1.0.4
 Summary: Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks
 Author: Labull Framework
 License-Expression: MIT

{labull_framework-1.0.2 → labull_framework-1.0.4}/labull_framework/magic_block/export.py

@@ -24,8 +24,9 @@ from __future__ import annotations
 
 import os
 import re
+import threading
 from pathlib import Path
-from typing import Any, Iterable
+from typing import Any, Callable, Iterable
 
 from . import devkit, parallel, validate
 from .sdk import (
@@ -611,6 +612,12 @@ def _starter_manifest(row: Any) -> str:
 # ──────────────────────────── 回：目录 → 逐块对比（两种入口，一套判据） ────────────────────────────
 
 
+#: 值得跑一遍"保存那套判据"的两种状态：**磁盘上那份与库里不一样**（`modified`），或者库里还没有
+#: 这一行（`not-in-db`）。`unchanged` 的**不跑** —— 库里那份就是它，而它当初保存时已经判过；
+#: 再判一遍纯白付，而这一步正是读回最贵的地方（见 `_judge()` 里那段说明）。
+CHECKED_STATUSES = ('modified', 'not-in-db')
+
+
 class _Collect:
     """一次扫描攒下来的东西。
 
@@ -628,7 +635,11 @@ class _Collect:
         self.skipped_folders: list[str] = []
 
 
-def scan_folders(upload: dict, include_missing: bool = False) -> dict:
+def scan_folders(
+    upload: dict,
+    include_missing: bool = False,
+    progress: Callable[[dict], None] | None = None,
+) -> dict:
     """**浏览器扫到的**那个目录，与库里的块逐块比一遍（只读，不写库）。
 
     :param upload: `{'root'?, 'folders': [{'where', 'files'}], 'failures'?, 'truncated'?}`
@@ -666,16 +677,21 @@ def scan_folders(upload: dict, include_missing: bool = False) -> dict:
         files = {str(name): str(body) for name, body in raw.items()} if isinstance(raw, dict) else {}
         collect.files += len(files)
         collect.folders.append({'abs': where, 'where': where, 'segments': segments, 'files': files})
-    return _judge(str(given.get('root') or ''), collect, include_missing)
+    return _judge(str(given.get('root') or ''), collect, include_missing, progress)
 
 
-def read_dir(path: str, include_missing: bool = False) -> dict:
+def read_dir(
+    path: str,
+    include_missing: bool = False,
+    progress: Callable[[dict], None] | None = None,
+) -> dict:
     """读一个**服务器上的**目录，与库里的块**逐块比一遍**（只读，不写库）。
 
     ⚠️ 控制台那条路走 `scan_folders()`（开发目录在用户自己机器上）；这一条留给
        "源码本来就在服务器上"的用法（CLI / 脚本）。两条入口的判断完全一样。
     :param include_missing: 默认 `False` —— 路径往往只指到一个块或一个模块的文件夹，
         "没扫到"不等于"要删掉"，默认列出来只会误导。
+    :param progress: 进度回调（可选），形状见 `_judge()`。
     """
     given = str(path or '').strip()
     collect = _Collect()
@@ -693,7 +709,7 @@ def read_dir(path: str, include_missing: bool = False) -> dict:
         return _result(str(root), collect, [], [])
 
     _discover(root, collect, [], 0)
-    return _judge(_posix(str(root)), collect, include_missing)
+    return _judge(_posix(str(root)), collect, include_missing, progress)
 
 
 def _new_block(disk: dict) -> dict:
@@ -738,8 +754,21 @@ def _new_block(disk: dict) -> dict:
     }
 
 
-def _judge(root: str, collect: _Collect, include_missing: bool) -> dict:
-    """配对 + 逐文件比 + 提前算"能不能存"（**两种读入口共用这一处**）。"""
+def _judge(
+    root: str,
+    collect: _Collect,
+    include_missing: bool,
+    progress: Callable[[dict], None] | None = None,
+) -> dict:
+    """配对 + 逐文件比 + 提前算"能不能存"（**两种读入口共用这一处**）。
+
+    :param progress: 进度回调（可选）。**只在流式读回那条口上有值**（见 `views.read_view`）：
+        它会收到 `{'phase': 'judged', 'blocks', 'checks'}` 与每个块算完时的
+        `{'phase': 'check', 'done', 'total', 'id', 'name', 'ok'}` —— 前端据此画进度条，
+        也因为**字节一直在往回走**，网关不会因为"半天没有回话"把整条请求掐成 504。
+        🔴 回调在**池子的线程里**被调用（见 `parallel.map_blocks` 那条边界）：
+        只许做"记下来"这种线程安全的事，**不许碰数据库**。所以这里传出去的是**纯数据**。
+    """
     pool = list(_model().objects.all())
     matched, orphan = _assign(collect.folders, pool)
     used = {pool[index].id: collect.folders[disk]['where'] for disk, index in matched.items()}
@@ -783,13 +812,47 @@ def _judge(root: str, collect: _Collect, include_missing: bool) -> dict:
             )
 
     # 🔴 每条 diff 上用**保存那套判据**提前算结论（"扫描说能存、真存又不过"是同一件事的两个说法）。
-    # 🔴 这一段是整条读回里**最贵的一步**（每块要起两个子进程：试加载 + 引用深检，实测 0.83s/块）
-    #    ⇒ 并发算、再按原顺序贴回那几条 diff 上（20 个块：16.7s → 5.5s）。
+    # 🔴 这一段是整条读回里**最贵的一步**（每块要起两个子进程：试加载 + 引用深检，实测 0.83s/块；
+    #    真实项目里块大一些，5 秒/块也常见）⇒ 并发算、再按原顺序贴回那几条 diff 上。
     #    ⚠️ 池子里跑的是**纯函数**（`validate.check_block` 不碰数据库），写库/改对象全在这条线程上。
-    targets = [item for item in blocks if item.get('canApply', False) and item['files']]
-    messages_of = parallel.map_blocks(
-        targets, lambda item: [message for _stage, message in validate.check_block(item['files'])],
-    )
+    #
+    # 🔴 **只校验"值得校验"的那两种状态**（`modified` / `not-in-db`），`unchanged` 的一律跳过。
+    #    为什么（这条是 504 那个问题的正路，量出来的）：
+    #      · `unchanged` = 磁盘上那一包与库里那一份**逐字节相同**。库里那一份是**当初保存时**
+    #        过过同一套判据的（保存那条路一个字都没松），再跑一遍不会得出别的结论 —— 纯白付；
+    #      · 而这一段的代价并不小：8 个块（全是没改动的）量到 **5.8 秒**、每次都真起 16 个子进程
+    #        （`scratch/probe/read-bench.py` 那一趟）。一个真实的开发目录 23 个块里通常只有 8 个改过
+    #        ⇒ 过去有 **2/3 的时间在重复校验没动过的东西**，而线上 gunicorn/nginx/ALB 都在 60 秒那道线上。
+    #      · 跳过它**不会**让错误溜进库：真有人手动勾上一个 `unchanged` 的块去存，`write_dir()` →
+    #        `service.save()` 会**再判一次**（判据只有那一处），失败照旧逐条报出来。
+    #    ⚠️ 代价是有意接受的：读回的清单里 `unchanged` 那几条不再显示"不能存：…" —— 没改动的块
+    #        本来就不该在这一趟里替它做体检（它上一次保存时已经做过）。
+    targets = [
+        item for item in blocks
+        if item.get('canApply', False) and item['files'] and item['status'] in CHECKED_STATUSES
+    ]
+    if progress is not None:
+        # 配对与逐文件比已经做完（这一段是便宜的）：先把"要校验几个"告诉调用方，
+        # 后面的进度才有分母。⚠️ 这一步在**调用线程**里跑，可以放心用。
+        progress({'phase': 'judged', 'blocks': len(blocks), 'checks': len(targets)})
+    done = {'n': 0}
+    done_lock = threading.Lock()
+
+    def checked(item: dict) -> list[str]:
+        messages = [message for _stage, message in validate.check_block(item['files'])]
+        if progress is not None:
+            # 🔴 只报"第几个算完了"，结论仍由调用线程按原顺序贴回（顺序是契约）。
+            with done_lock:
+                done['n'] += 1
+                sofar = done['n']
+            progress({
+                'phase': 'check', 'done': sofar, 'total': len(targets),
+                'id': str(item.get('id') or ''), 'name': str(item.get('name') or ''),
+                'ok': not messages,
+            })
+        return messages
+
+    messages_of = parallel.map_blocks(targets, checked)
     for item, messages in zip(targets, messages_of):
         if messages:
             item['canApply'] = False

{labull_framework-1.0.2 → labull_framework-1.0.4}/labull_framework/magic_block/parallel.py

@@ -13,6 +13,8 @@
      · `export._judge()` —— 并发算逐块校验结论，再顺序贴回那几条 diff；
      · `health.check_all_blocks()` —— 并发算结论，再顺序写那四列；
      · `export.write_dir()` —— 只并发"预热"校验结果，保存本身仍在调用线程里（见那里的说明）。
+   ⚠️ `map_blocks(..., on_done=...)` 那个**进度回调**也在池子的线程里跑（`export._judge()` 用它
+     给"流式读回"报进度）—— 所以它同样只许做"记下来"这种线程安全的事，**不许碰数据库**。
 
 🔴 **为什么要有上限**：一次全量体检 = N 个块 × 2 个子进程，每个子进程都要跑一遍 `django.setup()`。
    不限并发的话，20 个块就能同时拉起几十个 Python 进程：内存与 CPU 一起打满，
@@ -89,7 +91,11 @@ def _settings_count() -> Any:
     return None
 
 
-def map_blocks(items: Iterable[T], worker: Callable[[T], R]) -> list[R]:
+def map_blocks(
+    items: Iterable[T],
+    worker: Callable[[T], R],
+    on_done: Callable[[int, T, R], None] | None = None,
+) -> list[R]:
     """把 `worker` 铺到每一项上，**结果与入参一一对应（原顺序）**。
 
     🔴 **顺序是契约**：调用方拿回去是"第几个块 → 哪一条结论"，错位就是把 A 的结论贴到 B 上。
@@ -99,13 +105,38 @@ def map_blocks(items: Iterable[T], worker: Callable[[T], R]) -> list[R]:
         而控制台里一大半操作都是单个块），顺便也让"串行那一套"仍有一条现成的退路。
     🔴 `worker` 抛异常就**照原样抛**（与串行循环同一种行为：一个块炸了不该被悄悄吞掉）。
         要"一个块失败不拖累别的块"，由 worker 自己接住 —— `health.evaluate()` 就是这么写的。
+    🔴 `on_done(index, item, result)`：**每算完一个就报一次**（进度条 / 流式回话用它）。
+        它在**池子的线程里**被调用（串行那一路就在调用线程里），所以只能做"把一件事记下来"
+        这种线程安全的动作（`queue.Queue.put` / 计数）—— 照样**不许碰数据库**，与 worker 同一条边界。
+        传了它就一定会在**每一项**上都调用一次（异常那一路不调用：那一项没有结果可报）。
     """
     rows = list(items)
     if len(rows) <= 1:
-        return [worker(item) for item in rows]
+        out: list[R] = []
+        for index, item in enumerate(rows):
+            result = worker(item)
+            out.append(result)
+            if on_done is not None:
+                on_done(index, item, result)
+        return out
     size = min(worker_count(), len(rows))
     if size <= 1:
-        return [worker(item) for item in rows]
+        out = []
+        for index, item in enumerate(rows):
+            result = worker(item)
+            out.append(result)
+            if on_done is not None:
+                on_done(index, item, result)
+        return out
+    numbered = list(enumerate(rows))
+
+    def run_task(pair: tuple[int, T]) -> R:
+        index, item = pair
+        result = worker(item)
+        if on_done is not None:
+            on_done(index, item, result)
+        return result
+
     # ⚠️ `list(...)` 要写在 `with` 里面：`map()` 是惰性的，出了 `with` 池子已经关了。
     with ThreadPoolExecutor(max_workers=size, thread_name_prefix='labull-block') as pool:
-        return list(pool.map(worker, rows))
+        return list(pool.map(run_task, numbered))

{labull_framework-1.0.2 → labull_framework-1.0.4}/labull_framework/magic_block/views.py

@@ -523,6 +523,16 @@ def read_view(request: HttpRequest) -> HttpResponse:
         开发目录在用户自己机器上（导出就铺在那里），后端读不到它：由浏览器照导出报文里的
         `rules` 扫一遍，把"我扫到了什么"递上来（形状见 `frontend/magic-block/src/localfs.ts`）。
       · `{'path': '<服务器上的绝对路径>'}` —— 后端自己读那个目录（源码本来就在服务器上时用）。
+
+    🔴 **`stream: true` ⇒ 一行一个 JSON（NDJSON），边算边回**（1.0.3 起）：
+        这一条口一次要把整个目录收下来、再**逐块**做保存前那套判据（试加载 + 引用深检，
+        实测 0.8~3.7 秒/块）。块一多，整条请求就要几十秒"一声不响" —— 前置网关（nginx
+        `proxy_read_timeout` 默认 60 秒，很多云网关只给 30 秒）等不到任何字节就把它掐成
+        **504**，前端只看到一句 `请求失败：504 /magic-blocks/read`，而真正的原因
+        （"我在算第 7 个块"）一个字都传不出来。流式之后**字节一直在往回走**，网关不会掐，
+        前端也能画出进度条。
+        ⚠️ 老前端不发这个键 ⇒ 走原来的整份 JSON（那条路一个字都没改）。
+        ⚠️ 这一层只加"怎么回话"，判据仍然是 `_judge()` 那一处。
     """
     refused = _method(request, 'POST')
     if refused is not None:
@@ -530,11 +540,96 @@ def read_view(request: HttpRequest) -> HttpResponse:
     from .export import read_dir, scan_folders
 
     body = _body(request)
+    if body.get('stream') is True:
+        return _read_stream(body)
     if isinstance(body.get('folders'), list):
         return _json(scan_folders(body, include_missing=body.get('includeMissing') is True))
     return _json(read_dir(str(body.get('path') or ''), include_missing=body.get('includeMissing') is True))
 
 
+def _line(event: dict) -> bytes:
+    """一行 NDJSON（`ensure_ascii=False`：中文原样过去，前端不用再解一层）。"""
+    return (json.dumps(event, ensure_ascii=False) + '\n').encode('utf-8')
+
+
+def _read_stream(body: dict) -> HttpResponse:
+    """读回那一趟的**流式**回话（形状见 `read_view` 那段说明）。
+
+    事件（一行一个 JSON 对象）：
+      · `{'type': 'start', 'folders', 'files'}` —— 立刻发，先说清"这一趟要处理多少"；
+      · `{'type': 'judged', 'blocks', 'checks'}` —— 配对与逐文件比完，后面要校验几个；
+      · `{'type': 'check', 'done', 'total', 'id', 'name', 'ok'}` —— 每校验完一个块就发一条；
+      · `{'type': 'ping', 'seconds'}` —— 10 秒没有别的事就发一次心跳（**保活**用）；
+      · `{'type': 'result', 'result': {...}}` —— 整份结果（形状与整份 JSON 那条口**逐字相同**）；
+      · `{'type': 'error', 'message'}` —— 后端炸了（这一趟没有结果）。
+    🔴 干活的那一半在**后台线程**里跑：主线程（响应的生成器）只负责把队列里的东西写出去。
+       不这么写的话，`_judge()` 要等全部算完才返回，那"边算边回"就无从谈起。
+       ⚠️ 后台线程会自己开一条数据库连接（Django 的连接是每线程一份），所以 `finally` 里
+       `connections.close_all()` 收掉它 —— 不然每读回一次就漏一条连接。
+    """
+    import queue
+    import threading
+    import time
+
+    from django.db import connections
+    from django.http import StreamingHttpResponse
+
+    from .export import read_dir, scan_folders
+
+    events: queue.Queue = queue.Queue()
+    started = time.monotonic()
+    folders = body.get('folders')
+    folder_count = len(folders) if isinstance(folders, list) else 0
+    file_count = 0
+    if isinstance(folders, list):
+        for item in folders:
+            raw = item.get('files') if isinstance(item, dict) else None
+            file_count += len(raw) if isinstance(raw, dict) else 0
+
+    def work() -> None:
+        try:
+            if isinstance(folders, list):
+                result = scan_folders(
+                    body, include_missing=body.get('includeMissing') is True, progress=events.put)
+            else:
+                result = read_dir(
+                    str(body.get('path') or ''), include_missing=body.get('includeMissing') is True, progress=events.put)
+            events.put({'type': 'result', 'result': result})
+        except BaseException as exc:  # noqa: BLE001 —— 后台线程里炸了也只能从这条口说出去
+            events.put({'type': 'error', 'message': f'{type(exc).__name__}: {exc}'})
+        finally:
+            connections.close_all()
+            events.put(None)
+
+    def generate():
+        yield _line({'type': 'start', 'folders': folder_count, 'files': file_count})
+        thread = threading.Thread(target=work, name='labull-read', daemon=True)
+        thread.start()
+        while True:
+            try:
+                event = events.get(timeout=10)
+            except queue.Empty:
+                # 🔴 心跳不是"假装有进度"：它的唯一作用是**让字节继续流动**（见 `read_view` 那段）。
+                yield _line({'type': 'ping', 'seconds': round(time.monotonic() - started, 1)})
+                continue
+            if event is None:
+                break
+            if isinstance(event, dict) and event.get('phase') == 'judged':
+                yield _line({'type': 'judged', 'blocks': event.get('blocks', 0), 'checks': event.get('checks', 0)})
+                continue
+            if isinstance(event, dict) and event.get('phase') == 'check':
+                yield _line({'type': 'check', **{key: value for key, value in event.items() if key != 'phase'}})
+                continue
+            yield _line(event if isinstance(event, dict) else {'type': 'event', 'event': str(event)})
+
+    response = StreamingHttpResponse(generate(), content_type='application/x-ndjson; charset=utf-8')
+    # 🔴 让 nginx **别缓冲**：缓冲会把这一串攒起来一起发，"边算边回"就等于没有（进度条不动、
+    #    网关那边也可能照样等到超时）。这条头是 nginx 认的约定（不是标准头，浏览器忽略它）。
+    response['X-Accel-Buffering'] = 'no'
+    response['Cache-Control'] = 'no-store'
+    return response
+
+
 @staff_only
 def check_view(request: HttpRequest) -> HttpResponse:
     """`POST /magic-blocks/check` —— 重新体检（默认全量，也可以点名几块），然后**统一写库**。

{labull_framework-1.0.2 → labull_framework-1.0.4/labull_framework.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labull-framework
-Version: 1.0.2
+Version: 1.0.4
 Summary: Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks
 Author: Labull Framework
 License-Expression: MIT

{labull_framework-1.0.2 → labull_framework-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "labull-framework"
-version = "1.0.2"
+version = "1.0.4"
 description = "Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks"
 readme = "README-pypi.md"
 requires-python = ">=3.10"