nene2-python 1.7.0__tar.gz → 1.8.1__tar.gz

{nene2_python-1.7.0 → nene2_python-1.8.1}/CHANGELOG.md

@@ -5,6 +5,42 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.1] — 2026-05-20
+
+FT25〜FT28 フィールドトライアル — RequestId ヘルパー・structlog ログレベル・ThrottleMiddleware 改善。
+
+### Added
+- `nene2.middleware.get_request_id()` — FastAPI `Depends` で注入できる request ID ヘルパー関数 (FT25)
+- `setup_logging()` に `log_level: str = "INFO"` パラメータを追加し `AppSettings.log_level` との統合が容易に (FT26)
+- `ThrottleMiddleware` に `path_limits: dict[str, int] | None` パラメータを追加し、パスごとに異なるレート制限を設定可能に (FT28)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-25.md` 〜 `docs/field-trials/2026-05-field-trial-28.md`
+
+### Fixed
+- `ThrottleMiddleware` — ウィンドウ経過後も `_counts` に古いエントリが残り続ける問題を修正（定期クリーンアップを実装）(FT27)
+
+---
+
+## [1.8.0] — 2026-05-20
+
+FT18〜FT23 フィールドトライアル — ログテスト・Problem Details・ThrottleMiddleware・ドメイン例外・HealthCheck・RequestSizeLimit の各改善。
+
+### Added
+- `nene2.log.configure_for_testing()` — structlog を pytest の `caplog` でキャプチャできるように設定するヘルパー関数 (FT18)
+- `nene2.http.configure_problem_details(base_url)` — プロジェクト全体のデフォルト `base_url` を一箇所で設定する関数 (FT19)
+- `ThrottleMiddleware` — 全レスポンスに `X-RateLimit-Limit`/`Remaining`/`Reset` ヘッダーを付与 (FT20)
+- `SimpleDomainHandler` — `exception_class`/`problem_type`/`title`/`status` を渡すだけでドメイン例外ハンドラーを作成できるファクトリクラス (FT21)
+- `nene2.http.CompositeHealthCheck` — 複数の `HealthCheckProtocol` を集約するクラス (FT22)
+- `HealthCheckProtocol` に `@runtime_checkable` を追加 (FT22)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-18.md` 〜 `docs/field-trials/2026-05-field-trial-23.md`
+- `docs/how-to/problem-details.md` — Problem Details の使い方ガイドを追加
+
+### Changed
+- `RequestLoggingMiddleware` — `exclude_paths: list[str] | None` パラメータを追加（特定パスのログをスキップ可能に）(FT18)
+- `ThrottleMiddleware` — 内部の `_is_allowed()` を `_check_rate()` にリネームし、戻り値を `_RateInfo` dataclass に変更 (FT20)
+- `RequestSizeLimitMiddleware` — 413 レスポンスに `max_bytes` 構造化フィールドを追加 (FT23)
+
+---
+
 ## [1.7.0] — 2026-05-20
 
 FT14〜FT17 フィールドトライアル — プロトコル docstring 改善・ミドルウェアカスタマイズ・DB 例外統一・バグ修正。

{nene2_python-1.7.0 → nene2_python-1.8.1}/PKG-INFO

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

