nene2-python 1.8.40__tar.gz → 1.8.42__tar.gz

{nene2_python-1.8.40 → nene2_python-1.8.42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.40
+Version: 1.8.42
 Summary: NENE2 Python — minimal API framework following NENE2's design philosophy
 Project-URL: Homepage, https://github.com/hideyukiMORI/nene2-python
 Project-URL: Repository, https://github.com/hideyukiMORI/nene2-python

nene2_python-1.8.42/docs/field-trials/2026-05-field-trial-170.md

@@ -0,0 +1,242 @@
+# FT170: collections モジュール
+
+**日付**: 2026-05-21
+**テーマ**: `collections` モジュール — `namedtuple`・`defaultdict`・`Counter`・`deque`・`OrderedDict`・`ChainMap`
+**セキュリティ診断**: なし（170 % 3 = 2）
+
+---
+
+## 概要
+
+Python 標準ライブラリの `collections` モジュールを nene2-python フレームワーク上で検証した。
+`collections` は Python の基本データ構造を拡張する実用的なモジュールで、
+ドメインデータ集計・キャッシュ・グラフ探索・設定管理に直接使えるパターンを提供する。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft170-collections/`
+
+### 主要機能
+
+| クラス/関数 | 概要 |
+|---|---|
+| `ApiError` (namedtuple) | エラー情報の軽量イミュータブル型。`_asdict()` で辞書変換 |
+| `group_by_first_char()` | `defaultdict(list)` でグループ集計 |
+| `count_tags()` | `defaultdict(int)` で出現頻度集計 |
+| `build_adjacency_list()` | `defaultdict(list)` でグラフ構築 |
+| `word_frequency()` / `top_n_words()` | `Counter` で単語頻度・トップN |
+| `tag_overlap()` | `Counter` の intersection で共通タグを抽出 |
+| `merge_counts()` | 複数 `Counter` を `update()` で合算 |
+| `sliding_window_max()` | `deque` で O(n) スライディングウィンドウ最大値 |
+| `recent_n()` | `deque(maxlen=n)` でリングバッファ |
+| `bfs_path()` | `deque` をキューとして BFS 最短経路探索 |
+| `LruCache` | `OrderedDict` + `move_to_end()` で O(1) LRU キャッシュ |
+| `resolve_config()` / `config_source()` | `ChainMap` で env > file > defaults の優先順位設定 |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| GET | `/collections/namedtuple` | namedtuple デモ（距離計算・エラー構造体） |
+| POST | `/collections/group-by` | defaultdict でグループ集計 |
+| POST | `/collections/count-tags` | defaultdict でタグ集計 |
+| GET | `/collections/word-freq` | Counter で単語頻度分析 |
+| GET | `/collections/sliding-window` | deque でスライディングウィンドウ |
+| GET | `/collections/recent` | deque(maxlen) リングバッファ |
+| POST | `/collections/bfs` | BFS グラフ探索 |
+| PUT/GET | `/collections/lru/{key}` | OrderedDict LRU キャッシュ |
+| POST | `/collections/config` | ChainMap 設定レイヤー解決 |
+
+---
+
+## テスト結果
+
+**36 passed（摩擦ゼロ）**
+
+```
+36 passed in 0.94s
+```
+
+---
+
+## 摩擦ポイント
+
+**今回の FT では実装上の摩擦はゼロだった。**
+
+---
+
+## 観察点
+
+### 観察1: `defaultdict` は「キーがなければ初期値」を明示的に設計できる
+
+```python
+result: defaultdict[str, list[str]] = defaultdict(list)
+for word in words:
+    result[word[0]].append(word)  # KeyError なし
+```
+
+`dict.setdefault()` より意図が明確で、`if key not in d:` 分岐が不要になる。
+グループ集計・グラフ隣接リスト構築・カウンタ実装の3パターンで多用できる。
+
+### 観察2: `Counter` は集合演算（`+`, `-`, `&`, `|`）が使える辞書
+
+```python
+Counter(["python", "typing", "python"]) & Counter(["python", "asyncio"])
+# → Counter({"python": 1})  — min(2,1) = 1
+```
+
+`Counter` 同士の `+` は合算、`&` は最小値、`|` は最大値。
+複数の集計結果をマージする `merge_counts()` は `Counter.update()` で自然に書ける。
+`most_common(n)` で上位 N 件を O(n log n) で取得できる。
+
+### 観察3: `deque(maxlen=n)` はリングバッファとして使える
+
+```python
+buf: deque[str] = deque(maxlen=5)
+buf.extend(["a", "b", "c", "d", "e", "f"])
+list(buf)  # → ["b", "c", "d", "e", "f"]  — 最新5件のみ保持
+```
+
+`maxlen` を指定すると、追加時に先頭から自動削除される。
+ログ末尾 N 行・最近の操作履歴・スライディングウィンドウのバッファとして最適。
+`collections.deque` は `list` と異なり先頭操作が O(1)。
+
+### 観察4: `OrderedDict.move_to_end()` で O(1) LRU キャッシュが実装できる
+
+```python
+class LruCache:
+    def get(self, key: str) -> Any:
+        if key not in self._cache:
+            return None
+        self._cache.move_to_end(key)  # 最近使用済みとしてマーク
+        return self._cache[key]
+
+    def put(self, key: str, value: Any) -> None:
+        ...
+        if len(self._cache) > self.capacity:
+            self._cache.popitem(last=False)  # 最も古いものを削除
+```
+
+`Python 3.7+` の `dict` は挿入順を保証するが、`move_to_end()` がないため
+LRU の「使用順序の更新」には `OrderedDict` が必要。
+nene2 の `TtlCache` と組み合わせた TTL+LRU キャッシュへの発展も可能。
+
+### 観察5: `ChainMap` で設定レイヤーのオーバーライドが宣言的に書ける
+
+```python
+chain = ChainMap(env_vars, file_config, defaults)
+chain["DB_HOST"]  # env_vars → file_config → defaults の優先順位で検索
+```
+
+`os.environ` + ファイル設定 + デフォルト値の優先順位解決は
+従来 `{**defaults, **file_config, **env_vars}` で実装していたが、
+`ChainMap` は元の辞書を変更せず参照のみのため副作用がない。
+`chain.maps[0]` で最優先レイヤー、`chain.new_child()` でスコープを重ねることもできる。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- `Counter` はタグ・カテゴリの集計 Use Case で `GROUP BY` SQL の代替になる（小規模データ）
+- `LruCache` は nene2 の `TtlCache[V]` と組み合わせて TTL + LRU の複合キャッシュに発展できる
+- `ChainMap` は `AppSettings` の `pydantic-settings` が行っている env > file > default 解決と同じパターン
+- `deque` は WebSocket メッセージキューやストリーミングレスポンスのバッファとして適用できる
+- `namedtuple` は UseCase の軽量 Output DTO として `dataclass(frozen=True)` より軽量な選択肢になる
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+`defaultdict` は「エラーが出なくなった辞書」として直感的に受け入れられる。
+`Counter` は「辞書の特殊版」として理解でき、`.most_common()` が使いやすい。
+`deque` の「両端キュー」という概念は最初はピンとこないが、`maxlen` のリングバッファ用途はすぐに理解できる。
+
+**ドキュメント理解**: `defaultdict(list)` のファクトリ関数の渡し方（`list` を呼び出さない）は最初に混乱する。
+`defaultdict(lambda: [])` との違いを最初に説明すると理解が早い。
+
+**事故リスク**: 中。`defaultdict` は存在しないキーにアクセスすると自動で作成するため、
+タイポキーが無音で `{}` や `[]` に変わり、後続処理でのデバッグが難しくなる可能性。
+
+**規約の使いやすさ**: コピペで使えるパターンが多い。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+`Counter` を知らずに `dict` + `if key in d: d[key] += 1 else: d[key] = 1` を書いている。
+`Counter` を知ると即採用する。
+
+**コピペ可能性**: 高。特に `Counter(list).most_common(n)` のワンライナーは即戦力。
+
+**拡張時の罠**: `LruCache` で `OrderedDict` を使っているが、
+Python 3.7+ の `dict` で書き直そうとして `move_to_end()` がないことに気づかず壊す可能性。
+「`OrderedDict` には `move_to_end()` がある」という固有 API を README に明記するべき。
+
+**セキュリティ的な事故リスク**: 低。`collections` の誤用は機能バグには繋がるが、セキュリティリスクは低い。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+`Counter` は JavaScript の `reduce` で頻度集計するパターンと概念的に近い。
+`namedtuple` は TypeScript の `readonly struct` 的に理解できる。
+
+**エラーレスポンスの質**: `/collections/sliding-window` で `"a,b,c"` を送ると 422 が返る。
+クライアントには `{"error": "values must be comma-separated integers"}` が届き明確。
+
+**事故リスク**: 低。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+Django の `QuerySet.values().annotate(count=Count(...))` と `Counter` の使い分けが判断ポイント。
+DB に集計クエリを投げられるなら Django ORM が適切。
+インメモリ集計（小規模・一時的）には `Counter` が軽量。
+
+**本番投入可能性**: 問題なし。`LruCache` は nene2 の `TtlCache` と組み合わせて即本番投入できる。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+**コードレビューチェックポイント**:
+- [ ] `defaultdict` のキーが意図せず作成されていないか（`d[key]` アクセスだけでキーが生える）
+- [ ] `Counter` の `most_common()` が `None` を返さないことを前提にしているか（空リストなら空リストを返す）
+- [ ] `LruCache` が複数リクエストからアクセスされるグローバル状態の場合、`asyncio.Lock()` が必要か確認
+- [ ] `ChainMap` の子マップへの書き込みが親マップに伝播しないことを理解しているか
+
+**チームでの安全なパターン**: グローバルな `LruCache` インスタンスは `asyncio.Lock()` でガードするか、
+スレッドセーフな実装（`threading.RLock`）に置き換える。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+**ポリシー達成度**: 高
+
+**「初心者でも安全な API」達成度**: 中
+- `defaultdict` のキー自動生成は初心者には予期しない動作になりうる
+- `LruCache` のスレッドセーフ性は nene2 の非同期環境では注意が必要
+
+**設計上の負債・ドキュメント不足**:
+- nene2 の `TtlCache[V]` と `LruCache` の組み合わせパターンが未文書化
+- グローバルキャッシュインスタンスの非同期安全性に関する how-to がない
+
+**Follow-up Issue 候補**: `docs: キャッシュの TTL + LRU 複合パターンと非同期安全性の how-to を追加`
+
+---
+
+## Follow-up Issues
+
+| 優先度 | タイトル | 種別 |
+|---|---|---|
+| 中 | `docs: collections.Counter をタグ集計 Use Case に適用するパターンを how-to に追加` | docs |
+| 低 | `feat: TtlCache に LRU 退去ポリシーを追加するオプションを検討` | feat |
+
+---
+
+## まとめ
+
+`collections` モジュールは nene2-python の集計・キャッシュ・探索・設定管理に直接使える実用的な機能群。
+36 テスト全通過、摩擦ゼロ。
+
+`defaultdict` / `Counter` / `deque` の三点セットは Python バックエンドの必須知識。
+`OrderedDict.move_to_end()` による LRU キャッシュは nene2 の `TtlCache` と組み合わせる価値がある。
+`ChainMap` は `pydantic-settings` が内部でやっている設定レイヤー解決と同じパターンで、
+環境別設定のオーバーライドを副作用なしに実装できる。
+

nene2_python-1.8.42/docs/field-trials/2026-05-field-trial-171.md

@@ -0,0 +1,423 @@
+# FT171: asyncio モジュール
+
+**日付**: 2026-05-21
+**テーマ**: `asyncio` モジュール — `Task`・`gather`・`Lock`・`Queue`・`Semaphore`・`Event`・タイムアウト
+**セキュリティ診断**: **あり**（171 % 3 = 0）
+
+---
+
+## 概要
+
+Python 標準ライブラリの `asyncio` モジュールを nene2-python フレームワーク上で検証した。
+FastAPI は ASGI フレームワークであり、すべてのリクエストハンドラーが非同期で動作するため、
+`asyncio` の正しい使い方は nene2-python の設計の根幹。
+非同期レースコンディション・TOCTOU・グローバル状態の安全性が FT171 のセキュリティ診断の中心。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft171-asyncio/`
+
+### 主要機能
+
+| 関数/クラス | 概要 |
+|---|---|
+| `fetch_simulated()` / `fetch_all()` | `asyncio.gather` で並列フェッチ（模擬） |
+| `fetch_with_timeout()` | `asyncio.wait_for()` タイムアウト付きフェッチ |
+| `SafeCounter` | `asyncio.Lock()` で保護された並行カウンター |
+| `race_condition_demo()` | Lock あり/なしでのカウンター競合デモ |
+| `producer_consumer()` | `asyncio.Queue` を使ったプロデューサー・コンシューマー |
+| `limited_fetch()` | `asyncio.Semaphore` で並行数を制限したフェッチ |
+| `event_demo()` | `asyncio.Event` でタスク間シグナリング |
+| `run_with_timeout()` | `asyncio.wait_for` でタイムアウト制御 |
+| `measure_parallel_vs_sequential()` | 並列 vs 逐次の実行時間比較 |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| POST | `/asyncio/fetch-all` | gather で並列フェッチ |
+| GET | `/asyncio/fetch-timeout` | wait_for タイムアウト付きフェッチ |
+| GET | `/asyncio/race-condition` | Lock あり/なし競合デモ |
+| GET | `/asyncio/counter/increment` | Lock 保護カウンター加算 |
+| GET | `/asyncio/counter` | カウンター取得 |
+| POST | `/asyncio/counter/reset` | カウンターリセット |
+| GET | `/asyncio/producer-consumer` | Queue プロデューサー・コンシューマー |
+| POST | `/asyncio/limited-fetch` | Semaphore 並行数制限フェッチ |
+| GET | `/asyncio/event` | Event シグナリング |
+| GET | `/asyncio/timeout` | タイムアウト制御デモ |
+| GET | `/asyncio/parallel-vs-sequential` | 並列 vs 逐次の実行時間比較 |
+
+---
+
+## テスト結果
+
+**27 passed（摩擦1件: pytest-asyncio 追加が必要）**
+
+```
+27 passed in 1.22s
+```
+
+---
+
+## 摩擦ポイント
+
+### F-1: `pytest-asyncio` がデフォルト依存に含まれておらずエラー（深刻度: 低）
+
+**事象**: `@pytest.mark.asyncio` を使ったテストを書いたが、`pytest-asyncio` が未インストールで `ModuleNotFoundError`。  
+**原因**: FT サンドボックスの `pyproject.toml` には `pytest` しか含まれておらず、`pytest-asyncio` が未追加。  
+**対応**: `uv add pytest-asyncio` で追加。今後の asyncio 系 FT では最初から依存に含める。
+
+---
+
+## 観察点
+
+### 観察1: `asyncio.gather()` で複数タスクを並列実行し全完了を待つ
+
+```python
+tasks = [asyncio.create_task(fetch_simulated(url)) for url in urls]
+results = list(await asyncio.gather(*tasks))
+```
+
+`asyncio.gather()` はすべてのタスクの完了を待ち、結果リストを返す。
+順序はタスクの投入順が保証される（完了順ではない）。
+n 個の IO 待ちタスクを並列化すると実測でほぼ n 倍速くなることを確認（speedup > 1.5倍保証）。
+
+### 観察2: `asyncio.Lock()` でグローバル状態を保護する
+
+```python
+class SafeCounter:
+    def __init__(self) -> None:
+        self._count = 0
+        self._lock = asyncio.Lock()
+
+    async def increment(self) -> int:
+        async with self._lock:
+            self._count += 1
+            return self._count
+```
+
+asyncio は GIL があるため Python の `count += 1` は通常 atomic だが、
+`await asyncio.sleep(0)` 等の協調切り替えポイントがある場合、
+チェックと更新の間に他のコルーチンが割り込む可能性がある。
+FastAPI で `_count = await get(); await something(); await set(_count + 1)` のような分割書き込みは Lock 必須。
+
+### 観察3: `asyncio.Semaphore` で外部 API の並行数を制限する
+
+```python
+sem = asyncio.Semaphore(3)  # 同時に3つまで
+
+async def guarded_fetch(url: str) -> ...:
+    async with sem:
+        return await fetch(url)
+
+await asyncio.gather(*[guarded_fetch(url) for url in urls])
+```
+
+外部 API・DB 接続プールには必ず Semaphore で上限を設定する。
+`asyncio.gather()` に 1000 タスクを渡すと 1000 並列になり、外部サービスの DoS になりうる。
+
+### 観察4: `asyncio.wait_for()` はキャンセル後も内部タスクが走り続ける
+
+```python
+try:
+    result = await asyncio.wait_for(slow_operation(10), timeout=1.0)
+except asyncio.TimeoutError:
+    pass  # ← タイムアウトしたが内部の slow_operation は???
+```
+
+`asyncio.wait_for()` は `TimeoutError` 時にコルーチンに `CancelledError` を発生させる。
+コルーチンが `CancelledError` を適切にハンドリングしなければリソースリークになる。
+`try/finally` でクリーンアップを確実に行うパターンが必要。
+
+### 観察5: `asyncio.Event` でタスク間の順序を保証する
+
+```python
+ready = asyncio.Event()
+await ready.wait()   # シグナルを待つ
+ready.set()          # シグナルを発する
+```
+
+`asyncio.Event` は `threading.Event` の非同期版。
+ウェブソケット接続確立後に処理開始・DB 初期化完了後にリクエスト受付開始、などに使える。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- FastAPI のルートハンドラーはすべて非同期のため、`asyncio.Lock` + グローバル状態パターンは nene2 の `TtlCache[V]` に適用済み
+- `asyncio.Semaphore` は外部 API 呼び出し（`httpx.AsyncClient`）の並行数制限に必須
+- `asyncio.Queue` は nene2 の MCP サーバーでのメッセージキューとして直接使える
+- `asyncio.wait_for()` タイムアウトは nene2 の DB クエリタイムアウトパターンに適用できる
+- `asyncio.gather()` の `return_exceptions=True` オプションで個別の失敗を無視してできるだけ多く取得するパターンも有効
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+`async def` と `await` の概念は FastAPI のチュートリアルで最初に触れるが、
+「なぜ await が必要か」の理解が浅いまま使う傾向がある。
+
+**ドキュメント理解**: `asyncio.gather()` の使い方は直感的。
+`asyncio.Lock()` が必要な場面（グローバル状態の変更）は説明なしでは気づかない。
+nene2 how-to に「FastAPI で共有状態を使う場合は Lock 必須」の例があると事故を防げる。
+
+**事故リスク**: 高。`await` を書き忘れるとコルーチンオブジェクトが戻り値になり、
+実行されないまま成功したように見えるサイレントエラーになる。mypy / ruff が検出できる。
+
+**規約の使いやすさ**: `async with lock:` のパターンはコピペで使える。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+同期コードを async に変換するとき、ブロッキング処理（`time.sleep`・`open()`・`requests`）を
+`await` なしで呼んでしまいイベントループをブロックするミスが多い。
+
+**コピペ可能性**: `asyncio.gather()` と `asyncio.Semaphore()` はサンプルを見れば再現できる。
+
+**拡張時の罠**: `asyncio.Lock()` を使わずにグローバルな `dict` を書き換えると、
+同時リクエストで key が消えたりすることがある。テストでは再現しにくい。
+
+**セキュリティ的な事故リスク**: 高。非同期 TOCTOU は認証バイパスに直結する（後述のセキュリティ診断参照）。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+JavaScript の `Promise.all()` と `asyncio.gather()` は概念的に同等。
+`async/await` 構文も TypeScript と同じなので学習コストが低い。
+
+**エラーレスポンスの質**: `asyncio.TimeoutError` が `ErrorHandlerMiddleware` で捕捉されて 500 になる場合、
+クライアントには情報が少ない。エンドポイントレベルで 422 か 504 を返す設計が必要。
+
+**事故リスク**: 中。asyncio のイベントループブロッキングは JavaScript の概念と同じで理解しやすい。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+Django は WSGI（同期）が主流で、非同期対応は Django 3.1+ で追加された後付け機能。
+nene2-python の FastAPI は最初から非同期前提のため、`asyncio.Lock`・`asyncio.Semaphore` が設計の基本になる。
+
+**他フレームワークとの差異**:
+- Django: `django-channels` で非同期対応（後付け）
+- nene2-python: FastAPI + asyncio で最初から非同期
+- スレッドセーフな Django ミドルウェアの発想を asyncio に持ち込むと `threading.Lock` を使ってしまうミス
+
+**本番投入可能性**: 問題なし。`asyncio.Semaphore` による外部 API 並行数制限は本番必須。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+**コードレビューチェックポイント**:
+- [ ] グローバル/クラス変数への非同期書き込みに `asyncio.Lock()` が使われているか
+- [ ] ブロッキング IO（`open()`・`requests.get()`・`time.sleep()`）をイベントループで直接呼んでいないか
+- [ ] `asyncio.wait_for()` のキャンセル後にリソースリークが発生しないか（`try/finally` の確認）
+- [ ] 外部 API 呼び出しに `asyncio.Semaphore` で並行数制限があるか
+- [ ] `asyncio.gather(*tasks)` でエラーが1件でも起きると他タスクも失敗するが、`return_exceptions=True` が必要な場面かどうか
+
+**チームでの安全なパターン**: 認証チェックと状態変更の間に `await` がある場合は必ず TOCTOU レビューを実施する。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+**ポリシー達成度**: 高
+
+**「初心者でも安全な API」達成度**: 中
+- `SafeCounter` のように Lock を隠蔽した API を提供するパターンが必要
+- グローバル状態（`_lru`・`_counter` 等）を使う場合の Lock 要件が CLAUDE.md に未記載
+
+**設計上の負債**:
+- CLAUDE.md のセキュリティポリシーに「非同期レースコンディション」が明記されていない（テンプレートにはある）
+- nene2 の `TtlCache` の asyncio 安全性が明文化されていない
+
+**Follow-up Issue 候補**: `docs: CLAUDE.md の非同期セクションに asyncio.Lock 要件を追記`
+
+---
+
+## セキュリティ診断（FT171 % 3 = 0）
+
+> **診断方針**: Django・FastAPI・SQLAlchemy 本体でも CVE が報告されてきたレベルの
+> 攻撃ベクターを対象とする。「動いているから安全」は不正解。
+> 実装ミスが起きやすい箇所を意図的に探し、問題がなければその理由まで記録する。
+
+### 1. OWASP API Security Top 10 (2023)
+
+#### API1: BOLA / IDOR
+- **結果**: ✅ 該当なし（ユーザー所有リソースなし）。
+
+#### API2: 認証の破損
+- **結果**: ✅ 認証なし（FT サンドボックス）。
+
+#### API3: Mass Assignment
+- **結果**: ✅ Pydantic デフォルト（extra="ignore"）で未知フィールドは無視される。
+
+#### API4: 無制限リソース消費
+- `FetchBody.urls: list[str] = Field(max_length=20)` で最大20 URL
+- `LimitedFetchBody.concurrency: int = Field(ge=1, le=10)` で最大10並行
+- `Queue(maxsize=3)` で back-pressure あり  
+- **結果**: ✅ 全入力に上限あり。Semaphore で外部リソース使用量を制限している。
+
+#### API5〜API10
+- **結果**: ✅ 該当なし（外部 URL フェッチなし・認証エンドポイントなし）。
+
+---
+
+### 2. インジェクション攻撃
+
+- **結果**: ✅ 全体的に該当なし。`demos.py` はネットワーク接続なし・ファイル操作なし・SQL なし。
+
+---
+
+### 3. 認証・認可
+
+- **結果**: ✅ FT サンドボックスのため認証なし。nene2 本体の認証実装は FT165 で検証済み。
+
+---
+
+### 4. 入力バリデーション
+
+- `urls`, `concurrency`, `n`, `items`, `timeout`, `duration` すべてに `max_length` または `ge/le` あり  
+- **結果**: ✅ 全 HTTP 境界に型 + 範囲バリデーション済み。
+
+---
+
+### 5. 情報漏洩
+
+- **結果**: ⚠️ PyJWT PYSEC-2025-183 継続中（mcp 経由）。
+
+---
+
+### 6. Python / FastAPI 固有の攻撃ベクター
+
+#### 非同期レースコンディション — **FT171 の重点診断項目**
+
+**実測: asyncio でのグローバル状態競合**
+
+```python
+# 危険パターン — 認証チェックと処理の間に await がある
+async def handler() -> str:
+    if not authorized_users[user_id]:
+        return "denied"
+    await something()  # ← ここで他のコルーチンが user_id を無効化できる
+    return do_privileged_action(user_id)
+```
+
+実測 TOCTOU デモ: `authorized_users["user1"] = True` の状態で
+`check_and_use(user1)` と `revoke_in_race()` を `gather()` した結果、
+**revoke タスクがチェック後に実行されたにもかかわらず `"allowed: user1"` が返った**。
+
+これは「認証チェック → await → 権限変更 → 権限前提の操作」という TOCTOU の典型例。
+FastAPI のリクエストハンドラーで認証状態をグローバルな辞書で管理する場合に発生する。
+
+**FT171 サンドボックスの状況**: `/asyncio/counter` はグローバルな `_counter` を使用するが、
+`SafeCounter` の `asyncio.Lock()` で保護されているため安全。
+ただし `/asyncio/counter/increment` と `/asyncio/counter/reset` が連続して呼ばれると
+意図しないカウンターリセットが起きる（これは仕様上の問題であり、セキュリティ上の問題ではない）。
+
+**防御策（実装済み）**:
+- `SafeCounter._lock = asyncio.Lock()` でインクリメントを atomic 化
+- `async with self._lock:` で確認と更新を不可分に
+
+**残存リスク**: 認証に関わるグローバル状態（セッション管理等）を asyncio アプリで持つ場合、
+チェックと使用の間に `await` があれば必ず `asyncio.Lock()` でガードが必要。
+nene2-python はリクエストスコープで認証状態を持ちグローバル変数に書かないため、
+この問題は nene2 コアでは発生しない設計になっている。
+
+- **結果**: ✅ FT171 スコープでは Lock で保護済み。TOCTOU の概念的リスクを記録。
+
+#### イベントループブロッキング
+
+```python
+# 危険 — async 関数内でブロッキング IO を呼ぶ
+async def bad_handler() -> None:
+    time.sleep(5)         # ← イベントループ全体を5秒ブロック
+    data = open("file.txt").read()  # ← sync IO でブロック
+    requests.get(url)     # ← sync HTTP でブロック
+```
+
+FastAPI は `asyncio.run_in_executor()` または `await asyncio.to_thread()` で
+同期処理を別スレッドに委ねることができる。
+FT171 のデモ関数はすべて `asyncio.sleep()` を使い、ブロッキング処理なし。
+
+- **結果**: ✅ FT171 内にブロッキング IO なし。
+
+#### `asyncio.wait_for()` キャンセルリーク
+
+`asyncio.wait_for()` タイムアウト時、内部コルーチンに `CancelledError` が発生する。
+コルーチンが `CancelledError` を `except Exception:` で握りつぶすと、
+タスクが完了せずリソースがリークする可能性がある。
+
+FT171 の `slow_operation()` は `asyncio.sleep()` のみを使っており、
+`CancelledError` は `asyncio.sleep()` から正しく伝播する。
+
+- **結果**: ✅ `slow_operation()` はキャンセル安全。
+
+#### Semaphore 枯渇
+
+`asyncio.Semaphore(n)` を使っても、コルーチン内で例外が発生した場合
+`async with sem:` ブロックが `__aexit__` を呼んでセマフォを解放するかが重要。
+Python の `async with` は例外時も `__aexit__` を保証するため安全。
+
+- **結果**: ✅ `async with sem:` は例外時も正しく解放される。
+
+#### pickle / yaml
+- **結果**: ✅ 該当なし。
+
+#### 型強制攻撃 (Pydantic)
+- `concurrency: int = Field(ge=1, le=10)` — `"3"` 文字列は int 変換後に範囲チェック
+- **結果**: ✅ 範囲制限が適切。
+
+---
+
+### 7. 依存関係スキャン
+
+```
+Found 1 known vulnerability: pyjwt 2.12.1 PYSEC-2025-183 (mcp 経由)
+```
+
+- **スキャン結果**: 継続中（FT168 から変更なし）
+- **対応方針**: mcp の更新を待つ
+
+---
+
+### 診断サマリー
+
+| カテゴリ | 結果 | 最重要発見 |
+|---|---|---|
+| OWASP API Security Top 10 | ✅ 全通過 | 無制限リソース消費: Semaphore で適切に制限 |
+| インジェクション攻撃 | ✅ | 該当なし |
+| 認証・認可 | ✅ | FT サンドボックス |
+| 入力バリデーション | ✅ | 全境界に ge/le/max_length あり |
+| 情報漏洩 | ⚠️ | PyJWT 継続中 |
+| **非同期レースコンディション** | ✅ | Lock で保護済み。TOCTOU 概念リスクを文書化 |
+| イベントループブロッキング | ✅ | ブロッキング IO なし |
+| asyncio.wait_for キャンセルリーク | ✅ | 正しくキャンセル伝播 |
+| Semaphore 枯渇 | ✅ | async with が例外時も解放 |
+| 依存関係 CVE | ⚠️ | PYSEC-2025-183（継続中） |
+
+**総合評価**: 合格  
+**発見した新規脆弱性**: 0件  
+**セキュリティ観察**: TOCTOU パターンの概念リスクを記録（FT171 実装では発生しない設計）
+
+---
+
+## Follow-up Issues
+
+| 優先度 | タイトル | 種別 |
+|---|---|---|
+| 高 | `docs: CLAUDE.md の非同期セクションに asyncio.Lock 要件と TOCTOU 注意点を追記` | docs |
+| 中 | `docs: FastAPI でブロッキング IO を asyncio.to_thread() で安全に実行する how-to` | docs |
+| 低 | `feat: TtlCache の asyncio 安全性（Lock 保護）を明文化しテストを追加` | feat |
+
+---
+
+## まとめ
+
+`asyncio` モジュールは nene2-python の FastAPI 基盤に直結する重要機能。
+27 テスト全通過（摩擦1件: pytest-asyncio の追加が必要）。
+
+**セキュリティ診断**: 非同期レースコンディションの実測デモを実施した。
+TOCTOU（認証チェック後に `await` を挟んで状態変更が入るパターン）が概念的リスクとして存在するが、
+FT171 の実装では `asyncio.Lock()` で保護されているため安全。
+Semaphore による外部リソース並行数制限・`asyncio.wait_for()` のキャンセル安全性も確認した。
+
+`asyncio.gather()` による並列化（最大5倍高速化確認）・`asyncio.Semaphore` による流量制御・
+`asyncio.Queue` によるプロデューサー・コンシューマーパターンが nene2 本番実装で直接使えるパターンとして確立された。
+

{nene2_python-1.8.40 → nene2_python-1.8.42}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nene2-python"
-version = "1.8.40"
+version = "1.8.42"
 description = "NENE2 Python — minimal API framework following NENE2's design philosophy"
 readme = "README.md"
 license = {text = "MIT"}