Metadata-Version: 2.5
Name: fastship-py
Version: 0.21.0
Summary: モジュラモノリス + DDD のカーネル。集約・ドメインイベント・UnitOfWork・トランザクショナル outbox/inbox を業務語彙ゼロで提供する
Project-URL: Homepage, https://github.com/theindiehacker/fastship-py
Project-URL: Repository, https://github.com/theindiehacker/fastship-py
Author-email: taiyo tamura <gtaiyou24@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ddd,hexagonal-architecture,modular-monolith,outbox,unit-of-work
Requires-Python: >=3.14
Requires-Dist: fastapi<1.0.0,>=0.143.1
Requires-Dist: injector<1.0.0,>=0.22.0
Requires-Dist: psycopg[binary]<4.0.0,>=3.3.6
Requires-Dist: pydantic-settings<3.0.0,>=2.14.2
Requires-Dist: pydantic<3.0.0,>=2.13.0
Requires-Dist: sqlalchemy<3.0.0,>=2.1.0
Requires-Dist: starlette<2.0.0,>=1.8.0
Provides-Extra: fastmcp
Requires-Dist: fastmcp<5.0.0,>=4.1.3; extra == 'fastmcp'
Requires-Dist: mcp<3.0.0,>=2.2.0; extra == 'fastmcp'
Provides-Extra: gcp
Requires-Dist: google-auth<3.0.0,>=2.62.0; extra == 'gcp'
Requires-Dist: google-cloud-pubsub<3.0.0,>=2.43.0; extra == 'gcp'
Requires-Dist: requests<3.0.0,>=2.34.2; extra == 'gcp'
Provides-Extra: linter
Requires-Dist: import-linter<3.0.0,>=2.14; extra == 'linter'
Description-Content-Type: text/markdown

# 🚀 fastship-py

```bash
# app.fastship.jp テンプレートから作ったリポジトリの backend/ (pyproject.toml のあるところ) で実行する
uv sync
```

DB は PostgreSQL、API は FastAPI を前提にしており、SQLAlchemy / psycopg / FastAPI も一緒に入る (extras の指定は要らない)。モジュールの足し方は、テンプレートの `backend/README.md` にある。

## ⚙️ 環境変数

インフラ (Cloud Run など) が注入し、アプリ側では設定しない (Secret Manager の値は、実行基盤で同名の環境変数として公開する)。使う部品の行だけを設定すればよい。

| 環境変数 | 使う部品 | 必須か | 内容 |
|:---|:---|:---|:---|
| `DATABASE_WRITER_URL` | SQLAlchemy | 必須 | プライマリの接続先 |
| `DATABASE_READER_URL` | SQLAlchemy | 任意 | リードレプリカ (Read Pool のエンドポイント)。未設定ならすべてプライマリへ送る |
| `NOTIFICATION_PUBLISH_TO` | outbox の中継 | 任意 | 通知を発行するトピック。既定は `notifications` |
| `GOOGLE_CLOUD_PROJECT` | Pub/Sub (`[gcp]`) | エミュレータでは必須 | トピックのあるプロジェクト。未設定なら ADC から引く |
| `PUBSUB_EMULATOR_HOST` | Pub/Sub (`[gcp]`) | ローカルだけ | エミュレータの `host:port`。設定すると ADC を引かない |
| `NOTIFICATION_PUBLISH_TRIGGER` | 通知の発行の依頼 | ローカルだけ | `local` にすると、Cloud Tasks を使わず、コミットの後にその場で発行する。既定は `cloud_tasks` |
| `NOTIFICATION_PUBLISH_QUEUE` | 通知の発行の依頼 (`[gcp]`) | `cloud_tasks` では必須 | タスクを投入する Cloud Tasks のキュー (`projects/〇〇/locations/〇〇/queues/〇〇`) |
| `DI_FOR_PY` | DI コンテナ | 任意 | 有効にするプロファイル (カンマ区切り)。テストで `InMem` にするなど |

## 📚 How To
### 🧩 既定のモジュール (Common)

`Common` を `CompositeModule` の先頭に並べると、カーネルの部品が DI コンテナに登録され、outbox / inbox のテーブルも Alembic に載る

```python
from fastship.common.core import Common
from fastship.common.module import CompositeModule


class Backend(CompositeModule):
    def __init__(self) -> None:
        super().__init__([Common(), 〇〇()])
```

| interface | 本番・ローカル | テスト (`DI_FOR_PY=InMem`) |
|:---|:---|:---|
| `UnitOfWork` | `SQLAlchemyUnitOfWork` | `InMemUnitOfWork` |
| `EventContextProvider` | `NullEventContextProvider` | 同左 |
| `EventStore` (outbox) | `PostgreSQLEventStore` | `InMemEventStore` |
| `Inbox` (処理済みの印) | `PostgreSQLInbox` | `InMemInbox` |
| `NotificationPublisher` (中継) | `NotificationPublisherImpl` | 同左 |
| `NotificationPublishTrigger` (発行の依頼) | `CloudTasksNotificationPublishTrigger` (`NOTIFICATION_PUBLISH_TRIGGER=local` では `LocalNotificationPublishTrigger`) | `NotificationPublishTriggerStub` (依頼した回数を数える) |
| `MessagePublisher` | `CloudPubSubPublisher` | `MessagePublisherStub` (発行した通知を記録する) |
| `MessageSubscriber` | `CloudPubSubSubscriber` | `MessageSubscriberStub` (Notification の JSON を listener に振り分ける) |