@@ -0,0 +1,60 @@
+# Field Trial 18 — RequestLoggingMiddleware 実運用
+
+**Date:** 2026-05-20
+**App:** FT18 Request Logging API（structlog ログ・request_id 連携・JSON ログ形式検証）
+**Directory:** `/home/xi/docker/nene2-python-FT/ft18-request-logging/`
+**nene2-python version:** v1.7.0
+
+## 概要
+
+`RequestLoggingMiddleware` を `RequestIdMiddleware` と組み合わせて実際に動かし、
+ログ出力の内容・request_id との連携・テストでのログ検証方法を確認した。
+
+## 動作確認結果
+
+- `request.received` / `request.completed` のログが出力されること ✓
+- ログに `method`, `path`, `status_code`, `duration_ms` が含まれること ✓
+- `RequestIdMiddleware` と組み合わせると `request_id` がログに入ること ✓
+- ログに `request_id` が含まれ、レスポンスヘッダーの `X-Request-Id` と一致すること ✓
+
+## 摩擦点
+
+### FT18-F1 (MEDIUM, テスト容易性): structlog が pytest caplog で捕捉できない
+
+`RequestLoggingMiddleware` は structlog を使ってログを出力するが、
+structlog のデフォルト設定では Python stdlib の logging ハンドラーを経由せず
+直接 stdout に書き込む。
+
+そのため pytest の `caplog` では構造化ログを捕捉できない。
+テストで `structlog` のログを検証するには `capsys` で stdout を捕捉するか、
+structlog を stdlib logging に向ける設定変更が必要。
+
+```python
+# caplog では捕捉できない（摩擦）
+with caplog.at_level(logging.INFO, logger="nene2.middleware.request_logging"):
+    client.get("/health")
+assert len(caplog.records) == 0  # 常に 0 — ログが入らない
+```
+
+**対応案**: `nene2.log` に `configure_for_testing()` ヘルパーを追加し、
+テスト環境で `structlog` を stdlib logging ブリッジ経由で使える設定を提供する。
+
+### FT18-F2 (LOW, 拡張性): ログレベルをコンストラクタから変更できない
+
+`RequestLoggingMiddleware` は常に `logger.info()` を使う。
+ヘルスチェックなど高頻度のパスのログを `DEBUG` に落としたい場合や、
+特定パスのログを無効化したい場合にコンストラクタパラメータで設定できない。
+
+他のミドルウェア（`ThrottleMiddleware` の `exclude_paths` など）との一貫性が取れていない。
+
+**対応案**: `exclude_paths: list[str] | None = None` パラメータを追加して
+特定パスのログを無効化できるようにする。または `log_level` パラメータで
+デフォルトのログレベルを変更可能にする。
+
+## まとめ
+
+基本的なリクエストロギングは問題なく動作した。`RequestIdMiddleware` との連携も良好。
+摩擦はテスト時の `caplog` 非対応（F1: MEDIUM）と拡張性（F2: LOW）の2点。
+
+F1 は structlog の設計に起因するが、テスト用ヘルパーを提供することで改善できる。
+F2 は他のミドルウェアとの一貫性の問題。

nene2_python-1.8.1/docs/field-trials/2026-05-field-trial-19.md

