nene2-python 1.8.31__tar.gz → 1.8.33__tar.gz

{nene2_python-1.8.31 → nene2_python-1.8.33}/CHANGELOG.md

@@ -5,6 +5,43 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.33] — 2026-05-20
+
+FT100 フィールドトライアル — In-memory TTL レスポンスキャッシュパターン検証と nene2.cache モジュール追加。
+
+### Added
+- `nene2.cache` モジュールを新設 (#409) (FT100)
+  - `TtlCache[V]` — TTL 付きインメモリキャッシュ（ジェネリック型）
+  - `time.monotonic()` ベースの TTL で NTP 調整の影響を受けない
+  - `get()`, `set()`, `delete()`, `clear()`, `size()` API
+- Field trial report: `docs/field-trials/2026-05-field-trial-100.md` (FT100)
+
+---
+
+## [1.8.32] — 2026-05-20
+
+FT99 フィールドトライアル — Webhook HMAC-SHA256 署名検証パターン検証と nene2.security モジュール追加。
+
+### Added
+- `nene2.security` モジュールを新設 (#404) (FT99)
+  - `verify_hmac_signature(body, secret, signature, *, prefix="")` — GitHub/Stripe 方式の Webhook HMAC-SHA256 署名を timing-safe に検証
+  - `hmac.compare_digest()` による timing attack 対策済み
+- Field trial report: `docs/field-trials/2026-05-field-trial-99.md` (FT99)
+
+---
+
+## [1.8.31] — 2026-05-20
+
+FT97 フィールドトライアル — HTTP キャッシュヘッダーパターン検証と generate_etag() 追加。
+
+### Added
+- `nene2.http.generate_etag(data)` — ETag 生成ユーティリティ関数を追加 (#397) (FT97)
+  — dict / list / str / bytes から RFC 9110 形式の ETag 文字列を生成
+  — HTTP キャッシュ (`If-None-Match` / `304 Not Modified`) パターンで利用
+- Field trial reports: `docs/field-trials/2026-05-field-trial-92.md` 〜 `2026-05-field-trial-97.md` (FT92〜FT97)
+
+---
+
 ## [1.8.30] — 2026-05-20
 
 FT87 フィールドトライアル — カスタムレスポンスヘッダーパターン検証と problem_details_response() 改善。

{nene2_python-1.8.31 → nene2_python-1.8.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.31
+Version: 1.8.33
 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.33/docs/field-trials/2026-05-field-trial-100.md

@@ -0,0 +1,62 @@
+# Field Trial 100: In-memory TTL レスポンスキャッシュ
+
+## テーマ
+
+重い処理の結果を TTL 付きインメモリキャッシュに格納し、重複リクエストにキャッシュから応答するパターンを nene2 上で実装する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft100-response-cache/` に以下を実装:
+
+- `TtlCache` データクラス（TTL 付き辞書）
+- FastAPI lifespan でキャッシュを初期化・破棄
+- `Depends(get_cache)` でハンドラーに注入
+- キャッシュヒット/ミス判定、TTL 失効テスト
+
+## テスト結果
+
+全 7 テスト通過。
+
+## Friction Points
+
+### FP1: nene2 に TTL キャッシュユーティリティがない
+
+**状況**: キャッシュは Web API の基本パターンだが、nene2 に `TtlCache` のようなユーティリティが存在しない。`TtlCache` を毎回自前実装する必要がある。
+
+**影響**: 開発者がスレッドセーフでないキャッシュを実装してしまうリスク。また asyncio 環境での並行アクセスの考慮が漏れやすい（Python GIL により dict 操作自体はアトミックだが、get-then-set パターンは競合する）。
+
+**期待する API**:
+```python
+from nene2.cache import TtlCache
+
+cache = TtlCache(ttl_seconds=60.0)
+cache.set("key", value)
+value = cache.get("key")  # None if expired
+```
+
+### FP2: lifespan + グローバル変数パターンに型エラーが出る
+
+**状況**: キャッシュを lifespan で初期化してグローバル変数に格納するパターンで、`async def lifespan(app: FastAPI)` の型注釈に `type: ignore[type-arg]` が必要。
+
+```python
+_cache: TtlCache | None = None
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):  # type: ignore[type-arg] が必要
+    global _cache
+    _cache = TtlCache(ttl_seconds=60.0)
+    yield
+```
+
+`app.state` を使うパターンの方がよりクリーンだが、`app.state` の型付けも `app.state.cache` のアクセスで `Any` になる。
+
+### FP3: `app.state` でのキャッシュ管理がドキュメント化されていない
+
+**状況**: `lifespan-and-app-state.md` では `app.state.db` の例はあるが、キャッシュを `app.state` に格納するパターン（`request.app.state.cache`）の説明がない。
+
+**影響**: グローバル変数を使う開発者が多く、テスト時のリセットが困難になる。
+
+## まとめ
+
+キャッシュユーティリティ追加は中程度の価値あり（FP1）。FP2・FP3 はドキュメント摩擦。
+今回は FP1 を `nene2.cache` モジュールとして実装し、Issue を起票する。

nene2_python-1.8.33/docs/field-trials/2026-05-field-trial-97.md

@@ -0,0 +1,87 @@
+# Field Trial 97: HTTP キャッシュヘッダー (ETag / Cache-Control)
+
+**日付**: 2026-05-20
+**テーマ**: ETag・Cache-Control・304 Not Modified パターンを nene2 で実装
+**バージョン**: v1.8.30
+**結果**: 摩擦あり（コード修正なし）
+
+---
+
+## 目的
+
+HTTP キャッシュ機構（`ETag`, `Cache-Control`, `If-None-Match`, `304 Not Modified`）を nene2 ベースの API で実装するパターンを検証する。
+
+---
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft97-http-caching/` に以下を実装:
+
+- `app.py` — ETag 付き GET エンドポイント、`If-None-Match` による 304 返却、Cache-Control ヘッダー
+- 13 テスト（全 PASS）
+
+---
+
+## 確認できた良好な動作
+
+### ETag + 304 のパターン
+
+`If-None-Match` ヘッダーと ETag を比較して 304 を返すパターンは問題なく動作する。
+
+```python
+@app.get("/articles/{article_id}")
+def get_article(article_id: int, request: Request) -> Response:
+    data = _article_to_dict(article)
+    etag = _compute_etag(data)
+
+    if request.headers.get("if-none-match") == etag:
+        return Response(status_code=304, headers={"ETag": etag})
+
+    return JSONResponse(data, headers={"ETag": etag, "Cache-Control": "max-age=60"})
+```
+
+### 304 レスポンスにも X-Request-Id が付く
+
+`Response(status_code=304)` を返しても、外側の `RequestIdMiddleware` が `X-Request-Id` を付与する。
+
+---
+
+## 摩擦点
+
+### F97-1: nene2 に ETag 生成ユーティリティがない
+
+ETag 生成ロジック（MD5 ハッシュ）を各プロジェクトで手動実装する必要がある。各エンドポイントで繰り返し実装することになり DRY でない。
+
+```python
+def _compute_etag(data: object) -> str:
+    content = json.dumps(data, sort_keys=True, ensure_ascii=False)
+    return f'"{hashlib.md5(content.encode(), usedforsecurity=False).hexdigest()}"'
+```
+
+nene2 が `generate_etag(data)` などのユーティリティ関数を提供すれば再実装不要になる。
+
+### F97-2: `hashlib.md5()` に `usedforsecurity=False` が必要
+
+ruff のセキュリティルール `S324`（MD5 使用禁止）により、ETag 生成で `hashlib.md5()` を使うと lint エラーになる。ETag は暗号セキュリティ用途ではないが、明示的に `usedforsecurity=False` を指定する必要がある。
+
+```python
+# ❌ ruff S324 エラー
+hashlib.md5(content.encode()).hexdigest()
+
+# ✅ 正しい
+hashlib.md5(content.encode(), usedforsecurity=False).hexdigest()
+```
+
+nene2 のユーティリティ関数でラップすればプロジェクトごとに対処不要になる。
+
+### F97-3: Cache-Control ヘッダーの付与はエンドポイントごとに手動
+
+`JSONResponse(headers={"Cache-Control": "max-age=60"})` のように各エンドポイントで手動指定が必要。
+ミドルウェアでのデフォルト付与（例: 全 GET に `Cache-Control: no-cache` を付与する設定）がないため、付け忘れが起きやすい。
+
+---
+
+## 結論
+
+HTTP キャッシュヘッダーは nene2 と問題なく実装できるが、ETag 生成の共通化がない。
+`generate_etag()` などのユーティリティ関数を nene2 に追加することで摩擦を解消できる。

nene2_python-1.8.33/docs/field-trials/2026-05-field-trial-98.md

@@ -0,0 +1,97 @@
+# Field Trial 98: PATCH / Partial Update パターン
+
+**日付**: 2026-05-20
+**テーマ**: Pydantic v2 の `exclude_unset=True` を使った部分更新パターン
+**バージョン**: v1.8.31
+**結果**: 摩擦あり（コード修正なし）
+
+---
+
+## 目的
+
+HTTP PATCH で「送信されたフィールドのみ更新する」パターンを Pydantic v2 + nene2 で実装し、`None`（明示的 null）と「未送信」の区別ができることを検証する。
+
+---
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft98-patch-partial-update/` に以下を実装:
+
+- `app.py` — `PUT`（完全更新）と `PATCH`（部分更新）を持つユーザー CRUD
+- 12 テスト（全 PASS）
+
+---
+
+## 確認できた良好な動作
+
+### `exclude_unset=True` で未送信フィールドを除外
+
+`PatchUserBody` の全フィールドを `Optional` にし、`model_dump(exclude_unset=True)` で送信されたフィールドだけを取り出す。
+
+```python
+class PatchUserBody(BaseModel):
+    name: str | None = Field(default=None, max_length=100)
+    email: str | None = Field(default=None, max_length=200)
+    bio: str | None = Field(default=None, max_length=500)
+
+@app.patch("/users/{user_id}")
+def patch_user(user_id: int, body: PatchUserBody) -> JSONResponse:
+    updates = body.model_dump(exclude_unset=True)
+    updated = User(
+        user_id=user_id,
+        name=updates.get("name", current.name),
+        email=updates.get("email", current.email),
+        bio=updates.get("bio", current.bio),
+    )
+```
+
+### `{}` と `{"bio": null}` を区別できる
+
+`exclude_unset=True` により、空ボディ `{}` と `{"bio": null}` は正しく区別される。
+
+```python
+body_without_bio = PatchUserBody(name="Alice")
+assert "bio" not in body_without_bio.model_dump(exclude_unset=True)  # 未送信
+# {"bio": null} を送ると exclude_unset でも "bio" が含まれる → None に更新
+```
+
+---
+
+## 摩擦点
+
+### F98-1: PATCH ボディの全フィールドが Optional なため、バリデーションが緩くなる
+
+`PUT` ボディは必須フィールドあり（空だと 422）。`PATCH` ボディは全フィールド Optional なため、空ボディ `{}` も有効に受け入れられる。
+
+```python
+# PUT: name 省略 → 422
+client.put("/users/1", json={"email": "..."})  # 422
+
+# PATCH: 全フィールド省略 → 200（空更新）
+client.patch("/users/1", json={})  # 200（何も変わらない）
+```
+
+意図的な設計だが、API クライアント側が誤って空 PATCH を送っても検知できない。
+
+### F98-2: `model_dump()` と `model_dump(exclude_unset=True)` の違いを意識する必要がある
+
+`default=None` で定義したフィールドは、`model_dump()` では常に含まれる（`{"bio": None}`）。`exclude_unset=True` を忘れると「未送信」と「null 送信」の区別ができなくなる。
+
+```python
+# ❌ exclude_unset=True を忘れると未送信フィールドも含まれる
+updates = body.model_dump()  # {"name": None, "email": None, "bio": None}
+
+# ✅ 送信されたフィールドのみ
+updates = body.model_dump(exclude_unset=True)  # {}
+```
+
+### F98-3: `str | None` フィールドで「クリアしたい」と「変更なし」が混同しやすい
+
+`bio: str | None = None` の PATCH ボディでは、`{"bio": null}` が「bio を null にしたい」なのか「変更なし」なのかをクライアント側の意図だけで区別する必要がある。`exclude_unset=True` により `{"bio": null}` は「null に更新」として正しく扱えるが、API ドキュメントでこの挙動を明記する必要がある。
+
+---
+
+## 結論
+
+Pydantic v2 の `exclude_unset=True` + 全フィールド `Optional` の PATCH パターンは nene2 と問題なく組み合わせられる。
+主な摩擦はバリデーションの緩さと `model_dump` の使い分け。コード修正は不要。

nene2_python-1.8.33/docs/field-trials/2026-05-field-trial-99.md

@@ -0,0 +1,57 @@
+# Field Trial 99: Webhook HMAC-SHA256 署名検証
+
+## テーマ
+
+外部サービス（GitHub / Stripe 方式）からの Webhook を HMAC-SHA256 署名で検証するパターンを nene2 上で実装する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft99-webhook-hmac/` に以下を実装:
+
+- GitHub 方式: `X-Hub-Signature-256: sha256=<hex>` ヘッダーを HMAC-SHA256 で検証
+- Stripe 方式: `Stripe-Signature: t=<timestamp>,v1=<hex>` 形式の署名を検証
+- `hmac.compare_digest()` による timing-safe 比較
+- `await request.body()` + `await request.json()` の二重読み取りパターン
+
+## テスト結果
+
+全 7 テスト通過。
+
+## Friction Points
+
+### FP1: nene2 に Webhook 署名検証ユーティリティがない
+
+**状況**: GitHub/Stripe 方式の HMAC 署名検証は頻出パターンだが、nene2 に `verify_webhook_signature()` のようなユーティリティが存在しない。毎回 `hmac` モジュールを直接扱う必要がある。
+
+**影響**: `hmac.new()` / `hmac.compare_digest()` を知らない開発者が `==` 比較を使い、timing attack に脆弱な実装をしてしまうリスクがある。
+
+**期待する API**:
+```python
+from nene2.security import verify_hmac_signature
+
+# GitHub 方式
+verify_hmac_signature(body, secret, header_value, prefix="sha256=")
+
+# Stripe 方式
+verify_stripe_signature(body, secret, header_value)
+```
+
+### FP2: `await request.body()` → `await request.json()` の二重読み取りがドキュメント化されていない
+
+**状況**: Webhook 署名検証では生バイト（`request.body()`）を HMAC に通してから、JSONとしてパース（`request.json()`）する二重読み取りが必要。FastAPI は内部でボディをキャッシュするため動作するが、この挙動はフレームワークに依存した暗黙の知識。
+
+**影響**: 「一度 `body()` を読んだら `json()` は使えない」と誤解して `json.loads(body)` を書く開発者が出る。
+
+**期待するドキュメント**: how-to に「Webhook ハンドラーでの生ボディ + JSON 二重読み取りパターン」を追加。
+
+### FP3: BearerTokenMiddleware は Webhook 認証に使えない
+
+**状況**: nene2 の `BearerTokenMiddleware` は Bearer トークン認証に特化しており、HMAC 署名検証（リクエストボディを使った認証）には対応しない。Webhook エンドポイントでは `exclude_paths` で除外して自前検証するか、専用の Depends 関数を書く必要がある。
+
+**影響**: 摩擦は低いが、「nene2 の認証機構でWebhookも守れる」という誤解が生まれやすい。
+
+**期待するドキュメント**: how-to に「Webhook 署名検証 vs Bearer Token 認証の使い分け」を明記。
+
+## まとめ
+
+Webhook HMAC 検証自体は Python 標準ライブラリで実装できるが、セキュアな実装（timing-safe 比較）のためのユーティリティがないため FP1 として Issue を起票する。FP2・FP3 はドキュメント摩擦。

{nene2_python-1.8.31 → nene2_python-1.8.33}/docs/how-to/async-use-case.md

@@ -119,3 +119,44 @@ inspect.iscoroutinefunction(use_case.execute)  # → True/False
 ```
 
 型安全性は `mypy --strict` の静的解析で保証します。詳細は ADR-0010 を参照してください。
+
+---
+
+## 同期 DB 呼び出しのブロッキング問題
+
+`async def` ハンドラーで同期の DB 呼び出し（SQLAlchemy sync API 等）を行うと、イベントループをブロックして他のリクエストが詰まる。
+
+```python
+# ❌ async def 内での同期 DB 呼び出しはブロッキング
+@app.get("/notes")
+async def list_notes() -> JSONResponse:
+    notes = session.execute(select(Note)).scalars().all()  # ブロック！
+    return JSONResponse(...)
+```
+
+**解決策1: `run_in_threadpool` でスレッドプールで実行する**
+
+```python
+from nene2.middleware import run_in_threadpool
+
+@app.get("/notes")
+async def list_notes() -> JSONResponse:
+    notes = await run_in_threadpool(session.execute, select(Note))
+    return JSONResponse(...)
+```
+
+**解決策2: `def`（同期）ハンドラーを使う**
+
+同期 DB を使う場合は、ハンドラーを `async def` にしない。FastAPI が自動でスレッドプールで実行する。
+
+```python
+# ✅ def ハンドラー + 同期 DB = 問題なし
+@app.get("/notes")
+def list_notes() -> JSONResponse:
+    notes = session.execute(select(Note)).scalars().all()
+    return JSONResponse(...)
+```
+
+**解決策3: SQLAlchemy async API に移行する**
+
+長期的には SQLAlchemy の async API（`AsyncSession`）への移行を検討する。

nene2_python-1.8.33/docs/how-to/background-tasks.md

@@ -0,0 +1,101 @@
+# How-to: BackgroundTasks
+
+FastAPI の `BackgroundTasks` を使ってレスポンス後に処理を実行するパターンを説明する。
+
+---
+
+## 1. 基本パターン
+
+```python
+from fastapi import BackgroundTasks, FastAPI
+from fastapi.responses import JSONResponse
+
+app = FastAPI()
+
+def send_notification(message: str) -> None:
+    # 時間がかかる処理（メール送信・外部 API 呼び出し等）
+    print(f"Sending: {message}")
+
+@app.post("/orders", status_code=201)
+def create_order(
+    body: CreateOrderBody,
+    background_tasks: BackgroundTasks,
+) -> JSONResponse:
+    order = process_order(body)
+    background_tasks.add_task(send_notification, f"Order {order.order_id} created")
+    return JSONResponse({"order_id": order.order_id}, status_code=201)
+```
+
+---
+
+## 2. UseCase との分離
+
+UseCase を HTTP 非依存に保つため、`BackgroundTasks` は UseCase に渡さない。ハンドラー層でイベントを受け取り、BackgroundTasks に追加する。
+
+```python
+# ✅ UseCase は BackgroundTasks を知らない
+class CreateOrderUseCase:
+    def execute(self, body: CreateOrderInput) -> CreateOrderOutput:
+        order = Order(...)
+        return CreateOrderOutput(order_id=order.order_id, notify_email=body.email)
+
+# ハンドラー層で BackgroundTasks を使う
+@app.post("/orders", status_code=201)
+def create_order(
+    body: CreateOrderBody,
+    background_tasks: BackgroundTasks,
+    use_case: CreateOrderUseCase = Depends(get_use_case),
+) -> JSONResponse:
+    result = use_case.execute(CreateOrderInput(email=body.email))
+    background_tasks.add_task(send_notification, result.notify_email)
+    return JSONResponse({"order_id": result.order_id}, status_code=201)
+```
+
+---
+
+## 3. TestClient での挙動
+
+`TestClient` では `BackgroundTasks` がレスポンス返却 **前** に同期的に実行される。
+
+```python
+executed: list[str] = []
+
+def track_task(msg: str) -> None:
+    executed.append(msg)
+
+# テストでは BackgroundTasks が同期実行される
+r = client.post("/orders", json={"email": "alice@example.com"})
+assert r.status_code == 201
+assert len(executed) == 1  # すでに実行済み
+```
+
+本番環境では非同期実行（レスポンス後）だが、テストでは同期実行されることに注意。
+
+---
+
+## 4. 失敗しても 500 にならない
+
+`BackgroundTasks` 内で例外が発生しても、レスポンスはすでに送信済みのため 500 にはならない。エラーはログに記録される。
+
+```python
+def risky_task() -> None:
+    raise RuntimeError("Background task failed")
+
+# レスポンスは 201 で返る（バックグラウンドエラーは隠れる）
+background_tasks.add_task(risky_task)
+```
+
+重要な処理は BackgroundTasks に頼らず、ジョブキュー（Celery・ARQ 等）を使う。
+
+---
+
+## 5. async def との組み合わせ
+
+`background_tasks.add_task()` には同期・非同期どちらの関数も渡せる。
+
+```python
+async def async_notification(email: str) -> None:
+    await send_email_async(email)
+
+background_tasks.add_task(async_notification, user.email)
+```

nene2_python-1.8.33/docs/how-to/cors.md

@@ -0,0 +1,87 @@
+# How-to: CORS 設定
+
+`setup_middlewares()` の `cors_allowed_origins` パラメーターで CORS を有効化する方法を説明する。
+
+---
+
+## 1. 基本: 単一オリジンを許可
+
+```python
+from nene2.middleware import setup_middlewares
+
+app = FastAPI()
+setup_middlewares(app, cors_allowed_origins=["https://example.com"])
+```
+
+`cors_allowed_origins` を指定しない（デフォルト `None`）と CORS ミドルウェアは追加されない。
+
+---
+
+## 2. 複数オリジンを許可
+
+```python
+setup_middlewares(app, cors_allowed_origins=[
+    "https://app.example.com",
+    "https://admin.example.com",
+])
+```
+
+---
+
+## 3. 開発環境: localhost を許可
+
+```python
+import os
+
+origins = ["https://app.example.com"]
+if os.getenv("APP_ENV") == "local":
+    origins += ["http://localhost:3000", "http://localhost:5173"]
+
+setup_middlewares(app, cors_allowed_origins=origins)
+```
+
+**`allow_origins=["*"]` は禁止**。CLAUDE.md のセキュリティポリシーにより、ワイルドカードオリジンは開発環境でも使用不可。
+
+---
+
+## 4. credentials（Cookie・Authorization ヘッダー）を許可
+
+`setup_middlewares()` は内部で `allow_credentials=True` を設定しない。credentials が必要な場合は `CORSMiddleware` を直接追加する。
+
+```python
+from starlette.middleware.cors import CORSMiddleware
+
+app = FastAPI()
+setup_middlewares(app)  # 他のミドルウェア（RequestId 等）は通常通り設定
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["https://app.example.com"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+**注意**: `add_middleware` は LIFO のため、`CORSMiddleware` を後から追加すると最外側に配置される。`setup_middlewares()` の後に呼ぶことで、CORS が最も外側で処理される。
+
+---
+
+## 5. CORS とプリフライトリクエスト
+
+`OPTIONS` リクエスト（プリフライト）は `CORSMiddleware` が自動で処理する。`@app.options(...)` を定義する必要はない。
+
+---
+
+## 6. テストでの CORS ヘッダー確認
+
+```python
+def test_cors_header() -> None:
+    with TestClient(app) as client:
+        r = client.get("/items", headers={"Origin": "https://app.example.com"})
+        assert r.headers.get("access-control-allow-origin") == "https://app.example.com"
+
+def test_cors_not_allowed_for_unknown_origin() -> None:
+    with TestClient(app) as client:
+        r = client.get("/items", headers={"Origin": "https://evil.com"})
+        assert "access-control-allow-origin" not in r.headers
+```