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

{nene2_python-1.8.20 → nene2_python-1.8.21}/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.21}/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.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.20
+Version: 1.8.21
 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.21/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.21/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.21/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.21/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.21}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nene2-python"
-version = "1.8.20"
+version = "1.8.21"
 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.21}/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",
 ]

nene2_python-1.8.21/src/nene2/middleware/setup.py

@@ -0,0 +1,142 @@
+"""setup_middlewares() — register all nene2 middlewares in the correct order."""
+
+from typing import Any
+
+from starlette.applications import Starlette
+
+from .domain_exception import DomainExceptionHandlerProtocol
+from .error_handler import ErrorHandlerMiddleware
+from .request_id import RequestIdMiddleware
+from .request_logging import RequestLoggingMiddleware
+from .request_size_limit import RequestSizeLimitMiddleware
+from .security_headers import SecurityHeadersMiddleware
+from .throttle import ThrottleMiddleware
+
+_DEFAULT_MAX_BYTES = 1_048_576  # 1 MiB
+
+
+def setup_middlewares(
+    app: object,
+    *,
+    debug: bool = False,
+    domain_handlers: list[DomainExceptionHandlerProtocol] | None = None,
+    enable_request_logging: bool = True,
+    throttle_limit: int | None = None,
+    throttle_window: int = 60,
+    throttle_path_limits: dict[str, int] | None = None,
+    throttle_exclude_paths: list[str] | None = None,
+    max_request_bytes: int = _DEFAULT_MAX_BYTES,
+    request_size_path_limits: dict[str, int] | None = None,
+    request_size_exclude_paths: list[str] | None = None,
+    security_headers: bool = True,
+    hsts: bool = False,
+    csp: str | None = None,
+    security_extra_no_csp_paths: list[str] | None = None,
+) -> None:
+    """Register all nene2 middlewares in the correct order.
+
+    Starlette applies ``add_middleware`` in LIFO order (last added = outermost).
+    This function adds middlewares in the correct sequence so that **all responses**
+    — including 500 errors — receive ``X-Request-Id`` and security headers.
+
+    Effective stack (outermost → innermost)::
+
+        RequestId → SecurityHeaders → SizeLimit → Throttle → RequestLogging → ErrorHandler
+
+    **Minimal usage** — all options have sensible defaults::
+
+        from nene2.middleware import setup_middlewares
+
+        app = FastAPI()
+        setup_middlewares(app)
+
+    **With customisation**::
+
+        setup_middlewares(
+            app,
+            debug=True,
+            throttle_limit=60,  # 60 req/min
+            max_request_bytes=524_288,  # 512 KiB
+            hsts=True,
+        )
+
+    **Without throttle** (pass ``throttle_limit=None``, the default)::
+
+        setup_middlewares(app, throttle_limit=None)  # ThrottleMiddleware omitted
+
+    **Custom domain handlers**::
+
+        from nene2.middleware import SimpleDomainHandler
+
+        setup_middlewares(
+            app,
+            domain_handlers=[
+                SimpleDomainHandler(MyDomainError, "my-error", "My Error", 400),
+            ],
+        )
+
+    .. note::
+        This function calls :meth:`ErrorHandlerMiddleware.install` internally, which also
+        registers ``request_validation_error_handler`` so Pydantic 422 errors are formatted
+        as nene2 Problem Details.
+
+    Args:
+        app: The FastAPI (or Starlette) application instance.
+        debug: Expose exception messages in 500 responses (development only).
+        domain_handlers: Custom domain exception handlers for :class:`ErrorHandlerMiddleware`.
+        enable_request_logging: Whether to include :class:`RequestLoggingMiddleware`.
+        throttle_limit: Max requests per ``throttle_window`` seconds.
+            Pass ``None`` (default) to skip :class:`ThrottleMiddleware`.
+        throttle_window: Rate-limit window in seconds (default: 60).
+        throttle_path_limits: Per-path overrides for throttle limits.
+        throttle_exclude_paths: Paths excluded from throttling.
+        max_request_bytes: Maximum request body size in bytes (default: 1 MiB).
+        request_size_path_limits: Per-path size limits.
+        request_size_exclude_paths: Paths excluded from size limiting.
+        security_headers: Whether to include :class:`SecurityHeadersMiddleware` (default: True).
+        hsts: Enable Strict-Transport-Security header (default: False).
+        csp: Custom Content-Security-Policy value. Defaults to nene2's built-in policy.
+        security_extra_no_csp_paths: Additional paths to skip CSP (on top of /docs, /redoc).
+    """
+    if not isinstance(app, Starlette):
+        raise TypeError(f"app must be a Starlette/FastAPI instance, got {type(app)!r}")
+
+    # Add in reverse order — first added = innermost, last added = outermost.
+    # Desired outermost → innermost:
+    #   RequestId → SecurityHeaders → SizeLimit → Throttle → RequestLogging → ErrorHandler
+
+    # 1. Innermost: ErrorHandlerMiddleware (also registers RequestValidationError handler)
+    ErrorHandlerMiddleware.install(app, debug=debug, domain_handlers=domain_handlers)
+
+    # 2. RequestLoggingMiddleware (optional)
+    if enable_request_logging:
+        app.add_middleware(RequestLoggingMiddleware)
+
+    # 3. ThrottleMiddleware (optional)
+    if throttle_limit is not None:
+        throttle_kwargs: dict[str, Any] = {"limit": throttle_limit, "window": throttle_window}
+        if throttle_path_limits:
+            throttle_kwargs["path_limits"] = throttle_path_limits
+        if throttle_exclude_paths:
+            throttle_kwargs["exclude_paths"] = throttle_exclude_paths
+        app.add_middleware(ThrottleMiddleware, **throttle_kwargs)
+
+    # 4. RequestSizeLimitMiddleware
+    size_kwargs: dict[str, Any] = {"max_bytes": max_request_bytes}
+    if request_size_path_limits:
+        size_kwargs["path_limits"] = request_size_path_limits
+    if request_size_exclude_paths:
+        size_kwargs["exclude_paths"] = request_size_exclude_paths
+    app.add_middleware(RequestSizeLimitMiddleware, **size_kwargs)
+
+    # 5. SecurityHeadersMiddleware (optional)
+    if security_headers:
+        sec_kwargs: dict[str, Any] = {"hsts": hsts}
+        if csp is not None:
+            sec_kwargs["csp"] = csp
+        if security_extra_no_csp_paths:
+            sec_kwargs["extra_no_csp_paths"] = security_extra_no_csp_paths
+        app.add_middleware(SecurityHeadersMiddleware, **sec_kwargs)
+
+    # 6. Outermost: RequestIdMiddleware
+    app.add_middleware(RequestIdMiddleware)