nene2-python 1.8.6__tar.gz → 1.8.7__tar.gz

{nene2_python-1.8.6 → nene2_python-1.8.7}/CHANGELOG.md

@@ -5,6 +5,16 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.7] — 2026-05-20
+
+FT43〜FT44 フィールドトライアル — ThrottleMiddleware path_limits 確認・PaginationQueryParser バリデーション改善。
+
+### Added
+- `nene2.middleware.request_validation_error_handler` を公開エクスポートに追加 — FastAPI の `RequestValidationError` を Problem Details 形式に変換するハンドラーを `from nene2.middleware import request_validation_error_handler` でアクセス可能に (FT44)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-43.md`、`docs/field-trials/2026-05-field-trial-44.md`
+
+---
+
 ## [1.8.6] — 2026-05-20
 
 FT41〜FT42 フィールドトライアル — structlog テスト統合ドキュメント・configure_problem_details リセット関数。

{nene2_python-1.8.6 → nene2_python-1.8.7}/PKG-INFO

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

@@ -0,0 +1,112 @@
+# Field Trial 43: ThrottleMiddleware path_limits 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.6 時点
+**テーマ**: `ThrottleMiddleware` の `path_limits` パラメータを使ってエンドポイントごとにレート制限を設定するパターンの実運用確認
+
+---
+
+## 概要
+
+グローバルレート制限（`limit=100`）と、特定パスへの厳しい制限（`path_limits={"/api/search": 10, "/api/upload": 5}`）を組み合わせた API を実装し、動作を確認した。
+レートカウンターがパスごとに独立して管理されること、`X-RateLimit-*` ヘッダーが適切に付与されることを検証した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft43-throttle-path-limits/` に以下を作成:
+
+- **`app.py`** — グローバル + パスごとのレート制限設定、`/health` 除外パスの構成
+- **`test_app.py`** — 正常系・ヘッダー確認・path_limits 独立性・429 動作 (10 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 14 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP43-1: path_limits のカウンターはグローバルカウンターと完全に独立している
+
+**分類**: 摩擦なし（良い設計の確認）
+
+`path_limits` に指定したパスは `{client}:{path}` をキーとして使い、
+グローバルカウンター (`{client}`) とは別々に管理される。
+`/api/search` を使い切っても `/api/items` のカウンターには影響しない。
+
+```python
+# /api/search の制限 (3 req) を使い切っても
+for _ in range(3):
+    client.get("/api/search")
+# /api/items の制限は消費されていない
+r = client.get("/api/items")
+assert r.status_code == 200  # OK
+```
+
+**判断**: FT28 で実装した設計通り。パス別独立カウンターは想定通りに動作する。
+
+---
+
+### FP43-2: X-RateLimit-Limit ヘッダーがパスごとの制限値を反映する
+
+**分類**: 摩擦なし（良い設計の確認）
+
+`/api/search` へのリクエストには `X-RateLimit-Limit: 3` が付与され、
+`/api/items` へのリクエストには `X-RateLimit-Limit: 10` が付与される。
+クライアントはヘッダーを見て自分のリミットがいくつかを判断できる。
+
+**判断**: FT20 で実装したヘッダー付与が path_limits と正しく連携している。
+
+---
+
+### FP43-3: X-Forwarded-For がクライアントキーとして使われるためバイパスに注意
+
+**分類**: 設計上の制約（ドキュメントに記載済み・運用上の注意点）
+
+`X-Forwarded-For` ヘッダーがある場合、それをクライアント IP として使う設計のため、
+異なる `X-Forwarded-For` を送ることで別のクライアントとして扱われ、レート制限をバイパスできる。
+
+```python
+# 通常の IP で制限を使い切ったあと
+for _ in range(2):
+    client.get("/api/items")
+r = client.get("/api/items")
+assert r.status_code == 429
+
+# 別の IP を騙って送ると 200 になる
+r = client.get("/api/items", headers={"X-Forwarded-For": "10.0.0.1"})
+assert r.status_code == 200  # バイパスできてしまう
+```
+
+**判断**: ドキュメントの Warning セクションに記載されている既知の制限。
+信頼できるリバースプロキシを前段に置くことで軽減できる。
+テスト環境での動作確認として有用。
+
+---
+
+### FP43-4: path_limits の対象外パスはグローバル制限のみが適用される
+
+**分類**: 摩擦なし（設計の確認）
+
+`path_limits` に指定していないパス (`/api/items` など) はグローバルの `limit` が適用される。
+複数のエンドポイントに異なる制限を設けつつ、デフォルトのグローバル制限を基本として使う設計が自然に実現できる。
+
+**判断**: FT28 の設計通り。`path_limits` に指定のないパスは `{client}` をキーに使い、グローバルカウンターで管理される。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+---
+
+## 関連
+
+- `nene2.middleware.ThrottleMiddleware` (FT20, v1.8.0)
+- `ThrottleMiddleware.path_limits` (FT28, v1.8.1)
+- `ThrottleMiddleware` ウィンドウクリーンアップ (FT27, v1.8.1)
+- FT20 (ThrottleMiddleware ヘッダー実装, v1.8.0)
+- FT27 (ThrottleMiddleware クリーンアップ修正, v1.8.1)
+- FT28 (ThrottleMiddleware path_limits 実装, v1.8.1)

nene2_python-1.8.7/docs/field-trials/2026-05-field-trial-44.md

@@ -0,0 +1,110 @@
+# Field Trial 44: PaginationQueryParser + PaginationResponse 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.6 時点
+**テーマ**: `PaginationQueryParser` を `Annotated[..., Depends()]` 構文で使い `PaginationResponse.to_dict()` でスロット付きデータクラスをシリアライズするパターンの実運用確認
+
+---
+
+## 概要
+
+`PaginationQueryParser` を FastAPI の `Depends()` として注入し、
+`PaginationResponse` + `to_dict()` でスロット付き `dataclass(frozen=True, slots=True)` を
+シリアライズするパターンを実装した。
+`total` フィールドのあり/なし両パターン、および生の dict アイテムを含むケースも確認した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft44-pagination/` に以下を作成:
+
+- **`app.py`** — `PaginationQueryParser` Depends 注入、スロット付きデータクラス `Product`、3 つのエンドポイント（total あり/なし/生 dict）
+- **`test_app.py`** — デフォルト・カスタム・オフセット・total・スロット付きシリアライズ・422 (10 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 14 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP44-1: OpenAPI スキーマにクエリパラメータが正しく文書化される
+
+**分類**: 摩擦なし（良い設計の確認）
+
+`Annotated[PaginationQueryParser, Depends()]` 構文を使うと、
+`Query(ge=1, le=100, description="Items per page (1–100)")` の情報が
+FastAPI の自動 OpenAPI スキーマ生成に反映される。
+`/openapi.json` の `parameters` に `limit`・`offset` が説明付きで表示される。
+
+**判断**: FT10 で実装した `Depends()` 対応の効果が確認できた。
+
+---
+
+### FP44-2: PaginationResponse.to_dict() は元のアイテムを変更しない
+
+**分類**: 摩擦なし（設計の確認）
+
+`to_dict()` は `dataclasses.asdict()` で新しい dict を生成するため、
+元の `dataclass` インスタンスは変更されない。immutable な `frozen=True` データクラスが
+そのままリポジトリで保持できる。
+
+---
+
+### FP44-3: items が空リストのときも to_dict() が正常動作する
+
+**分類**: 摩擦なし（エッジケース確認）
+
+`items=[]` のとき `to_dict()` は `{"items": [], "limit": 20, "offset": 100, "total": 50}`
+を返す。ページを超えたオフセットでのリクエストが自然に処理される。
+
+---
+
+### FP44-4: Depends() 使用時のバリデーションエラーが Problem Details 形式にならない
+
+**分類**: 摩擦あり（Issues #268 で対応）
+
+`PaginationQueryParser` を `Depends()` として使うと、
+`limit=0` や `limit=101` のバリデーションは FastAPI が実行し、
+エラーは FastAPI のデフォルト Pydantic 形式（`{"detail": [...]}`）になる:
+
+```json
+{"detail": [{"type": "greater_than_equal", ...}]}
+```
+
+一方、nene2 の `ValidationException` は Problem Details 形式:
+
+```json
+{"type": "...", "title": "Validation Failed", "status": 422, "errors": [...]}
+```
+
+この不一致を解消するため、`nene2.middleware.request_validation_error_handler` を
+FastAPI の exception handler として登録することで Problem Details 形式に統一できる:
+
+```python
+from fastapi.exceptions import RequestValidationError
+from nene2.middleware import request_validation_error_handler
+
+app.add_exception_handler(RequestValidationError, request_validation_error_handler)
+```
+
+**対応**: `request_validation_error_handler` は `error_handler.py` に既存実装済みだったが、
+`nene2.middleware` からエクスポートされていなかった (Issue #268)。
+`nene2.middleware.__init__` に追加することで `from nene2.middleware import request_validation_error_handler` が可能になった。
+
+---
+
+## フレームワーク変更
+
+- `nene2.middleware.__init__` に `request_validation_error_handler` を追加エクスポート (#268)
+
+---
+
+## 関連
+
+- `nene2.http.PaginationQueryParser` (FT10, v1.3.0)
+- `nene2.http.PaginationResponse` (FT10, v1.3.0)
+- `nene2.middleware.request_validation_error_handler`
+- FT10 (PaginationQueryParser Depends 対応, v1.3.0)
+- Issue #268 (request_validation_error_handler エクスポート追加)

{nene2_python-1.8.6 → nene2_python-1.8.7}/pyproject.toml

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

{nene2_python-1.8.6 → nene2_python-1.8.7}/src/nene2/middleware/__init__.py

@@ -1,7 +1,7 @@
 """NENE2 middleware pipeline."""
 
 from .domain_exception import DomainExceptionHandlerProtocol, SimpleDomainHandler
-from .error_handler import ErrorHandlerMiddleware
+from .error_handler import ErrorHandlerMiddleware, request_validation_error_handler
 from .request_id import RequestIdMiddleware, get_request_id, request_id_var
 from .request_logging import RequestLoggingMiddleware
 from .request_size_limit import RequestSizeLimitMiddleware
@@ -12,6 +12,7 @@ __all__ = [
     "DomainExceptionHandlerProtocol",
     "SimpleDomainHandler",
     "ErrorHandlerMiddleware",
+    "request_validation_error_handler",
     "RequestIdMiddleware",
     "get_request_id",
     "RequestLoggingMiddleware",

{nene2_python-1.8.6 → nene2_python-1.8.7}/uv.lock

@@ -925,7 +925,7 @@ wheels = [
 
 [[package]]
 name = "nene2-python"
-version = "1.8.6"
+version = "1.8.7"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },