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

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

@@ -5,6 +5,17 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.30] — 2026-05-20
+
+FT87 フィールドトライアル — カスタムレスポンスヘッダーパターン検証と problem_details_response() 改善。
+
+### Added
+- `problem_details_response()` に `headers: dict[str, str] | None = None` パラメーターを追加 (#369) (FT87)
+  — エラーレスポンスに `Retry-After`（429）、`WWW-Authenticate`（401）などのカスタムヘッダーを付与可能に
+- Field trial reports: `docs/field-trials/2026-05-field-trial-85.md`, `2026-05-field-trial-86.md`, `2026-05-field-trial-87.md` (FT85, FT86, FT87)
+
+---
+
 ## [1.8.29] — 2026-05-20
 
 FT84 フィールドトライアル — 認証 Depends ユーティリティ検証と make_require_auth() 追加。

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.30
+Version: 1.8.31
 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
@@ -28,6 +28,7 @@ Requires-Dist: httpx>=0.27
 Requires-Dist: mcp>=1.0
 Requires-Dist: pydantic-settings>=2.6
 Requires-Dist: pydantic>=2.9
+Requires-Dist: pyjwt>=2.12.0
 Requires-Dist: python-multipart>=0.0.12
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: sqlalchemy>=2.0.49

nene2_python-1.8.31/docs/field-trials/2026-05-field-trial-88.md

@@ -0,0 +1,163 @@
+# FT88: ドメインイベント — 同期イベントバスパターン検証
+
+**日付**: 2026-05-20  
+**テーマ**: FastAPI/nene2 でのドメインイベント実装方法と摩擦点  
+**バージョン**: v1.8.30  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft88-domain-events/`
+
+---
+
+## 概要
+
+ドメインイベント（`OrderPlacedEvent`, `OrderCancelledEvent`）を発行し、
+通知・監査ログなどのサイドエフェクトを分離するパターンを検証。
+シンプルな同期 `EventBus` を自前実装し、nene2 のアーキテクチャと組み合わせた。
+nene2 に EventBus の仕組みがないため、ガイダンスの欠如が摩擦ポイントとなる。
+
+---
+
+## 実装パターン
+
+### EventBus（自前実装）
+
+```python
+type EventHandler[T] = Callable[[T], None]
+
+class EventBus:
+    def __init__(self) -> None:
+        self._handlers: dict[type, list[EventHandler[Any]]] = defaultdict(list)
+        self.published: list[Any] = []  # テスト用
+
+    def subscribe[T](self, event_type: type[T], handler: EventHandler[T]) -> None:
+        self._handlers[event_type].append(handler)
+
+    def publish(self, event: Any) -> None:
+        self.published.append(event)
+        for handler in self._handlers[type(event)]:
+            handler(event)
+```
+
+### UseCase でのイベント発行
+
+```python
+@app.post("/orders", response_model=OrderResponse, status_code=201)
+def place_order(body: PlaceOrderBody) -> JSONResponse:
+    order = Order(...)
+    _orders[order.order_id] = order
+
+    # ← イベント発行
+    event_bus.publish(OrderPlacedEvent(
+        order_id=order.order_id,
+        customer_id=order.customer_id,
+        total=order.total,
+    ))
+    return JSONResponse({...}, status_code=201)
+```
+
+---
+
+## 発見した問題
+
+### 問題1: EventBus が nene2 に含まれていない
+
+nene2 はドメインイベントのアーキテクチャパターンを提供していない。
+ユーザーが自前で `EventBus` を実装する必要があり、設計が人によって異なる。
+「どのレイヤーでイベントを発行するか」「イベントをどう注入するか」のガイダンスがない。
+
+### 問題2: 同期イベントバスでは例外がHTTPレスポンスに影響する
+
+```python
+# イベントハンドラーで例外が発生すると...
+def _on_order_placed(event: OrderPlacedEvent) -> None:
+    send_email(event)  # ← これが失敗すると
+
+# → ErrorHandlerMiddleware が 500 を返す
+# → 注文は作成されたのに 500 でクライアントに返る
+```
+
+「注文は DB に保存されたが通知送信に失敗」の場合、
+同期バスでは HTTP レスポンスが 500 になってしまう。
+`BackgroundTasks` と組み合わせるか、非同期バスを使う必要があるが、
+nene2 ドキュメントにそのパターンが示されていない。
+
+### 問題3: TestClient.delete() が json= をサポートしない
+
+```python
+# ❌ TypeError: TestClient.delete() got an unexpected keyword argument 'json'
+client.delete("/orders/1", json={"reason": "..."})
+
+# ✅ 回避策
+client.request("DELETE", "/orders/1", json={"reason": "..."})
+```
+
+DELETE + リクエストボディのパターンを httpx の TestClient がサポートしない。
+この摩擦は nene2 に起因しないが、DELETE + ボディが必要な API 設計時にハマる。
+
+---
+
+## テスト結果（全14件パス）
+
+```
+test_place_order_returns_201                        PASSED
+test_place_order_publishes_event                    PASSED
+test_place_order_triggers_notification              PASSED
+test_place_order_records_audit_log                  PASSED
+test_cancel_order_returns_204                       PASSED
+test_cancel_order_publishes_event                   PASSED
+test_cancel_order_404                               PASSED
+test_cancel_order_does_not_publish_event_on_404     PASSED
+test_event_bus_subscribe_and_publish                PASSED
+test_event_bus_multiple_handlers                    PASSED
+test_event_bus_unrelated_handler_not_called         PASSED
+test_event_bus_records_published_events             PASSED
+test_friction_event_bus_not_part_of_nene2           PASSED
+test_friction_event_handler_exception_propagates    PASSED
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F88-1 | EventBus が nene2 に含まれていない、ガイダンスもない | 中 |
+| F88-2 | 同期イベントバスではハンドラー例外が HTTP 500 になる、BackgroundTasks との組み合わせガイドがない | 高 |
+| F88-3 | TestClient.delete() が json= をサポートしない（httpx の制限） | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★☆☆
+
+EventBus 自体の実装は簡単。Python 3.12 のジェネリクス構文 (`type EventHandler[T]`) で
+型安全にハンドラーを登録できる。問題はアーキテクチャの指針がないこと。
+
+### 実害の深刻さ ★★★★☆
+
+F88-2 の「サイドエフェクト失敗で HTTP 500」は実際の運用で問題になる。
+メール送信・Slack 通知などの外部連携は失敗しても注文作成は成功扱いにしたい。
+`BackgroundTasks` との組み合わせパターンが必要。
+
+### 修正のしやすさ ★★★★☆
+
+- F88-1: ドキュメント（アーキテクチャガイド）を追加するだけ
+- F88-2: `BackgroundTasks` とのパターン例を how-to に追加
+- F88-3: コードコメント or ドキュメントで `client.request()` を使うよう明記
+
+### 総合コメント
+
+nene2 は「薄い HTTP 層」原則で UseCase とドメインを分離しているため、
+EventBus を UseCase に注入するのは自然に実装できる。
+ただし、「どこで EventBus を初期化して DI するか」が明確でなく、
+グローバル変数 vs lifespan + app.state vs Depends() の選択に迷う。
+
+---
+
+## 推奨アクション
+
+1. **docs**: how-to ガイドに「ドメインイベントパターン」を追加
+   - シンプルな同期 EventBus の実装例
+   - BackgroundTasks と組み合わせた非同期サイドエフェクトパターン
+   - EventBus の DI 方法（lifespan + app.state または module-level singleton）
+2. **docs**: DELETE + リクエストボディのテスト方法 (`client.request("DELETE", ...)`) を明記

nene2_python-1.8.31/docs/field-trials/2026-05-field-trial-89.md

@@ -0,0 +1,184 @@
+# FT89: カスタムバリデーション — Pydantic バリデーターと nene2 ValidationException の統合
+
+**日付**: 2026-05-20  
+**テーマ**: カスタム Pydantic バリデーター・クロスフィールド検証・nene2 ValidationException の統合  
+**バージョン**: v1.8.30  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft89-custom-validation/`
+
+---
+
+## 概要
+
+Pydantic v2 の `@field_validator` / `@model_validator` を使ったカスタムバリデーションと
+nene2 の `ValidationException` の統合を検証。
+`@model_validator` で `raise ValueError(...)` すると
+nene2 の Problem Details で `field: "request"` になる摩擦が発見された。
+
+---
+
+## 検証したパターン
+
+### 1. クロスフィールドバリデーション（`@model_validator`）
+
+```python
+class DateRangeBody(BaseModel):
+    start_date: date
+    end_date: date
+
+    @model_validator(mode="after")
+    def end_date_after_start_date(self) -> "DateRangeBody":
+        if self.end_date <= self.start_date:
+            raise ValueError("end_date must be after start_date")
+        return self
+```
+
+✅ 動作するが、エラーレスポンスの `field` が `"request"` になる（後述）。
+
+### 2. フィールドレベルバリデーション（`@field_validator`）
+
+```python
+class PasswordBody(BaseModel):
+    @field_validator("new_password")
+    @classmethod
+    def new_password_not_same_as_current(cls, value: str, info: FieldValidationInfo) -> str:
+        if info.data.get("current_password") == value:
+            raise ValueError("new_password must differ from current_password")
+        return value
+```
+
+✅ `field: "new_password"` が正しく設定される。
+
+### 3. UseCase 層からの ValidationException
+
+```python
+def validate_business_rule(label: str) -> None:
+    errors: list[ValidationError] = []
+    if label.lower() in RESERVED_LABELS:
+        errors.append(ValidationError(
+            field="label",
+            message=f"'{label}' is reserved.",
+            code="reserved-label",
+        ))
+    if errors:
+        raise ValidationException(errors)
+```
+
+✅ 完全にコントロール可能。field / message / code を自由に設定できる。
+
+---
+
+## 発見した問題
+
+### 問題1: `@model_validator` のエラーが `field: "request"` になる
+
+```python
+# @model_validator で raise ValueError
+# → Pydantic の loc: ("body",) or ()
+# → nene2 の request_validation_error_handler で "body" を除くと空
+# → field = "request" になる
+
+# 実際のレスポンス:
+{
+  "type": "https://nene2.dev/problems/validation-failed",
+  "errors": [
+    {
+      "field": "request",          # ← "end_date" や "end_date_after_start_date" ではない
+      "message": "Value error, end_date must be after start_date",
+      "code": "value_error"
+    }
+  ]
+}
+```
+
+`@field_validator("end_date")` のエラーは `field: "end_date"` になるが、
+`@model_validator` のエラーは `field: "request"` になる。
+クライアント（TypeScript など）がフィールド単位でエラーを表示する場合、
+どのフィールドにエラーが対応するかが不明になる。
+
+### 回避策: UseCase 層で ValidationException を raise
+
+```python
+@app.post("/date-ranges")
+def create_date_range(body: DateRangeBody) -> JSONResponse:
+    # Pydantic の @model_validator をやめて UseCase 層で検証
+    errors: list[ValidationError] = []
+    if body.end_date <= body.start_date:
+        errors.append(ValidationError("end_date", "end_date must be after start_date", "invalid"))
+    if errors:
+        raise ValidationException(errors)
+    ...
+```
+
+`ValidationException` を使えば field 名を明示できる。
+ただし Pydantic の `@model_validator` との二重定義になる。
+
+---
+
+## テスト結果（全16件パス）
+
+```
+test_date_range_valid_returns_201                             PASSED
+test_date_range_end_before_start_returns_422                  PASSED
+test_date_range_same_dates_returns_422                        PASSED
+test_date_range_reserved_label_returns_422                    PASSED
+test_password_change_valid_returns_204                        PASSED
+test_password_change_same_as_current_returns_422              PASSED
+test_password_change_mismatch_returns_422                     PASSED
+test_password_too_short_returns_422                           PASSED
+test_event_valid_returns_201                                  PASSED
+test_event_empty_tag_returns_422                              PASSED
+test_event_duplicate_tags_returns_422                         PASSED
+test_event_too_many_tags_returns_422                          PASSED
+test_explicit_error_missing_title_returns_422                 PASSED
+test_validation_error_response_is_problem_details_format      PASSED
+test_friction_pydantic_error_field_path_in_problem_details    PASSED
+test_friction_multiple_validation_errors_all_returned         PASSED
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F89-1 | `@model_validator` のエラーが `field: "request"` になり具体的なフィールド名が失われる | 中 |
+| F89-2 | クロスフィールドバリデーションを Pydantic で書くか UseCase で書くかの指針がない | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★★☆
+
+Pydantic v2 の `@field_validator` は直感的で nene2 と自然に統合できる。
+`@model_validator` も動くが、エラーの `field` 名が `"request"` になる不一致が惜しい。
+
+### 実害の深刻さ ★★★☆☆
+
+`field: "request"` 問題は、クライアントサイドがフィールド単位でバリデーション
+エラーを表示しない場合（メッセージを表示するだけ）は問題にならない。
+しかし TypeScript/React でフォームのフィールドにエラーを表示する場合は不便。
+
+### 修正のしやすさ ★★★★☆
+
+F89-1 はドキュメントだけで対応可能（`@model_validator` より `ValidationException` を推奨と明記）。
+または `request_validation_error_handler` で `model_validator` の loc パターンを
+検出して field 名を抽出するよう改善することも検討できる。
+
+### 総合コメント
+
+nene2 の `ValidationException` + `ValidationError` パターンは優れている。
+フィールド名・メッセージ・コードが明示的で、クライアントに構造化エラーを返せる。
+Pydantic の `@field_validator` との組み合わせも問題なし。
+`@model_validator` の field パス問題は既知の FastAPI/Pydantic の挙動で、
+ドキュメントで「クロスフィールドバリデーションは UseCase で行う」と案内するのが現実的。
+
+---
+
+## 推奨アクション
+
+1. **docs**: how-to ガイドに「カスタムバリデーションパターン」を追加
+   - `@field_validator` は nene2 Problem Details と自然に統合される
+   - クロスフィールドバリデーションは `ValidationException` で行うと `field` 名が正確
+   - `@model_validator` のエラーは `field: "request"` になることを明記
+2. **docs**: Pydantic バリデーションと UseCase バリデーションの使い分けを説明

nene2_python-1.8.31/docs/field-trials/2026-05-field-trial-90.md

@@ -0,0 +1,147 @@
+# FT90: ファイルアップロード — multipart/form-data バリデーションパターン検証
+
+**日付**: 2026-05-20  
+**テーマ**: FastAPI UploadFile + nene2 でのファイルアップロードバリデーション  
+**バージョン**: v1.8.30  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft90-file-upload/`
+
+---
+
+## 概要
+
+`UploadFile` を使ったファイルアップロード、コンテントタイプ・サイズバリデーション、
+複数ファイル一括アップロード、`RequestSizeLimitMiddleware` との共存を検証。
+`setup_middlewares()` のパラメーター名の非自明さと、
+FastAPI がコンテントタイプを自動検証しないことが摩擦として発見された。
+
+---
+
+## 実装パターン
+
+### 単一ファイルアップロード + バリデーション
+
+```python
+_ALLOWED_IMAGE_TYPES = frozenset({"image/jpeg", "image/png", "image/webp", "image/gif"})
+_MAX_FILE_SIZE = 5 * 1024 * 1024  # 5 MB
+
+@app.post("/files", response_model=FileResponse, status_code=201)
+async def upload_file(
+    file: UploadFile = File(description="ファイル"),
+    description: str = Form(default="", max_length=500),
+) -> JSONResponse:
+    if file.content_type not in _ALLOWED_IMAGE_TYPES:
+        return problem_details_response(
+            "invalid-content-type", "Invalid Content Type", 415,
+            headers={"Accept": ", ".join(sorted(_ALLOWED_IMAGE_TYPES))},
+        )
+    content = await file.read()
+    if len(content) > _MAX_FILE_SIZE:
+        return problem_details_response("file-too-large", "File Too Large", 413, ...)
+    ...
+```
+
+### nene2 の RequestSizeLimitMiddleware との共存
+
+```python
+# ✅ 正しいパラメーター名: max_request_bytes
+setup_middlewares(app, max_request_bytes=10 * 1024 * 1024)
+
+# ❌ 間違い（TypeError になる）
+setup_middlewares(app, max_request_size=10 * 1024 * 1024)
+```
+
+---
+
+## 発見した問題
+
+### 問題1: `setup_middlewares()` のパラメーター名が非自明
+
+`max_request_bytes` という名前は正確だが、
+`max_request_size` や `max_body_size` を試みるユーザーが多い。
+`TypeError: setup_middlewares() got an unexpected keyword argument 'max_request_size'. Did you mean 'max_request_bytes'?`
+というエラーが出るため気付けるが、IDE 補完がないと分かりにくい。
+
+### 問題2: FastAPI は UploadFile のコンテントタイプを自動検証しない
+
+```python
+# コンテントタイプを偽って送信しても FastAPI は受け付ける
+client.post("/files", files={"file": ("evil.exe", content, "image/jpeg")})
+# → content_type="image/jpeg" として処理される（EXE バイナリでも）
+```
+
+本番環境では `file.content_type` ヘッダーだけでなく、
+ファイルの魔法バイト（magic bytes）を検証する必要があるが、
+nene2 ドキュメントにそのパターンが示されていない。
+
+### 問題3: `async def` ハンドラーが必要
+
+`UploadFile.read()` は `await` が必要なため、ハンドラーを `async def` で定義する必要がある。
+nene2 の run_in_threadpool パターン（FT76）との組み合わせで注意が必要。
+
+---
+
+## テスト結果（全13件パス）
+
+```
+test_upload_valid_jpeg_returns_201                              PASSED
+test_upload_png_returns_201                                     PASSED
+test_upload_with_description_form_field                         PASSED
+test_upload_invalid_content_type_returns_415                    PASSED
+test_upload_too_large_returns_413                               PASSED
+test_upload_same_content_returns_same_id                        PASSED
+test_get_uploaded_file_info                                     PASSED
+test_get_nonexistent_file_returns_404                           PASSED
+test_list_files_after_upload                                    PASSED
+test_batch_upload_multiple_files                                PASSED
+test_batch_upload_invalid_type_returns_415                      PASSED
+test_friction_upload_file_missing_returns_422                   PASSED
+test_friction_content_type_not_validated_by_fastapi             PASSED
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F90-1 | `setup_middlewares()` の `max_request_bytes` パラメーター名が非自明（`max_request_size` と間違えやすい） | 低 |
+| F90-2 | FastAPI は UploadFile のコンテントタイプを自動検証しない（魔法バイト検証のパターン未文書） | 中 |
+| F90-3 | `UploadFile.read()` は `async def` が必要（sync ハンドラーとの混在に注意） | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★★☆
+
+`UploadFile` + `File()` のパターンは直感的。
+Form フィールドと同時に送信する場合も `data={"field": "value"}` で簡単。
+`problem_details_response(headers=...)` で 415 の `Accept` ヘッダーも付けられた（FT87 の成果）。
+
+### 実害の深刻さ ★★★☆☆
+
+F90-2 はセキュリティ観点で中程度。
+コンテントタイプを偽ったファイルアップロードは現実の攻撃手法。
+nene2 ドキュメントに魔法バイト検証の例があれば防げる。
+
+### 修正のしやすさ ★★★★★
+
+F90-1: `max_request_bytes` のドキュメントに `max_request_size` との違いを明記するだけ。
+F90-2: ドキュメントに魔法バイト検証の例を追加。
+F90-3: ドキュメントに `async def` が必要な旨を明記。
+
+### 総合コメント
+
+nene2 の `RequestSizeLimitMiddleware` との共存は問題なし。
+`problem_details_response()` を使ったエラー応答（415, 413）もきれいに動く。
+FT87 で追加した `headers` パラメーターが早速役立った（415 に `Accept` ヘッダーを付与）。
+
+---
+
+## 推奨アクション
+
+1. **docs**: how-to に「ファイルアップロード」ガイドを追加
+   - `UploadFile` + コンテントタイプ・サイズバリデーションのパターン
+   - 魔法バイト（magic bytes）検証の例
+   - `RequestSizeLimitMiddleware` との組み合わせ（`max_request_bytes` を明示）
+2. **docs**: `max_request_bytes` パラメーターに `max_request_size` との混同を防ぐ注記