flode 0.60.3__py3-none-any.whl

flode/server/routes/libraries.py

@@ -0,0 +1,129 @@
+"""Block library エンドポイント (ADR-0029)。
+
+`/api/v1/libraries` 系は ``.flwlib.json`` で配布されるマスク Subsystem 集合を提供する。
+``/api/v1/blocks`` (= Block class registry) と責務分離する: blocks は **コード上の**
+Block class 定義、libraries は **ファイル上の** Subsystem テンプレート。
+
+エンドポイント:
+
+* ``GET /api/v1/libraries`` — 全 library のメタデータ (entry の ``subsystem`` body は
+  含めない; サイズが大きいため)
+* ``GET /api/v1/libraries/{lib}/{entry}`` — 1 entry の subsystem body を含めた詳細
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+
+from ..library_registry import LibraryRegistry, build_library_registry
+
+router = APIRouter(prefix="/libraries", tags=["libraries"])
+
+
+def _registry(request: Request) -> LibraryRegistry:
+    """app.state から library registry を取り出す型安全 helper (lifespan 未起動時 lazy build)。
+
+    .. note::
+
+        本関数の lazy build 経路 (``app.state.library_registry is None``) は
+        **テスト専用**。本番 lifespan (``create_app`` 内) では必ず
+        ``build_library_registry`` を起動時に呼ぶため、このパスに到達したら
+        設定の不整合 (= バグ) を示す。
+    """
+    reg = getattr(request.app.state, "library_registry", None)
+    if reg is None:
+        # テスト fixture 等で lifespan が起動していない場合の lazy build
+        settings = getattr(request.app.state, "settings", None)
+        library_paths = list(getattr(settings, "library_paths", []) or [])
+        bundle_builtin = bool(getattr(settings, "bundle_builtin_libraries", True))
+        reg = build_library_registry(library_paths, bundle_builtin=bundle_builtin)
+        request.app.state.library_registry = reg
+    if not isinstance(reg, LibraryRegistry):
+        raise HTTPException(status_code=500, detail="library_registry state is corrupted")
+    return reg
+
+
+def _entry_metadata_dict(entry: Any) -> dict[str, Any]:
+    """:class:`LibraryEntry` を REST response 用 dict に変換 (subsystem body 抜き)。"""
+    return {
+        "id": entry.id,
+        "display_name": entry.display_name,
+        "display_name_i18n": dict(entry.display_name_i18n),
+        "description": entry.description,
+        "description_i18n": dict(entry.description_i18n),
+        "category_suffix": entry.category_suffix,
+    }
+
+
+def _library_metadata_dict(lib: Any) -> dict[str, Any]:
+    """:class:`Library` を REST response 用 dict に変換 (entries は metadata だけ)。"""
+    return {
+        "name": lib.name,
+        "display_name": lib.display_name,
+        "display_name_i18n": dict(lib.display_name_i18n),
+        "description": lib.description,
+        "description_i18n": dict(lib.description_i18n),
+        "version": lib.version,
+        "entries": [_entry_metadata_dict(e) for e in lib.entries],
+    }
+
+
+@router.get("")
+def list_libraries(request: Request) -> dict[str, Any]:
+    """全 library のメタデータを返す (entry の subsystem body は含めない、ADR-0029)。
+
+    Body サイズ削減のため、各 entry の重い ``subsystem`` (内部 blocks/connections) は
+    ``GET /api/v1/libraries/{lib}/{entry}`` で個別 fetch する設計。
+
+    Returns:
+        ``{"libraries": [...], "load_errors": [...], "schema_version": "libraries.v1",
+        "supported_locales": ["en", "ja"]}``。
+    """
+    # 遅延 import で循環回避 (registry_translations は SUPPORTED_LOCALES のみ使う)
+    from ..registry_translations import SUPPORTED_LOCALES
+
+    reg = _registry(request)
+    return {
+        "libraries": [_library_metadata_dict(lib) for lib in reg.libraries.values()],
+        "load_errors": [{"path": e.path, "message": e.message} for e in reg.load_errors],
+        "schema_version": "libraries.v1",
+        "supported_locales": list(SUPPORTED_LOCALES),
+    }
+
+
+@router.get("/{library_name}/{entry_id}")
+def get_library_entry(request: Request, library_name: str, entry_id: str) -> dict[str, Any]:
+    """1 entry の subsystem body を含めた詳細を返す (ADR-0029)。
+
+    Inline 配置時の drop 経路で frontend が呼ぶ。subsystem body は
+    ``Subsystem.to_dict()`` の出力と byte-identical (= REST 経由でも byte-identical を維持)。
+
+    Returns:
+        ``{"id", "display_name", ..., "subsystem": {"id", "type", "params"}}``。
+
+    Raises:
+        HTTPException: 404 — library / entry が registry に存在しない場合。
+    """
+    reg = _registry(request)
+    lib = reg.libraries.get(library_name)
+    if lib is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Library {library_name!r} not found in registry",
+        )
+    entry = lib.get_entry(entry_id)
+    if entry is None:
+        raise HTTPException(
+            status_code=404,
+            detail=(
+                f"Entry {entry_id!r} not found in library {library_name!r} "
+                f"(available: {[e.id for e in lib.entries]})"
+            ),
+        )
+    return {
+        **_entry_metadata_dict(entry),
+        # ``subsystem`` は ``Subsystem.to_dict()`` の出力 (= byte-identical)
+        "subsystem": entry.subsystem,
+    }

flode/server/routes/models.py

@@ -0,0 +1,67 @@
+"""モデル静的解析ルート (SPEC-0027: SM-D Stage 0、v0.54.0 新設)。
+
+``POST /api/v1/models/resolve-dtypes`` — 影の型解決 (shadow dtype propagation)。
+
+セキュリティ上の要点 (security-reviewer 向け):
+
+- **静的解析のみでユーザーコード (PythonFunction) を一切実行しない**。
+  エンジン (``flode.core.dtypes``) は PythonFunction を含むモデルでは
+  ``_build()`` を呼ばない static mode に縮退する (二経路設計)。
+  そのため ``/simulations`` の python_ack (409) ゲートは不要
+- モデルの構築・path 検証は既存 ``_resolve_simulator`` を再利用
+  (``resolve_workspace_path`` による path traversal 防御込み、400/403/404)
+- 型解決自体の失敗は **HTTP 200 + diagnostics** (Stage 0 は「解析できなかった」
+  ことも測定対象のため、SPEC-0027 Q4)
+
+Note: v0.21.0 で削除された legacy models router とは無関係の新設。
+"""
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from starlette.concurrency import run_in_threadpool
+
+from .simulations import _resolve_simulator, _start_validation_detail
+
+router = APIRouter(prefix="/models", tags=["models"])
+
+
+@router.get("/resolve-dtypes")
+async def resolve_dtypes_get_stub() -> dict[str, Any]:
+    """GET は不可 (blocks router の 405 stub と同じ流儀)。"""
+    raise HTTPException(
+        status_code=405,
+        detail="Use POST /api/v1/models/resolve-dtypes with a JSON body "
+        "({'model': {...}} or {'model_path': '...'}).",
+    )
+
+
+@router.post("/resolve-dtypes")
+async def resolve_dtypes_endpoint(request: Request) -> dict[str, Any]:
+    """影の型解決を行い ``dtypes.v1`` payload を返す (SPEC-0027 §5.2)。
+
+    Request body は ``model_path`` または ``model`` のうち正確に 1 つを含む
+    JSON object (``POST /simulations`` と同じ 2 形式)。実行は一切行わず、
+    シミュレーション結果にも保存ファイルにも影響しない (Stage 0 = 表示・測定のみ)。
+
+    モデル構築と型解決は threadpool で行い、大きいモデルでも event loop
+    (= 実行中シミュレーションの WS 配信) を止めない (security-reviewer SHOULD-2)。
+    """
+    try:
+        payload = await request.json()
+    except ValueError as e:
+        raise HTTPException(
+            status_code=400,
+            detail=_start_validation_detail("Body must be valid JSON"),
+        ) from e
+    if not isinstance(payload, dict):
+        raise HTTPException(
+            status_code=400,
+            detail=_start_validation_detail("Body must be a JSON object"),
+        )
+
+    def _resolve() -> dict[str, Any]:
+        simulator, _display_id = _resolve_simulator(request, payload)
+        return simulator.resolve_dtypes().to_payload()
+
+    return await run_in_threadpool(_resolve)

flode/server/routes/simulations.py

@@ -0,0 +1,355 @@
+"""シミュレーション制御 + WebSocket エンドポイント (ADR-0011 §(1)(2)、ADR-0041 §5)。
+
+v0.21.0: legacy ``model_id`` 受付を削除。``model_path`` (= workspace 相対 path)
+または ``model`` (= インライン dict) のいずれかを必須に。
+
+ADR-0056: シミュレーション開始エラーは構造化 detail で返す
+(``{detail: {category, template_key, ...}}``)。WS の ``error`` メッセージは廃止し、
+``failed`` 1 件に構造化フィールドをマージして送る (= runtime 側で実施)。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import json
+import logging
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request, WebSocket, WebSocketDisconnect
+
+from ...blocks.pythonfunc import (
+    compute_python_digest,
+    get_python_block_policy,
+    iter_python_functions,
+)
+from ...core.simulator import Simulator
+from ...exceptions import (
+    FlodeError,
+    ModelLoadError,
+    PathTraversalError,
+    PythonBlocksDisabledError,
+    SimulationStillRunningError,
+)
+from ..errors import CATEGORY_PYTHON_FUNCTION_UNCONFIRMED, build_failure_payload
+from ..runtime import SimulationManager
+from ..security import resolve_workspace_path
+
+_logger = logging.getLogger("flode.server.routes.simulations")
+
+router = APIRouter(prefix="/simulations", tags=["simulations"])
+
+_INLINE_DISPLAY_ID = "<inline>"
+"""インライン model 経由のシミュレーションの ``model_id`` 表示値 (ADR-0041 §5)。
+
+複数のインライン実行が共存しても ``simulation_id`` で区別できるため、
+``model_id`` 表示は固定値で OK。frontend は ``"<inline>"`` をトラッキング
+タブで「未保存」表示等に使う想定。
+"""
+
+
+def _manager(request: Request) -> SimulationManager:
+    return request.app.state.simulation_manager  # type: ignore[no-any-return]
+
+
+def _start_validation_detail(message: str) -> dict[str, Any]:
+    """ADR-0056 §B-2: start API のシンプルな validation error 用の構造化 detail。
+
+    例外が無いケース (= body の形式違反等) で使う。``ModelLoadError`` や
+    ``BlockSpecError`` 等の例外がある場合は ``build_failure_payload`` を直接使う。
+    """
+    return {
+        "category": "start_validation",
+        "template_key": "error.start_validation",
+        "template_args": {"message": message},
+        "block_id": None,
+        "block_ids": [],
+        "block_type": None,
+        "block_label": None,
+        "t": None,
+        "raw_message": message,
+        "raw_traceback": None,
+    }
+
+
+def _exception_detail(exc: BaseException) -> dict[str, Any]:
+    """例外から start API 用の構造化 detail を組み立てる (ADR-0056 §B-2)。"""
+    return build_failure_payload(exc, simulator=None, t=None)
+
+
+def _python_unconfirmed_detail(simulator: Simulator, digest: str) -> dict[str, Any]:
+    """SPEC-0023 soft gate (ADR-0073 §論点 4 (S)): 409 用の構造化 detail。
+
+    ``template_args.digest`` をクライアントが echo して再送する。この機構は
+    「このモデルは Python を実行する」の告知と同意のための **UX 機構** であり、
+    セキュリティ機構ではない (REST を直接叩けば ack を自分で付けられる)。
+    """
+    entries = list(iter_python_functions(simulator.blocks))
+    labels = [qid for qid, _ in entries]
+    ids = [pf.id for _, pf in entries if isinstance(pf.id, str)]
+    return {
+        "category": CATEGORY_PYTHON_FUNCTION_UNCONFIRMED,
+        "template_key": "error.python_function_unconfirmed",
+        "template_args": {"block_labels": labels, "digest": digest},
+        "block_id": ids[0] if ids else None,
+        "block_ids": ids,
+        "block_type": "flode.blocks.pythonfunc.PythonFunction",
+        "block_label": labels[0] if labels else None,
+        "t": None,
+        "raw_message": (
+            "This model contains PythonFunction blocks. Running it executes their Python "
+            "code with your privileges. Re-send with python_ack=<digest> to confirm."
+        ),
+        "raw_traceback": None,
+    }
+
+
+def _enforce_python_gates(simulator: Simulator, payload: dict[str, Any]) -> None:
+    """``PythonFunction`` を含むモデルの start 前チェック (SPEC-0023 / ADR-0073 §論点 4)。
+
+    * hard gate: プロセス policy が禁止なら **403** (構造化 detail
+      ``python_function_disabled``)。``_build()`` でも同じ判定が走るので、ここでの
+      早期拒否は「ワーカーを起動せずに即答する」ための重複であり bypass 点ではない
+    * soft gate: ``python_ack`` が digest と一致しなければ **409**
+
+    ``PythonFunction`` を含まないモデルでは何もしない (= ``python_ack`` は無視、
+    既存クライアント完全互換)。
+    """
+    digest = compute_python_digest(simulator)
+    if digest is None:
+        return
+    policy = get_python_block_policy()
+    if not policy.allowed:
+        first = next(iter_python_functions(simulator.blocks), None)
+        block_id = first[1].id if first is not None else None
+        reason = f" ({policy.reason})" if policy.reason else ""
+        exc = PythonBlocksDisabledError(
+            f"PythonFunction: execution of Python blocks is disabled in this server{reason}. "
+            f"Start the server with --allow-python-blocks or set [server] "
+            f"allow_python_blocks = true to enable it.",
+            block_id=block_id,
+        )
+        raise HTTPException(status_code=403, detail=_exception_detail(exc))
+    ack = payload.get("python_ack")
+    if not isinstance(ack, str) or ack != digest:
+        raise HTTPException(status_code=409, detail=_python_unconfirmed_detail(simulator, digest))
+
+
+def _scope_batch_size(request: Request) -> int:
+    return int(request.app.state.settings.scope_batch_size)
+
+
+def _resolve_simulator(request: Request, payload: dict[str, Any]) -> tuple[Simulator, str]:
+    """request body から ``Simulator`` を構築する (ADR-0041 §論点 5-A)。
+
+    v0.21.0: 2 形式のみ。相互排他で 1 つだけ指定:
+
+    * ``{"model_path": str}`` — workspace 相対 path。``resolve_workspace_path``
+      で path traversal 防御を通してから ``Simulator.load``。
+    * ``{"model": dict}`` — インライン (= 未保存 editingModel の試行実行)。
+      ``Simulator.from_dict`` で構築、fs アクセスなし。
+
+    Returns:
+        ``(simulator, display_id)``。``display_id`` はトラッキング表示用 (=
+        path では path 文字列、inline では ``"<inline>"``)。
+    """
+    # `key in payload` ベース検出 (= falsy 値も「指定あり」として拾う)
+    specified_keys = [k for k in ("model_path", "model") if k in payload]
+    model_path = payload.get("model_path")
+    model_inline = payload.get("model")
+    if len(specified_keys) == 0:
+        raise HTTPException(
+            status_code=400,
+            detail=_start_validation_detail(
+                "Body must specify exactly one of: 'model_path' "
+                "(workspace-relative) or 'model' (inline)."
+            ),
+        )
+    if len(specified_keys) > 1:
+        raise HTTPException(
+            status_code=400,
+            detail=_start_validation_detail(
+                "Body must specify exactly one of 'model_path' / 'model' "
+                f"(mutually exclusive). Got: {specified_keys}."
+            ),
+        )
+
+    if model_path is not None:
+        if not isinstance(model_path, str):
+            raise HTTPException(
+                status_code=400,
+                detail=_start_validation_detail("'model_path' must be a string"),
+            )
+        settings = request.app.state.settings
+        workspace_root = settings.workspace_root
+        try:
+            resolved = resolve_workspace_path(workspace_root, model_path)
+        except PathTraversalError as e:
+            # _resolve_simulator は models route とも共有のため、監査ログには
+            # 実際の endpoint パスを記録する (security-reviewer SHOULD-3)
+            _logger.warning("Path traversal rejected in %s: %s", request.url.path, e)
+            raise HTTPException(
+                status_code=403,
+                detail=_start_validation_detail(
+                    "Path traversal rejected (see server log for details)."
+                ),
+            ) from e
+        if not resolved.exists():
+            raise HTTPException(
+                status_code=404,
+                detail=_start_validation_detail(f"Model file not found: {model_path}"),
+            )
+        if resolved.is_dir():
+            raise HTTPException(
+                status_code=400,
+                detail=_start_validation_detail(
+                    f"'model_path' is a directory, not a file: {model_path}"
+                ),
+            )
+        try:
+            simulator = Simulator.load(resolved)
+        except ModelLoadError as e:
+            raise HTTPException(status_code=400, detail=_exception_detail(e)) from e
+        return simulator, model_path
+
+    # model_inline (= dict)
+    if not isinstance(model_inline, dict):
+        raise HTTPException(
+            status_code=400,
+            detail=_start_validation_detail("'model' must be a JSON object"),
+        )
+    try:
+        simulator = Simulator.from_dict(model_inline)
+    except ModelLoadError as e:
+        raise HTTPException(status_code=400, detail=_exception_detail(e)) from e
+    return simulator, _INLINE_DISPLAY_ID
+
+
+@router.post("")
+async def start_simulation(request: Request) -> dict[str, str]:
+    """シミュレーションを開始する (ADR-0041 §論点 5-A、2 形式対応)。
+
+    Request body は ``model_path`` または ``model`` のうち **正確に 1 つ** を
+    含む JSON object。詳細は ``_resolve_simulator`` docstring 参照。
+    """
+    payload = await request.json()
+    if not isinstance(payload, dict):
+        raise HTTPException(
+            status_code=400,
+            detail=_start_validation_detail("Body must be a JSON object"),
+        )
+
+    simulator, display_id = _resolve_simulator(request, payload)
+    _enforce_python_gates(simulator, payload)
+
+    manager = _manager(request)
+    loop = asyncio.get_running_loop()
+    sim_id = manager.start(
+        model_id=display_id,
+        simulator=simulator,
+        loop=loop,
+        scope_batch_size=_scope_batch_size(request),
+    )
+    return {"simulation_id": sim_id, "model_id": display_id}
+
+
+@router.get("")
+def list_simulations(request: Request) -> dict[str, Any]:
+    manager = _manager(request)
+    return {"simulations": [dataclasses.asdict(s) for s in manager.list_simulations()]}
+
+
+@router.get("/{sim_id}")
+def get_simulation(request: Request, sim_id: str) -> dict[str, Any]:
+    manager = _manager(request)
+    try:
+        state = manager.get_state(sim_id)
+    except FlodeError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+    return dataclasses.asdict(state)
+
+
+@router.post("/{sim_id}/stop")
+def stop_simulation(request: Request, sim_id: str) -> dict[str, str]:
+    manager = _manager(request)
+    try:
+        manager.stop(sim_id)
+    except FlodeError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+    return {"simulation_id": sim_id, "status": "stop_requested"}
+
+
+@router.get("/{sim_id}/results")
+def get_results(request: Request, sim_id: str) -> dict[str, Any]:
+    manager = _manager(request)
+    try:
+        return manager.get_results(sim_id)
+    except SimulationStillRunningError as e:
+        raise HTTPException(status_code=409, detail=str(e)) from e
+    except FlodeError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+
+
+@router.websocket("/{sim_id}/stream")
+async def stream(websocket: WebSocket, sim_id: str) -> None:
+    """シミュレーション進捗 + Scope データを WebSocket で配信。
+
+    クライアントは接続後、サーバから JSON メッセージを順次受信する:
+    ``progress`` / ``scope_batch`` / ``completed`` / ``stopped`` / ``failed``。
+
+    ADR-0056: 旧 ``error`` メッセージは廃止 (= 失敗時の構造化フィールドは
+    ``failed`` メッセージにマージされる)。
+
+    クライアントが ``{"type": "stop"}`` を送るとサーバ側で
+    ``SimulationManager.stop`` を呼ぶ。
+
+    Note:
+        WS は live 接続向け。途中参加した場合は接続前の ``progress`` /
+        ``scope_batch`` 取り損ない、内部 ``asyncio.Queue`` (max 1024) が満杯時は
+        古いメッセージから drop される (ADR-0011 §(2) / Risk #2)。完全な結果は
+        ``GET /api/v1/simulations/{id}/results`` で取得すること。
+    """
+    await websocket.accept()
+    manager: SimulationManager = websocket.app.state.simulation_manager
+    try:
+        # クライアント受信タスク (停止コマンド用) を並走
+        async def _receiver() -> None:
+            try:
+                while True:
+                    text = await websocket.receive_text()
+                    try:
+                        data = json.loads(text)
+                    except json.JSONDecodeError:
+                        continue
+                    if isinstance(data, dict) and data.get("type") == "stop":
+                        try:
+                            manager.stop(sim_id)
+                        except FlodeError:
+                            pass
+            except WebSocketDisconnect:
+                return
+
+        recv_task = asyncio.create_task(_receiver())
+        try:
+            async for msg in manager.stream(sim_id):
+                await websocket.send_json(msg)
+        finally:
+            recv_task.cancel()
+    except FlodeError as e:
+        # ADR-0056: 旧 ``error`` メッセージは廃止。WS 確立中のドメイン例外
+        # (例: 未知の simulation_id) は構造化 ``failed`` で 1 件返してから閉じる。
+        terminal = {"type": "failed", "duration_sec": 0.0}
+        terminal.update(build_failure_payload(e, simulator=None, t=None))
+        try:
+            await websocket.send_json(terminal)
+        except RuntimeError:
+            pass
+    except WebSocketDisconnect:
+        pass
+    finally:
+        # WebSocket がまだ閉じていなければ閉じる (クライアント側の disconnect で
+        # すでに閉じている可能性もある)
+        try:
+            await websocket.close()
+        except RuntimeError:
+            pass