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

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

@@ -5,6 +5,28 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.8] — 2026-05-20
+
+FT45 フィールドトライアル — SecurityHeadersMiddleware CSP バグ修正。
+
+### Fixed
+- `SecurityHeadersMiddleware` — `csp=""` を渡したとき空の `Content-Security-Policy` ヘッダーが付与される問題を修正。`csp=""` の場合は CSP ヘッダーを付与しないよう変更 (#271) (FT45)
+
+### Added
+- Field trial report: `docs/field-trials/2026-05-field-trial-45.md`
+
+---
+
+## [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.8}/PKG-INFO

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

@@ -0,0 +1,108 @@
+# Field Trial 45: SecurityHeadersMiddleware 詳細カスタマイズ実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.7 時点
+**テーマ**: `SecurityHeadersMiddleware` の全オプション（CSP・HSTS・Permissions-Policy・extra_no_csp_paths）を組み合わせた実運用確認
+
+---
+
+## 概要
+
+`SecurityHeadersMiddleware` の CSP カスタマイズ・HSTS 設定・Permissions-Policy カスタマイズ・
+カスタム docs_url との組み合わせを実装した。
+2 つの摩擦点を発見し、うち 1 件 (FP45-3) を修正した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft45-security-headers/` に以下を作成:
+
+- **`app.py`** — カスタム `docs_url`/`openapi_url` + `SecurityHeadersMiddleware` 全オプション
+- **`test_app.py`** — 静的ヘッダー・CSP・HSTS・Permissions-Policy・extra_no_csp_paths (12 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 16 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP45-1: カスタム docs_url 使用時に extra_no_csp_paths の設定を忘れやすい
+
+**分類**: 軽微な摩擦（ドキュメント追記で対応）
+
+FastAPI の `docs_url="/api/docs"` のようにカスタム URL を使う場合、
+`SecurityHeadersMiddleware` のデフォルト `no_csp_paths` には
+`/docs`・`/redoc`・`/openapi.json` しか含まれない。
+`/api/docs` には CSP が付いてしまい、Swagger UI の CDN アセットが CSP でブロックされる。
+
+```python
+# カスタム docs_url 使用時の必須設定
+app.add_middleware(
+    SecurityHeadersMiddleware,
+    extra_no_csp_paths=["/api/docs", "/api/redoc", "/api/openapi.json"],
+)
+```
+
+**判断**: FT15 で実装した `extra_no_csp_paths` で対応可能だが、
+デフォルトの `docs_url` を変更したときに `extra_no_csp_paths` も更新する必要があることを
+ドキュメントで注意喚起する価値がある。
+
+---
+
+### FP45-2: HSTS は本番環境以外で有効にしてはならない
+
+**分類**: 注意喚起（設計通り・ドキュメント記載済み）
+
+`hsts` パラメータを設定すると、`Strict-Transport-Security` ヘッダーが付与される。
+http:// でアクセスすると次回以降 https:// を強制するため、開発環境での誤設定に注意が必要。
+`hsts=None` のデフォルトは意図的な安全設計。
+
+**判断**: 設計通り。ドキュメントの Warning で注意喚起済み。
+
+---
+
+### FP45-3: csp="" のとき空の CSP ヘッダーが付与されていた
+
+**分類**: バグ（#271 で修正）
+
+`csp=""` を渡すと `Content-Security-Policy: ` という空ヘッダーが付与されていた。
+ユーザーが CSP を無効化しようとして `csp=""` を渡すと、空 CSP が付く予期しない動作になる。
+
+**修正**: `dispatch()` を `self._csp` が truthy のときのみ CSP ヘッダーを付与するよう変更。
+`csp=""` は「CSP ヘッダーを付けない」として扱われる。
+
+```python
+# 修正前
+if request.url.path not in self._no_csp_paths:
+    response.headers["Content-Security-Policy"] = self._csp
+
+# 修正後
+if request.url.path not in self._no_csp_paths and self._csp:
+    response.headers["Content-Security-Policy"] = self._csp
+```
+
+---
+
+### FP45-4: 全オプション組み合わせは問題なく動作する
+
+**分類**: 摩擦なし（設計の確認）
+
+`csp`・`permissions_policy`・`hsts`・`extra_no_csp_paths` の全オプションを同時に指定しても
+正常に動作することを確認した。
+
+---
+
+## フレームワーク変更
+
+- `SecurityHeadersMiddleware.dispatch()` — `csp=""` のとき CSP ヘッダーを付与しないよう修正 (#271)
+
+---
+
+## 関連
+
+- `nene2.middleware.SecurityHeadersMiddleware`
+- FT15 (CSP カスタマイズ, v1.7.0)
+- FT32 (HSTS・Permissions-Policy 追加, v1.8.3)
+- Issue #271 (csp="" バグ修正)

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

@@ -1,6 +1,6 @@
 [project]
 name = "nene2-python"
-version = "1.8.6"
+version = "1.8.8"
 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.8}/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.8}/src/nene2/middleware/security_headers.py

@@ -63,6 +63,6 @@ class SecurityHeadersMiddleware(BaseHTTPMiddleware):
         response.headers["Permissions-Policy"] = self._permissions_policy
         if self._hsts:
             response.headers["Strict-Transport-Security"] = self._hsts
-        if request.url.path not in self._no_csp_paths:
+        if request.url.path not in self._no_csp_paths and self._csp:
             response.headers["Content-Security-Policy"] = self._csp
         return response

{nene2_python-1.8.6 → nene2_python-1.8.8}/tests/nene2/middleware/test_security_headers.py

@@ -130,3 +130,16 @@ def test_default_no_csp_paths_still_work_with_extra_paths() -> None:
     assert "Content-Security-Policy" not in client.get("/docs").headers
     assert "Content-Security-Policy" not in client.get("/custom").headers
     assert "Content-Security-Policy" in client.get("/ping").headers
+
+
+def test_csp_empty_string_disables_csp_header() -> None:
+    app = FastAPI()
+    app.add_middleware(SecurityHeadersMiddleware, csp="")
+
+    @app.get("/ping")
+    async def ping() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    r = client.get("/ping")
+    assert "Content-Security-Policy" not in r.headers

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

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