nene2-python 1.8.32__tar.gz → 1.8.33__tar.gz

{nene2_python-1.8.32 → nene2_python-1.8.33}/CHANGELOG.md

@@ -5,6 +5,19 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.33] — 2026-05-20
+
+FT100 フィールドトライアル — In-memory TTL レスポンスキャッシュパターン検証と nene2.cache モジュール追加。
+
+### Added
+- `nene2.cache` モジュールを新設 (#409) (FT100)
+  - `TtlCache[V]` — TTL 付きインメモリキャッシュ（ジェネリック型）
+  - `time.monotonic()` ベースの TTL で NTP 調整の影響を受けない
+  - `get()`, `set()`, `delete()`, `clear()`, `size()` API
+- Field trial report: `docs/field-trials/2026-05-field-trial-100.md` (FT100)
+
+---
+
 ## [1.8.32] — 2026-05-20
 
 FT99 フィールドトライアル — Webhook HMAC-SHA256 署名検証パターン検証と nene2.security モジュール追加。

{nene2_python-1.8.32 → nene2_python-1.8.33}/PKG-INFO

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

@@ -0,0 +1,62 @@
+# Field Trial 100: In-memory TTL レスポンスキャッシュ
+
+## テーマ
+
+重い処理の結果を TTL 付きインメモリキャッシュに格納し、重複リクエストにキャッシュから応答するパターンを nene2 上で実装する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft100-response-cache/` に以下を実装:
+
+- `TtlCache` データクラス（TTL 付き辞書）
+- FastAPI lifespan でキャッシュを初期化・破棄
+- `Depends(get_cache)` でハンドラーに注入
+- キャッシュヒット/ミス判定、TTL 失効テスト
+
+## テスト結果
+
+全 7 テスト通過。
+
+## Friction Points
+
+### FP1: nene2 に TTL キャッシュユーティリティがない
+
+**状況**: キャッシュは Web API の基本パターンだが、nene2 に `TtlCache` のようなユーティリティが存在しない。`TtlCache` を毎回自前実装する必要がある。
+
+**影響**: 開発者がスレッドセーフでないキャッシュを実装してしまうリスク。また asyncio 環境での並行アクセスの考慮が漏れやすい（Python GIL により dict 操作自体はアトミックだが、get-then-set パターンは競合する）。
+
+**期待する API**:
+```python
+from nene2.cache import TtlCache
+
+cache = TtlCache(ttl_seconds=60.0)
+cache.set("key", value)
+value = cache.get("key")  # None if expired
+```
+
+### FP2: lifespan + グローバル変数パターンに型エラーが出る
+
+**状況**: キャッシュを lifespan で初期化してグローバル変数に格納するパターンで、`async def lifespan(app: FastAPI)` の型注釈に `type: ignore[type-arg]` が必要。
+
+```python
+_cache: TtlCache | None = None
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):  # type: ignore[type-arg] が必要
+    global _cache
+    _cache = TtlCache(ttl_seconds=60.0)
+    yield
+```
+
+`app.state` を使うパターンの方がよりクリーンだが、`app.state` の型付けも `app.state.cache` のアクセスで `Any` になる。
+
+### FP3: `app.state` でのキャッシュ管理がドキュメント化されていない
+
+**状況**: `lifespan-and-app-state.md` では `app.state.db` の例はあるが、キャッシュを `app.state` に格納するパターン（`request.app.state.cache`）の説明がない。
+
+**影響**: グローバル変数を使う開発者が多く、テスト時のリセットが困難になる。
+
+## まとめ
+
+キャッシュユーティリティ追加は中程度の価値あり（FP1）。FP2・FP3 はドキュメント摩擦。
+今回は FP1 を `nene2.cache` モジュールとして実装し、Issue を起票する。

nene2_python-1.8.33/docs/how-to/webhook.md

@@ -0,0 +1,151 @@
+# How-to: Webhook 受信と HMAC-SHA256 署名検証
+
+GitHub や Stripe などの外部サービスから Webhook を受信し、HMAC-SHA256 署名を検証するパターンを説明する。
+
+---
+
+## 1. 基本パターン（GitHub 方式）
+
+GitHub は `X-Hub-Signature-256: sha256=<hex>` ヘッダーで署名を送る。
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from nene2.security import verify_hmac_signature
+
+WEBHOOK_SECRET = "your-secret-key"
+
+app = FastAPI()
+
+@app.post("/webhooks/github")
+async def github_webhook(request: Request) -> JSONResponse:
+    signature = request.headers.get("X-Hub-Signature-256", "")
+    body = await request.body()
+
+    if not signature:
+        return JSONResponse({"error": "Missing signature"}, status_code=400)
+
+    if not verify_hmac_signature(body, WEBHOOK_SECRET, signature, prefix="sha256="):
+        return JSONResponse({"error": "Invalid signature"}, status_code=401)
+
+    payload = await request.json()
+    event = request.headers.get("X-GitHub-Event", "unknown")
+    # ... イベント処理
+    return JSONResponse({"status": "received", "event": event})
+```
+
+---
+
+## 2. Stripe 方式（timestamp 付き署名）
+
+Stripe は `Stripe-Signature: t=<timestamp>,v1=<hex>` 形式で送る。timestamp + body を HMAC する。
+
+```python
+import hashlib
+import hmac
+import time
+
+@app.post("/webhooks/stripe")
+async def stripe_webhook(request: Request) -> JSONResponse:
+    stripe_sig = request.headers.get("Stripe-Signature", "")
+    body = await request.body()
+
+    if not stripe_sig:
+        return JSONResponse({"error": "Missing Stripe-Signature"}, status_code=400)
+
+    parts = dict(item.split("=", 1) for item in stripe_sig.split(",") if "=" in item)
+    timestamp = parts.get("t", "")
+    v1_sig = parts.get("v1", "")
+
+    # Stripe 方式: "timestamp." + body を HMAC する
+    signed_payload = f"{timestamp}.".encode() + body
+    if not verify_hmac_signature(signed_payload, WEBHOOK_SECRET, v1_sig):
+        return JSONResponse({"error": "Invalid signature"}, status_code=401)
+
+    payload = await request.json()
+    return JSONResponse({"status": "received", "type": payload.get("type")})
+```
+
+---
+
+## 3. `await request.body()` → `await request.json()` の二重読み取り
+
+署名検証では生バイト（`body()`）が必要だが、その後 JSON としてもパースしたい。
+FastAPI はボディを内部でキャッシュするので、両方呼び出せる。
+
+```python
+@app.post("/webhooks/example")
+async def handler(request: Request) -> JSONResponse:
+    # ✅ body() を先に呼んでも json() は正常に動く
+    body = await request.body()        # 生バイト取得（署名検証用）
+    payload = await request.json()     # JSON パース（内部キャッシュを使う）
+    return JSONResponse({"size": len(body), "action": payload.get("action")})
+```
+
+`json.loads(body)` でも動作するが、`await request.json()` の方が Pydantic モデル変換と統一感がある。
+
+---
+
+## 4. `verify_hmac_signature()` の API
+
+```python
+from nene2.security import verify_hmac_signature
+
+verify_hmac_signature(
+    body: bytes,       # 検証するバイト列
+    secret: str,       # 共有シークレット
+    signature: str,    # 検証対象の署名文字列（prefix 込み可）
+    *,
+    prefix: str = "",  # 署名の prefix（例: "sha256="）
+) -> bool
+```
+
+`hmac.compare_digest()` で timing attack 対策済み。署名の比較に `==` を使わないこと。
+
+---
+
+## 5. BearerTokenMiddleware との使い分け
+
+| パターン | 認証方法 | nene2 サポート |
+|---|---|---|
+| API クライアント認証 | `Authorization: Bearer <token>` | `BearerTokenMiddleware` |
+| Webhook 署名検証 | リクエストボディ + シークレット | `verify_hmac_signature()` |
+
+Webhook エンドポイントは `BearerTokenMiddleware` の `exclude_paths` に加えて、
+自前の署名検証を行う。ミドルウェアでは raw body を読む関係で `BearerTokenMiddleware` は使用できない。
+
+```python
+from nene2.middleware import BearerTokenMiddleware
+
+app.add_middleware(
+    BearerTokenMiddleware,
+    verifier=token_verifier,
+    exclude_paths=["/webhooks/"],  # Webhook エンドポイントを除外
+)
+```
+
+---
+
+## 6. テスト
+
+```python
+import hashlib
+import hmac
+
+def make_github_sig(body: bytes, secret: str) -> str:
+    return "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+
+def test_webhook_valid() -> None:
+    payload = b'{"action": "opened"}'
+    r = client.post(
+        "/webhooks/github",
+        content=payload,
+        headers={
+            "Content-Type": "application/json",
+            "X-Hub-Signature-256": make_github_sig(payload, "your-secret-key"),
+            "X-GitHub-Event": "issues",
+        },
+    )
+    assert r.status_code == 200
+```

{nene2_python-1.8.32 → nene2_python-1.8.33}/pyproject.toml

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

nene2_python-1.8.33/src/nene2/cache/__init__.py

@@ -0,0 +1,5 @@
+"""In-memory TTL キャッシュユーティリティ."""
+
+from .ttl import TtlCache
+
+__all__ = ["TtlCache"]

nene2_python-1.8.33/src/nene2/cache/ttl.py

@@ -0,0 +1,57 @@
+"""TTL 付きインメモリキャッシュ."""
+
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class _Entry[V]:
+    value: V
+    expires_at: float
+
+
+@dataclass
+class TtlCache[V]:
+    """TTL 付きインメモリキャッシュ。
+
+    asyncio コンテキストでの利用を想定。Python GIL により dict 操作は
+    アトミックで安全だが、get-then-set のような複合操作は排他しない。
+
+    Args:
+        ttl_seconds: キャッシュエントリの生存時間（秒）。
+
+    Example:
+        cache: TtlCache[dict[str, object]] = TtlCache(ttl_seconds=60.0)
+        cache.set("key", {"data": 42})
+        value = cache.get("key")
+    """
+
+    ttl_seconds: float
+    _store: dict[str, _Entry[V]] = field(default_factory=dict, init=False, repr=False)
+
+    def get(self, key: str) -> V | None:
+        """キーに対応する値を返す。TTL 切れの場合は None を返してエントリを削除する。"""
+        entry = self._store.get(key)
+        if entry is None:
+            return None
+        if time.monotonic() > entry.expires_at:
+            del self._store[key]
+            return None
+        return entry.value
+
+    def set(self, key: str, value: V) -> None:
+        """キーと値を TTL 付きで格納する。"""
+        self._store[key] = _Entry(value=value, expires_at=time.monotonic() + self.ttl_seconds)
+
+    def delete(self, key: str) -> None:
+        """キーに対応するエントリを削除する。存在しなくても例外は発生しない。"""
+        self._store.pop(key, None)
+
+    def clear(self) -> None:
+        """すべてのエントリを削除する。"""
+        self._store.clear()
+
+    def size(self) -> int:
+        """TTL 切れを除いた有効なエントリ数を返す。"""
+        now = time.monotonic()
+        return sum(1 for e in self._store.values() if e.expires_at > now)

nene2_python-1.8.33/tests/nene2/cache/test_ttl.py

@@ -0,0 +1,76 @@
+"""Tests for nene2.cache.TtlCache."""
+
+import time
+
+import pytest
+
+from nene2.cache import TtlCache
+
+
+def test_set_and_get_returns_value() -> None:
+    cache = TtlCache(ttl_seconds=60.0)
+    cache.set("key", {"data": 42})
+    assert cache.get("key") == {"data": 42}
+
+
+def test_get_missing_key_returns_none() -> None:
+    cache = TtlCache(ttl_seconds=60.0)
+    assert cache.get("nonexistent") is None
+
+
+def test_expired_entry_returns_none() -> None:
+    cache = TtlCache(ttl_seconds=0.01)
+    cache.set("key", "value")
+    time.sleep(0.02)
+    assert cache.get("key") is None
+
+
+def test_expired_entry_is_removed_from_store() -> None:
+    cache = TtlCache(ttl_seconds=0.01)
+    cache.set("key", "value")
+    time.sleep(0.02)
+    cache.get("key")  # TTL 切れでエントリ削除
+    assert cache.size() == 0
+
+
+def test_delete_removes_entry() -> None:
+    cache = TtlCache(ttl_seconds=60.0)
+    cache.set("key", "value")
+    cache.delete("key")
+    assert cache.get("key") is None
+
+
+def test_delete_missing_key_does_not_raise() -> None:
+    cache = TtlCache(ttl_seconds=60.0)
+    cache.delete("nonexistent")  # should not raise
+
+
+def test_clear_removes_all_entries() -> None:
+    cache = TtlCache(ttl_seconds=60.0)
+    cache.set("a", 1)
+    cache.set("b", 2)
+    cache.clear()
+    assert cache.size() == 0
+
+
+def test_size_excludes_expired_entries() -> None:
+    cache = TtlCache(ttl_seconds=0.01)
+    cache.set("expired", "value")
+    time.sleep(0.02)
+    cache.set("fresh", "value")
+    assert cache.size() == 1
+
+
+def test_overwrite_resets_ttl() -> None:
+    cache = TtlCache(ttl_seconds=60.0)
+    cache.set("key", "old")
+    cache.set("key", "new")
+    assert cache.get("key") == "new"
+
+
+@pytest.mark.parametrize("value", [None, 0, "", [], {}, False])
+def test_falsy_values_are_stored_correctly(value: object) -> None:
+    cache = TtlCache(ttl_seconds=60.0)
+    cache.set("key", value)
+    assert cache.get("key") == value
+    assert cache.size() == 1

{nene2_python-1.8.32 → nene2_python-1.8.33}/uv.lock

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