@@ -0,0 +1,98 @@
+# FT19: problem_details_response() RFC 9457 実運用検証
+
+**日付**: 2026-05-20
+**テーマ**: `problem_details_response()` を使って RFC 9457 準拠のエラー応答を実装する
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft19-problem-details/`
+
+---
+
+## 目的
+
+`nene2.http.problem_details_response()` を実際のアプリ（記事 API）に組み込み、
+401/404/422 のエラー応答を RFC 9457 形式で返すパターンを検証する。
+また、`ErrorHandlerMiddleware` との統合状況を確認する。
+
+---
+
+## 実施内容
+
+記事 CRUD API（`/articles/{article_id}`）を作成し、以下のシナリオで `problem_details_response()` を使用:
+
+- **401 Unauthorized**: X-API-Key ヘッダー未提供または無効
+- **404 Not Found**: 存在しない記事 ID へのアクセス（`extra={"article_id": article_id}` 付き）
+- **422 Validation Failed**: 空のタイトルで記事作成（`extra={"errors": [...]}` 付き）
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・準拠確認）
+| テスト | 結果 |
+|---|---|
+| test_get_article_success | PASS |
+| test_get_article_not_found_returns_problem_details | PASS |
+| test_unauthorized_returns_problem_details | PASS |
+| test_validation_error_returns_problem_details | PASS |
+| test_problem_details_type_is_absolute_url | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_base_url_is_not_customizable_per_call | PASS | あり |
+| test_validation_exception_and_problem_details_not_integrated | PASS | なし（当初の予想と逆） |
+| test_no_typed_problem_type_constants | PASS | あり |
+
+---
+
+## 発見した摩擦点
+
+### FT19-F1: プロジェクト全体の base_url を一箇所で設定できない
+
+**概要**: `problem_details_response()` は `base_url` パラメータを持つが、
+プロジェクト全体で一箇所に設定する仕組みがない。
+複数のハンドラーで同じ `base_url` を保証するには、
+毎回引数で渡すか、プロジェクトでラッパー関数を書く必要がある。
+
+**影響**: 大規模プロジェクトで `base_url` の不統一が発生しやすい。
+
+**期待する解決策**: `configure_problem_details(base_url: str)` のような
+モジュールレベルの設定関数を提供する。
+
+---
+
+### FT19-F2: ErrorHandlerMiddleware と problem_details_response() の統合（摩擦なし）
+
+当初「`ErrorHandlerMiddleware` が `ValidationException` を処理する際に
+`application/json` を返すのではないか」と懸念していたが、
+実際には `problem_details_response()` を内部で使っており、
+`application/problem+json` が正しく返される。
+
+**結論**: 摩擦なし。むしろ正しく統合されている。
+
+---
+
+### FT19-F3: problem_type 文字列に型安全な定数がない
+
+**概要**: `problem_type` は文字列リテラルで渡すため、タイポがあっても
+mypy では検出されない。同じプロジェクト内で `"not-found"` と `"not_found"` が
+混在してもエラーにならない。
+
+**影響**: 大規模プロジェクトで problem_type の不統一が起きやすい。
+
+**期待する解決策**: 標準的な problem_type 定数のドキュメント化、
+またはユーザーが StrEnum を使うパターンのガイダンス。
+（フレームワーク側で全 problem_type を定義するのは over-engineering のため、
+ドキュメントやパターン提示が適切）
+
+---
+
+## まとめ
+
+`problem_details_response()` は RFC 9457 に準拠しており、`ErrorHandlerMiddleware` と
+も正しく統合されている。実用上の摩擦は以下の 2 点:
+
+1. **プロジェクト全体の base_url 設定機構がない** → Issue 化して修正対象
+2. **problem_type 文字列の型安全性がない** → Issue 化してドキュメント対応
+
+v1.4.0 で追加された `exclude_paths`、FT15-FT18 で追加された各ミドルウェア改善も
+本 FT で間接的に動作確認できた。

nene2_python-1.8.1/docs/field-trials/2026-05-field-trial-20.md

@@ -0,0 +1,94 @@
+# FT20: ThrottleMiddleware 実運用検証
+
+**日付**: 2026-05-20
+**テーマ**: `ThrottleMiddleware` を使ったレート制限 API の実運用検証
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft20-throttle/`
+
+---
+
+## 目的
+
+`nene2.middleware.ThrottleMiddleware` を実際のアプリ（公開 API + ヘルスチェック）に組み込み、
+レート制限の動作確認と摩擦点を発見する。
+
+---
+
+## 実施内容
+
+- `limit=3, window=60` のレート制限を設定した FastAPI アプリを作成
+- `/health` を `exclude_paths` で除外
+- `/api/data`、`/api/expensive` の 2 エンドポイントにレート制限を適用
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・機能確認）
+| テスト | 結果 |
+|---|---|
+| test_health_check_is_not_rate_limited | PASS |
+| test_requests_within_limit_succeed | PASS |
+| test_requests_exceeding_limit_return_429 | PASS |
+| test_rate_limit_429_includes_retry_after_header | PASS |
+| test_rate_limit_applies_across_different_endpoints | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_no_rate_limit_headers_on_successful_responses | PASS | あり |
+| test_no_per_path_rate_limits | PASS | あり |
+| test_memory_not_cleaned_up_over_time | PASS | あり |
+
+---
+
+## 発見した摩擦点
+
+### FT20-F1: 通常レスポンスに X-RateLimit-* ヘッダーが付かない
+
+**概要**: 429 応答には `Retry-After` ヘッダーが付くが、
+通常のレスポンスには `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset`
+が付かない。
+
+**影響**: クライアントが自分のレート制限状況をリアルタイムで把握できない。
+SDK やクライアントが事前にスロットリングする「adaptive throttling」が実装できない。
+
+**期待する解決策**: 全レスポンスに `X-RateLimit-*` ヘッダーを付与するオプションを追加。
+
+---
+
+### FT20-F2: エンドポイントごとに異なるレート制限を設定できない
+
+**概要**: `ThrottleMiddleware` は全エンドポイントで同一の `limit`/`window` のみ対応。
+コスト大きなエンドポイント（`/api/expensive`: 10req/min）と軽いエンドポイント
+（`/api/data`: 100req/min）で異なる制限を設定できない。
+
+**影響**: 実運用では計算コストの重いエンドポイントを個別に絞りたいケースが多い。
+
+**期待する解決策**: `path_limits: dict[str, int] | None = None` のようなパスごとの
+レート制限設定パラメータを追加。
+
+---
+
+### FT20-F3: 古い IP エントリがメモリから削除されない
+
+**概要**: `_counts` dict のエントリは、ウィンドウ経過後もメモリに残り続ける。
+リクエスト時に古いエントリを上書きするだけで、削除はしない設計。
+
+**影響**: 長時間稼働するサーバーでユニーク IP が多い場合、メモリが増加し続ける。
+
+**期待する解決策**: ウィンドウ経過後の古いエントリを定期的に削除する
+クリーンアップ機構（ローリングクリーンアップや LRU キャッシュ制限など）を追加。
+
+---
+
+## まとめ
+
+`ThrottleMiddleware` の基本機能（IP ベースの固定ウィンドウレート制限、429 応答、
+`Retry-After` ヘッダー、`exclude_paths`）は問題なく動作する。
+実運用でよく必要になる以下の 3 点が摩擦として発見された:
+
+1. **`X-RateLimit-*` ヘッダーの欠如** → クライアントが制限状況を把握できない
+2. **パスごとのレート制限が不可** → 計算コストの差があるエンドポイントの制御が難しい
+3. **古いエントリのメモリ残留** → 長時間稼働時のメモリリーク懸念
+
+F1 (X-RateLimit headers) が最も実装インパクトが高く、今回の修正対象とする。