- ローカルは本番と同じ実装を使い、環境変数 (`DATABASE_WRITER_URL` / `PUBSUB_EMULATOR_HOST` など) をローカルの DB とエミュレータに向ける。発行の依頼だけは、Cloud Tasks にエミュレータが無いため `NOTIFICATION_PUBLISH_TRIGGER=local` で切り替える
- 実装は最初に使うときに作られる。InMem では DB や Pub/Sub の設定が要らない
- アダプタ (リポジトリ・ストアなど) は、`@inject` のコンストラクタで実装の型 (`SQLAlchemyUnitOfWork` / `InMemUnitOfWork`) を受け取る (`UnitOfWork` で受けて `isinstance` で絞らない)。`Common` は `SQLAlchemyUnitOfWork` と `InMemUnitOfWork` の鍵も登録し、`UnitOfWork` に登録したのと同じインスタンスを返す。`UnitOfWork` を別の実装に差し替えているときは `TypeError` になる
- `@transactional` の実体 (`ApplicationServiceLifeCycle`) と、中継・印の片付けのユースケース (`NotificationApplicationService`・`InboxApplicationService`) も `Common` が登録する
- `CompositeModule` は起動のときに、全モジュールの listener を DI に登録する (`ExchangeListeners`)。Worker の受け口 (`NotificationResource`) が `MessageSubscriber` に渡す
- Pub/Sub と Cloud Tasks の実装を使うには extras の `[gcp]` を入れる (「📤 Pub/Sub への発行」)。入れていなくても、`Common` の import と InMem での起動はできる

束縛を差し替えるときは、差し替えるモジュールを `Common` の後ろに並べる (後から登録した束縛が勝つ)

```python
class 〇〇(AppModule):
    @override
    async def startup(self) -> None:
        DIContainer.instance().register(
            DI.of(EventContextProvider, {}, TenantEventContextProvider),  # マルチテナントの場合
        )
```

### 🌐 API

<details><summary><b>🌐 モジュールの API を載せる</b></summary>

モジュールの `routers` に APIRouter を並べると、`CompositeModule` が全モジュールの `routers` を 1 つにまとめる (書かないモジュールは何も載せない)。

```python
from fastapi import APIRouter


class 〇〇(AppModule):
    @property
    @override
    def routers(self) -> list[APIRouter]:
        return [UserResource().router]
```

`api.py`:
```python
from fastapi import FastAPI
from fastship.common.port.adapter.resource import add_exception_handlers

from core import Backend  # 全モジュールを束ねた CompositeModule

backend = Backend()
app = FastAPI(lifespan=lifespan)  # lifespan で backend.startup() / backend.shutdown() を呼ぶ
add_exception_handlers(app)  # エラー応答を RFC 9457 にそろえる (「⚠️ エラー応答」)

for router in backend.routers:
    app.include_router(router)
```

- lifespan の中ではなく、`app` を作った直後に載せる (lifespan の外で呼ぶ `app.openapi()` にも載り、テストで lifespan を回してもルートが重複しない)
- `routers` は起動 (DI 登録) の前に呼ばれる。Resource のコンストラクタでは DI を解決せず、リクエストを処理するときに解決する
- `@transactional` のアプリケーションサービスを呼ぶルートは `def` で書く (FastAPI がスレッドで動かす)。`async def` から呼ぶと RuntimeError で断る

</details>

### 🤖 MCP

<details><summary><b>🤖 モジュールのツールを MCP サーバーに載せる</b></summary>

