nene2-python 1.6.0__tar.gz → 1.8.0__tar.gz

{nene2_python-1.6.0 → nene2_python-1.8.0}/CHANGELOG.md

@@ -5,6 +5,47 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [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 例外統一・バグ修正。
+
+### Added
+- `SecurityHeadersMiddleware` — `csp: str | None` パラメータで Content-Security-Policy 値をカスタマイズ可能に (FT15)
+- `SecurityHeadersMiddleware` — `extra_no_csp_paths: list[str] | None` パラメータでカスタム OpenAPI パスの CSP スキップを設定可能に (FT15)
+- `DatabaseIntegrityException` — UNIQUE/FK/CHECK 制約違反時に発生する新例外クラス (FT16)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-14.md` 〜 `docs/field-trials/2026-05-field-trial-17.md`
+
+### Changed
+- `AsyncUseCaseProtocol` / `UseCaseProtocol` — docstring に `@runtime_checkable` の `isinstance` 制限と `inspect.iscoroutinefunction()` によるランタイム確認方法を明記 (FT14)
+- `SqlAlchemyTransactionManager.transactional()` — `IntegrityError` をキャッチして `DatabaseIntegrityException` にラップするよう変更 (FT16)
+
+### Fixed
+- `SqlAlchemyQueryExecutor.write()` — `IntegrityError` が `DatabaseIntegrityException` にラップされない不整合を修正 (FT17-F1)
+- `SqlAlchemyQueryExecutor.write()` と `_BoundQueryExecutor.write()` — UPDATE/DELETE で 0 行影響した場合に前の INSERT の `lastrowid` が返るバグを修正; INSERT のみ `lastrowid`、UPDATE/DELETE は `rowcount` を返すよう変更 (FT17-F2)
+
+---
+
 ## [1.6.0] — 2026-05-20
 
 FT13 (ValidationException実運用) field trial — validation DX improvements.

{nene2_python-1.6.0 → nene2_python-1.8.0}/PKG-INFO

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

@@ -0,0 +1,45 @@
+# Field Trial 14 — AsyncUseCaseProtocol 実運用
+
+**Date:** 2026-05-20
+**App:** Weather Dashboard API（複数都市の天気を asyncio.gather で並列取得）
+**Directory:** `/home/xi/docker/nene2-python-FT/ft14-async/`
+**nene2-python version:** v1.6.0
+
+## 概要
+
+`AsyncUseCaseProtocol` を使った非同期 UseCase を実際に実装し、
+`asyncio.gather` による並列 I/O の動作とプロトコルの挙動を検証した。
+
+## 動作確認結果
+
+- `AsyncUseCaseProtocol` の `isinstance` 検査が正しく動くこと ✓
+- `asyncio.gather` で 4 都市を並列取得した場合、50ms（直列の場合 200ms）で完了すること ✓
+- `FetchDashboardUseCase(fetch_weather: AsyncUseCaseProtocol[...])` のコンストラクタインジェクションが機能すること ✓
+- FastAPI の `async def` ハンドラーから非同期 UseCase を `await` で呼び出せること ✓
+
+## 摩擦点
+
+### FT14-F1 (LOW, ドキュメント): runtime_checkable の制限がプロトコルの docstring に記載されていない
+
+`isinstance(sync_obj, AsyncUseCaseProtocol)` が `True` を返す（Python の `@runtime_checkable` は
+メソッド名の存在のみを検査し、async/sync を区別しない）。
+
+```python
+class FakeSyncWeather:
+    def execute(self, input_: WeatherInput) -> str:  # async ではない
+        return "fake"
+
+isinstance(FakeSyncWeather(), AsyncUseCaseProtocol)  # → True（注意が必要）
+```
+
+この制限は ADR-0010 に記録済みだが、`AsyncUseCaseProtocol` の docstring には記載されていない。
+利用者が docstring だけ見て `isinstance` でランタイムガードを書くと誤動作する。
+
+**対応**: プロトコルの docstring に「mypy --strict が静的に保証する; isinstance はメソッド名のみを検査する」旨を追記する。
+
+## まとめ
+
+基本動作は問題なし。`asyncio.gather` パターン・コンストラクタインジェクション・FastAPI 統合のいずれも
+摩擦なく動作した。唯一の摩擦は docstring によるドキュメントギャップ（LOW）のみ。
+
+FT14 は「設計が正しく実装されている」ことの確認として有用だった。

nene2_python-1.8.0/docs/field-trials/2026-05-field-trial-15.md

@@ -0,0 +1,67 @@
+# Field Trial 15 — SecurityHeadersMiddleware 実運用
+
+**Date:** 2026-05-20
+**App:** FT15 Security Headers API（セキュリティヘッダーの付与・CSP 動作確認）
+**Directory:** `/home/xi/docker/nene2-python-FT/ft15-security-headers/`
+**nene2-python version:** v1.6.0
+
+## 概要
+
+`SecurityHeadersMiddleware` を実際のアプリに組み込み、各ヘッダーの付与動作・
+CSP スキップロジック・カスタマイズ可能性を検証した。
+
+## 動作確認結果
+
+- 通常エンドポイントに `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Content-Security-Policy`, `Permissions-Policy` の全ヘッダーが付与されること ✓
+- `/docs`, `/redoc`, `/openapi.json` では `Content-Security-Policy` がスキップされること ✓
+- CSP スキップ時も他のヘッダーは引き続き付与されること ✓
+
+## 摩擦点
+
+### FT15-F1 (MEDIUM, 拡張性): カスタム OpenAPI パスで CSP スキップが効かない
+
+`SecurityHeadersMiddleware` がスキップする OpenAPI パスは `_OPENAPI_PATHS` 定数で
+`{"/docs", "/redoc", "/openapi.json"}` にハードコードされている。
+
+FastAPI では `docs_url` / `redoc_url` でカスタムパスを設定できるが、
+カスタムパス（例: `/api-docs`）では CSP スキップが効かず、Swagger UI が CDN アセットを
+ブロックされる可能性がある。
+
+```python
+app = FastAPI(docs_url="/api-docs", redoc_url="/api-redoc")
+app.add_middleware(SecurityHeadersMiddleware)
+# → /api-docs に CSP "default-src 'self'" が付いてしまう
+```
+
+**対応**: コンストラクタに `extra_no_csp_paths: list[str] | None = None` を追加し、
+ユーザーがカスタム OpenAPI パスを指定できるようにする。または `ThrottleMiddleware` と
+同様の `exclude_paths` パターンで完全スキップを可能にする。
+
+### FT15-F2 (LOW, 拡張性): CSP をコンストラクタで上書きできない
+
+CSP の値 `"default-src 'self'"` はモジュールレベルの `_HEADERS` 定数にハードコードされており、
+コンストラクタから上書きできない。
+
+CDN アセットを許可したい（`content-src 'self' cdn.example.com`）など、
+CSP を変更したいユーザーは `_HEADERS` をモジュールレベルで直接書き換えるしかなく、
+グローバルな副作用が発生する。
+
+```python
+# 現状の唯一の方法（副作用あり）
+from nene2.middleware import security_headers
+security_headers._HEADERS["Content-Security-Policy"] = "default-src 'self' cdn.example.com"
+```
+
+**対応**: `SecurityHeadersMiddleware(csp: str | None = None)` でコンストラクタから
+CSP 値を上書きできるようにする。
+
+## まとめ
+
+基本動作は問題なし。全セキュリティヘッダーの付与・OpenAPI パスでの CSP スキップも
+正常に機能した。摩擦は拡張性の面で2点あり：
+
+- FT15-F1 (MEDIUM): カスタム OpenAPI パスで CSP スキップが効かない
+- FT15-F2 (LOW): CSP 値をコンストラクタから変更できない
+
+`ThrottleMiddleware` が `exclude_paths` を持つのに対し、`SecurityHeadersMiddleware` は
+カスタマイズポイントがゼロであるため、実用アプリでの柔軟性が低い。

nene2_python-1.8.0/docs/field-trials/2026-05-field-trial-16.md

@@ -0,0 +1,62 @@
+# Field Trial 16 — transactional(callback) パターン実運用
+
+**Date:** 2026-05-20
+**App:** 銀行口座送金 API（送金元の残高を減らして送金先に加算する atomic 操作）
+**Directory:** `/home/xi/docker/nene2-python-FT/ft16-transaction/`
+**nene2-python version:** v1.6.0
+
+## 概要
+
+`transactional(callback)` パターンを実際の送金ユースケースに適用し、
+ロールバック挙動・例外処理・async コンテキストとの相互作用を検証した。
+
+## 動作確認結果
+
+- `transactional(callback)` が atomic に実行されること ✓
+- `CHECK 制約違反`（残高 < 0）発生時に全操作がロールバックされること ✓
+- `UNIQUE 制約違反`（IntegrityError）でもロールバックが正しく行われること ✓
+- SQLite `:memory:` + `StaticPool` で `SqlAlchemyQueryExecutor` と `SqlAlchemyTransactionManager` を同一 DB に向けられること ✓
+
+## 摩擦点
+
+### FT16-F1 (MEDIUM, API一貫性): IntegrityError が DatabaseConnectionException にラップされない
+
+`SqlAlchemyTransactionManager.transactional()` は `OperationalError` のみを
+`DatabaseConnectionException` に変換し、`IntegrityError`（UNIQUE 制約違反・FK 制約違反など）は
+生の SQLAlchemy 例外として呼び出し側に伝播する。
+
+UseCase 層でフレームワーク独自例外に統一されていないため、
+呼び出し元が SQLAlchemy の例外型に依存した `except IntegrityError` を書く必要がある。
+
+```python
+from sqlalchemy.exc import IntegrityError
+
+with pytest.raises(IntegrityError):  # 摩擦: SQLAlchemy 依存が漏れ出す
+    tx_manager.transactional(_duplicate_insert)
+```
+
+**対応案**: `IntegrityError` も `DatabaseConnectionException`（または新設の `DatabaseIntegrityException`）にラップする。または `transactional()` がキャッチすべき SQLAlchemy 例外一覧をドキュメントに明記する。
+
+### FT16-F2 (LOW, 非同期対応): async コンテキストから transactional() を呼ぶとイベントループをブロックする
+
+`SqlAlchemyTransactionManager.transactional()` は同期 API であるため、
+FastAPI の `async def` ハンドラーから直接呼ぶとイベントループをブロックする。
+現状の実装でも動作はするが、高負荷時にパフォーマンス劣化の原因になりうる。
+
+```python
+@app.post("/transfer")
+async def transfer(...) -> JSONResponse:
+    # 同期 transactional() を直接呼んでいる（イベントループブロッキング）
+    result = transfer_uc.execute(...)
+```
+
+**対応案**: `asyncio.to_thread()` でのラップをドキュメントに記載する。
+または `AsyncSqlAlchemyTransactionManager` を将来的に追加する（SQLAlchemy async core を利用）。
+
+## まとめ
+
+コアの atomic 保証（コミット・ロールバック）は期待通りに機能した。
+摩擦は例外ハンドリングの API 一貫性（F1: MEDIUM）と非同期対応（F2: LOW）の2点。
+
+F1 は UseCase 層が SQLAlchemy に依存するアーキテクチャ上の問題であり、
+Clean Architecture の原則に照らして対応が必要。

nene2_python-1.8.0/docs/field-trials/2026-05-field-trial-17.md

@@ -0,0 +1,66 @@
+# Field Trial 17 — 複数ドメイン連携実運用
+
+**Date:** 2026-05-20
+**App:** タスク管理API（Task + Category の2ドメイン連携）
+**Directory:** `/home/xi/docker/nene2-python-FT/ft17-multi-domain/`
+**nene2-python version:** v1.6.0 (local dev build)
+
+## 概要
+
+Task（タスク）と Category（カテゴリ）の2ドメインを連携させたアプリを実装し、
+`SqlAlchemyQueryExecutor.write()` と `DatabaseIntegrityException`、
+`transactional(callback)` の混在パターンの DX を検証した。
+
+## 動作確認結果
+
+- カテゴリ一覧・タスク一覧・カテゴリでのフィルタリングが動作すること ✓
+- タスク完了（UPDATE）操作が正常に機能すること ✓（ただし FT17-F2 の制約あり）
+- `transactional()` 内の `IntegrityError` が `DatabaseIntegrityException` に変換されること ✓
+
+## 摩擦点
+
+### FT17-F1 (HIGH, バグ): SqlAlchemyQueryExecutor.write() が IntegrityError をキャッチしない
+
+`_BoundQueryExecutor.write()`（`transactional()` 内部で使われる）は FT16 で `IntegrityError` を
+`DatabaseIntegrityException` に変換するよう修正されたが、
+`SqlAlchemyQueryExecutor.write()`（直接呼び出し）は対応していない。
+
+同じ「INSERT が重複するケース」でも、使う API によって異なる例外型が飛ぶ：
+
+```python
+# 直接 write() → IntegrityError (SQLAlchemy)
+executor.write("INSERT INTO categories (name) VALUES (:name)", {"name": "dup"})
+
+# transactional() 内 write() → DatabaseIntegrityException (nene2)
+tx_manager.transactional(lambda ex: ex.write("INSERT INTO categories (name) VALUES (:name)", {"name": "dup"}))
+```
+
+UseCase 層でどちらの API を使うかによって `except` 節を変える必要があり、一貫性がない。
+
+**対応**: `SqlAlchemyQueryExecutor.write()` でも `IntegrityError` をキャッチして
+`DatabaseIntegrityException` にラップする。
+
+### FT17-F2 (HIGH, バグ): write() が UPDATE/DELETE で 0 行影響した場合に誤った値を返す
+
+`write()` は `result.lastrowid or result.rowcount` を返すが、SQLite では UPDATE/DELETE の後も
+`cursor.lastrowid` が前の INSERT の rowid を保持する。
+
+```python
+# DB に id=1 の行がある状態で
+result = executor.write("UPDATE items SET name = 'x' WHERE id = 999")  # 0行影響
+# result == 1 (前のINSERTのlastrowid) — 期待値は 0
+```
+
+`if affected == 0: raise NotFound` のパターンが正しく動かない。
+
+**対応**: SQL が `INSERT` で始まる場合のみ `lastrowid` を使い、UPDATE/DELETE は `rowcount` を返す。
+
+## まとめ
+
+ドメイン間連携（JOIN クエリ、カテゴリフィルタリング）は問題なく動作した。
+ただし `SqlAlchemyQueryExecutor.write()` に HIGH レベルのバグが2件あり:
+
+- FT17-F1: `IntegrityError` が `DatabaseIntegrityException` に変換されない（API 非対称）
+- FT17-F2: UPDATE/DELETE で 0 行影響した場合の戻り値が不正
+
+両方とも `_BoundQueryExecutor.write()` には修正済みだが、`SqlAlchemyQueryExecutor.write()` に未適用。

nene2_python-1.8.0/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.0/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.0/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.0/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化・修正対象）。