nene2_python-1.8.1/docs/field-trials/2026-05-field-trial-21.md

@@ -0,0 +1,104 @@
+# FT21: DomainExceptionHandler 実運用検証
+
+**日付**: 2026-05-20
+**テーマ**: `DomainExceptionHandlerProtocol` を使ったカスタム例外ハンドリングの実運用検証
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft21-domain-exception/`
+
+---
+
+## 目的
+
+`nene2.middleware.ErrorHandlerMiddleware` の `domain_handlers` オプションを使い、
+複数のカスタムドメイン例外を Problem Details に変換するパターンを検証する。
+
+---
+
+## 実施内容
+
+ブログ記事 API（`/posts/{post_id}`）を作成し、以下のドメイン例外を実装:
+
+- `PostNotFoundError` → 404 problem-details
+- `PostAccessDeniedError` → 403 problem-details
+- `PostAlreadyPublishedError` → 409 problem-details
+
+各例外に対応する `DomainExceptionHandlerProtocol` 実装クラスを作成し、
+`ErrorHandlerMiddleware(domain_handlers=[...])` に登録。
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・機能確認）
+| テスト | 結果 |
+|---|---|
+| test_get_existing_post_returns_200 | PASS |
+| test_get_nonexistent_post_returns_404_problem_details | PASS |
+| test_get_other_users_post_returns_403 | PASS |
+| test_publish_already_published_returns_409 | PASS |
+| test_publish_unpublished_post_succeeds | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_no_base_class_for_domain_exception_handlers | PASS | あり |
+| test_handler_registration_requires_list_at_middleware_init | PASS | あり（軽微） |
+| test_unregistered_exception_falls_through_to_500 | PASS | あり（仕様だが摩擦） |
+
+---
+
+## 発見した摩擦点
+
+### FT21-F1: DomainExceptionHandler のボイラープレートが多い
+
+**概要**: `DomainExceptionHandlerProtocol` を満たすクラスを毎回 `handles()`/`handle()` の
+2 メソッドで実装する必要がある。多くのケースでパターンは同じ:
+1. `isinstance()` チェック
+2. `problem_details_response()` を呼ぶ
+
+**影響**: 3 つのドメイン例外に対して 3 つのハンドラークラスを書かなければならず、
+コード量が増える。
+
+**期待する解決策**:
+```python
+# 現状（各例外ごとにクラスが必要）
+class PostNotFoundHandler:
+    def handles(self, exc: Exception) -> bool:
+        return isinstance(exc, PostNotFoundError)
+    def handle(self, exc: Exception) -> Response:
+        return problem_details_response("post-not-found", "Not Found", 404)
+
+# 期待: ファクトリで一行
+handler = SimpleDomainHandler(PostNotFoundError, "post-not-found", "Post Not Found", 404)
+```
+
+---
+
+### FT21-F2: ハンドラーをミドルウェア初期化時にしか登録できない
+
+**概要**: `ErrorHandlerMiddleware` に `register_handler()` や `add_handler()` のような
+動的登録メソッドがないため、ミドルウェア初期化時に全ハンドラーをリストで渡す必要がある。
+
+**影響**: ドメインモジュールが分散している場合、一箇所に集めて渡す必要がある。
+（これは設計上妥当とも言えるが、大規模プロジェクトでは不便）
+
+**判断**: 初期化時一括登録は依存関係が明示的で好ましい設計のため、今回は修正しない。
+
+---
+
+### FT21-F3: 未登録ドメイン例外は 500 にフォールスルーする
+
+**概要**: `domain_handlers` への登録を忘れると 500 応答になる。
+ログを確認しないと原因が分からない。
+
+**判断**: `debug=True` で例外メッセージが `detail` に含まれるため、
+開発中は `ErrorHandlerMiddleware(debug=True)` を使えばデバッグ可能。
+ドキュメントに明記する対応が適切。
+
+---
+
+## まとめ
+
+`DomainExceptionHandlerProtocol` + `ErrorHandlerMiddleware` の組み合わせは機能するが、
+各例外ごとにクラスを 1 つ書く必要があるボイラープレートが摩擦の主な原因。
+
+`SimpleDomainHandler` ファクトリを追加することで DX が大幅に向上する（FT21-F1 → Issue化・修正対象）。

nene2_python-1.8.1/docs/field-trials/2026-05-field-trial-22.md

@@ -0,0 +1,87 @@
+# FT22: HealthCheckProtocol 実運用検証
+
+**日付**: 2026-05-20
+**テーマ**: `HealthCheckProtocol` を使ったヘルスチェックエンドポイントの実運用検証
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft22-health-check/`
+
+---
+
+## 目的
+
+`nene2.http.HealthCheckProtocol` と `DatabaseHealthCheck` を使って
+DB + 外部サービスを組み合わせた `/health` エンドポイントを実装するパターンを検証する。
+
+---
+
+## 実施内容
+
+- SQLite in-memory DB の `DatabaseHealthCheck` を組み込み
+- 外部 API の可用性を表す `ExternalApiHealthCheck`（モック）を実装
+- 両者を組み合わせる `CompositeCheck`（手動実装）を作成
+- `/health` エンドポイントを手動で FastAPI に登録
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・機能確認）
+| テスト | 結果 |
+|---|---|
+| test_health_returns_200_when_all_checks_pass | PASS |
+| test_health_returns_503_when_service_unavailable | PASS |
+| test_database_check_passes | PASS |
+| test_api_data_endpoint_works | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_no_composite_health_check_provided | PASS | あり |
+| test_health_endpoint_not_integrated_with_framework | PASS | あり |
+| test_health_status_checks_is_flat_string_dict | PASS | あり（軽微） |
+
+---
+
+## 発見した摩擦点
+
+### FT22-F1: 複数チェックを集約する CompositeHealthCheck がない
+
+**概要**: DB チェック + 外部サービスチェックなど複数の `HealthCheckProtocol` を
+組み合わせる場合、毎回集約クラスを手書きする必要がある。
+
+**影響**: 実運用では複数チェックの組み合わせが一般的で、
+その度に同じ集約ロジックを再実装することになる。
+
+**期待する解決策**: `CompositeHealthCheck(checks: list[HealthCheckProtocol])` クラスを
+`nene2.http` に追加する。
+
+---
+
+### FT22-F2: /health エンドポイントの FastAPI 登録ヘルパーがない
+
+**概要**: `HealthCheckProtocol` を実装しても、それを `/health` エンドポイントとして
+FastAPI に登録する仕組みがない。毎回同じパターンのエンドポイント定義を手書きする必要がある。
+
+**影響**: ボイラープレートが多い（status_code 分岐、JSON レスポンス形式など）。
+
+**期待する解決策**: `CompositeHealthCheck` 自体に FastAPI ルーターを生成するメソッドを
+追加するより、`CompositeHealthCheck` があれば残りは app.py 側で 5 行で済むため、
+今回は F1 の修正で十分と判断。
+
+---
+
+### FT22-F3: HealthStatus.checks が dict[str, str] のみ（軽微）
+
+**概要**: `HealthStatus.checks` の型が `dict[str, str]` のため、
+レイテンシや接続プール情報などの構造化詳細を含めることができない。
+
+**判断**: RFC ヘルスチェックの標準的な形式は文字列ステータスで十分なため、
+現状の型で問題なし。要件があれば `extra` フィールドを追加する方向で対応。
+
+---
+
+## まとめ
+
+`HealthCheckProtocol` と `DatabaseHealthCheck` は機能するが、
+複数チェックの集約クラスがないため実運用で毎回同じコードを書く必要がある。
+
+`CompositeHealthCheck` の追加が最も有効な改善（FT22-F1 → Issue化・修正対象）。