MCP サーバーは [FastMCP](https://gofastmcp.com) で立てる (fastmcp 4.1.3 で確かめた)。extras の `fastmcp` を付けて入れ、`fastmcp` 自体も直接の依存として宣言する (「🪄 lint の設定」)。
```bash
uv add 'fastship-py[fastmcp]' fastmcp
```

モジュールの `tools` に FastMCP の Tool を並べると、`CompositeModule` が全モジュールの `tools` を 1 つにまとめる (書かないモジュールは何も載せない)。
ツールの例外は、API と同じ方針で MCP のエラーに変わる (モジュールは何も付けなくてよい)。

```python
from fastmcp.tools import Tool


class UserTool:
    def register_user(self, email_address: str) -> UserOutput: ...


class 〇〇(AppModule):
    @property
    @override
    def tools(self) -> list[Tool]:
        tool = UserTool()
        return [Tool.from_function(tool.register_user, name="register_user", description="ユーザーを登録する")]
```

| ツールの中の例外 | ログ | モデルに返すもの |
|:--|:--|:--|
| FastMCP が扱う例外 (`ToolError` などの FastMCPError、MCPError、上流の 429・タイムアウト) | FastMCP が | FastMCP が決める (`ToolError` ならそのメッセージ) |
| `SystemException` | `logging()` (エラーコードの level) | エラーコードのメッセージ (detail は返さない) |
| `ValueError` / `AssertionError` (pydantic の検証エラーを含む) | COMMON_2000 (型と送出した場所だけ。pydantic はモデル名も) | 「不正なリクエストです」 |
| それ以外 | COMMON_1000 とトレースバック | 「想定外の原因エラーが発生しました」 |

例外の中身は、クライアントにも OTel のスパンにも残さない。

`mcp_server.py`:
```python
import os
from contextlib import asynccontextmanager

from fastapi import FastAPI
from fastmcp import FastMCP
from fastmcp.server.auth import RemoteAuthProvider
from fastmcp.server.auth.providers.jwt import JWTVerifier
from pydantic import AnyHttpUrl

from core import Backend  # 全モジュールを束ねた CompositeModule

backend = Backend()

host = os.environ["MCP_HOST"]  # この MCP サーバーを公開するホスト名 (例: mcp.example.com)
issuer = os.environ["MCP_AUTH_ISSUER"]  # IdP の issuer (例: https://example.us.auth0.com/)
# IdP が発行したアクセストークン (JWT) を検証する。トークンが無い・正しくないリクエストは 401 で断る。
# 認可サーバー (IdP) の場所を /.well-known/oauth-protected-resource で知らせ、MCP のクライアントにトークンを取らせる
auth = RemoteAuthProvider(
    token_verifier=JWTVerifier(
        jwks_uri=os.environ["MCP_AUTH_JWKS_URI"],
        issuer=issuer,
        audience=os.environ["MCP_AUTH_AUDIENCE"],
    ),
    authorization_servers=[AnyHttpUrl(issuer)],
    base_url=f"https://{host}",
)
# ToolError 以外の例外の中身 (SQL・入力値など) を、クライアントに返さない
mcp = FastMCP("app", tools=backend.tools, auth=auth, mask_error_details=True)
# 公開するホスト名と localhost 以外の Host、信頼しない Origin を断る (DNS rebinding を防ぐ)
mcp_app = mcp.http_app(stateless_http=True, json_response=True, host_origin_protection=True, allowed_hosts=[host])


@asynccontextmanager
async def lifespan(_: FastAPI):
    await backend.startup()  # DI 登録。呼ばないと、DI を解決するツールがすべて失敗する
    async with mcp_app.lifespan(mcp_app):  # mount したアプリの lifespan は動かないため、ここで動かす
        yield
    await backend.shutdown()


app = FastAPI(lifespan=lifespan)
app.mount("/", mcp_app)  # エンドポイントは /mcp
```

- この認証は、IdP が動的クライアント登録 (DCR) に対応している前提。対応していない IdP は、FastMCP の専用のプロバイダーを `auth=` に渡す (Cognito は `AWSCognitoProvider`、Identity Platform は `GoogleProvider`、Auth0 の Auth for MCP は `Auth0MCPProvider`)
- ツールの中では、検証済みのトークンを `fastmcp.server.dependencies.get_access_token()` で読む。IdP のユーザー ID は `claims["sub"]`
- `auth=` を外すのは、localhost だけで動かすときに限る。外したまま公開すると、書き込みのツールも誰でも呼べる
- ツール名は全モジュールで 1 つの名前空間 (重なると ValueError)。`name=` に ASCII (`[A-Za-z0-9_.-]`) で渡す (日本語の関数名のままだと、名前の形式を強制するクライアントに拒まれる)
- ツールは `Tool.from_function` で、関数かメソッドから作る (ほかの作り方は例外を変換できないため断る)
- ツールの引数・戻り値の型は実行時に import する (`TYPE_CHECKING` に移すと登録の時点で NameError)。ruff の TC001〜TC003 は、ツールのファイルでは外す (`per-file-ignores`)
- ツールは値を返す同期関数 (`def`) で書き、`@transactional` のアプリケーションサービスをそのまま呼ぶ。`async def` (同期の DB の処理がイベントループを止める) とジェネレータは断るため、FastMCP のバックグラウンドタスク (`task=True`) は使えない
- モデル向けの説明は `description=` で渡す (docstring だと実装のメモまでモデルに渡る)
- `tools` も `routers` と同じく起動 (DI 登録) の前に呼ばれるため、コンストラクタでは DI を解決しない
- ツールの中で起きたドメインイベントも、API と同じく何も付けずに発行される (「📮 通知の発行 (Cloud Tasks)」)

</details>

### 💾 Persistence

<details><summary><b>💾 テーブルクラス ( SQLAlchemy ) の実装</b></summary>

テーブルクラスは `sqlalchemy` を直接 import するため、`uv add sqlalchemy` で直接の依存として宣言する (「🪄 lint の設定」)。

`〇〇.port.adapter.persistence.repository.sqlalchemy.user.driver.users_table_row.py`
```python
from sqlalchemy import String
from sqlalchemy.orm import Mapped, mapped_column

# NOTE: テーブルクラスは `DataBase` を継承して作ること
from fastship.common.port.adapter.persistence.sqlalchemy import DataBase


class UsersTableRow(DataBase):
    __tablename__ = "users"

    id: Mapped[str] = mapped_column(String(36), primary_key=True)
    name: Mapped[str] = mapped_column(String(50), index=True)  # index 名は ix_users_name
```

`〇〇.port.adapter.persistence.repository.sqlalchemy.user.driver.__init__.py`
```python
from .users_table_row import UsersTableRow
# 他のテーブルクラス
```

テーブルクラスを足したら、そのモジュールの `tables` にドライバーモジュールのパスを足す

```python
class 〇〇(AppModule):
    @property
    @override
    def tables(self) -> list[str]:
        return ["〇〇.port.adapter.persistence.repository.sqlalchemy.user.driver"]
```

</details>

<details><summary><b>🚚 マイグレーション (Alembic)</b></summary>

事前にマイグレーション用のパッケージを生成
```bash
uv add alembic
uv run alembic init migration
```

`migration/env.py`:
```python
# alembic init の生成物から、target_metadata = None をこの 3 行に差し替える

from fastship.common.port.adapter.persistence.sqlalchemy import DataBase
from core import Backend  # 全モジュールを束ねた CompositeModule

target_metadata = DataBase.metadata_of(Backend())
```

</details>

<details><summary><b>🔀 リードレプリカへの読み書き振り分け (SQLAlchemy)</b></summary>

接続先は `DATABASE_WRITER_URL` / `DATABASE_READER_URL` で注入する (「⚙️ 環境変数」)。Read Pool のノード数を増減しても、エンドポイントは変わらないためアプリ側の変更は要らない。

```python
from fastship.common.port.adapter.persistence.sqlalchemy import SQLAlchemyUnitOfWork

unit_of_work = SQLAlchemyUnitOfWork.from_settings(pool_pre_ping=True)
```

トランザクション (`unit_of_work.session()`) は、読み取りや更新系の生 SQL (`text()`) も含めてすべてプライマリで実行する (レプリカの古い値で更新すると lost update になる)。

読み取り (`unit_of_work.query()`) は、トランザクションの中ならそのセッション (プライマリ) で読むため、リポジトリは中か外かを気にせず `query()` で読める。
別のスレッドや子タスク (`asyncio.to_thread` など) の `query()` はトランザクションの外になる。外では次のように振り分ける。

| クエリ | 送り先 |
|:---|:---|
| 読み取り (`select()` / `session.get()` / `text()`) | リーダー |
| 書き込み (flush / `insert()` / `update()` / `delete()`) | ライター |
| `SELECT ... FOR UPDATE` (`with_for_update()`) | ライター |
| 一度でもライターへ送ったセッションの以降のクエリ | ライター (書き込み直後に古いデータを読まない) |
| `session.use_writer()` を呼んだ後のクエリ | ライター (レプリカ遅延を許容できない読み取り) |

```python
with unit_of_work.query() as session:
    session.use_writer()
    session.get(...)
```

認可の判定 (無効化された API キー、停止されたユーザー、取り消された権限など) は、レプリカ遅延の間に古い状態で許可しないよう、`session.use_writer()` を呼んでプライマリから読むこと。

</details>

<details><summary><b>🧭 アプリケーションサービスとトランザクション (@transactional)</b></summary>

アプリケーションサービスの 1 つのメソッドが、1 つのユースケース・1 つのトランザクション。`@transactional` は、呼び出しの前にトランザクションを始め、正常に戻ればコミットし、例外なら巻き戻す。

アプリケーションサービスは入れ子にしない。中から別の `@transactional` (や `UnitOfWork.start()`) を呼ぶと `RuntimeError` になり、外側も巻き戻る。
- 同期の購読者 (ドメインイベントの publish の中) から呼んでも同じく断る
- この `RuntimeError` を外側で握ると、外側がコミットされてしまう (握らないこと)
- 別のスレッドや子タスクで呼ぶと断れず、外側が巻き戻っても残る別のトランザクションになる (呼ばないこと)
- コミットの後の発行の依頼 (「📮 通知の発行」) はトランザクションの外のため、呼んでよい

代わりに、複数のユースケースで使う処理はドメインサービスに置く。別の集約の変更は、ドメインイベントの通知を受けた listener (「📥 push サブスクリプションの受信」) が別のトランザクションで行う。

`〇〇.application.invoice.invoice_application_service.py`
```python
class InvoiceApplicationService:
    @inject
    def __init__(self, invoices: InvoiceRepository, closing: InvoiceClosingService) -> None:
        self.invoices = invoices
        self.closing = closing  # ドメインサービス

    @transactional
    def confirm(self, command: ConfirmInvoice) -> None:
        invoice = self.invoices.invoice_of(command.invoice_id)
        self.closing.confirm(invoice)  # InvoiceConfirmed を publish する
        self.invoices.save(invoice)
        # 注文の作成 (別の集約) は、InvoiceConfirmed の通知を受けた listener が行う
```

</details>

<details><summary><b>🛡️ トランザクションの範囲 (行レベルセキュリティ)</b></summary>

`@transactional(scope=...)` で、そのトランザクションの範囲 (PostgreSQL の行レベルセキュリティが読む `SET LOCAL` など) を決める。
範囲は `RequestScope` を継承した frozen dataclass で書き (frozen でないと TypeError)、`of` で指示 (self の次の引数) から作り、`set` でコネクションに設定する。

`〇〇.application.scope.py`
```python
from dataclasses import dataclass
from typing import Self, override

from sqlalchemy import Connection, func, select

from fastship.common.application import RequestScope


@dataclass(frozen=True)
class TenantScope(RequestScope[Connection]):
    tenant_id: str

    @classmethod
    @override
    def of(cls, command: TenantCommand) -> Self:
        return cls(command.tenant_id)

    @override
    def set(self, connection: Connection) -> None:
        # 3 つ目の引数 (is_local) を true にし、トランザクションの終わりで外す (コネクションはプールで使い回す)
        connection.execute(select(func.set_config("app.tenant_id", self.tenant_id, True)))
```

```python
class TenantApplicationService:
    @transactional(scope=TenantScope)
    def tenant_of(self, command: TenantOfCommand) -> TenantDpo: ...
```

- 範囲はトランザクション (`unit_of_work.session()`) にだけ乗り、外の `unit_of_work.query()` には乗らない
- listener から範囲付きのアプリケーションサービスを呼べる

</details>

<details><summary><b>📬 outbox / inbox (PostgreSQL)</b></summary>

ドメインイベントは、集約の更新と同じトランザクションで `stored_events` に保存する (outbox)。中継が未発行のイベントを MQ に発行する。
MQ は同じ通知を 1 回以上届ける。受信側は、アプリケーションサービスが冪等にするか、`Inbox` の印で重複を捨てる (inbox)。

テーブル (`stored_events` / `inbox`) と、ストア・中継・`Inbox` の DI 登録は `Common` が行う (「🧩 既定のモジュール」)。
ストアと `Inbox` は `SQLAlchemyUnitOfWork` を受け取り、そのセッションに書く (`Common` が、`UnitOfWork` に登録したのと同じインスタンスを渡す)

中継は同時に走らせてもよく、発行に失敗したイベントがあってもほかを止めない。ただし同じイベントを 2 回発行しうる (commit の前に中継が落ちたとき、待つのをやめた発行 (30 秒) が後から届いたとき)。

受信側で重複を捨てたいアプリケーションサービスは、自分のトランザクションの中で `inbox.claim(key)` を呼ぶ (外では RuntimeError)。キーは通知の `notification_id` と処理の名前から作る。

`〇〇.port.adapter.messaging.invoice_confirmed_listener.py` (listener は入口)
```python
class InvoiceConfirmedListener(ExchangeListener):
    def filtered_dispatch(self, event_type: str, text_message: str) -> None:
        n = json.loads(text_message)
        self.order_service.create(
            CreateOrder(message_id=f"order.create:{n['notification_id']}", invoice_id=n["event"]["invoice_id"])
        )
```

`〇〇.application.order.order_application_service.py`
```python
from fastship.common.application import transactional
from fastship.common.notification import Inbox


class OrderApplicationService:
    @inject
    def __init__(self, inbox: Inbox, orders: OrderRepository) -> None:
        self.inbox = inbox
        self.orders = orders

    @transactional
    def create(self, command: CreateOrder) -> None:
        if not self.inbox.claim(command.message_id):  # 注文と同じトランザクションで印を書く
            return  # 処理済み (重複)
        self.orders.add(Order.create(command.invoice_id))
```

- 印は処理と一緒に確定し、失敗すれば巻き戻って再配送でやり直す
- 冪等にできる処理 (業務キーで upsert する、済んでいれば何もしない、など) では `Inbox` は要らない
- 1 つの通知を複数の listener が受けるときは、listener ごとに別のキーにする (1 つでも失敗すると、再配送で全部の listener が呼ばれる)
- 印の確定の後に失敗しうる処理 (メールの送信・外部 API の呼び出しなど) は、同じアプリケーションサービスに入れない (再配送でやり直されない)。発行したドメインイベントを受ける、別の listener に分ける
- 印の表 (`inbox`) には行レベルセキュリティを付けず、範囲で絞ったロールにも `SELECT`・`INSERT`・`DELETE` を許す。キーには、範囲 (テナントなど) をまたいで一意な値 (`notification_id` など) を使う

処理済みの印は、Cloud Scheduler などから `InboxApplicationService.prune_inbox()` を定期的に呼んで消す (既定は 14 日を過ぎたもの)。保持期間は、MQ が再配送しうる期間 (Pub/Sub は最大 7 日) より長く取る (短いと、消した後の再配送を二重に処理する)。

</details>

### 📨 Messaging

<details><summary><b>📤 Pub/Sub への発行</b></summary>

GCP の SDK は extras に分けている。`gcp` を付けて入れる
```bash
uv add 'fastship-py[gcp]'
```

接続先は `GOOGLE_CLOUD_PROJECT` / `PUBSUB_EMULATOR_HOST` で注入する (「⚙️ 環境変数」)。
Pub/Sub 以外の MQ を使うときは、`MessagePublisher` / `MessageSubscriber` を `Common` の後ろのモジュールで差し替える (「🧩 既定のモジュール」)。

- 発行は Pub/Sub が受け取るまで同期で待ち (最大 30 秒)、失敗すると例外になる。async の処理から呼ぶときは、`asyncio.to_thread` などでスレッドに逃がす
- 本文 (Notification の JSON) に加えて、`event_type` と `partition_key` を属性にも載せる。サブスクリプションのフィルタで、購読するイベントを絞れる

```bash
gcloud pubsub subscriptions create billing --topic=notifications \
  --message-filter='attributes.partition_key = "tenant-1"'
```

</details>

<details><summary><b>🔐 Worker に届くリクエストの認証</b></summary>

Worker (push・Cloud Tasks・Cloud Scheduler から呼ばれる Cloud Run) の入口は、Cloud Run の IAM で守る。アプリは OIDC トークンを検証しない。

```mermaid
flowchart LR
    push["Pub/Sub の push<br>(push の SA のトークン)"]
    tasks["Cloud Tasks・Cloud Scheduler<br>(発行の SA のトークン)"]
    other["それ以外"]
    push --> iam{{"Cloud Run の IAM<br>(トークンを確かめ、run.invoker で絞る)"}}
    tasks --> iam
    other -.->|"403"| iam
    iam --> subscriber["/notifications"]
    iam --> receiver["/notifications/publish"]
```

受け口は `NotificationResource` が持つ。Worker のアプリに載せる

```python
from fastapi import FastAPI
from fastship.common.port.adapter.resource import add_exception_handlers
from fastship.common.port.adapter.resource.notification import NotificationResource

app = FastAPI(lifespan=lifespan, openapi_url=None)  # lifespan で backend.startup() を呼ぶ (DI 登録)
add_exception_handlers(app)
# POST /notifications (push の受信) と POST /notifications/publish (outbox の発行)
app.include_router(NotificationResource().router)
```

- `NotificationResource` は `Common.routers` に入らない。Worker (未認証の呼び出しを拒否する Cloud Run) にだけ載せる。API (未認証の呼び出しを受ける) に載せると、誰でも通知を送り込める
- ブラウザからの呼び出し (`Origin` が付くもの、`Sec-Fetch-Site` が `none` 以外のもの) は 403 で断る (Worker をホストに公開したとき (`docker run -p` など) に、悪意のあるページから動かされないため)。push とキューはどちらのヘッダーも付けない
- Cloud Run が OIDC トークンを確かめ、`roles/run.invoker` を持たない呼び出しをアプリに届く前に断るため、アプリ側の検証は要らない (Google の公式資料)
  - [Pub/Sub の push サブスクリプションの認証](https://docs.cloud.google.com/pubsub/docs/authenticate-push-subscriptions)
  - [Pub/Sub から Cloud Run を呼ぶ](https://docs.cloud.google.com/run/docs/tutorials/pubsub)
  - [Cloud Tasks から Cloud Run を呼ぶ](https://docs.cloud.google.com/run/docs/triggering/using-tasks)
- Cloud Run 以外 (トークンを確かめない実行基盤) で動かすときは、載せるときに自分で検証を足す (`app.include_router(NotificationResource().router, dependencies=[Depends(verify_token)])`)。受け口は本文を検証の後に読む

インフラ
- Worker は未認証の呼び出しを拒否する (`--no-allow-unauthenticated`)
- `roles/run.invoker` は、push の SA と発行の SA の 2 つにだけ渡す。タスクを投入する API・batch・Worker の SA には渡さない
  - push サブスクリプション: `--push-auth-service-account` (push の SA)
  - Cloud Tasks のキュー (`http_target.oidc_token`) と Cloud Scheduler (`--oidc-service-account-email`): 発行の SA
- IAM はサービス単位のため、ルートごとには分けない (どちらの SA も、Worker のすべてのルートを呼べる)

守りが成り立つ条件
- **キュー:** `http_target` の `uri_override` でパス (`/notifications/publish`) まで固定し、`uri_override_enforce_mode = "ALWAYS"` で上書きする (terraform-modules の worker モジュールは満たす)。満たさないと、キューに投入できる SA が、発行の SA のトークンで任意のパス (例: `/notifications` への偽の push) を呼べる
- **投入する SA の権限:** 投入する SA は発行の SA への actAs を持つ (「📮 通知の発行 (Cloud Tasks)」のインフラ)。そのため、SA を付けて動かすものを作る権限 (Cloud Tasks のキューの作成・変更、Cloud Scheduler のジョブ・Cloud Run のサービス・ジョブの作成など) や、ほかのキューへの投入の権限を渡さない。渡すと、`uri_override` の無いキューやジョブから、発行の SA のトークンで `/notifications` に偽の push を送れる
- **継承した付与:** Cloud Run の IAM は、プロジェクト単位の `run.invoker` や `roles/editor` (既定の Compute Engine の SA など) も通すため、そうした付与は避ける。既定の SA への自動の付与は、組織のポリシー `iam.automaticIamGrantsForDefaultServiceAccounts` で止められる

</details>

<details><summary><b>📥 push サブスクリプションの受信</b></summary>

```mermaid
flowchart LR
    publisher["CloudPubSubPublisher"] --> topic[["Pub/Sub トピック"]]
    topic --> push["push サブスクリプション<br>(OIDC トークンを付ける)"]
    push --> iam{{"Worker の Cloud Run の IAM<br>(トークンを確かめる)"}}
    iam --> resource["NotificationResource<br>(POST /notifications)"]
    resource --> subscriber["CloudPubSubSubscriber"]
    subscriber --> listener["ExchangeListener"]
```

受け口は `NotificationResource` の `POST /notifications`。Worker に載せる (「🔐 Worker に届くリクエストの認証」)。
push サブスクリプションの endpoint は `https://worker-〇〇.run.app/notifications` にする。

- listener は受け口に渡さなくてよい (`CompositeModule` が登録する)。登録が無い (`CompositeModule.startup()` を通していない) と 500 で断る (通知を黙って捨てない)
- listener が例外を送出すると 2xx 以外を返し、Pub/Sub が再配送する。重複は listener が呼ぶアプリケーションサービスが捨てる (「📬 outbox / inbox」)
- Content-Type が JSON (`application/json`・`application/*+json`) でない通知は、無いものも 415 で断る (ブラウザが事前確認なしに送れる POST を防ぐ)
- listener の `filtered_dispatch` は同期関数 (`def`) で書く (`async def` は起動のときに断る)
- 読めないメッセージ (JSON のオブジェクトでない本文を含む) は 400 を返し、再配送され続けるため、push サブスクリプションにはデッドレタートピックを設定する

</details>

<details><summary><b>📮 通知の発行 (Cloud Tasks)</b></summary>

ドメインイベントを outbox に追記したトランザクションは、コミットした後に通知の発行を Cloud Tasks に依頼する。API・Worker の listener・MCP のツールのどれでも、何も付けなくてよい。
依頼を受けた Worker が outbox の未発行の通知を MQ に発行する (中継の動きは「📬 outbox / inbox」)。1 分ごとの Cloud Scheduler も同じエンドポイントを呼び、依頼に失敗した分を拾う。

```mermaid
sequenceDiagram
    autonumber
    actor U as 利用者
    participant API as API / Worker
    participant DB as Cloud SQL
    participant Q as Cloud Tasks
    participant S as Cloud Scheduler
    participant WK as Worker
    participant PS as Pub/Sub
    U->>API: POST /orders
    API->>DB: 集約 + outbox をコミット
    API->>Q: タスクを投入 (outbox に追記したときだけ)
    API-->>U: 201 (発行を待たない)
    rect rgba(80, 160, 255, 0.15)
    Note over Q,WK: キューは同時に 1 本だけ呼ぶ
    Q->>WK: POST /notifications/publish (キューが OIDC トークンを付ける)
    WK->>DB: 未発行の通知を 100 件ずつ読む
    WK->>PS: 発行
    WK->>DB: 発行済みにする
    end
    S-->>WK: POST /notifications/publish (1 分ごと。依頼に失敗したときの保険)
```

依頼 (`CloudTasksNotificationPublishTrigger`)
- outbox に追記したコミットごとに、1 つのタスクを `NOTIFICATION_PUBLISH_QUEUE` に投入する。宛先と OIDC トークンはキューの `http_target` が決める
- 投入は応答の前に行い、待つのは 5 秒まで。失敗しても応答は成功のまま返り (ログに残る)、Scheduler の発行が拾う

発行 (`NotificationResource` の `POST /notifications/publish`)
- 60 秒を過ぎたら止め (Cloud Tasks・Scheduler・Cloud Run の期限より前に返す)、残りは次の依頼か Scheduler が送る
- 発行に失敗した通知があっても 204 を返す (outbox に残り、Cloud Tasks の再試行を積み上げない)。DB に接続できないなどの想定外の例外は 500 になり、Cloud Tasks が再試行する
- 発行は、リクエストの文脈 (ContextVar に置いたテナントなど) を引き継がない

インフラ
- キューは同時に 1 本だけ呼ぶ (`max_concurrent_dispatches = 1`)。発行が重ならず、後のタスクが前のタスクの後に溜まった通知を拾う
- キューに `http_target` を設定する (宛先とトークンの決まりは「🔐 Worker に届くリクエストの認証」)。投入は `tasks.buffer` で行うため、`http_target` の無いキューでは動かない
- Cloud Scheduler のジョブで、1 分ごとに同じ URL へ、発行の SA のトークンを付けて POST する
- 宛先は Cloud Run の既定の URL (`run.app`) にする。内部からの通信だけを受け付ける Worker に Cloud Tasks と Cloud Scheduler が届くのは、同じプロジェクトから既定の URL を呼んだときだけ
- タスクを投入する API・batch・Worker の SA には、キューの `cloudtasks.tasks.create` (`roles/cloudtasks.enqueuer`) と、発行の SA への actAs (`roles/iam.serviceAccountUser`) が要る。投入する側はトークンを付けないが、Cloud Tasks は actAs が無い投入を 403 で断る
  - actAs は、発行の SA そのものに付ける (`gcloud iam service-accounts add-iam-policy-binding <発行の SA> --member=serviceAccount:<投入する SA> --role=roles/iam.serviceAccountUser`)。プロジェクト単位で付けると、push の SA や既定の Compute Engine の SA も使えるようになる

ローカルとテスト
- `NOTIFICATION_PUBLISH_TRIGGER=local` にすると Cloud Tasks (公式のエミュレータが無い) を使わず、コミットの後、応答の前にその場で発行する (API・Worker・stdio の MCP)。Worker はトークンを検証しないので、Pub/Sub のエミュレータの push もそのまま受けられる
- `DI_FOR_PY=InMem` では依頼を数えるだけで発行しない。発行まで確かめるテストは、`NotificationApplicationService.publish_notifications()` を自分で呼ぶ

</details>

### 🛠️ Other

<details><summary><b>📦 DI コンテナ</b></summary>

登録方法:
```python
from sqlalchemy import create_engine

from fastship.common.application import UnitOfWork
from fastship.common.port.adapter.persistence.inmem import InMemUnitOfWork
from fastship.common.port.adapter.persistence.sqlalchemy import SQLAlchemyUnitOfWork
from fastship.di import DI, DIContainer

engine = create_engine("postgresql+psycopg://...")

DIContainer.instance().register(
    DI.of(UnitOfWork, {"InMem": InMemUnitOfWork()}, SQLAlchemyUnitOfWork(engine)),
)
```

DI から引くもの (`resolve` するクラスと、`@inject` のコンストラクタが受け取るクラス) は、すべて register する。register していないと、`resolve` は `LookupError` になる (黙って作らない。作ると、登録した実装と別のインスタンスが渡っても気づけない)。
実装がそのクラス自身なら、`DI.of(〇〇ApplicationService, {}, 〇〇ApplicationService)` と書く。register したものは、プロセスに 1 つだけ作られる。

`UnitOfWork` と、それを使うカーネルの部品 (`SQLAlchemyUnitOfWork` / `InMemUnitOfWork` の鍵・`@transactional` の実体・outbox / inbox・中継) は、`Common` がまとめて登録する (「🧩 既定のモジュール」)。差し替えたいものだけを後ろのモジュールで登録する。

利用方法:
```python
from injector import inject

from fastship.common.domain.model import DomainRegistry
from fastship.di import DIContainer

# `DI_FOR_PY=InMem` なら InMemUnitOfWork、`DI_FOR_PY=` なら SQLAlchemyUnitOfWork のインスタンスを取得
unit_of_work = DIContainer.instance().resolve(UnitOfWork)
〇〇_repository = DomainRegistry.resolve(〇〇Repository)


class 〇〇ApplicationService:
    @inject
    def __init__(self, 〇〇_repository: 〇〇Repository) -> None: ...


DIContainer.instance().register(
    DI.of(〇〇Repository, {"InMem": InMem〇〇Repository}, SQLAlchemy〇〇Repository),
    DI.of(〇〇ApplicationService, {}, 〇〇ApplicationService),
)
```

</details>

<details><summary><b>⚠️ エラー応答 (RFC 9457)</b></summary>

`ErrorJson` は [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) の Problem Details を表し、`ErrorCode` から組み立てる。`type` は `/errors/{コード名}` になり、クライアントは `type` の完全一致で分岐する。
`add_exception_handlers(app)` は、例外を `ErrorJson` (`application/problem+json`) の応答に変える例外ハンドラを登録する。

| 例外 | ステータス | `type` |
|:---|:---|:---|
| `SystemException` | `ErrorCode` の `http_status` | `/errors/{コード名}` |
| `ValueError` / `AssertionError` (ドメインの自己検証) | 400 | `/errors/COMMON_2000` |
| `RequestValidationError` (リクエストのスキーマ検証) | 422 | `/errors/COMMON_2001` |
| `HTTPException` (未定義ルートの 404・405、`fastapi.security` の 401/403 など) | 例外のステータス | `about:blank` |
| その他の例外 | 500 | `/errors/COMMON_1000` |

- `SystemException.detail` はログ用で内部の情報を含みうるため、応答の `detail` には渡さない。`ValueError` / `AssertionError` のログにも、例外の型と送出した場所だけを出す (メッセージには入力値が入りうる)
- 応答を変えたい例外は、`add_exception_handlers(app)` の後に `app.add_exception_handler` で登録する (同じ例外なら後から登録したものが勝つ)。応答は `ErrorJson.of(エラーコード, str(request.url)).to_response()` で返す

```json
{"type": "/errors/USER_NOT_FOUND", "title": "ユーザーが見つかりません", "status": 404, "instance": "https://api.example.com/users/1"}
```

OpenAPI のエラー応答は、`ErrorJson.openapi(エラーコード, ...)` を `responses=` に渡す。

```python
app = FastAPI(responses=ErrorJson.openapi(CommonCode.COMMON_2001, CommonCode.COMMON_1000))  # 全エンドポイント共通


@router.get("/me", responses=ErrorJson.openapi(AuthCode.UNAUTHORIZED, IdentityCode.USER_NOT_FOUND))  # そのルート固有
```

</details>

### ✏️ Style Check

```bash
uv run ruff format --check . && uv run ruff check . && uv run ty check && uv run deptry . && uv run lint-imports
```

<details><summary><b>🪄 lint の設定 (ruff / ty / deptry)</b></summary>

設定は fastship が持たない。テンプレートの `pyproject.toml` にある設定を、プロジェクトで自由に変える。
- fastship-py 経由で入る依存 (`fastapi` / `injector` / `pydantic` / `pydantic-settings` / `sqlalchemy`、extras の `fastmcp`) も、import するならプロジェクトの `dependencies` に直接書く (書かないと deptry が DEP003 として検出する)
- `src` 直下のモジュールは `[tool.deptry]` の `known_first_party` に並べる (並べないと自分のモジュールを未宣言の依存とみなす)

```toml
[tool.deptry.per_rule_ignores]
DEP002 = ["uvicorn"]  # import せずに使う依存
```

</details>

<details><summary><b>🏛 アーキテクチャ規約 (import-linter)</b></summary>

テンプレートの `pyproject.toml` の `[tool.importlinter]` が規約を有効にしている。
- 規約の中身 (層の順序や許可する import) は fastship のコード (`fastship.linter.architecture`) にあり、fastship-py を更新すると変わる
- `root_packages` には `src` 直下のモジュールをすべて並べる (足し忘れは lint-imports が検出する)。空だと import-linter が動かないため、テンプレートは見本の `example` モジュールを持つ

プロジェクト独自の設定や contract も `[tool.importlinter]` に足す
```toml
[tool.importlinter]
root_packages = ["billing"]
include_external_packages = true  # sqlalchemy などの外部パッケージを forbidden_modules に書くときに要る

[[tool.importlinter.contracts]]
id = "no-sqlalchemy-in-domain"
name = "ドメイン層は永続化の技術を知らない"
type = "forbidden"
source_modules = ["billing.domain"]
forbidden_modules = ["sqlalchemy"]
```

**ヘキサゴナルアーキテクチャ** (モジュール内部の依存)

<img src="docs/images/hexagonal.svg" alt="core → middleware → port → application → domain → exception の向きにだけ import できる。domain を import できるのは core / application / port.adapter.persistence / port.adapter.service だけ">

**モジュラモノリス** (モジュール間の依存)

<img src="docs/images/modular-monolith.svg" alt="モジュール間の import は ACL アダプター (port.adapter.service.〇〇.adapter) から相手の公開 IF (port.adapter.resource) へだけ">

</details>
