nene2-python 1.8.3__tar.gz → 1.8.4__tar.gz

{nene2_python-1.8.3 → nene2_python-1.8.4}/CHANGELOG.md

@@ -5,6 +5,22 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.4] — 2026-05-20
+
+FT33〜FT36 フィールドトライアル — バリデーション・DB整合性・混合認証・非同期ヘルスチェック改善。
+
+### Added
+- `AsyncHealthCheckProtocol` — `async def check() -> HealthStatus` の Protocol (FT36)
+- `AsyncCompositeHealthCheck` — 複数の非同期ヘルスチェックを `asyncio.gather` で並列実行して集約するクラス (FT36)
+- `docs/how-to/validation.md` — `ValidationCode(StrEnum)` パターンと複数フィールドバリデーションの how-to ガイドを追加 (FT33)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-33.md` 〜 `docs/field-trials/2026-05-field-trial-36.md`
+
+### Changed
+- `docs/how-to/run-tests.md` — インメモリ SQLite テスト用 `StaticPool` パターンを追記 (FT34)
+- `docs/how-to/configure-auth.md` — AND / OR 条件の違いと `EitherOrAuthMiddleware` パターンを追記 (FT35)
+
+---
+
 ## [1.8.3] — 2026-05-20
 
 FT31〜FT32 フィールドトライアル — HealthCheck・SecurityHeaders 改善。

{nene2_python-1.8.3 → nene2_python-1.8.4}/PKG-INFO

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

@@ -0,0 +1,111 @@
+# Field Trial 33: ValidationException カスタムエラーコード実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.3 時点
+**テーマ**: `ValidationException` と `ValidationError.code` フィールドを活用した型安全なエラーコードの実運用パターン検証
+
+---
+
+## 概要
+
+ユーザー登録 API を題材に、`ValidationCode(StrEnum)` パターンでドメイン固有のバリデーションコードを定義し、
+`ValidationException` / `ValidationError` と組み合わせて複数フィールドの検証エラーをクライアントに返すフローを検証した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft33-validation-codes/` に以下を作成:
+
+- **`app.py`** — `ValidationCode(StrEnum)` + `ValidationException` によるユーザー登録 API
+- **`test_app.py`** — 正常系・各バリデーションエラー・複数エラー収集の動作テスト (5 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (3 件)
+
+```python
+class ValidationCode(StrEnum):
+    REQUIRED = "required"
+    INVALID_FORMAT = "invalid_format"
+    TOO_SHORT = "too_short"
+    TOO_LONG = "too_long"
+    ALREADY_EXISTS = "already_exists"
+    OUT_OF_RANGE = "out_of_range"
+
+def _validate_registration(body: RegisterBody) -> list[ValidationError]:
+    errors: list[ValidationError] = []
+    if len(body.username) < 3:
+        errors.append(ValidationError("username", "3文字以上必要です", ValidationCode.TOO_SHORT))
+    if "@" not in body.email:
+        errors.append(ValidationError("email", "有効なメールアドレスを入力してください", ValidationCode.INVALID_FORMAT))
+    if body.age < 0 or body.age > 150:
+        errors.append(ValidationError("age", "年齢は 0〜150 の範囲で入力してください", ValidationCode.OUT_OF_RANGE))
+    return errors
+```
+
+**テスト結果**: 8 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP33-1: フレームワークが標準エラーコードを定義していない
+
+**分類**: 設計通り（摩擦なし）
+
+`required` / `invalid_format` / `too_short` / `too_long` 等のよく使うコードを
+フレームワーク側が `ValidationCode` として提供していない。
+各プロジェクトで自前定義が必要。
+
+**判断**: ドメイン固有のコードはプロジェクトで定義するのが適切。フレームワークが網羅的に
+定義すると過剰な依存・名前衝突・拡張困難になる。`StrEnum` パターンを how-to ドキュメントに
+追記することで、新規プロジェクトの立ち上がりをサポートする。
+
+**対応**: `docs/how-to/validation.md` への `StrEnum` パターン記載（ドキュメントのみ）
+
+---
+
+### FP33-2: `ValidationException.single()` の `code` パラメータにデフォルト値がない
+
+**分類**: 既知の設計制約（摩擦なし）
+
+`code` パラメータは必須。`"required"` 等よく使うコードでもデフォルト値なし。
+
+**判断**: 明示的なコードが可読性・型安全性を高める設計上の意図。
+デフォルト値をつけると「コードなし」での利用が増え、クライアント側でのエラーハンドリングが困難になる。
+これは摩擦ではなく既知の制約として受け入れる。
+
+---
+
+### FP33-3: ネストフィールドのエラーパスに点記法ヘルパーがない
+
+**分類**: 軽微な摩擦
+
+`body.email` のようなネストパスを `ValidationError.field` に渡す際、正規化ヘルパーがない。
+任意文字列として渡すのみ。
+
+```python
+error = ValidationError(field="address.city", message="必須です", code="required")
+# 正規化なし — 任意の文字列を受け入れる
+```
+
+**判断**: ネストパスの表現方法（ドット区切り・スラッシュ・配列表記）はプロジェクトにより異なるため、
+フレームワーク側でヘルパーを提供するメリットは小さい。
+ドキュメントでの推奨パターン（ドット区切り）記載で対応。
+
+---
+
+## 所感
+
+`ValidationCode(StrEnum)` パターンは極めて自然に機能する。
+`ValidationError` コンストラクタに `StrEnum` 値をそのまま渡せるため、型安全性と
+JSON シリアライズ（文字列として出力）が同時に確保される。複数フィールドのエラー収集も
+リストに積み上げるだけで直感的。
+
+フレームワーク側で追加の変更は不要。how-to ドキュメントへの `StrEnum` パターン追記のみ対応する。
+
+---
+
+## 関連
+
+- `nene2.validation.ValidationException`
+- `nene2.validation.ValidationError`
+- FT13 (ValidationException実運用, v1.6.0) の後継検証

nene2_python-1.8.4/docs/field-trials/2026-05-field-trial-34.md

@@ -0,0 +1,119 @@
+# Field Trial 34: DatabaseIntegrityException + SimpleDomainHandler 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.3 時点
+**テーマ**: UNIQUE 制約違反 → `DatabaseIntegrityException` → `SimpleDomainHandler` → 409 Problem Details のパイプライン実運用検証
+
+---
+
+## 概要
+
+SQLite UNIQUE 制約を持つ `users` テーブルに `SqlAlchemyQueryExecutor` でアクセスし、
+重複 username の登録が自動的に `DatabaseIntegrityException` へ変換され、
+`SimpleDomainHandler` が 409 Conflict Problem Details を返す完全なパイプラインを検証した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft34-db-integrity/` に以下を作成:
+
+- **`app.py`** — SQLite インメモリ DB + `SqlAlchemyQueryExecutor` + `SimpleDomainHandler` による UNIQUE 違反ハンドリング
+- **`test_app.py`** — 正常系・409・Problem Details 構造・バリデーションエラー混在 (6 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+```python
+handlers = [
+    SimpleDomainHandler(
+        DatabaseIntegrityException,
+        "username-already-taken",
+        "Username Already Taken",
+        409,
+        detail="このユーザー名はすでに使用されています",
+    ),
+]
+app.add_middleware(ErrorHandlerMiddleware, domain_handlers=handlers)
+```
+
+**テスト結果**: 10 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP34-1: `DatabaseIntegrityException` のメッセージが SQLAlchemy の生テキスト
+
+**分類**: 既知の制約（摩擦あり・軽微）
+
+```
+(sqlite3.IntegrityError) UNIQUE constraint failed: users.username
+```
+
+どのフィールドが重複したかを取り出すには文字列パースが必要。
+DB エンジンごとにメッセージ形式が異なる（SQLite / MySQL / PostgreSQL）。
+
+**判断**: フレームワーク側でフィールド抽出 API を提供することも可能だが、
+エンジン依存のパースロジックを組み込むと移植性が下がる。
+アプリ側でドメイン固有の例外（`UsernameTakenException` など）に変換するパターンを推奨。
+
+---
+
+### FP34-2: 制約種別を示すサブクラスがない
+
+**分類**: 既知の制約（摩擦あり・軽微）
+
+`DatabaseIntegrityException` は UNIQUE / FK / CHECK 制約を区別しない。
+違反種別で異なるレスポンスを返したい場合は文字列パースが必要。
+
+**判断**: 制約種別サブクラスの追加は有用だが、DB エンジンごとの判定ロジックが複雑になる。
+現時点はアプリ側で try/except してドメイン例外に変換する方針を how-to ドキュメントで説明。
+
+---
+
+### FP34-3: テスト用インメモリ SQLite に `StaticPool` が必要
+
+**分類**: 摩擦あり → **ドキュメント対応**
+
+`SqlAlchemyQueryExecutor` はクエリごとに `engine.begin()` / `engine.connect()` で
+コネクションを開く。`sqlite:///:memory:` はコネクションごとに独立した DB を作成するため、
+`StaticPool` なしではクエリ間でテーブルが見えなくなる場合がある。
+
+```python
+# 推奨パターン
+engine = create_engine(
+    "sqlite:///:memory:",
+    connect_args={"check_same_thread": False},
+    poolclass=StaticPool,
+)
+```
+
+**対応**: `docs/how-to/run-tests.md` に `StaticPool` 使用を明記。
+
+---
+
+### FP34-4: `SimpleDomainHandler` は制約種別を区別できない
+
+**分類**: 設計通り（摩擦なし）
+
+`SimpleDomainHandler` は例外クラスのみで判定する。
+UNIQUE 違反と FK 違反を別々の HTTP ステータスにマップしたい場合は
+`DomainExceptionHandlerProtocol` を実装する必要がある。
+
+**判断**: `SimpleDomainHandler` はシンプルケース専用のヘルパーという設計意図通り。
+複雑なケースには Protocol 実装を使うのが正しい。
+
+---
+
+## フレームワーク変更
+
+- `docs/how-to/run-tests.md` に `StaticPool` パターンを追記 (FP34-3 対応)
+
+---
+
+## 関連
+
+- `nene2.database.DatabaseIntegrityException`
+- `nene2.database.SqlAlchemyQueryExecutor`
+- `nene2.middleware.SimpleDomainHandler`
+- FT16 (DatabaseIntegrityException 実装, v1.7.0)
+- FT21 (SimpleDomainHandler 実装, v1.8.0)

nene2_python-1.8.4/docs/field-trials/2026-05-field-trial-35.md

@@ -0,0 +1,90 @@
+# Field Trial 35: 混合認証（Bearer Token OR API Key）実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.3 時点
+**テーマ**: `BearerTokenMiddleware` と `ApiKeyAuthMiddleware` の組み合わせパターン、
+および「いずれか一方で可（OR 条件）」認証の実装コストを確認する
+
+---
+
+## 概要
+
+Bearer Token 専用・API Key 専用の各ベースラインを確認した後、
+2 つのミドルウェアをスタックした場合の挙動と、
+OR 条件認証のカスタム実装を比較した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft35-mixed-auth/` に以下を作成:
+
+- **`app.py`** — 4 パターンのアプリ（Bearer のみ・API Key のみ・両方スタック・EitherOr カスタム）
+- **`test_app.py`** — 全パターンの動作検証 (13 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (3 件)
+
+**テスト結果**: 16 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP35-1: ミドルウェアを2つスタックすると AND 条件になる
+
+**分類**: 摩擦あり（設計上の制約）
+
+`BearerTokenMiddleware` と `ApiKeyAuthMiddleware` を両方 `add_middleware` すると、
+各ミドルウェアが独立して検証するため「両方必須（AND）」になる。
+Bearer Token のみ・API Key のみの場合どちらも 401。
+
+```python
+# この設定は AND 条件（両方必須）
+app.add_middleware(ApiKeyAuthMiddleware, ...)
+app.add_middleware(BearerTokenMiddleware, ...)
+```
+
+**判断**: Starlette のミドルウェアスタックの仕様通り。
+`configure-auth.md` に明記し、AND と OR の違いを説明する。
+
+---
+
+### FP35-2: OR 条件の認証にはカスタムミドルウェアの実装が必要
+
+**分類**: 摩擦あり（実装コスト発生）
+
+「Bearer または API Key のいずれかで可」を実現するには
+`BaseHTTPMiddleware` を継承してカスタム実装する必要がある。
+フレームワークに汎用 OR ミドルウェアはない。
+
+ただし、`LocalTokenVerifier` / `TokenVerifierProtocol` は再利用可能なため、
+カスタム実装のコードは約 30 行と軽量。
+
+**判断**: OR 条件の仕様はプロジェクトによって多様すぎるため、
+フレームワークが汎用実装を提供するより、パターンをドキュメントで示す方が適切。
+
+**対応**: `docs/how-to/configure-auth.md` に `EitherOrAuthMiddleware` パターンを追記。
+
+---
+
+### FP35-3: TokenVerifierProtocol の再利用性が高い（好印象）
+
+**分類**: 良い設計の確認
+
+`LocalTokenVerifier` はそのままカスタムミドルウェア内で使えるため、
+トークン比較ロジック（`secrets.compare_digest`）を重複実装する必要がない。
+Protocol 分離の設計が効いている。
+
+---
+
+## フレームワーク変更
+
+- `docs/how-to/configure-auth.md` に「AND / OR の違い」と `EitherOrAuthMiddleware` パターンを追記 (FP35-1, FP35-2 対応)
+
+---
+
+## 関連
+
+- `nene2.auth.BearerTokenMiddleware`
+- `nene2.auth.ApiKeyAuthMiddleware`
+- `nene2.auth.LocalTokenVerifier`
+- FT11 (exclude_paths, LocalTokenVerifier.from_env, v1.4.0)

nene2_python-1.8.4/docs/field-trials/2026-05-field-trial-36.md

@@ -0,0 +1,92 @@
+# Field Trial 36: CompositeHealthCheck 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.3 時点
+**テーマ**: `CompositeHealthCheck` で複数の依存サービス（DB・外部 API・キャッシュ）の健全性を集約し、`HealthStatus.http_status_code` を使って `/health` エンドポイントを実装するパターン。および非同期ヘルスチェックのギャップを発見・修正。
+
+---
+
+## 概要
+
+SQLite DB・外部 API（モック）・キャッシュ（モック）の 3 つの依存を `CompositeHealthCheck` で集約し、
+部分障害時に個別のチェック名と全体 `"error"` ステータスを返すパターンを検証した。
+
+主な発見: 非同期チェックに対応するプロトコルとクラスがなく、外部 HTTP API を非同期で確認するヘルスチェックが書けない摩擦を発見。`AsyncHealthCheckProtocol` と `AsyncCompositeHealthCheck` を追加して対応。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft36-composite-health/` に以下を作成:
+
+- **`app.py`** — DB / 外部 API / キャッシュの 3 チェックを集約した `/health` エンドポイント
+- **`test_app.py`** — 全正常・DB 障害・部分障害・各チェック名の確認 (5 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 9 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP36-1: 非同期ヘルスチェックに対応するプロトコルがない
+
+**分類**: 摩擦あり → **実装で対応**
+
+`HealthCheckProtocol.check()` は同期のみ。外部 HTTP API への非同期 `httpx.AsyncClient` 呼び出しや
+非同期 DB クライアントを使うヘルスチェックを書けない。
+
+**対応**: `AsyncHealthCheckProtocol` と `AsyncCompositeHealthCheck` を `nene2.http` に追加 (#254)。
+`asyncio.gather` で全チェックを並列実行するため、レスポンスタイムも最適化される。
+
+```python
+class AsyncApiHealthCheck:
+    async def check(self) -> HealthStatus:
+        async with httpx.AsyncClient() as client:
+            r = await client.get("https://api.example.com/health")
+        status = "ok" if r.status_code == 200 else "error"
+        return HealthStatus(status=status, checks={"external_api": status})
+
+composite = AsyncCompositeHealthCheck([db_check, AsyncApiHealthCheck()])
+```
+
+---
+
+### FP36-2: チェックの名前を集約時に指定できない
+
+**分類**: 設計通り（摩擦なし）
+
+チェックの名前は `HealthStatus.checks` の dict キーで決まる（チェック実装側が定義する）。
+集約側での名前 override はできない。
+
+**判断**: チェック実装がその名前を知っているべきという責務分離の観点で正しい設計。
+集約側での名前指定を可能にすると DRY 違反になりやすい。
+
+---
+
+### FP36-3: 同名キーを持つチェックが複数あると後勝ちになる
+
+**分類**: 軽微な摩擦（ドキュメント対応）
+
+2 つのチェックが同じキーを `checks` に返した場合、`dict.update()` で後のチェックが勝つ。
+衝突検出の仕組みはない。
+
+**判断**: 各チェックがユニークな名前を使う規約で対応。
+
+---
+
+## フレームワーク変更
+
+- `nene2.http.AsyncHealthCheckProtocol` — `async def check() -> HealthStatus` の Protocol を追加 (FP36-1)
+- `nene2.http.AsyncCompositeHealthCheck` — 並列実行の集約クラスを追加 (FP36-1)
+- テスト 6 件追加
+
+---
+
+## 関連
+
+- `nene2.http.CompositeHealthCheck`
+- `nene2.http.HealthStatus`
+- FT22 (CompositeHealthCheck 実装, v1.8.0)
+- FT31 (HealthStatus.http_status_code, v1.8.3)
+- Issue #254

{nene2_python-1.8.3 → nene2_python-1.8.4}/docs/how-to/configure-auth.md

@@ -45,9 +45,56 @@ API_KEYS=["key1","key2"]
 curl -H "X-Api-Key: key1" http://localhost:8080/notes
 ```
 
-## Using both at once
+## Using both at once (AND condition)
 
-When both `BEARER_TOKEN_ENABLED` and `API_KEY_ENABLED` are set, requests must pass both checks. In practice you would choose one or the other.
+When both middlewares are added via `add_middleware`, requests must pass **both** checks (AND condition). A Bearer token alone or an API key alone will both result in 401.
+
+## Either-or authentication (Bearer Token OR API Key)
+
+If you want to accept **either** a Bearer token or an API key — whichever is present — the built-in middlewares cannot express this. Implement a custom middleware that reuses the existing verifiers:
+
+```python
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+from nene2.auth import LocalTokenVerifier
+from nene2.auth.exceptions import TokenVerificationException
+from nene2.http.problem_details import problem_details_response
+
+class EitherOrAuthMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, *, bearer_tokens: list[str], api_keys: list[str],
+                 exclude_paths: list[str] | None = None) -> None:
+        super().__init__(app)
+        self._bearer = LocalTokenVerifier(bearer_tokens)
+        self._api_key = LocalTokenVerifier(api_keys)
+        self._exclude_paths = set(exclude_paths or [])
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        if request.url.path in self._exclude_paths:
+            return await call_next(request)
+
+        auth = request.headers.get("Authorization", "")
+        if auth.startswith("Bearer "):
+            try:
+                if self._bearer.verify(auth[len("Bearer "):]):
+                    return await call_next(request)
+            except TokenVerificationException:
+                pass
+
+        api_key = request.headers.get("X-Api-Key", "")
+        if api_key:
+            try:
+                if self._api_key.verify(api_key):
+                    return await call_next(request)
+            except TokenVerificationException:
+                pass
+
+        return problem_details_response(
+            "unauthorized", "Unauthorized", 401,
+            "A valid Bearer token or X-Api-Key header is required.",
+        )
+```
 
 ## Disabling auth in tests
 

{nene2_python-1.8.3 → nene2_python-1.8.4}/docs/how-to/run-tests.md

@@ -86,6 +86,23 @@ async def test_async_list_notes() -> None:
     assert result.total == 0
 ```
 
+## In-memory SQLite for integration tests
+
+When using `SqlAlchemyQueryExecutor` or `SqlAlchemyTransactionManager` with an in-memory SQLite database, always pass `poolclass=StaticPool`. Without it, SQLAlchemy may open a new physical connection that sees an empty database.
+
+```python
+from sqlalchemy import create_engine
+from sqlalchemy.pool import StaticPool
+
+engine = create_engine(
+    "sqlite:///:memory:",
+    connect_args={"check_same_thread": False},
+    poolclass=StaticPool,
+)
+```
+
+`StaticPool` guarantees all logical connections share the same underlying SQLite connection, so tables created in one operation are visible to the next.
+
 ## Coverage requirements
 
 | Scope | Target |

nene2_python-1.8.4/docs/how-to/validation.md

@@ -0,0 +1,101 @@
+# How-to: バリデーションエラーを扱う
+
+`nene2.validation` の `ValidationException` と `ValidationError` を使って、
+ドメインバリデーションエラーをクライアントに返す方法を説明する。
+
+---
+
+## 1. ValidationCode を StrEnum で定義する
+
+フレームワークは標準エラーコードを定義しない。プロジェクトごとに `StrEnum` で定義する。
+
+```python
+from enum import StrEnum
+
+class ValidationCode(StrEnum):
+    REQUIRED = "required"
+    INVALID_FORMAT = "invalid_format"
+    TOO_SHORT = "too_short"
+    TOO_LONG = "too_long"
+    ALREADY_EXISTS = "already_exists"
+    OUT_OF_RANGE = "out_of_range"
+```
+
+`StrEnum` を使うと:
+- `ValidationError` コンストラクタに直接渡せる（型安全）
+- JSON シリアライズ時に文字列値として出力される
+- IDE の補完・静的解析が効く
+
+---
+
+## 2. 複数フィールドのバリデーション
+
+リストにエラーを積み上げて `ValidationException` をまとめて raise する。
+
+```python
+from nene2.validation import ValidationError, ValidationException
+
+def validate_registration(username: str, email: str, age: int) -> None:
+    errors: list[ValidationError] = []
+
+    if len(username) < 3:
+        errors.append(ValidationError("username", "3文字以上必要です", ValidationCode.TOO_SHORT))
+    if "@" not in email:
+        errors.append(ValidationError("email", "有効なメールアドレスを入力してください", ValidationCode.INVALID_FORMAT))
+    if age < 0 or age > 150:
+        errors.append(ValidationError("age", "年齢は 0〜150 の範囲で入力してください", ValidationCode.OUT_OF_RANGE))
+
+    if errors:
+        raise ValidationException(errors)
+```
+
+レスポンス例 (422):
+
+```json
+{
+  "type": "https://example.com/problems/validation-failed",
+  "title": "Validation Failed",
+  "status": 422,
+  "errors": [
+    {"field": "username", "message": "3文字以上必要です", "code": "too_short"},
+    {"field": "email",    "message": "有効なメールアドレスを入力してください", "code": "invalid_format"}
+  ]
+}
+```
+
+---
+
+## 3. 単一フィールドのバリデーション
+
+`ValidationException.single()` で 1 行で raise できる。
+
+```python
+from nene2.validation import ValidationException
+
+raise ValidationException.single("email", "メールアドレスは必須です", ValidationCode.REQUIRED)
+```
+
+---
+
+## 4. ネストフィールドのパス
+
+ネストしたフィールドのパスはドット区切りの文字列で渡す（正規化ヘルパーはない）。
+
+```python
+ValidationError("address.city", "必須です", ValidationCode.REQUIRED)
+ValidationError("items.0.quantity", "1 以上を入力してください", ValidationCode.OUT_OF_RANGE)
+```
+
+---
+
+## 5. ErrorHandlerMiddleware との連携
+
+`nene2.middleware.ErrorHandlerMiddleware` をアプリに追加すると、
+`ValidationException` が自動で 422 Problem Details レスポンスに変換される。
+
+```python
+from nene2.middleware import ErrorHandlerMiddleware
+
+app = FastAPI()
+app.add_middleware(ErrorHandlerMiddleware)
+```

{nene2_python-1.8.3 → nene2_python-1.8.4}/pyproject.toml

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

{nene2_python-1.8.3 → nene2_python-1.8.4}/src/nene2/http/__init__.py

@@ -1,10 +1,18 @@
 """HTTP helpers — JSON responses, pagination, problem details, health."""
 
-from .health import CompositeHealthCheck, HealthCheckProtocol, HealthStatus
+from .health import (
+    AsyncCompositeHealthCheck,
+    AsyncHealthCheckProtocol,
+    CompositeHealthCheck,
+    HealthCheckProtocol,
+    HealthStatus,
+)
 from .pagination import PaginationQuery, PaginationQueryParser, PaginationResponse
 from .problem_details import configure_problem_details, problem_details_response
 
 __all__ = [
+    "AsyncCompositeHealthCheck",
+    "AsyncHealthCheckProtocol",
     "CompositeHealthCheck",
     "HealthCheckProtocol",
     "HealthStatus",