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

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

@@ -5,6 +5,16 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.5] — 2026-05-20
+
+FT37〜FT40 フィールドトライアル — RequestSizeLimitMiddleware パスごとサイズ制限とドキュメント改善。
+
+### Added
+- `RequestSizeLimitMiddleware` に `path_limits: dict[str, int] | None = None` パラメータを追加 — パスごとに異なるリクエストボディサイズ制限を設定可能に (FT39)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-37.md` 〜 `docs/field-trials/2026-05-field-trial-40.md`
+
+---
+
 ## [1.8.4] — 2026-05-20
 
 FT33〜FT36 フィールドトライアル — バリデーション・DB整合性・混合認証・非同期ヘルスチェック改善。

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

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

@@ -0,0 +1,77 @@
+# Field Trial 37: PaginationResponse + PaginationQueryParser 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.4 時点
+**テーマ**: `PaginationQueryParser` の `Depends()` パターンと `PaginationResponse.to_dict()` を使ったページネーションパイプラインの実運用確認
+
+---
+
+## 概要
+
+50 件の `Product` データを `PaginationQueryParser` で limit/offset 制御し、
+`PaginationResponse.to_dict()` で slotted dataclass を自動シリアライズして `JSONResponse` に変換するパイプラインを検証した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft37-pagination/` に以下を作成:
+
+- **`app.py`** — `Annotated[PaginationQueryParser, Depends()]` パターンの `/api/products` エンドポイント
+- **`test_app.py`** — デフォルト・カスタム・最終ページ・無効値・Depends 動作確認 (9 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 13 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP37-1: `Annotated[PaginationQueryParser, Depends()]` と書く必要がある
+
+**分類**: 軽微な摩擦（FastAPI 標準パターン）
+
+`def list(pagination: PaginationQueryParser = Depends())` ではなく
+`def list(pagination: Annotated[PaginationQueryParser, Depends()])` が推奨パターン。
+FastAPI の仕様に従っているが、初見では迷いやすい。
+
+**判断**: `docs/how-to/validation.md` および新規作成する how-to への記載で対応。
+
+---
+
+### FP37-2: `to_dict()` は dataclass のみ自動シリアライズ
+
+**分類**: 既知の制約（軽微）
+
+`PaginationResponse.to_dict()` は `dataclasses.is_dataclass()` で判定する。
+Pydantic モデルの items は `.model_dump()` を個別に呼ぶ必要がある。
+通常の dict はそのまま通過する。
+
+**判断**: dataclass 向け最適化という設計意図通り。
+Pydantic モデルとの混在ユースケースは how-to ドキュメントに記載する。
+
+---
+
+### FP37-3: `total` 省略時に `"total"` キーが消える（設計通り）
+
+**分類**: 設計通り（摩擦なし）
+
+`PaginationResponse(items=[], limit=10, offset=0)` のように `total` を渡さないと
+`to_dict()` の結果に `"total"` キーが含まれない。
+`total=None` を明示しても同じ結果。
+
+**判断**: 全件数を取得しない効率的なページネーションをサポートする意図通り。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+---
+
+## 関連
+
+- `nene2.http.PaginationQueryParser`
+- `nene2.http.PaginationResponse`
+- FT10 (PaginationResponse.to_dict() スロット対応, v1.3.0)

nene2_python-1.8.5/docs/field-trials/2026-05-field-trial-38.md

@@ -0,0 +1,85 @@
+# Field Trial 38: SqlAlchemyTransactionManager.transactional() 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.4 時点
+**テーマ**: 注文作成（在庫更新 + 注文レコード作成）をトランザクションで包み、途中での例外発生時のロールバック動作を確認する
+
+---
+
+## 概要
+
+`SqlAlchemyTransactionManager.transactional(callback)` を使って複数の DB 書き込みを一つのトランザクションに包み、途中で例外が発生した場合のロールバック動作を検証した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft38-transactions/` に以下を作成:
+
+- **`app.py`** — 在庫チェック + 在庫減少 + 注文作成を `transactional()` で包んだ注文 API
+- **`test_app.py`** — 正常注文・在庫不足・ロールバック確認・連続注文 (6 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (3 件)
+
+**テスト結果**: 9 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP38-1: コールバック内で型アノテーションに `DatabaseQueryExecutorInterface` が必要
+
+**分類**: 軽微な摩擦（mypy --strict 使用時）
+
+```python
+def _do_create(db: object) -> int:
+    ...
+```
+
+`db` を `object` 型にするとメソッド呼び出しに mypy エラーが出る。
+`DatabaseQueryExecutorInterface` をインポートして型アノテーションする必要がある。
+
+**判断**: mypy --strict の設計上当然の制約。インポートはやや冗長だが許容範囲。
+`db: DatabaseQueryExecutorInterface` が推奨パターンとしてドキュメントに記載されている。
+
+---
+
+### FP38-2: savepoint（ネストトランザクション）はサポートしない
+
+**分類**: 既知の制約（設計通り）
+
+`DatabaseQueryExecutorInterface` が持つのは `fetch_all` / `fetch_one` / `write` のみ。
+SQLAlchemy の savepoint 機能（`SAVEPOINT` / `ROLLBACK TO SAVEPOINT`）は使えない。
+
+**判断**: フレームワークの抽象化レイヤーが Pure SQL テキストベースの設計を採用しているため、
+ORM/Connection 固有の高度な機能は意図的に除外されている。
+savepoint が必要な場合は SQLAlchemy を直接使う Repository を実装するのが正しいパターン。
+
+---
+
+### FP38-3: トランザクション途中の例外はすべてロールバックされる（設計通り）
+
+**分類**: 設計通り（摩擦なし）
+
+```python
+def _callback(db: DatabaseQueryExecutorInterface) -> None:
+    db.write("INSERT ...")  # ← この変更も
+    raise ValueError("oops")  # ← ここで例外 → 全部ロールバック
+```
+
+例外の種類に関わらず（`DatabaseIntegrityException` 以外でも）全変更がロールバックされる。
+これは `SqlAlchemyTransactionManager.transactional()` の期待される動作。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+---
+
+## 関連
+
+- `nene2.database.SqlAlchemyTransactionManager`
+- `nene2.database.DatabaseQueryExecutorInterface`
+- FT16 (DatabaseIntegrityException, v1.7.0)
+- FT34 (DatabaseIntegrityException 実運用, v1.8.3)

nene2_python-1.8.5/docs/field-trials/2026-05-field-trial-39.md

@@ -0,0 +1,95 @@
+# Field Trial 39: RequestSizeLimitMiddleware 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.4 時点
+**テーマ**: `RequestSizeLimitMiddleware` で JSON ボディとバイナリアップロードのサイズを制限するパターンと、パスごとに異なる制限を設定したいユースケースの確認
+
+---
+
+## 概要
+
+小さな `max_bytes` 制限（200 bytes）を設定したアプリで、正常なリクエスト・超過リクエスト・除外パス・境界値を検証した。
+主な発見: パスごとに異なる制限（例: 通常 API は 1 MiB、アップロードエンドポイントは 10 MiB）が設定できない摩擦を発見。`path_limits` パラメータを追加して対応。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft39-request-size/` に以下を作成:
+
+- **`app.py`** — `RequestSizeLimitMiddleware(max_bytes=200, exclude_paths=[...])` の動作確認アプリ
+- **`test_app.py`** — 正常・超過・除外パス・境界値の動作確認 (8 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (3 件)
+
+**テスト結果**: 11 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP39-1: パスごとに異なる max_bytes を設定できない
+
+**分類**: 摩擦あり → **実装で対応**
+
+`RequestSizeLimitMiddleware` は全体で一つの `max_bytes` のみ設定できる。
+アップロードエンドポイント（例: 10 MiB）と通常 API（例: 1 MiB）で異なる制限を設定したい場合、
+`exclude_paths` でアップロードを除外してハンドラー内で手動チェックするしかなかった。
+
+**対応**: `ThrottleMiddleware.path_limits` と同様のパターンで `path_limits: dict[str, int] | None` を追加 (#259)。
+
+```python
+app.add_middleware(
+    RequestSizeLimitMiddleware,
+    max_bytes=1_048_576,                  # デフォルト: 1 MiB
+    path_limits={
+        "/upload/file": 10_485_760,       # /upload/file: 10 MiB
+        "/api/import": 5_242_880,         # /api/import: 5 MiB
+    },
+)
+```
+
+413 レスポンスの `max_bytes` フィールドはパス固有の制限値を返す。
+
+---
+
+### FP39-2: max_bytes 構造化フィールドが 413 レスポンスに含まれる（FT23 改善の確認）
+
+**分類**: 良い設計の確認
+
+```json
+{
+  "status": 413,
+  "type": ".../payload-too-large",
+  "title": "Payload Too Large",
+  "max_bytes": 200
+}
+```
+
+`max_bytes` フィールドがあることでクライアントがプログラムで制限値を知れる。
+FT23 で追加された改善が実際に役立つことを確認。
+
+---
+
+### FP39-3: Content-Length ヘッダーによる早期拒否が機能する
+
+**分類**: 設計通り（摩擦なし）
+
+Content-Length ヘッダーが `max_bytes` を超える場合、ボディを読む前に 413 を返す。
+メモリ効率が良い設計。
+
+---
+
+## フレームワーク変更
+
+- `RequestSizeLimitMiddleware` に `path_limits: dict[str, int] | None = None` を追加 (FP39-1)
+- テスト 2 件追加
+
+---
+
+## 関連
+
+- `nene2.middleware.RequestSizeLimitMiddleware`
+- FT12 (RequestSizeLimitMiddleware exclude_paths, v1.5.0)
+- FT23 (413 レスポンスに max_bytes 追加, v1.8.0)
+- FT28 (ThrottleMiddleware path_limits, v1.8.1)
+- Issue #259

nene2_python-1.8.5/docs/field-trials/2026-05-field-trial-40.md

@@ -0,0 +1,87 @@
+# Field Trial 40: 多ドメイン連携（Article + Tag 紐付け）実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.4 時点
+**テーマ**: 1 つの UseCase が 2 つのリポジトリ（Article + Tag）を横断するパターンの実運用確認
+
+---
+
+## 概要
+
+`TagArticleUseCase` が `InMemoryArticleRepository` と `InMemoryTagRepository` を
+コンストラクタインジェクションで受け取り、記事へのタグ付けを管理するパターンを実装した。
+複数の無効 TagId がある場合に `ValidationException` で全エラーを一度に収集するパターンも確認。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft40-multi-domain/` に以下を作成:
+
+- **`app.py`** — Article + Tag の 2 ドメインを跨ぐ `TagArticleUseCase` と FastAPI エンドポイント
+- **`test_app.py`** — 正常タグ付け・不正タグ・404・複数バリデーションエラー (7 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 11 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP40-1: 複数リポジトリを受け取る UseCase は自然に書ける（良い設計）
+
+**分類**: 摩擦なし（設計の確認）
+
+フレームワークは UseCase 構造に制約を課さないため、
+複数のリポジトリを `__init__` で受け取るパターンが素直に実装できる。
+CLAUDE.md の「UseCase は他の UseCase を呼ばない」ルールに従い、
+各リポジトリを直接呼ぶことで依存関係がシンプルに保たれる。
+
+---
+
+### FP40-2: カスタムドメイン例外は SimpleDomainHandler 登録が必要
+
+**分類**: 軽微な摩擦（設計通り・注意喚起）
+
+`ValidationException` は `ErrorHandlerMiddleware` が自動で 422 に変換するが、
+`ArticleNotFoundException` のようなカスタムドメイン例外は
+`SimpleDomainHandler` を明示的に登録しないと 500 になる。
+登録を忘れると意図しない 500 レスポンスになるため注意が必要。
+
+```python
+# 忘れると 500 になる
+handlers = [
+    SimpleDomainHandler(ArticleNotFoundException, "article-not-found", "Not Found", 404),
+]
+app.add_middleware(ErrorHandlerMiddleware, domain_handlers=handlers)
+```
+
+**判断**: ドメイン例外の HTTP マッピングを明示的にする設計は正しい。
+`configure-auth.md` と同様に how-to ドキュメントでパターンを示す価値がある。
+
+---
+
+### FP40-3: 複数ドメイン横断バリデーションエラーを一括収集できる
+
+**分類**: 良い設計の確認
+
+`ValidationException` リストにエラーを積み上げてから raise するパターンで、
+複数の無効 TagId を一度のリクエストでまとめてクライアントに通知できる。
+FT33 で確認した `ValidationCode(StrEnum)` パターンと組み合わせると更に型安全になる。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+---
+
+## 関連
+
+- `nene2.use_case.UseCaseProtocol`
+- `nene2.validation.ValidationException`
+- `nene2.middleware.SimpleDomainHandler`
+- FT13 (ValidationException 実運用, v1.6.0)
+- FT21 (SimpleDomainHandler 実装, v1.8.0)
+- FT33 (ValidationCode StrEnum パターン, v1.8.3)

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

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

{nene2_python-1.8.4 → nene2_python-1.8.5}/src/nene2/middleware/request_size_limit.py

@@ -23,7 +23,18 @@ class RequestSizeLimitMiddleware(BaseHTTPMiddleware):
     then reads the actual body to catch chunked-transfer requests that
     omit Content-Length entirely.
 
-    Use ``exclude_paths`` to bypass the size limit for specific endpoints::
+    Use ``path_limits`` to set per-path limits that override the default::
+
+        app.add_middleware(
+            RequestSizeLimitMiddleware,
+            max_bytes=1_048_576,  # default: 1 MiB
+            path_limits={
+                "/upload/file": 10_485_760,  # /upload/file: 10 MiB
+                "/api/import": 5_242_880,  # /api/import: 5 MiB
+            },
+        )
+
+    Use ``exclude_paths`` to bypass the size limit entirely::
 
         app.add_middleware(
             RequestSizeLimitMiddleware,
@@ -37,35 +48,40 @@ class RequestSizeLimitMiddleware(BaseHTTPMiddleware):
         app: object,
         *,
         max_bytes: int = _DEFAULT_MAX_BYTES,
+        path_limits: dict[str, int] | None = None,
         exclude_paths: list[str] | None = None,
     ) -> None:
         super().__init__(app)  # type: ignore[arg-type]
         self._max_bytes = max_bytes
+        self._path_limits: dict[str, int] = path_limits or {}
         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:
+        path = request.url.path
+        if path in self._exclude_paths:
             return await call_next(request)
 
+        effective_limit = self._path_limits.get(path, self._max_bytes)
+
         content_length = request.headers.get("Content-Length")
         if content_length is not None:
             try:
-                if int(content_length) > self._max_bytes:
-                    return self._too_large()
+                if int(content_length) > effective_limit:
+                    return self._too_large(effective_limit)
             except ValueError:
                 pass
 
         body = await request.body()
-        if len(body) > self._max_bytes:
-            return self._too_large()
+        if len(body) > effective_limit:
+            return self._too_large(effective_limit)
 
         return await call_next(request)
 
-    def _too_large(self) -> Response:
+    def _too_large(self, limit: int) -> Response:
         return problem_details_response(
             "payload-too-large",
             "Payload Too Large",
             413,
-            _TOO_LARGE.format(limit=self._max_bytes),
-            extra={"max_bytes": self._max_bytes},
+            _TOO_LARGE.format(limit=limit),
+            extra={"max_bytes": limit},
         )

{nene2_python-1.8.4 → nene2_python-1.8.5}/tests/nene2/middleware/test_request_size_limit.py

@@ -69,6 +69,45 @@ def test_malformed_content_length_is_tolerated() -> None:
     assert response.status_code == 200
 
 
+def test_path_limits_overrides_default_for_specific_paths() -> None:
+    app = FastAPI()
+    app.add_middleware(
+        RequestSizeLimitMiddleware,
+        max_bytes=100,
+        path_limits={"/upload/large": 5000},
+    )
+
+    @app.post("/upload")
+    async def upload() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    @app.post("/upload/large")
+    async def upload_large() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    assert client.post("/upload", content=b"x" * 200).status_code == 413
+    assert client.post("/upload/large", content=b"x" * 200).status_code == 200
+
+
+def test_path_limits_413_response_shows_path_limit_not_default() -> None:
+    app = FastAPI()
+    app.add_middleware(
+        RequestSizeLimitMiddleware,
+        max_bytes=1000,
+        path_limits={"/strict": 50},
+    )
+
+    @app.post("/strict")
+    async def strict() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    r = client.post("/strict", content=b"x" * 100)
+    assert r.status_code == 413
+    assert r.json()["max_bytes"] == 50
+
+
 def test_exclude_paths_bypasses_size_limit() -> None:
     app = FastAPI()
     app.add_middleware(

{nene2_python-1.8.4 → nene2_python-1.8.5}/uv.lock

@@ -925,7 +925,7 @@ wheels = [
 
 [[package]]
 name = "nene2-python"
-version = "1.8.4"
+version = "1.8.5"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },