nene2-python 1.8.27__tar.gz → 1.8.29__tar.gz

{nene2_python-1.8.27 → nene2_python-1.8.29}/CHANGELOG.md

@@ -5,6 +5,31 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.28] — 2026-05-20
+
+FT83 フィールドトライアル — Depends() DI パターン検証と PaginationResponse / PaginationDep 改善。
+
+### Added
+- `PaginationResponse.model_dump()` を `to_dict()` の Pydantic 互換エイリアスとして追加 (#355) (FT83)
+  — Pydantic v2 ユーザーが `model_dump()` を期待して AttributeError になる問題を解消
+- `PaginationDep` 型エイリアスを `nene2.http` に追加 (#355) (FT83)
+  — `Annotated[PaginationQueryParser, Depends(PaginationQueryParser)]` の省略形
+- Field trial report: `docs/field-trials/2026-05-field-trial-83.md` (FT83)
+
+---
+
+## [1.8.27] — 2026-05-20
+
+FT81 フィールドトライアル — CORS 設定パターン検証と setup_middlewares() への CORS 統合。
+
+### Added
+- `setup_middlewares()` に `cors_allowed_origins` / `cors_allow_credentials` / `cors_allow_methods` / `cors_allow_headers` パラメーターを追加 (#348) (FT81)
+  — `CORSMiddleware` を最外側に自動配置し、OPTIONS プリフライトが確実に処理される
+  — `cors_allowed_origins=["*"]` を渡すと `ValueError` を raise（wildcard 禁止ポリシーの実装強制）
+- Field trial report: `docs/field-trials/2026-05-field-trial-81.md` (FT81)
+
+---
+
 ## [1.8.26] — 2026-05-20
 
 FT80 フィールドトライアル — LocalMcpServer + HttpxMcpClient MCP E2E 検証と list_tools() 追加。

{nene2_python-1.8.27 → nene2_python-1.8.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.27
+Version: 1.8.29
 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.29/docs/field-trials/2026-05-field-trial-82.md

@@ -0,0 +1,198 @@
+# FT82: Background Tasks — FastAPI BackgroundTasks と nene2 の組み合わせ
+
+**日付**: 2026-05-20  
+**テーマ**: FastAPI BackgroundTasks を nene2 アーキテクチャと組み合わせた際の動作とパターン検証  
+**バージョン**: v1.8.27  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft82-background-tasks/`
+
+---
+
+## 概要
+
+FastAPI の `BackgroundTasks` は「レスポンス返却後に処理を実行する」仕組みで、
+メール送信・在庫更新・監査ログなどのユースケースに使う。
+nene2 のミドルウェアスタック（`setup_middlewares()`）との共存、
+例外ハンドリングの限界、UseCase への注入パターンを検証した。
+
+---
+
+## 実装パターン
+
+### 基本パターン（ハンドラーで BackgroundTasks を受け取る）
+
+```python
+from fastapi import BackgroundTasks
+
+@app.post("/orders")
+def create_order(body: OrderBody, background_tasks: BackgroundTasks) -> JSONResponse:
+    output = use_case.execute(CreateOrderInput(item=body.item, quantity=body.quantity))
+    # レスポンス送信後にバックグラウンドで実行される
+    background_tasks.add_task(send_order_confirmation, output.order_id, output.item)
+    background_tasks.add_task(update_inventory, output.item, output.quantity)
+    return JSONResponse({...}, status_code=201)
+```
+
+### UseCase を注入可能にするパターン（テスト用ファクトリー）
+
+```python
+def create_app_with_use_case(
+    create_order_fn: Callable[[CreateOrderInput], CreateOrderOutput]
+) -> FastAPI:
+    factory_app = FastAPI()
+    setup_middlewares(factory_app)
+
+    @factory_app.post("/orders")
+    def _create_order(body: OrderBody, background_tasks: BackgroundTasks) -> JSONResponse:
+        output = create_order_fn(...)
+        background_tasks.add_task(send_order_confirmation, output.order_id, output.item)
+        return JSONResponse({...}, status_code=201)
+
+    return factory_app
+
+# テストでの使用
+injected_app = create_app_with_use_case(lambda _: mock_output)
+```
+
+---
+
+## 発見した問題
+
+### 問題1: バックグラウンドタスクの例外がクライアントに見えない
+
+```python
+# バックグラウンドタスクが例外を投げても...
+def send_email(order_id: int) -> None:
+    raise SMTPConnectionError("Mail server down")
+
+@app.post("/orders")
+def create_order(body: OrderBody, background_tasks: BackgroundTasks) -> JSONResponse:
+    output = use_case.execute(...)
+    background_tasks.add_task(send_email, output.order_id)
+    return JSONResponse({...}, status_code=201)  # ← 201 が返る
+
+# クライアントには 201 が届く（メール失敗は見えない）
+```
+
+FastAPI の設計上、レスポンスはすでに送信済みのため
+バックグラウンドタスクのエラーを HTTP レスポンスコードで伝えられない。
+エラーはサーバーログに記録されるが、クライアントには `201 Created` が届く。
+
+### 問題2: nene2 に BackgroundTasks 推奨パターンがない
+
+```python
+# UseCase にどうやって BackgroundTasks を渡すか、ドキュメントがない
+
+# ❌ UseCase の中で直接 BackgroundTasks を使う（アーキテクチャ違反）
+class CreateOrderUseCase:
+    def execute(self, input_: CreateOrderInput, bg: BackgroundTasks) -> CreateOrderOutput:
+        ...
+        bg.add_task(send_email, ...)  # UseCase が HTTP 境界に依存してしまう
+
+# ✅ ハンドラー層で BackgroundTasks を使い、UseCase は純粋に保つ
+@app.post("/orders")
+def create_order(body: OrderBody, background_tasks: BackgroundTasks) -> JSONResponse:
+    output = use_case.execute(CreateOrderInput(...))  # UseCase はクリーン
+    background_tasks.add_task(send_email, output.order_id)  # ハンドラー層で副作用
+    return JSONResponse({...})
+```
+
+正しいパターン（UseCase を純粋に保ちハンドラー層で BackgroundTasks を使う）が
+nene2 のドキュメントに記載されていない。
+
+### 問題3: バックグラウンドタスクの実行確認ができない
+
+```python
+# 「タスクをキューした」ことと「タスクが成功した」ことを HTTP で区別できない
+r = client.post("/orders/1/alert")
+# レスポンスは {"queued": True} — 成功したかどうかはわからない
+```
+
+本番運用では Celery・ARQ・FastAPI Scheduler などの外部ジョブキューが必要。
+「BackgroundTasks は軽量な one-shot 処理向け」という点がドキュメントに不足。
+
+---
+
+## テスト結果（全16件パス）
+
+```
+test_create_order_returns_201                              PASSED
+test_get_order_returns_200                                 PASSED
+test_get_nonexistent_order_returns_404                     PASSED
+test_background_tasks_execute_after_response               PASSED  # TestClient は同期実行
+test_multiple_background_tasks_all_execute                 PASSED
+test_background_task_with_alert                            PASSED
+test_background_task_not_queued_on_404                     PASSED  # 404 ではタスク未実行
+test_failing_background_task_does_not_affect_response      PASSED  # 例外 → 200 のまま
+test_failing_background_task_started                       PASSED
+test_request_id_present_with_background_tasks              PASSED  # nene2 と共存
+test_security_headers_present_with_background_tasks        PASSED  # nene2 と共存
+test_validation_error_does_not_queue_background_tasks      PASSED  # 422 では未実行
+test_injectable_use_case_pattern                           PASSED  # DI パターン動作
+test_friction_background_exception_not_visible_to_client   PASSED  # 摩擦記録
+test_friction_no_nene2_background_task_pattern             PASSED  # 摩擦記録
+test_friction_background_task_cannot_return_result         PASSED  # 摩擦記録
+```
+
+---
+
+## 重要な発見: TestClient はバックグラウンドタスクを同期実行する
+
+```python
+client = TestClient(app)
+r = client.post("/orders", json={"item": "Widget", "quantity": 1})
+# TestClient はレスポンスを返す前にバックグラウンドタスクも実行する
+assert "confirmation:order_1:Widget" in notification_log  # ✅ すでに実行済み
+```
+
+`TestClient` はバックグラウンドタスクをリクエスト完了前に同期的に実行するため、
+テストでは `background_tasks.add_task()` で追加した処理を即座に検証できる。
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F82-1 | バックグラウンドタスクの例外がクライアントに見えない（FastAPI 設計上の制約） | 中 |
+| F82-2 | nene2 に BackgroundTasks 推奨パターン（UseCase との分離）のドキュメントがない | 低 |
+| F82-3 | バックグラウンドタスクは result を返せない（外部キューが必要） | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★★☆
+
+`background_tasks.add_task(fn, arg1, arg2)` は非常にシンプルで直感的。
+FastAPI のドキュメントを読めば即座に使える。
+nene2 のミドルウェアスタックとの共存も問題なし。
+
+### 実害の深刻さ ★★☆☆☆
+
+バックグラウンド例外がクライアントに見えない問題は、
+軽量な通知タスク（メール送信）であれば許容範囲。
+ただし「注文確定」のような業務的に重要な処理を
+バックグラウンドタスクに入れるのは設計ミス — そこは UseCase に残すべき。
+
+### 修正のしやすさ ★★★★★
+
+必要なのはドキュメントのみ:
+- UseCase はクリーンに保つ（BackgroundTasks を引数に取らない）
+- ハンドラー層でのみ `background_tasks.add_task()` を呼ぶ
+- 失敗して困る処理はバックグラウンドタスクに入れない
+- TestClient はバックグラウンドタスクを同期実行する（テスト性良好）
+
+### 総合コメント
+
+FastAPI の `BackgroundTasks` は nene2 と相性が良く、
+`setup_middlewares()` のミドルウェアスタックとも完全に共存する。
+X-Request-Id・セキュリティヘッダーも正常に付与される。
+摩擦の大部分は「どう使うべきか」のドキュメント不足であり、
+フレームワークの改修は不要。
+
+---
+
+## 推奨アクション
+
+1. **docs**: BackgroundTasks パターン（UseCase との分離、TestClient の同期実行）を how-to ガイドに追加
+2. **minor**: BackgroundTasks は「失敗しても OK な副作用のみ」というガイドラインの明記

nene2_python-1.8.29/docs/field-trials/2026-05-field-trial-83.md

@@ -0,0 +1,223 @@
+# FT83: Depends() DI — FastAPI Depends を nene2 アーキテクチャで活用するパターン検証
+
+**日付**: 2026-05-20  
+**テーマ**: UseCase・認証・Pagination の Depends 組み合わせパターンと dependency_overrides  
+**バージョン**: v1.8.27  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft83-depends-injection/`
+
+---
+
+## 概要
+
+FastAPI の `Depends()` を nene2 の UseCase + Repository パターンと組み合わせた。
+依存チェーン（Repository → UseCase → Handler）、認証 Depends、
+`PaginationQueryParser` の統合、テスト時の `dependency_overrides` による差し替えを検証した。
+`PaginationResponse.model_dump()` が存在しない（`to_dict()` が正しい）という
+Pydantic ユーザーがつまずく摩擦点を発見した。
+
+---
+
+## 実装パターン
+
+### Repository → UseCase の Depends チェーン
+
+```python
+from typing import Annotated
+from fastapi import Depends
+
+def get_repo() -> InMemoryProductRepository:
+    return _repo  # シングルトン
+
+def get_list_use_case(
+    repo: Annotated[InMemoryProductRepository, Depends(get_repo)],
+) -> ListProductsUseCase:
+    return ListProductsUseCase(repo)
+
+@app.get("/products")
+def list_products(
+    use_case: Annotated[ListProductsUseCase, Depends(get_list_use_case)],
+) -> JSONResponse:
+    products, total = use_case.execute(...)
+    return JSONResponse(...)
+```
+
+### PaginationQueryParser + UseCase の両方を Depends
+
+```python
+@app.get("/products")
+def list_products(
+    pagination: Annotated[PaginationQueryParser, Depends(PaginationQueryParser)],
+    use_case: Annotated[ListProductsUseCase, Depends(get_list_use_case)],
+) -> JSONResponse:
+    products, total = use_case.execute(
+        limit=pagination.limit, offset=pagination.offset
+    )
+    return JSONResponse(
+        PaginationResponse(
+            items=[...], total=total, limit=pagination.limit, offset=pagination.offset
+        ).to_dict()  # ← model_dump() ではなく to_dict()
+    )
+```
+
+### 認証 Depends（Bearer Token）
+
+```python
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+security = HTTPBearer(auto_error=False)
+
+def get_current_user(
+    credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(security)],
+) -> str | None:
+    if credentials is None:
+        return None
+    return verify_token(credentials.credentials)
+
+def require_auth(user: Annotated[str | None, Depends(get_current_user)]) -> str:
+    if user is None:
+        raise HTTPException(status_code=401)
+    return user
+
+@app.post("/products")
+def create_product(
+    body: ProductBody,
+    use_case: Annotated[CreateProductUseCase, Depends(get_create_use_case)],
+    current_user: Annotated[str, Depends(require_auth)],
+) -> JSONResponse: ...
+```
+
+### テスト時の dependency_overrides
+
+```python
+custom_repo = InMemoryProductRepository()
+custom_repo.create("Test Product", 100)
+
+app.dependency_overrides[get_repo] = lambda: custom_repo
+# テスト実行
+del app.dependency_overrides[get_repo]  # クリーンアップ
+```
+
+---
+
+## 発見した問題
+
+### 問題1: PaginationResponse.model_dump() が存在しない
+
+```python
+# ❌ Pydantic ユーザーは model_dump() を期待してしまう
+PaginationResponse(...).model_dump()  # AttributeError!
+
+# ✅ 正しいメソッド
+PaginationResponse(...).to_dict()
+```
+
+`PaginationResponse` は dataclass だが、Pydantic v2 に慣れているユーザーは
+`model_dump()` を期待して AttributeError に直面する。
+FastAPI の OpenAPI ドキュメントや response_model を使うには
+Pydantic BaseModel にするか、FastAPI の Response 型として登録する必要がある。
+
+### 問題2: Annotated[T, Depends(fn)] の記述が冗長
+
+```python
+# 現在の書き方（型情報が Annotated の外側と内側に重複）
+def list_products(
+    pagination: Annotated[PaginationQueryParser, Depends(PaginationQueryParser)],
+    use_case: Annotated[ListProductsUseCase, Depends(get_list_use_case)],
+) -> JSONResponse: ...
+
+# 理想（nene2 が型エイリアスを提供）
+type PaginationDep = Annotated[PaginationQueryParser, Depends(PaginationQueryParser)]
+
+@app.get("/products")
+def list_products(pagination: PaginationDep, ...) -> JSONResponse: ...
+```
+
+`PaginationQueryParser` の `Annotated` エイリアスを nene2 が提供すれば
+毎回書く冗長さが解消される。
+
+### 問題3: nene2 の認証 Depends ユーティリティがない
+
+```python
+# nene2.auth に Depends ユーティリティがない
+# ユーザーは HTTPBearer + LocalTokenVerifier を手動で組み合わせる必要がある
+
+# 理想:
+from nene2.auth.deps import CurrentUser, require_auth
+# これが存在しない
+```
+
+`LocalTokenVerifier.from_env()` は実装されているが、
+FastAPI の Depends パターンに接続する `CurrentUser` 型や
+`require_auth` Depends がない。
+
+---
+
+## テスト結果（全16件パス）
+
+```
+test_list_products_empty                        PASSED
+test_create_product_returns_201                  PASSED
+test_get_product_returns_200                     PASSED
+test_get_nonexistent_returns_404                 PASSED
+test_create_product_requires_auth                PASSED
+test_create_product_with_auth_succeeds           PASSED
+test_pagination_with_depends                     PASSED  # PaginationQueryParser Depends 動作
+test_pagination_second_page                      PASSED
+test_override_repo_with_custom_data              PASSED  # dependency_overrides 動作
+test_override_repo_empty                         PASSED
+test_request_id_with_depends                     PASSED  # nene2 ミドルウェアと共存
+test_security_headers_with_depends               PASSED
+test_validation_error_returns_422                PASSED
+test_friction_annotated_syntax_verbosity         PASSED  # 摩擦記録
+test_friction_use_case_chains_in_depends         PASSED  # 摩擦記録
+test_friction_no_nene2_depends_utilities         PASSED  # 摩擦記録
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F83-1 | `PaginationResponse.model_dump()` が存在しない（`to_dict()` が正しい）— Pydantic ユーザー混乱 | 中 |
+| F83-2 | `Annotated[PaginationQueryParser, Depends(PaginationQueryParser)]` の冗長記述 | 低 |
+| F83-3 | nene2 認証の Depends ユーティリティ (`CurrentUser`, `require_auth`) がない | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★☆☆
+
+`Depends()` のパターン自体は FastAPI の機能なので明確。
+ただし Repository → UseCase → Handler の3層チェーンは
+Spring/NestJS の DI に慣れたユーザーには違和感がある
+（Constructor Injection ではなく Function Injection）。
+`dependency_overrides` によるテスト差し替えは非常に優れた機能。
+
+### 実害の深刻さ ★★☆☆☆
+
+`PaginationResponse.to_dict()` を知らなければ AttributeError で即座に詰まる。
+nene2 ドキュメントに `PaginationResponse` の使い方が記載されているが、
+`model_dump()` と混同するユーザーが続出する可能性がある。
+
+### 修正のしやすさ ★★★★★
+
+- `PaginationResponse` に `model_dump()` の alias を追加（または別名で明記）
+- `Annotated[PaginationQueryParser, Depends(PaginationQueryParser)]` を `PaginationDep` 型エイリアスとして公開
+- `nene2.auth.deps` モジュールに `CurrentUser` 型と `require_auth` Depends を追加
+
+### 総合コメント
+
+FastAPI の `Depends()` は nene2 のアーキテクチャと非常に相性がよく、
+Repository の差し替えも `dependency_overrides` で簡単にできる。
+主な摩擦は `PaginationResponse.to_dict()` の名前（Pydantic との不整合）と
+認証 Depends ユーティリティの欠如。どちらも小さな追加で解決できる。
+
+---
+
+## 推奨アクション
+
+1. **Issue**: `PaginationResponse` に `model_dump()` エイリアスを追加（Pydantic ユーザー向け）
+2. **Issue**: `nene2.http` に `PaginationDep` 型エイリアスを追加（`PaginationQueryParser` の Depends）
+3. **Issue**: `nene2.auth.deps` モジュールに認証 Depends ユーティリティを追加

nene2_python-1.8.29/docs/field-trials/2026-05-field-trial-84.md

@@ -0,0 +1,151 @@
+# FT84: 認証 Depends ユーティリティ — CurrentUser / require_auth パターン検証
+
+**日付**: 2026-05-20  
+**テーマ**: nene2.auth に認証 Depends ユーティリティがない摩擦点と make_require_auth 設計検証  
+**バージョン**: v1.8.28  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft84-auth-depends/`
+
+---
+
+## 概要
+
+`LocalTokenVerifier` と `TokenVerifierProtocol` は実装されているが、
+FastAPI の Depends パターンに接続するユーティリティがない。
+ユーザーは `HTTPBearer` → `verify()` → 未認証 401 を毎プロジェクトで手組みする必要がある。
+`make_require_auth(verifier)` ファクトリーを追加することで解消できる。
+
+---
+
+## 発見した問題
+
+### 問題1: 認証 Depends を毎回手組みする必要がある
+
+```python
+# 現状: プロジェクトごとに以下のコードを書く必要がある (50+ 行のボイラープレート)
+
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from nene2.auth import LocalTokenVerifier
+
+security = HTTPBearer(auto_error=False)
+_verifier = LocalTokenVerifier.from_env("BEARER_TOKENS")
+
+def get_current_user(
+    credentials: HTTPAuthorizationCredentials | None = Depends(security),
+) -> str | None:
+    if credentials is None:
+        return None
+    if not _verifier.verify(credentials.credentials):
+        return None
+    return credentials.credentials
+
+def require_auth(user: str | None = Depends(get_current_user)) -> str:
+    if user is None:
+        raise HTTPException(status_code=401)
+    return user
+
+# ハンドラーで使う
+@app.post("/items")
+def create(body: ItemBody, user: str = Depends(require_auth)) -> JSONResponse: ...
+```
+
+### 問題2: 任意認証パターンが冗長
+
+```python
+# 未認証でも通るが user を取得したいパターン
+def optional_auth(user: str | None = Depends(get_current_user)) -> str | None:
+    return user  # None = 未認証、str = ユーザーID
+
+@app.get("/feed")
+def get_feed(user: str | None = Depends(optional_auth)) -> JSONResponse:
+    if user:
+        return JSONResponse({"personalized": True})
+    return JSONResponse({"personalized": False})
+```
+
+### 問題3: TokenVerifierProtocol を Depends で直接使えない
+
+```python
+# こういう書き方をしたくなるが Depends は callable を期待する
+@app.post("/items")
+def create(
+    body: ItemBody,
+    token: Annotated[str, Depends(LocalTokenVerifier.from_env("TOKENS"))],  # ← 機能しない
+) -> JSONResponse: ...
+```
+
+---
+
+## テスト結果（全12件パス）
+
+```
+test_public_endpoint_no_auth                     PASSED
+test_create_item_with_valid_token                PASSED
+test_create_item_without_token_returns_401       PASSED
+test_create_item_with_invalid_token_returns_401  PASSED
+test_get_me_returns_user_info                    PASSED
+test_delete_item_authenticated                   PASSED
+test_delete_item_unauthenticated_returns_401     PASSED
+test_request_id_present_on_401                  PASSED  # nene2 ミドルウェアと共存
+test_security_headers_present_on_401            PASSED  # nene2 ミドルウェアと共存
+test_friction_boilerplate_for_auth_depends       PASSED  # 摩擦記録
+test_friction_optional_auth_pattern_verbose      PASSED  # 摩擦記録
+test_friction_verifier_not_injectable_as_depends PASSED  # 摩擦記録
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F84-1 | 認証 Depends ボイラープレートを毎プロジェクトで手組みする必要がある | 中 |
+| F84-2 | 任意認証（Optional User）パターンが冗長 | 低 |
+| F84-3 | `TokenVerifierProtocol` を Depends で直接使えない | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★☆☆☆
+
+「nene2 でトークン認証を追加する」という操作に必要なステップが多すぎる。
+`BearerTokenMiddleware` は全経路に認証を入れるには便利だが、
+「このエンドポイントだけ認証を要求」パターンに Depends ユーティリティがない。
+FastAPI の HTTPBearer を使う方法は FastAPI のドキュメントを参照しなければわからない。
+
+### 実害の深刻さ ★★★☆☆
+
+認証は多くのプロジェクトで必要。毎回 50 行のボイラープレートを書くのは
+DRY 原則に反する。バグが入りやすく、テスト漏れにもつながる。
+
+### 修正のしやすさ ★★★★★
+
+`make_require_auth(verifier)` 関数を `nene2.auth` に追加するだけ:
+
+```python
+def make_require_auth(verifier: TokenVerifierProtocol) -> Callable[..., str]:
+    security = HTTPBearer(auto_error=False)
+    def get_current_user(credentials: ... = Depends(security)) -> str | None:
+        if credentials is None or not verifier.verify(credentials.credentials):
+            return None
+        return credentials.credentials
+    def require_auth(user: str | None = Depends(get_current_user)) -> str:
+        if user is None:
+            raise HTTPException(status_code=401)
+        return user
+    return require_auth
+```
+
+### 総合コメント
+
+nene2 の認証機能は「ミドルウェアで全経路を保護する」ユースケースは
+`BearerTokenMiddleware` でカバーされている。
+不足しているのは「特定エンドポイントのみ認証を要求する」ユースケース。
+`make_require_auth()` を追加することで「nene2 だけで完結」できる。
+
+---
+
+## 推奨アクション
+
+1. **Issue #358**: `nene2.auth` に `make_require_auth(verifier)` ファクトリーを追加
+   — `require_auth = make_require_auth(LocalTokenVerifier.from_env("TOKENS"))` パターンを実現

{nene2_python-1.8.27 → nene2_python-1.8.29}/pyproject.toml

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

{nene2_python-1.8.27 → nene2_python-1.8.29}/src/nene2/auth/__init__.py

@@ -2,6 +2,7 @@
 
 from .api_key import ApiKeyAuthMiddleware
 from .bearer_token import BearerTokenMiddleware
+from .deps import make_require_auth
 from .exceptions import TokenVerificationException
 from .interfaces import TokenIssuerProtocol, TokenVerifierProtocol
 from .local_verifier import LocalTokenVerifier
@@ -13,4 +14,5 @@ __all__ = [
     "TokenIssuerProtocol",
     "TokenVerificationException",
     "TokenVerifierProtocol",
+    "make_require_auth",
 ]

nene2_python-1.8.29/src/nene2/auth/deps.py

@@ -0,0 +1,50 @@
+"""FastAPI Depends utilities for authentication.
+
+Provides ``make_require_auth`` to wire :class:`TokenVerifierProtocol` into
+FastAPI's dependency injection system without boilerplate.
+"""
+
+from collections.abc import Callable
+from typing import Annotated
+
+from fastapi import Depends, HTTPException
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from .interfaces import TokenVerifierProtocol
+
+_security = HTTPBearer(auto_error=False)
+
+
+def make_require_auth(verifier: TokenVerifierProtocol) -> Callable[..., str]:
+    """Return a FastAPI Depends-compatible callable that enforces token authentication.
+
+    Usage::
+
+        from nene2.auth import LocalTokenVerifier, make_require_auth
+
+        verifier = LocalTokenVerifier.from_env("BEARER_TOKENS")
+        require_auth = make_require_auth(verifier)
+
+
+        @app.post("/items")
+        def create_item(
+            body: ItemBody,
+            token: Annotated[str, Depends(require_auth)],
+        ) -> JSONResponse: ...
+
+    Args:
+        verifier: A :class:`TokenVerifierProtocol` implementation to validate tokens.
+
+    Returns:
+        A dependency function that returns the raw token string when authenticated,
+        or raises ``HTTP 401`` when the token is absent or invalid.
+    """
+
+    def _get_token(
+        credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(_security)],
+    ) -> str:
+        if credentials is None or not verifier.verify(credentials.credentials):
+            raise HTTPException(status_code=401, detail="Invalid or missing token")
+        return credentials.credentials
+
+    return _get_token