nene2_python-1.8.1/docs/field-trials/2026-05-field-trial-23.md

@@ -0,0 +1,80 @@
+# FT23: RequestSizeLimitMiddleware 実運用検証
+
+**日付**: 2026-05-20
+**テーマ**: `RequestSizeLimitMiddleware` を使った大容量リクエスト拒否の実運用検証
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft23-size-limit/`
+
+---
+
+## 目的
+
+`nene2.middleware.RequestSizeLimitMiddleware` をドキュメントアップロード API に組み込み、
+サイズ制限の動作確認と摩擦点を発見する。
+
+---
+
+## 実施内容
+
+- `max_bytes=1024`（1KB）の制限を設定した API を作成
+- `/upload/large` を `exclude_paths` で除外（大容量ファイル用）
+- 通常の JSON エンドポイント (`/api/note`) と小容量アップロード (`/upload/small`) でテスト
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・機能確認）
+| テスト | 結果 |
+|---|---|
+| test_small_request_passes | PASS |
+| test_large_request_to_normal_endpoint_returns_413 | PASS |
+| test_excluded_path_accepts_large_request | PASS |
+| test_small_upload_to_non_excluded_endpoint_passes | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_no_per_path_size_limits | PASS | あり |
+| test_413_response_does_not_include_max_bytes_in_structured_field | PASS | あり |
+| test_content_length_header_absent_still_checked | PASS | なし（正しい動作） |
+
+---
+
+## 発見した摩擦点
+
+### FT23-F1: エンドポイントごとに異なるサイズ制限を設定できない
+
+**概要**: ThrottleMiddleware と同じ問題。全エンドポイントに同一の `max_bytes` しか設定できない。
+
+**判断**: FT20 の ThrottleMiddleware と同様の問題で、別 Issue (#222) として既存。
+今回は重複 Issue を作成しない。
+
+---
+
+### FT23-F2: 413 レスポンスの制限値が構造化フィールドで返されない
+
+**概要**: 413 応答の `detail` フィールドに "Request body must not exceed 1024 bytes." と
+テキストで含まれるが、`max_bytes: 1024` のような構造化フィールドがない。
+
+**影響**: クライアント SDK が制限値を機械的に読み取れない。
+人間が読むログやエラーメッセージには十分だが、プログラム的な利用が難しい。
+
+**期待する解決策**: `_too_large()` レスポンスに `extra={"max_bytes": self._max_bytes}` を追加。
+
+---
+
+### FT23-F3: Content-Length なしでも body チェックが動作する（摩擦なし）
+
+チャンクエンコードで Content-Length ヘッダーがない場合でも、
+実際の body を読んでサイズチェックするため、バイパスできない。これは正しい動作。
+
+---
+
+## まとめ
+
+`RequestSizeLimitMiddleware` の基本機能（Content-Length チェック、body チェック、
+`exclude_paths`、413 Problem Details 応答）は問題なく動作する。
+
+摩擦点:
+1. **413 レスポンスに max_bytes 構造化フィールドがない** → Issue 化・修正対象
+2. **パスごとのサイズ制限が不可** → 既存 Issue (#222) と共通問題

nene2_python-1.8.1/docs/field-trials/2026-05-field-trial-24.md

@@ -0,0 +1,89 @@
+# FT24: AppSettings 実運用検証
+
+**日付**: 2026-05-20
+**テーマ**: `AppSettings` を使った環境変数ベースの設定管理パターンの実運用検証
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft24-app-settings/`
+
+---
+
+## 目的
+
+`nene2.config.AppSettings` を実際のアプリに組み込み、
+環境変数から設定を読み込んでミドルウェアを設定するパターンを検証する。
+
+---
+
+## 実施内容
+
+`AppSettings` の各フィールドを使って以下を設定:
+- `ErrorHandlerMiddleware(debug=settings.app_debug)`
+- `RequestSizeLimitMiddleware(max_bytes=settings.max_body_size)`
+- `ThrottleMiddleware(limit=settings.throttle_limit, window=settings.throttle_window)` (conditional)
+- `SecurityHeadersMiddleware` (conditional)
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・機能確認）
+| テスト | 結果 |
+|---|---|
+| test_health_endpoint_returns_env | PASS |
+| test_debug_false_by_default | PASS |
+| test_settings_loaded_from_env_vars | PASS |
+| test_throttle_disabled_via_settings | PASS |
+| test_max_body_size_from_settings | PASS |
+| test_db_url_sqlite_default | PASS |
+| test_db_url_mysql_format | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_list_fields_not_parseable_from_env_string | PASS | あり（ドキュメント） |
+| test_no_log_level_setting | PASS | あり |
+| test_no_middleware_factory_helper | PASS | あり（設計上の判断） |
+
+---
+
+## 発見した摩擦点
+
+### FT24-F1: list[str] フィールドを環境変数で設定する方法がドキュメントにない
+
+**概要**: `cors_origins`、`bearer_tokens`、`api_keys` は `list[str]` 型だが、
+環境変数から設定するには JSON 形式 (`["a","b"]`) が必要。
+単純な `"token1,token2"` ではパースされない。
+
+**判断**: pydantic-settings の標準動作のため、リファレンスドキュメントに記載する。
+
+---
+
+### FT24-F2: ログレベルの設定フィールドがない
+
+**概要**: `app_debug: bool` しかなく、`INFO`/`WARNING`/`ERROR` の粒度制御ができない。
+
+**影響**: ステージング環境で `INFO` ログを出しつつ、本番では `WARNING` に絞りたいが、
+現在は `app_debug=true` でしか詳細ログを出す方法がない。
+
+**期待する解決策**: `log_level: str = "INFO"` フィールドを追加。
+
+---
+
+### FT24-F3: AppSettings からミドルウェアを自動設定するヘルパーがない
+
+**概要**: AppSettings の設定値をミドルウェアに適用するには、
+毎回条件分岐付きのボイラープレートを手書きする必要がある。
+
+**判断**: `configure_middleware(app, settings)` ヘルパーは「薄い HTTP 層」の設計哲学に反し、
+フレームワークの主張が強くなりすぎる。FT アプリ側でパターンを提示する対応が適切。
+今回はドキュメント追加のみ。
+
+---
+
+## まとめ
+
+`AppSettings` は環境変数から型安全に設定を読み込む機能として正しく動作する。
+実運用での摩擦は:
+
+1. **list[str] 環境変数の書き方がわかりにくい** → ドキュメント追加対応
+2. **log_level フィールドがない** → Issue 化・修正対象
+3. **ミドルウェア自動設定ヘルパーがない** → 設計上の判断で修正しない