nene2-python 1.8.20__tar.gz → 1.8.22__tar.gz

{nene2_python-1.8.20 → nene2_python-1.8.22}/CHANGELOG.md

@@ -5,6 +5,20 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.21] — 2026-05-20
+
+FT75 フィールドトライアル — ミドルウェアスタック順序問題の発見と根本解決。
+
+### Added
+- `setup_middlewares(app, ...)` ユーティリティ関数を追加 (#320 #321) (FT75)
+  — 全ミドルウェアを正しい順序（RequestId 最外側・ErrorHandler 最内側）で一括登録し、
+  エラーレスポンスにも X-Request-Id とセキュリティヘッダーが確実に付与される
+- `docs/how-to/middleware-stack.md` — ミドルウェア順序の解説ガイドを追加
+- CLAUDE.md セクション 8 に推奨 `add_middleware` 順序を追記
+- Field trial report: `docs/field-trials/2026-05-field-trial-75.md` (FT75)
+
+---
+
 ## [1.8.20] — 2026-05-20
 
 FT72 フィールドトライアル — DatabaseIntegrityException + ErrorHandlerMiddleware.install() 改善。

{nene2_python-1.8.20 → nene2_python-1.8.22}/CLAUDE.md

@@ -233,6 +233,35 @@ AI エージェント（Claude 等）がこのコードベースを正確に理
 - `nene2.http.problem_details_response()` で RFC 9457 エラー応答
 - `nene2.http.PaginationQueryParser` でページネーション
 
+### ミドルウェアスタック順序（重要）
+
+`app.add_middleware()` は **LIFO**（後から追加したものが外側になる）。
+直感と逆なので注意 — 「外側に置きたいものを後から追加する」。
+
+**推奨 `add_middleware` 呼び出し順**（最初が最内側・最後が最外側）:
+
+```python
+# ✅ 正しい順序
+app.add_middleware(ErrorHandlerMiddleware)           # 最内側: ハンドラー例外を捕捉
+app.add_middleware(RequestLoggingMiddleware)         # ↑
+app.add_middleware(ThrottleMiddleware, ...)          # |
+app.add_middleware(RequestSizeLimitMiddleware, ...)  # |
+app.add_middleware(SecurityHeadersMiddleware)        # ↓  全レスポンスにヘッダー付与
+app.add_middleware(RequestIdMiddleware)              # 最外側: 全レスポンスに X-Request-Id 付与
+```
+
+```python
+# ❌ よくある間違い — ErrorHandler を最後（最外側）に追加
+app.add_middleware(RequestIdMiddleware)
+app.add_middleware(ErrorHandlerMiddleware)   # 最外側にすると...
+# → 500 エラーに X-Request-Id が付かない（内側のミドルウェアをバイパスするため）
+# → 500 エラーにセキュリティヘッダーが付かない
+```
+
+`ErrorHandlerMiddleware` が例外を捕捉して新しい Response を返すとき、
+それより内側のミドルウェアはバイパスされる（Starlette の `BaseHTTPMiddleware` の仕様）。
+`RequestIdMiddleware` と `SecurityHeadersMiddleware` は必ず **ErrorHandler より外側** に置くこと。
+
 ### REST 規約
 - リソース名は複数形: `/notes`, `/tags`
 - ID はパスパラメータ: `/notes/{note_id}`

{nene2_python-1.8.20 → nene2_python-1.8.22}/PKG-INFO

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

@@ -0,0 +1,69 @@
+# FT73: PaginationQueryParser.parse() 静的メソッド実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: `PaginationQueryParser.parse(Request)` レガシーパターンと `ErrorHandlerMiddleware.install()` の連携確認  
+**バージョン**: v1.8.20  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft73-pagination-parse/`
+
+---
+
+## 概要
+
+`PaginationQueryParser.parse(request)` 静的メソッド（`Depends()` を使わないパターン）を検証した。
+カスタム `default_limit` / `max_limit` の動作と、
+v1.8.20 で追加した `ErrorHandlerMiddleware.install()` との連携も確認した。
+
+---
+
+## 実装内容
+
+- `GET /items` — `PaginationQueryParser.parse(request)` でデフォルト (limit=20, max=100)
+- `GET /items/custom` — `parse(request, default_limit=5, max_limit=10)` でカスタム値
+- `ErrorHandlerMiddleware.install(app)` を使用（v1.8.20 の新機能）
+- `ValidationException` による 422 を nene2 Problem Details 形式で返す
+
+---
+
+## テスト結果
+
+**11/11 passed**
+
+| テスト | 結果 |
+|---|---|
+| `test_default_pagination_returns_20_items` | PASSED |
+| `test_custom_limit_and_offset` | PASSED |
+| `test_limit_too_large_returns_422` | PASSED |
+| `test_limit_zero_returns_422` | PASSED |
+| `test_negative_offset_returns_422` | PASSED |
+| `test_non_integer_limit_returns_422` | PASSED |
+| `test_non_integer_offset_returns_422` | PASSED |
+| `test_custom_default_limit_applied` | PASSED |
+| `test_custom_max_limit_enforced` | PASSED |
+| `test_custom_max_limit_at_boundary` | PASSED |
+| `test_last_page_returns_remaining_items` | PASSED |
+
+---
+
+## Friction Points
+
+なし。
+
+**特筆点**:
+- `PaginationQueryParser.parse()` は `ValidationException` を raise するため、
+  `ErrorHandlerMiddleware.install(app)` と組み合わせると
+  非整数値・範囲外の入力が自動的に 422 nene2 Problem Details で返る。
+- `parse()` が返す `PaginationQuery` (named dataclass) は `limit` / `offset` を保持し、
+  `Depends()` パターンの `PaginationQueryParser` インスタンスと同じインターフェースで使える。
+- `default_limit` / `max_limit` のカスタマイズが `parse()` の引数で完結するため、
+  ルートごとに異なるページネーション制限を設定しやすい。
+- `ErrorHandlerMiddleware.install(app)` が v1.8.20 で正式追加され、
+  `ValidationException` の 422 フォーマット統一が一行で完了するようになった。
+
+---
+
+## 結論
+
+`PaginationQueryParser.parse()` は `Depends()` パターンが使えないシナリオ
+（例: ミドルウェアや `WebSocket` ハンドラー内）で有効な代替手段。
+`default_limit` / `max_limit` のカスタマイズと `ValidationException` の自動 422 変換が
+`ErrorHandlerMiddleware.install()` との組み合わせで自然に機能する。

nene2_python-1.8.22/docs/field-trials/2026-05-field-trial-74.md

@@ -0,0 +1,76 @@
+# FT74: カスタム HealthCheckProtocol 実装の実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: ユーザー定義 `HealthCheckProtocol` / `AsyncHealthCheckProtocol` 実装と `CompositeHealthCheck` の連携  
+**バージョン**: v1.8.20  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft74-custom-health/`
+
+---
+
+## 概要
+
+ユーザーが `HealthCheckProtocol` を実装する実際のシナリオ（メモリ・DB・外部サービス）を
+`CompositeHealthCheck` / `AsyncCompositeHealthCheck` に組み合わせて動作を検証した。
+
+---
+
+## 実装内容
+
+### カスタム同期ヘルスチェック
+- `AlwaysOkCheck` — 常に ok を返すベースライン
+- `ToggleableCheck` — テストで on/off できるトグル可能なチェック
+- `MemoryCheck` — 閾値ベースのメモリ使用量チェック（psutil なしでシミュレート）
+
+### カスタム非同期ヘルスチェック
+- `AsyncAlwaysOkCheck` — 常に ok を返す非同期版
+- `AsyncToggleableCheck` — 非同期版トグルチェック
+
+### エンドポイント
+- `GET /health` — `CompositeHealthCheck` (同期)
+- `GET /health/async` — `AsyncCompositeHealthCheck` (非同期)
+- `create_app(db_healthy, cache_healthy, memory_usage_pct)` でテストシナリオを切り替え
+
+---
+
+## テスト結果
+
+**13/13 passed**
+
+| テスト | 結果 | 種別 |
+|---|---|---|
+| `test_always_ok_check_returns_ok` | PASSED | 単体 |
+| `test_toggleable_check_returns_error_when_unhealthy` | PASSED | 単体 |
+| `test_memory_check_ok_under_threshold` | PASSED | 単体 |
+| `test_memory_check_error_over_threshold` | PASSED | 単体 |
+| `test_composite_ok_when_all_checks_pass` | PASSED | 単体 |
+| `test_composite_error_when_any_check_fails` | PASSED | 単体 |
+| `test_health_status_http_code_200_when_ok` | PASSED | 単体 |
+| `test_health_status_http_code_503_when_error` | PASSED | 単体 |
+| `test_sync_health_endpoint_returns_200_when_all_ok` | PASSED | HTTP 統合 |
+| `test_sync_health_endpoint_returns_503_when_db_down` | PASSED | HTTP 統合 |
+| `test_sync_health_endpoint_returns_503_when_memory_high` | PASSED | HTTP 統合 |
+| `test_async_health_endpoint_returns_200_when_all_ok` | PASSED | HTTP 統合 |
+| `test_async_health_endpoint_returns_503_when_cache_down` | PASSED | HTTP 統合 |
+
+---
+
+## Friction Points
+
+なし。
+
+**特筆点**:
+- `HealthCheckProtocol` / `AsyncHealthCheckProtocol` はどちらも `@runtime_checkable Protocol` なので、
+  特定の基底クラスを継承せずとも `check()` メソッドを実装するだけで準拠できる。
+- `CompositeHealthCheck` は各チェックの `checks` dict をフラットマージするため、
+  複数チェックが同一キーを持つと後のチェックが上書きする。キーの命名が重要。
+- `HealthStatus.http_status_code` は 200 / 503 を自動で返すため、
+  HTTP ハンドラーで `status_code=status.http_status_code` とするだけで正しいステータスコードになる。
+- `create_app(db_healthy=False)` の DI パターンで HTTP テストにおける「障害シミュレーション」が簡潔に書ける。
+
+---
+
+## 結論
+
+`HealthCheckProtocol` の実装は `check() -> HealthStatus` を持つだけで完了する。
+`CompositeHealthCheck` がフラットマージすることを把握した上で、
+各チェックのキー命名を一意にすれば、複数チェックの組み合わせは完全に直感的に動作する。

nene2_python-1.8.22/docs/field-trials/2026-05-field-trial-75.md

@@ -0,0 +1,128 @@
+# FT75: ミドルウェアスタック順序依存性の実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: Starlette LIFO ミドルウェア順序の落とし穴 — エラーレスポンスにヘッダーが付かない問題  
+**バージョン**: v1.8.20  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft75-middleware-order/`
+
+---
+
+## 概要
+
+nene2 が提供する 6 つのミドルウェアを組み合わせた際の順序依存バグを検証した。
+「ErrorHandler を最外側に」という直感が **間違い** であることを実際のテストで実証し、
+全レスポンスに X-Request-Id とセキュリティヘッダーを付与するための正しい順序を確認した。
+
+---
+
+## 発見した問題
+
+### Starlette BaseHTTPMiddleware の動作原理
+
+`app.add_middleware(X)` は **LIFO**（後から追加したものが外側になる）で積まれる。
+
+```python
+app.add_middleware(A)  # 内側
+app.add_middleware(B)  # 外側
+# スタック: B(A(Router))
+# リクエスト: B → A → Router
+# レスポンス: Router → A → B
+```
+
+### 落とし穴: ErrorHandler を最外側にすると何が起きるか
+
+```python
+# 「直感」による書き方
+app.add_middleware(RequestIdMiddleware)       # 内側
+app.add_middleware(SecurityHeadersMiddleware) # 内側
+app.add_middleware(ErrorHandlerMiddleware)    # 最外側（最後に追加）
+
+# スタック: ErrorHandler(SecurityHeaders(RequestId(Router)))
+```
+
+ハンドラーが例外を raise すると:
+1. `ErrorHandlerMiddleware.dispatch` が例外を捕捉
+2. `problem_details_response(...)` で **新しい Response を直接 return**
+3. この Response は内側の `SecurityHeaders` も `RequestId` も **通過しない**
+4. 結果: **500 エラーに X-Request-Id もセキュリティヘッダーも付かない**
+
+### 正しい順序
+
+ErrorHandler を **最内側** に置き、RequestId と SecurityHeaders を **外側** に置く。
+
+```python
+# 正しい書き方（最初に add するものが最内側）
+app.add_middleware(ErrorHandlerMiddleware)           # 最内側
+app.add_middleware(RequestLoggingMiddleware)
+app.add_middleware(ThrottleMiddleware, ...)
+app.add_middleware(RequestSizeLimitMiddleware, ...)
+app.add_middleware(SecurityHeadersMiddleware)
+app.add_middleware(RequestIdMiddleware)              # 最外側
+
+# スタック: RequestId(SecurityHeaders(SizeLimit(Throttle(RequestLogging(ErrorHandler(Router))))))
+# 全レスポンス（エラー含む）が SecurityHeaders と RequestId を通過する ✓
+```
+
+---
+
+## テスト結果
+
+**10/10 passed**
+
+| テスト | 結果 | 観察内容 |
+|---|---|---|
+| `test_correct_order_500_is_problem_details` | PASSED | ErrorHandler は内側でも 500 を捕捉できる |
+| `test_correct_order_500_has_request_id` | PASSED | RequestId が外側 → 500 にも付く |
+| `test_correct_order_500_has_security_headers` | PASSED | SecurityHeaders が外側 → 500 にも付く |
+| `test_correct_order_413_is_problem_details` | PASSED | SizeLimitMiddleware は内部で直接 problem_details_response を返す |
+| `test_correct_order_413_has_request_id` | PASSED | 413 にも X-Request-Id が付く |
+| `test_correct_order_413_has_security_headers` | PASSED | 413 にもセキュリティヘッダーが付く |
+| `test_naive_order_500_missing_request_id` | PASSED | 直感的順序だと 500 に X-Request-Id が**付かない**ことを実証 |
+| `test_naive_order_500_missing_security_headers` | PASSED | 直感的順序だと 500 にセキュリティヘッダーが**付かない**ことを実証 |
+
+---
+
+## Friction Points
+
+### 🔴 重大: ミドルウェア推奨順序がドキュメント化されていない
+
+`add_middleware` の呼び出し順序について nene2 のドキュメントに推奨順序が存在しない。
+Starlette の LIFO 動作は非直感的であり、「ErrorHandler が最外側にあるべき」という誤解を招きやすい。
+
+実際の影響:
+- **ErrorHandler を最外側に置く（最後に add する）と** 500 エラーに X-Request-Id が付かない
+- **Security audit で「エラーレスポンスにセキュリティヘッダーがない」と指摘される**
+- 本番環境で気づかずに運用してしまう可能性が高い
+
+**推奨順序（コメント付き）をドキュメントに追加すべき。**
+
+---
+
+## 使用感（主観評価）
+
+**直感性: ★★☆☆☆**  
+LIFO の仕組みを知っていても、「外側に置きたいものを後から add する」という逆転発想は
+毎回確認しないと間違える。Express.js でも同じ罠があり、FastAPI/Starlette ユーザーが
+最も頻繁にハマる問題のひとつ。
+
+**実害の深刻さ: ★★★★★**  
+単に動かない（すぐ気づく）ではなく、**動くが一部の非機能要件が欠落する**パターン。
+Security headers がエラーページだけ欠落していても CI は通るし、
+X-Request-Id がエラーレスポンスにないことはログ追跡するまで気づかない。
+
+**修正のしやすさ: ★★★★★**  
+順序を正しくするだけなので、原因がわかれば修正は 1 分。
+問題は「原因に気づく」のが遅いこと。
+
+**フレームワーク側で改善できること**:  
+CLAUDE.md や how-to ガイドに推奨スタック順序を明記するだけで解決できる。
+ミドルウェアを `ErrorHandlerMiddleware.install()` のように一括登録する
+`setup_middlewares(app)` ユーティリティがあると事故を防げる。
+
+---
+
+## 結論
+
+ミドルウェア順序のバグは **動作するが静かに壊れている** 類の問題で、
+実際の本番事故に直結しやすい。正しい順序（ErrorHandler 最内側・RequestId 最外側）を
+nene2 の公式ドキュメントと CLAUDE.md に追記することを強く推奨する。

nene2_python-1.8.22/docs/field-trials/2026-05-field-trial-76.md

@@ -0,0 +1,152 @@
+# FT76: async ハンドラー + sync SQLAlchemy のイベントループブロッキング
+
+**日付**: 2026-05-20  
+**テーマ**: FastAPI の async def ハンドラー内で同期 DB 処理を呼ぶとどうなるか  
+**バージョン**: v1.8.21  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft76-async-sync-db/`
+
+---
+
+## 概要
+
+FastAPI は `async def` と `def` を混在できるが、同期処理の扱いが根本的に異なる。
+nene2 の DB 層（`SqlAlchemyQueryExecutor` / `SqlAlchemyTransactionManager`）は同期実装のため、
+`async def` ハンドラー内から直接呼ぶとイベントループをブロックする。
+このFTでは3パターンの挙動を実測し、nene2 として何を提供すべきかを検証した。
+
+---
+
+## テスト対象の3パターン
+
+| パターン | 実装 | 動作 |
+|---|---|---|
+| A | `async def` 内で `time.sleep()` / 同期DB直呼び | **イベントループをブロック** |
+| B | `async def` 内で `run_in_executor()` 経由 | スレッドプールにオフロード（安全） |
+| C | `def` ハンドラー（同期） | FastAPI が自動でスレッドプールに退避（安全） |
+
+---
+
+## 発見した問題
+
+### 問題1: async ハンドラー + sync DB = サイレントブロッキング
+
+```python
+# ❌ よくある間違い
+@app.post("/tasks")
+async def create_task(body: TaskBody) -> JSONResponse:
+    result = _create_task_sync(body.title)  # time.sleep / Session(...) など
+    return JSONResponse(result, status_code=201)
+```
+
+`async def` 内で `time.sleep()` や同期 `Session` を呼ぶと、実行中は asyncio のイベントループが
+完全に停止する。他のリクエストはそのリクエストが完了するまで待たされる。
+
+**特に危険なのは「少量のデータなら問題が出ない」点**。
+開発中 / ステージング環境では顕在化せず、本番で同時アクセスが増えてから遅延が爆発する。
+
+### 問題2: nene2 に async DB 層がない
+
+```python
+# v1.8.21 時点: 存在しない
+from nene2.database import AsyncSqlAlchemyQueryExecutor  # ImportError
+```
+
+`SqlAlchemyQueryExecutor.fetch_all()` / `SqlAlchemyTransactionManager.begin()` は
+すべて同期実装。async def ハンドラーと組み合わせるには自前で `run_in_executor` を書く必要がある。
+
+### 問題3: run_in_executor パターンが冗長で発見しにくい
+
+```python
+# ✅ 正しいが、毎回これを書くのは辛い
+@app.post("/tasks")
+async def create_task(body: TaskBody) -> JSONResponse:
+    loop = asyncio.get_event_loop()
+    result = await loop.run_in_executor(None, _create_task_sync, body.title, body.simulate_ms)
+    return JSONResponse(result, status_code=201)
+```
+
+- `asyncio.get_event_loop()` は Python 3.10+ で deprecation warning を出すことがある
+- `None` の意味（default executor = ThreadPoolExecutor）が自明でない
+- 複数の引数を渡すには `functools.partial` か lambda が必要になりさらに冗長になる
+
+### 問題4: `def` ハンドラーが実は最もシンプルで安全
+
+```python
+# ✅ sync def は FastAPI が自動でスレッドプールに退避する
+@app.post("/tasks")
+def create_task(body: TaskBody) -> JSONResponse:
+    result = _create_task_sync(body.title)  # 安全
+    return JSONResponse(result, status_code=201)
+```
+
+`async def` を書く必然性がないなら `def` を使うべきだが、
+「FastAPI = async」というイメージから全ハンドラーを `async def` にするユーザーが多い。
+nene2 のドキュメントがこれを明示していない。
+
+---
+
+## テスト結果（全12件パス）
+
+```
+test_sync_in_async_creates_task     PASSED  # パターンA: 機能はする（ブロッキングだが）
+test_executor_creates_task          PASSED  # パターンB: executor 経由
+test_sync_def_creates_task          PASSED  # パターンC: sync def
+test_list_tasks                     PASSED
+test_sync_def_does_not_block_event_loop  PASSED  # イベントループが自由であることを確認
+test_sync_in_async_blocks_when_slow     PASSED  # 200ms スリープがそのまま待機時間になる
+test_executor_avoids_blocking           PASSED
+test_middlewares_work_with_all_patterns PASSED  # setup_middlewares() は全パターンで動作
+test_422_on_invalid_title_length        PASSED
+test_422_on_negative_simulate_ms        PASSED
+test_no_async_db_layer_in_nene2         PASSED  # 非同期DB層が存在しないことを確認
+test_threadpool_pattern_is_verbose      PASSED  # 冗長さのドキュメンタリーテスト
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F76-1 | nene2 に async DB 層がなく、async ハンドラーでは run_in_executor が必要 | 高 |
+| F76-2 | async def + sync DB のブロッキングがサイレント（警告なし） | 高 |
+| F76-3 | run_in_executor の書き方が冗長で、正しい引数渡しが分かりにくい | 中 |
+| F76-4 | ドキュメントが async def vs def の使い分けを説明していない | 中 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★☆☆☆
+
+「FastAPI を使っているので全ハンドラーを async def にする」のは自然な発想。
+しかし nene2 の DB 層は同期なので、これが罠になる。
+`async def` で書いたコードが正常に動き、テストも全部通る — でも本番では爆発する。
+「動いているから正しい」と思ってしまう構造が非常にやっかいで直感に反する。
+
+### 実害の深刻さ ★★★★☆
+
+本番環境で同時アクセスが増えてからはじめて顕在化する。
+レスポンスが遅い → サーバーがダウン、という流れをたどる典型的なパフォーマンス地雷。
+「なぜか重い」「スケールしない」という症状で現れるため、根本原因の特定も遅れやすい。
+
+### 修正のしやすさ ★★☆☆☆
+
+`run_in_executor` パターンを知っていれば直せるが、記述が冗長で毎回ハンドラーに書くのはつらい。
+根本解決（async DB 層の実装）はSQLAlchemy async対応が必要で、工数が大きい。
+`def` ハンドラーへの移行が最もシンプルだが、`async` 依存のロジックが混在していると難しい。
+
+### 総合コメント
+
+FastAPI + SQLAlchemy の組み合わせは最も多いユースケースの一つ。
+「nene2 を使えばすぐ始められる」が「パフォーマンス問題で詰まる」という流れは
+ユーザー離れを引き起こす可能性がある。
+`def` vs `async def` の使い分けガイドラインと、将来的な async DB サポートが必要。
+
+---
+
+## 推奨アクション
+
+1. **Issue**: `async def` ハンドラー内での `SqlAlchemy` 同期呼び出し警告をドキュメントに追加
+2. **Issue**: `run_in_threadpool()` ヘルパー（または `asyncify()` パターン）の提供
+3. **将来**: `AsyncSqlAlchemyQueryExecutor` の実装（SQLAlchemy 2.0 async 対応）

nene2_python-1.8.22/docs/how-to/middleware-stack.md

@@ -0,0 +1,111 @@
+# How-To: ミドルウェアスタックの正しい設定
+
+## 結論（TL;DR）
+
+```python
+# この順序で add_middleware を呼ぶ
+app.add_middleware(ErrorHandlerMiddleware)           # 最内側
+app.add_middleware(RequestLoggingMiddleware)
+app.add_middleware(ThrottleMiddleware, limit=100, window=60)
+app.add_middleware(RequestSizeLimitMiddleware, max_bytes=1_048_576)
+app.add_middleware(SecurityHeadersMiddleware)
+app.add_middleware(RequestIdMiddleware)              # 最外側
+```
+
+---
+
+## なぜこの順序なのか
+
+### Starlette の LIFO ルール
+
+`app.add_middleware()` は **後から追加したものが外側**（LIFO）になる。
+
+```
+add_middleware(A)  →  B(A(Router))
+add_middleware(B)
+```
+
+リクエストは外側から内側へ（B → A → Router）、
+レスポンスは内側から外側へ（Router → A → B）流れる。
+
+### ErrorHandler を最外側にすると何が壊れるか
+
+```python
+# ❌ 間違い
+app.add_middleware(RequestIdMiddleware)
+app.add_middleware(ErrorHandlerMiddleware)  # 最外側
+# スタック: ErrorHandler(RequestId(Router))
+```
+
+ハンドラーが例外を raise したとき:
+
+1. `ErrorHandlerMiddleware.dispatch` が例外を捕捉
+2. `problem_details_response(...)` で **新しい Response を直接 return**
+3. この Response は内側の `RequestId` ミドルウェアを **通過しない**
+4. 結果: **500 エラーに `X-Request-Id` が付かない**
+
+同じ理由で `SecurityHeadersMiddleware` が内側にあると、
+エラーレスポンスにセキュリティヘッダーが付かない。
+
+### 正しい順序のスタック図
+
+```
+RequestIdMiddleware            ← 全レスポンス（200〜5xx）に X-Request-Id を付与
+  └─ SecurityHeadersMiddleware ← 全レスポンスにセキュリティヘッダーを付与
+       └─ RequestSizeLimitMiddleware ← 413 を直接返す（ErrorHandler 不要）
+            └─ ThrottleMiddleware   ← 429 を直接返す（ErrorHandler 不要）
+                 └─ RequestLoggingMiddleware
+                      └─ ErrorHandlerMiddleware ← ハンドラー例外を 500 に変換
+                           └─ Router (FastAPI handlers)
+```
+
+`RequestSizeLimitMiddleware` と `ThrottleMiddleware` は自身で `problem_details_response()` を
+返すため、ErrorHandler の内外に置いても 413/429 の形式は変わらない。
+ただし `X-Request-Id` が付くかどうかは `RequestIdMiddleware` の位置次第。
+
+---
+
+## 使用しないミドルウェアがある場合
+
+一部のミドルウェアを省略しても、残りの順序は同じルールに従う:
+
+```python
+# ThrottleMiddleware と RequestLoggingMiddleware を省略した場合
+app.add_middleware(ErrorHandlerMiddleware)
+app.add_middleware(RequestSizeLimitMiddleware, max_bytes=1_048_576)
+app.add_middleware(SecurityHeadersMiddleware)
+app.add_middleware(RequestIdMiddleware)
+```
+
+---
+
+## ErrorHandlerMiddleware.install() を使う場合
+
+`install()` は `add_middleware` と `add_exception_handler` をまとめて行うが、
+他のミドルウェアとの順序設定は手動で行う必要がある:
+
+```python
+# install() は最初に呼ぶ（最内側になる）
+ErrorHandlerMiddleware.install(app)          # 内側
+
+# その後に他のミドルウェアを追加
+app.add_middleware(RequestSizeLimitMiddleware, max_bytes=1_048_576)
+app.add_middleware(SecurityHeadersMiddleware)
+app.add_middleware(RequestIdMiddleware)       # 外側
+```
+
+---
+
+## よくある質問
+
+**Q: `RequestSizeLimitMiddleware` は ErrorHandler の内外どちらに置くべきか?**
+
+A: 内外どちらでも機能するが、`RequestIdMiddleware` より内側にすることで
+413 レスポンスにも `X-Request-Id` が付く。上記の推奨順序に従えばよい。
+
+**Q: カスタムミドルウェアはどこに追加するか?**
+
+A: そのミドルウェアの性質による:
+- 全レスポンスに何かを追加したい → `RequestIdMiddleware` の直前（外側）
+- ハンドラー例外をキャッチしたい → `ErrorHandlerMiddleware` の直後（内側）
+- リクエストを早期拒否したい → `RequestSizeLimitMiddleware` や `ThrottleMiddleware` の近く

{nene2_python-1.8.20 → nene2_python-1.8.22}/pyproject.toml

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

{nene2_python-1.8.20 → nene2_python-1.8.22}/src/nene2/middleware/__init__.py

@@ -6,6 +6,7 @@ from .request_id import RequestIdMiddleware, get_request_id, request_id_var
 from .request_logging import RequestLoggingMiddleware
 from .request_size_limit import RequestSizeLimitMiddleware
 from .security_headers import SecurityHeadersMiddleware
+from .setup import setup_middlewares
 from .throttle import ThrottleMiddleware
 
 __all__ = [
@@ -18,6 +19,7 @@ __all__ = [
     "RequestLoggingMiddleware",
     "RequestSizeLimitMiddleware",
     "SecurityHeadersMiddleware",
+    "setup_middlewares",
     "ThrottleMiddleware",
     "request_id_var",
 ]