nene2-python 1.8.23__tar.gz → 1.8.25__tar.gz

{nene2_python-1.8.23 → nene2_python-1.8.25}/CHANGELOG.md

@@ -5,6 +5,28 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.24] — 2026-05-20
+
+FT78 フィールドトライアル — ThrottleMiddleware の境界動作検証とドキュメント強化。
+
+### Changed
+- `ThrottleMiddleware` クラス docstring に Fixed Window バースト特性とマルチプロセス非対応の警告を追記 (#335) (FT78)
+- `setup_middlewares()` の `throttle_limit` docstring にマルチプロセス警告を追記 (#335) (FT78)
+- Field trial report: `docs/field-trials/2026-05-field-trial-78.md` (FT78)
+
+---
+
+## [1.8.23] — 2026-05-20
+
+FT77 フィールドトライアル — BearerToken + ApiKey 混在認証と include_paths 追加。
+
+### Added
+- `BearerTokenMiddleware` / `ApiKeyAuthMiddleware` に `include_paths` パラメーターを追加 (#331) (FT77)
+  — プレフィックスマッチで「守りたいパス」を直接指定でき、混在認証の `exclude_paths` 二重管理を解消
+- Field trial report: `docs/field-trials/2026-05-field-trial-77.md` (FT77)
+
+---
+
 ## [1.8.22] — 2026-05-20
 
 FT76 フィールドトライアル — async def + sync DB ブロッキング問題と run_in_threadpool 追加。

{nene2_python-1.8.23 → nene2_python-1.8.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.23
+Version: 1.8.25
 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.25/docs/field-trials/2026-05-field-trial-78.md

@@ -0,0 +1,164 @@
+# FT78: ThrottleMiddleware 境界動作
+
+**日付**: 2026-05-20  
+**テーマ**: レート制限のウィンドウリセット・バースト動作・path_limits の挙動検証  
+**バージョン**: v1.8.23  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft78-throttle-boundary/`
+
+---
+
+## 概要
+
+`ThrottleMiddleware` の境界動作を詳細に検証した。
+基本機能（429 返却、Retry-After ヘッダー、path_limits）は期待通り動作した。
+一方で、Fixed Window アルゴリズムの構造的な制限と、
+マルチプロセス環境での in-memory 共有不可という制約が明確になった。
+
+---
+
+## 動作確認
+
+### 429 レスポンス形式
+
+```json
+{
+  "type": "https://httpstatuses.com/too-many-requests",
+  "title": "Too Many Requests",
+  "status": 429,
+  "detail": "Rate limit exceeded. Retry after 58 seconds."
+}
+```
+
+Retry-After ヘッダーあり ✅
+
+### レート制限ヘッダー（全レスポンスに付与）
+
+```
+X-RateLimit-Limit: 3
+X-RateLimit-Remaining: 2
+X-RateLimit-Reset: 1747742980
+```
+
+全レスポンス（200 も 429 も）にヘッダーが付く ✅
+
+### path_limits: グローバルカウンターと独立 ✅
+
+```python
+app.add_middleware(ThrottleMiddleware, limit=100, path_limits={"/api/search": 5})
+```
+
+`/api/search` の制限 (5) は `/api/data` のグローバル制限 (100) と完全に独立。
+
+---
+
+## 発見した問題
+
+### 問題1: Fixed Window バースト問題（設計上の制限）
+
+固定ウィンドウ方式では、ウィンドウ境界で最大 `2 × limit` のリクエストが短時間に通過できる。
+
+```
+window=60s, limit=3 の場合:
+  t=59s: 3 req 通過（ウィンドウ1の末尾）
+  t=61s: 3 req 通過（ウィンドウ2の先頭）
+  → 2秒間に 6 req が通ってしまう
+```
+
+Flask-Limiter デフォルトの Sliding Window では防げるが、
+nene2 は計算コストの低い Fixed Window を採用している。
+
+ドキュメントにこの制限を明記すべき。
+
+### 問題2: in-memory カウンターはマルチプロセス非対応
+
+`_counts` は Python の `dict` で保持されており、
+複数の uvicorn ワーカー（`gunicorn -w 4`）や Docker Pod では共有されない。
+
+実効的な制限は `limit × worker_count` になる。
+本番で水平スケールさせると全くレート制限が機能しない。
+
+**ドキュメントに警告はある**（コードの docstring）が、README や使用例には書かれていない。
+
+### 問題3: カウント状態の観察手段がない
+
+現在のカウント状態（「このIPが今 N/M 消費」）を外部から取得する手段がない。
+デバッグ時に困る。
+
+```python
+# これが欲しいが存在しない
+info = middleware.get_rate_info(ip="192.168.1.1")
+print(info.current_count, info.remaining)
+```
+
+### 問題4: exclude_paths はヘッダーも返さない
+
+除外パスにはレート制限ヘッダーが一切付かない。
+クライアントが「このパスは制限外か？」を知る方法がない。
+
+---
+
+## テスト結果（全14件パス）
+
+```
+test_requests_within_limit_are_allowed              PASSED
+test_exceeding_limit_returns_429                    PASSED
+test_429_response_is_problem_details                PASSED
+test_rate_limit_headers_present_on_200              PASSED
+test_rate_limit_remaining_decrements                PASSED
+test_retry_after_header_present_on_429              PASSED
+test_retry_after_reasonable_value                   PASSED
+test_path_limits_independent_from_global            PASSED
+test_path_limits_headers_show_path_limit            PASSED
+test_exclude_paths_bypass_throttle                  PASSED
+test_window_resets_after_elapsed                    PASSED
+test_friction_no_global_ip_tracking_visible_to_user PASSED
+test_friction_in_memory_state_not_shared_across_workers  PASSED
+test_friction_fixed_window_burst_at_boundary        PASSED
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F78-1 | Fixed Window バースト問題がドキュメントに明記されていない | 中 |
+| F78-2 | マルチプロセス非対応（in-memory）がドキュメントに明記されていない | 高 |
+| F78-3 | カウント状態の観察 API がない | 低 |
+| F78-4 | exclude_paths のパスにレート制限ヘッダーが付かない | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★★☆
+
+`setup_middlewares(app, throttle_limit=60, throttle_window=60)` で一発設定できる点は非常に快適。
+`path_limits` / `exclude_paths` のパラメーター名も直感的。
+`Retry-After` が自動で付くのはエレガント。
+
+### 実害の深刻さ ★★★★☆
+
+マルチプロセス非対応は本番で深刻。
+「レート制限を設定したのに効いていない」というデバッグは非常に時間がかかる。
+ただし docstring に警告が書かれており、見れば分かる（見逃しやすいが）。
+
+### 修正のしやすさ ★★★★★
+
+ドキュメント追記のみで対応できる問題が多い。
+実装変更（Redis 対応）は将来的な機能拡張として Issues に記録する程度でよい。
+
+### 総合コメント
+
+基本機能は非常によくできている。
+問題は「制限の文書化」が不足している点。
+Fixed Window の特性とマルチプロセス制約を README や使用例に追記するだけで
+UX が大幅に改善する。実装は変えなくてよい。
+
+---
+
+## 推奨アクション
+
+1. **Issue**: ThrottleMiddleware のドキュメントに Fixed Window バースト特性を追記
+2. **Issue**: ThrottleMiddleware のドキュメントにマルチプロセス非対応の警告を目立つ位置に追記
+3. **将来**: Redis カウンターバックエンドの検討（外部依存なので慎重に）

nene2_python-1.8.25/docs/field-trials/2026-05-field-trial-79.md

@@ -0,0 +1,186 @@
+# FT79: RequestLoggingMiddleware と構造化ログ
+
+**日付**: 2026-05-20  
+**テーマ**: リクエストログに何が含まれるか — 機密情報漏洩リスクとデバッグ適性の確認  
+**バージョン**: v1.8.24  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft79-request-logging/`
+
+---
+
+## 概要
+
+`RequestLoggingMiddleware` と `structlog` の組み合わせを検証した。
+基本機能は期待通り動作し、セキュリティ設計（ボディをログしない）も適切。
+一方で、リクエストボディの選択的ログ記録やリクエストごとの動的コンテキスト追加といった
+デバッグ用途での柔軟性の欠如が摩擦点として判明した。
+
+---
+
+## ログ出力の内容（確認済み）
+
+### request.received
+
+```json
+{
+  "event": "request.received",
+  "level": "info",
+  "logger": "nene2.middleware.request_logging",
+  "method": "GET",
+  "path": "/api/users",
+  "request_id": "abc-123",
+  "service": "ft79-app",
+  "version": "1.0.0"
+}
+```
+
+### request.completed
+
+```json
+{
+  "event": "request.completed",
+  "level": "info",
+  "logger": "nene2.middleware.request_logging",
+  "method": "GET",
+  "path": "/api/users",
+  "status_code": 200,
+  "duration_ms": 1.4,
+  "request_id": "abc-123",
+  "service": "ft79-app",
+  "version": "1.0.0"
+}
+```
+
+---
+
+## セキュリティ設計（良い点）
+
+### リクエストボディをログしない ✅
+
+```python
+# POST /api/users {"name": "alice", "password": "super-secret-pw"}
+# → ログには password が含まれない
+```
+
+nene2 は `url.path` のみをログし、ボディも Cookie も Authorization ヘッダーも記録しない。
+Django の `request_finished` シグナルや Flask-Login のデフォルト設定で
+機密情報がログに漏洩するケースと対照的に、nene2 はデフォルトで安全。
+
+### クエリパラメーターをログしない ✅
+
+```
+GET /api/users?secret_token=hidden
+```
+
+`url.path` は `/api/users` のみを返すため、クエリパラメーターはログに含まれない。
+URLにAPIキーを含める（推奨されないが）パターンでも機密情報が漏洩しない。
+
+---
+
+## 発見した問題
+
+### 問題1: extra_context が静的のみ — リクエストごとの動的コンテキストが追加できない
+
+```python
+# 現状: アプリ起動時の静的な値のみ
+app.add_middleware(
+    RequestLoggingMiddleware,
+    extra_context={"service": "my-api", "version": "1.0.0"},
+)
+```
+
+```python
+# 欲しいが実現できない: リクエストごとの動的な値
+# → JWT から取り出した user_id をログに含めたい
+# → テナントIDをログに含めたい
+app.add_middleware(
+    RequestLoggingMiddleware,
+    context_extractor=lambda request: {"user_id": get_user_id(request)},  # 非対応
+)
+```
+
+`structlog.contextvars.bind_contextvars()` を直接使えば可能だが、
+その場合はミドルウェアを自作する必要がある。
+
+### 問題2: デバッグ時のリクエストボディログ方法が不明
+
+本番では不要だが、開発時にリクエストボディをログしたいケースがある。
+現状では nene2 でこれを行う方法がなく、
+カスタムミドルウェアを追加するか `add_route_logging` のようなデコレーターを自作する必要がある。
+
+### 問題3: configure_for_testing() を使わないと caplog でキャプチャできない
+
+```python
+# conftest.py に必須
+from nene2.log import configure_for_testing
+configure_for_testing()
+```
+
+この設定を忘れると `caplog` で nene2 のログがキャプチャできず、
+「テストしてるのにログが出ない」という混乱を招く。
+ドキュメントへの明示が必要。
+
+---
+
+## テスト結果（全14件パス）
+
+```
+test_request_received_logged            PASSED
+test_request_completed_logged           PASSED
+test_method_and_path_in_log             PASSED
+test_status_code_in_completed_log       PASSED
+test_duration_in_completed_log          PASSED
+test_extra_context_in_log               PASSED
+test_health_not_logged                  PASSED
+test_request_body_not_in_log            PASSED
+test_request_query_params_in_nene2_log  PASSED  # nene2はクエリを含まない ✅
+test_error_request_still_logged         PASSED
+test_error_request_has_status_500       PASSED
+test_friction_no_request_body_logging_api  PASSED
+test_friction_no_response_body_logging  PASSED
+test_friction_no_user_id_in_log_without_custom_context  PASSED
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F79-1 | extra_context が静的のみ — リクエストごとの動的コンテキスト（user_id等）が追加できない | 中 |
+| F79-2 | デバッグ用のリクエストボディログ方法がない | 低 |
+| F79-3 | configure_for_testing() 未設定だと caplog でログがキャプチャできない | 中 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★★★
+
+`setup_middlewares(app)` で自動的にリクエストログが有効になるのは非常に快適。
+`extra_context` で追加フィールドを注入できる設計もわかりやすい。
+`exclude_paths` でヘルスチェックを除外できるのも実務的。
+
+### 実害の深刻さ ★★☆☆☆
+
+機密情報をログしないデフォルト設計は本番環境で非常に重要で、これは大きな強み。
+`configure_for_testing()` の存在を知らないと pytest で詰まるが、
+ドキュメントに追記すれば解決する軽い問題。
+
+### 修正のしやすさ ★★★★☆
+
+動的コンテキストの追加は `context_extractor` コールバックを追加すれば実現できる。
+実装は `dispatch()` 内で `context_extractor(request)` を呼んで結果を `bind_contextvars()` に渡すだけ。
+
+### 総合コメント
+
+RequestLoggingMiddleware は実用的でセキュリティ設計も適切。
+`configure_for_testing()` のドキュメント強化と、
+`context_extractor` パラメーターの追加でさらに実用性が高まる。
+全体的に「使っていて気持ちいい」ミドルウェア。
+
+---
+
+## 推奨アクション
+
+1. **Issue**: `RequestLoggingMiddleware` に `context_extractor` コールバックパラメーターを追加
+2. **Issue**: `configure_for_testing()` の使い方を README のテストセクションに追記

{nene2_python-1.8.23 → nene2_python-1.8.25}/pyproject.toml

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

{nene2_python-1.8.23 → nene2_python-1.8.25}/src/nene2/middleware/request_logging.py

@@ -1,6 +1,8 @@
 """Request logging middleware using structlog."""
 
+import contextlib
 import time
+from collections.abc import Callable
 
 import structlog
 from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
@@ -20,6 +22,21 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
             Useful for high-frequency health-check endpoints where log noise is unwanted.
         extra_context: Additional key-value pairs bound to every request log entry
             (e.g. ``{"service": "my-api", "version": "1.0.0"}``).
+        context_extractor: Optional callable ``(request) -> dict[str, str]`` that
+            returns per-request dynamic context (e.g. user ID from JWT, tenant ID).
+            The returned dict is merged into the log context for each request::
+
+                def get_log_context(request: Request) -> dict[str, str]:
+                    return {"user_id": request.headers.get("X-User-Id", "anonymous")}
+
+
+                app.add_middleware(
+                    RequestLoggingMiddleware,
+                    context_extractor=get_log_context,
+                )
+
+            If the extractor raises an exception, it is silently skipped so that
+            logging failures never break request handling.
     """
 
     def __init__(
@@ -27,10 +44,12 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
         app: object,
         exclude_paths: list[str] | None = None,
         extra_context: dict[str, str] | None = None,
+        context_extractor: Callable[[Request], dict[str, str]] | None = None,
     ) -> None:
         super().__init__(app)  # type: ignore[arg-type]
         self._exclude_paths = set(exclude_paths or [])
         self._extra_context: dict[str, str] = extra_context or {}
+        self._context_extractor = context_extractor
 
     async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
         if request.url.path in self._exclude_paths:
@@ -38,11 +57,16 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
 
         start = time.perf_counter()
         structlog.contextvars.clear_contextvars()
+        dynamic_context: dict[str, str] = {}
+        if self._context_extractor is not None:
+            with contextlib.suppress(Exception):
+                dynamic_context = self._context_extractor(request)
         structlog.contextvars.bind_contextvars(
             request_id=request_id_var.get(),
             method=request.method,
             path=request.url.path,
             **self._extra_context,
+            **dynamic_context,
         )
         logger.info("request.received")
         response = await call_next(request)

{nene2_python-1.8.23 → nene2_python-1.8.25}/src/nene2/middleware/setup.py

@@ -90,6 +90,12 @@ def setup_middlewares(
         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.
+
+            .. warning::
+                ``ThrottleMiddleware`` uses an in-memory counter that is **not
+                shared across workers or pods**.  Multi-process deployments will
+                see an effective limit of ``throttle_limit × worker_count``.
+                See :class:`ThrottleMiddleware` for details.
         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.

{nene2_python-1.8.23 → nene2_python-1.8.25}/src/nene2/middleware/throttle.py

@@ -55,6 +55,20 @@ class ThrottleMiddleware(BaseHTTPMiddleware):
     Path-limited endpoints are tracked independently from the global counter
     (the key includes the path, so ``/api/expensive`` quota is separate from
     the default quota for other paths).
+
+    .. warning:: **Single-process only.**
+        Counters are stored in an in-memory dict.  When running multiple
+        uvicorn workers (e.g. ``gunicorn -w 4``) or multiple containers,
+        each process maintains its own counter, so the effective rate limit
+        is ``limit × worker_count``.  For multi-process deployments, enforce
+        rate limits at the reverse proxy (nginx, Caddy) or use a shared
+        store (Redis).
+
+    .. note:: **Fixed-window burst at boundaries.**
+        Fixed-window counting can pass up to ``2 × limit`` requests in a
+        short burst when requests arrive just before and just after a window
+        boundary.  If you need protection against burst traffic, consider
+        sliding-window rate limiting at the proxy layer.
     """
 
     def __init__(

{nene2_python-1.8.23 → nene2_python-1.8.25}/tests/nene2/middleware/test_request_logging.py

@@ -95,3 +95,81 @@ def test_exclude_paths_passes_requests_through() -> None:
     client = TestClient(app)
     assert client.get("/health").status_code == 200
     assert client.get("/items").status_code == 200
+
+
+def test_context_extractor_adds_dynamic_context() -> None:
+    """context_extractor が返した値がログコンテキストに含まれる。"""
+    captured: list[dict] = []
+    app = FastAPI()
+    app.add_middleware(
+        RequestLoggingMiddleware,
+        context_extractor=lambda req: {"user_id": req.headers.get("X-User-Id", "anon")},
+    )
+    app.add_middleware(RequestIdMiddleware)
+
+    @app.get("/ping")
+    async def ping() -> JSONResponse:
+        captured.append(dict(structlog.contextvars.get_contextvars()))
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    client.get("/ping", headers={"X-User-Id": "user-42"})
+    assert captured[0]["user_id"] == "user-42"
+
+
+def test_context_extractor_default_is_none() -> None:
+    """context_extractor を省略した場合は従来通り動作する。"""
+    captured: list[dict] = []
+    app = FastAPI()
+    app.add_middleware(RequestLoggingMiddleware)
+    app.add_middleware(RequestIdMiddleware)
+
+    @app.get("/ping")
+    async def ping() -> JSONResponse:
+        captured.append(dict(structlog.contextvars.get_contextvars()))
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    client.get("/ping")
+    assert "user_id" not in captured[0]
+
+
+def test_context_extractor_exception_is_silently_skipped() -> None:
+    """context_extractor が例外を投げてもリクエスト処理が続行される。"""
+    app = FastAPI()
+
+    def _exploding_extractor(req: object) -> dict[str, str]:
+        raise RuntimeError("extractor failure")
+
+    app.add_middleware(RequestLoggingMiddleware, context_extractor=_exploding_extractor)
+    app.add_middleware(RequestIdMiddleware)
+
+    @app.get("/ping")
+    async def ping() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app, raise_server_exceptions=False)
+    r = client.get("/ping")
+    assert r.status_code == 200  # ログの失敗がリクエスト処理を壊さない
+
+
+def test_context_extractor_merges_with_extra_context() -> None:
+    """context_extractor と extra_context が両方指定されても正しくマージされる。"""
+    captured: list[dict] = []
+    app = FastAPI()
+    app.add_middleware(
+        RequestLoggingMiddleware,
+        extra_context={"service": "my-api"},
+        context_extractor=lambda req: {"user_id": "user-1"},
+    )
+    app.add_middleware(RequestIdMiddleware)
+
+    @app.get("/ping")
+    async def ping() -> JSONResponse:
+        captured.append(dict(structlog.contextvars.get_contextvars()))
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    client.get("/ping")
+    assert captured[0]["service"] == "my-api"
+    assert captured[0]["user_id"] == "user-1"

{nene2_python-1.8.23 → nene2_python-1.8.25}/uv.lock

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