Skip to main content

🚀 fastship-py

# 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 から引く (Cloud Run ではメタデータサーバー)
PUBSUB_EMULATOR_HOST Pub/Sub ([gcp]) ローカルだけ エミュレータの host:port。設定すると ADC (実際の GCP の資格情報) を引かない。本番では設定しない
NOTIFICATION_PUBLISH_TRIGGER 通知の発行の依頼 ローカルだけ local にすると、Cloud Tasks を使わず、コミットの後にその場で発行する。既定は cloud_tasks。本番では設定しない
NOTIFICATION_PUBLISH_QUEUE 通知の発行の依頼 ([gcp]) cloud_tasks では必須 タスクを投入する Cloud Tasks のキュー (projects/〇〇/locations/〇〇/queues/〇〇)。宛先と OIDC トークンはキューの http_target が固定する
DI_FOR_PY DI コンテナ 任意 有効にするプロファイル (カンマ区切り)。テストで InMem にするなど

📚 How To

🧩 既定のモジュール (Common)

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

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 (DATABASE_* の接続先) InMemUnitOfWork
EventContextProvider NullEventContextProvider 同左
EventStore (outbox) PostgreSQLEventStore InMemEventStore
ConsumedNotificationStore (inbox) PostgreSQLConsumedNotificationStore InMemConsumedNotificationStore
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 の設定が要らない
  • CompositeModule は起動のときに、全モジュールの listener を DI に登録する (ExchangeListeners)。Worker の受け口 (NotificationResource) が MessageSubscriber に渡す
  • Pub/Sub と Cloud Tasks の実装を使うには extras の [gcp] を入れる (「📤 Pub/Sub への発行」)。入れていなくても、Common の import と InMem での起動はできる

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

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

🌐 API

🌐 モジュールの API を載せる

モジュールの routers に APIRouter を並べる。CompositeModule に並べた全モジュールの routers が 1 つにまとまる。 routers を書かないモジュール (購読だけのものなど) は何も載せない。

from fastapi import APIRouter


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

api.py:

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 がスレッドで動かす)。DB の処理とコミットの後の発行の依頼は同期で動くため、async def のルートから呼ぶと、@transactional が RuntimeError で断る

🤖 MCP

🤖 モジュールのツールを MCP サーバーに載せる

MCP サーバーは FastMCP で立てる (fastmcp 4.1.3 で確かめた)。FastMCP は extras に分けている。 fastmcp を付けて入れ、fastmcp 自体も直接の依存として宣言する (宣言しないと deptry が推移的な依存 (DEP003) として検出する)。

uv add 'fastship-py[fastmcp]' fastmcp

モジュールの tools に FastMCP の Tool を並べる。CompositeModule に並べた全モジュールの tools が 1 つにまとまる。 tools を書かないモジュールは何も載せない。

CompositeModule.tools は全ツールの関数を包み (fastship.common.port.adapter.tool.translate_errors)、例外を API (add_exception_handlers) と同じ方針で MCP のエラーに変える。 モジュールは何も付けなくてよい。

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 とトレースバック 「想定外の原因エラーが発生しました」

例外の中身はクライアントに返さず、FastMCP の mask_error_details の設定にも頼らない。元の例外も切り離し、OTel のスパンなどにメッセージを残さない。

引数の検証 (不足・余分・型の誤り) は、本体の前に FastMCP が行い、どの引数が誤りかをモデルに返す (WARNING で記録する)。

mcp_server.py:

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 が発行した JWT を JWTVerifier で検証し、RemoteAuthProvider で認可サーバーの場所を知らせる。この形は、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 つの名前空間になる。重なると CompositeModule.tools が ValueError を送出する (FastMCP は警告だけで後勝ちに置き換えるため)
  • ツールは Tool.from_function で、関数かメソッドから作る。Tool.from_tool やプロキシのツール、functools.partial や呼び出し可能なインスタンスから作ったツールは、例外を変換できないため CompositeModule.tools が断る
  • ツール名は name= に ASCII ([A-Za-z0-9_.-]) で渡す。既定は関数名で、日本語のメソッド名のままだと、名前の形式を強制するクライアントに拒まれる
  • ツールの引数・戻り値の型は実行時に import する。Tool.from_function は登録の時点で型ヒントを解決するため、TYPE_CHECKING に移すと NameError になる。ruff の TC001〜TC003 は、ツールのファイルでは外す (per-file-ignores)
  • ツールは値を返す同期関数 (def) で書く。async def とジェネレータは CompositeModule.tools が断る。UnitOfWork はスレッドごとに DB のセッションを持ち、async のツールはイベントループの 1 スレッドで動くため、await の間に別の呼び出しのトランザクションが混ざる。ジェネレータは本体が変換の外で動く
  • そのため、FastMCP のバックグラウンドタスク (task=True、async の関数を求める) は使えない
  • ツールの説明 (description) はモデルが読み、ツールを選ぶのに使う。docstring を使うと実装のメモまで渡るため、モデル向けの説明は description= で渡す
  • tools は起動 (DI 登録) の前に呼ばれる。Tool の元のクラスのコンストラクタでは DI を解決せず、ツールが呼ばれたときに解決する
  • 同期 (def) のツールは、FastMCP がスレッドで動かす。API の def のルートと同じく、@transactional のアプリケーションサービスをそのまま呼べる
  • ツールの中で起きたドメインイベントは、API と同じく、アプリケーションサービスの境界がコミットの後に発行を依頼する (「📮 通知の発行 (Cloud Tasks)」)。ツールにも FastMCP にも何も付けなくてよい。stdio で動かすローカル (エミュレータ) では、コミットの後にその場で発行する

💾 Persistence

💾 テーブルクラス ( SQLAlchemy ) の実装

テーブルクラスは sqlalchemy を直接 import するため、uv add sqlalchemy で直接の依存として宣言する (fastship-py 経由で入っていても、宣言しないと deptry が推移的な依存 (DEP003) として検出する)。

〇〇.port.adapter.persistence.repository.sqlalchemy.user.driver.users_table_row.py

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

from .users_table_row import UsersTableRow
# 他のテーブルクラス

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

class 〇〇(AppModule):
    @property
    @override
    def tables(self) -> list[str]:
        return ["〇〇.port.adapter.persistence.repository.sqlalchemy.user.driver"]
🚚 マイグレーション (Alembic)

事前にマイグレーション用のパッケージを生成

uv add alembic
uv run alembic init migration

migration/env.py:

# 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())
🔀 リードレプリカへの読み書き振り分け (SQLAlchemy)

接続先は DATABASE_WRITER_URL / DATABASE_READER_URL で注入する (冒頭の「⚙️ 環境変数」を参照)。

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

unit_of_work = SQLAlchemyUnitOfWork.from_settings(pool_pre_ping=True)

トランザクション (unit_of_work.session()) は、読み取りも含めてすべてプライマリで実行する。 レプリカの遅延した値を元に更新すると、プライマリの新しい値を上書きしてしまう (lost update) ため。 更新系の生 SQL (text()) もここで実行する。

読み取り (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() を呼んだ後のクエリ ライター (レプリカ遅延を許容できない読み取り)
with unit_of_work.query() as session:
    session.use_writer()
    session.get(...)

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

Read Pool のノード数を増減しても、エンドポイントは変わらないためアプリ側の変更は要らない。

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

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

〇〇.application.scope.py

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)))
class TenantApplicationService:
    @transactional(scope=TenantScope)
    def tenant_of(self, command: TenantOfCommand) -> TenantDpo: ...
  • @transactional は、呼び出しのたびに self の次の引数 (指示) から TenantScope.of(command) で範囲を作る。 範囲は値で比べる (frozen dataclass で書く。同一性で比べるクラスは、デコレータが TypeError で断る)
  • SQLAlchemyUnitOfWork は、トランザクションがコネクションを開くたびに set(connection) を呼ぶ (SQLAlchemy の after_begin)。 SAVEPOINT では呼び直さない (外側で設定した範囲が残る)。set で例外が出たら、そのコネクションを無効にする
  • 範囲はトランザクション (unit_of_work.session()) にだけ乗る。トランザクションの外の unit_of_work.query() には乗らない。 範囲のあるトランザクションが flush に失敗した後の query() は、範囲の無いセッションに切り替えずに断る
  • 入れ子の @transactional は、外側と同じ値の範囲か、範囲の指定なしでしか join できない。違えば ScopeConflictError。 listener は MessageSubscriber が範囲なしで始めたトランザクションの中で動くため、範囲付きのアプリケーションサービスを呼べない
📬 outbox / inbox (PostgreSQL)

ドメインイベントは、集約の更新と同じトランザクションで stored_events に保存する (outbox)。中継が未発行のイベントを MQ に発行する。 受信側は、listener の処理と同じトランザクションで consumed_notifications に記録し、同じ通知が 2 回届いても 1 回だけ処理する (inbox)。

テーブル (stored_events / consumed_notifications) と、ストア・中継の DI 登録は Common が行う (「🧩 既定のモジュール」)。 ストアは UnitOfWork に登録した SQLAlchemyUnitOfWork のセッションに書く

中継 (NotificationPublisherImpl)

  • 未発行 (published_at が空) の行を FOR UPDATE SKIP LOCKED で 100 件ずつ取り出し、NOTIFICATION_PUBLISH_TO に発行して published_at を付ける
  • 100 件ごとに commit し、残りが無くなるまで繰り返す。溜まったときもメモリを食わず、commit の前に止められても巻き戻るのは最後の 100 件分だけ。発行できなかった行が出たら、その回で止める (障害中に同じ行を送り続けない)
  • 発行済みを行ごとに記録するため、id の小さいイベントが後から commit されても取りこぼさない
  • 中継が同時に走っても、ほかの中継がロックしている行は飛ばして分担する
  • 取り出した行はまとめて MQ に渡し、まとめて待つ (MessagePublisher.publish_all)。Pub/Sub は 1 回の RPC にまとめて送り、障害中も待つのは全体で 30 秒まで (CloudPubSubPublisher.PUBLISH_TIMEOUT)
  • 発行できた行だけを発行済みにする。発行できなかった行は次の中継で発行する。まとめて送れない MQ の実装 (publish_all を上書きしないもの) は 1 件ずつ送り、最初の失敗で打ち切る
  • 発行に失敗した行は後回しにする (失敗した回数の少ない順に取り出す)。発行できないイベントがあっても、ほかのイベントは止まらない
  • 同じイベントを 2 回発行するのは、発行した後 commit する前に中継が落ちたときと、待つのをやめた (30 秒を過ぎた) 発行が後から届いたとき。受信側の inbox が重複を捨てる

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

📨 Messaging

📤 Pub/Sub への発行

GCP の SDK は extras に分けている。gcp を付けて入れる

uv add 'fastship-py[gcp]'

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

  • 発行は Pub/Sub が受け取るまで同期で待つ (最大 300 秒)。async の処理から呼ぶときは、asyncio.to_thread などでスレッドに逃がす
  • 発行に失敗すると例外になる (黙って捨てない)
  • 本文 (Notification の JSON) に加えて、event_type と partition_key を属性にも載せる。サブスクリプションのフィルタで、購読するイベントを絞れる
gcloud pubsub subscriptions create billing --topic=notifications \
  --message-filter='attributes.partition_key = "tenant-1"'
🔐 Worker に届くリクエストの認証

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

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 のアプリに載せる

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 など) に、悪意のあるページから listener を動かされたり、発行を繰り返させられたりしないようにする。push とキューは、どちらのヘッダーも付けない

  • Cloud Run が、リクエストに付いた OIDC トークンを確かめる。roles/run.invoker を持たない呼び出しは、アプリに届く前に断られる

  • Google の公式資料でも、受け手が Cloud Run なら、アプリ側の検証は要らない

  • Cloud Run 以外 (トークンを確かめない実行基盤) で Worker を動かすときは、利用者が自分でトークンを検証する。載せるときに検証を足せる (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) を呼べる
  • 継承した付与: Cloud Run の IAM は、プロジェクト単位の run.invoker や roles/editor (既定の Compute Engine の SA など) も通す。そうした付与は避ける。既定の SA への自動の付与は、組織のポリシー iam.automaticIamGrantsForDefaultServiceAccounts で止められる
📥 push サブスクリプションの受信
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 が起動のときに DI に登録する (ExchangeListeners)。受け口に渡さなくてよい。登録が無いと 500 で断る (通知を黙って捨てない)
  • 2xx 以外を返すと Pub/Sub が再配送する。同じメッセージが 2 回届いても、inbox が重複を捨てる
  • Content-Type が JSON (application/json・application/*+json) でない通知は 415 で断る (Content-Type が無いものも)。ブラウザが事前確認なしに送れる POST で listener を動かされないようにする。Pub/Sub の push は application/json を付けて送る
  • listener の filtered_dispatch は同期関数 (def) で書く。async def は起動のとき (ExchangeListeners) に断る
  • subscriber は配送ごとに別のスレッドで listener を動かす。UnitOfWork はスレッドごとに DB のセッションを持つため、並行する配送のトランザクションが混ざらず、イベントループも塞がない
  • 読めないメッセージ (JSON のオブジェクトでない本文を含む) は 400 を返し、再配送され続ける。push サブスクリプションにはデッドレタートピックを設定する
📮 通知の発行 (Cloud Tasks)

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

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 分ごと。依頼に失敗したときの保険)

受け口は NotificationResource の POST /notifications/publish。push の受け口と一緒に Worker に載る (「🔐 Worker に届くリクエストの認証」)。

依頼 (CloudTasksNotificationPublishTrigger)

  • 最外の境界のコミットの後、その境界で outbox に追記したときだけ依頼する。ロールバック・入れ子の内側の境界・追記しない境界 (参照だけのリクエスト・通知の発行そのもの) では依頼しない
  • NOTIFICATION_PUBLISH_QUEUE のキューへ、REST の tasks.buffer で投入する。宛先 (/notifications/publish) と OIDC トークンはキューの http_target が固定するため、URL もトークンも付けない (google-cloud-tasks のクライアントは buffer を持たないため、google-auth で呼ぶ)
  • 依頼はコミットの後、応答の前に行う (トークンの取得から投入までの合計で、待つのは 5 秒まで。投入は別のスレッド (daemon・最大 8 本、呼んだ側の文脈を引き継ぐ) で動かし、5 秒で待つのをやめる。打ち切った投入が裏で 4 本残っているときは、待たずに断る。打ち切った投入が後から失敗したら、その理由もログに残る)。失敗しても応答は成功のまま返り、失敗はログに残る。未発行の通知は Scheduler の発行で送られる
  • 依頼の先は、最初に依頼するときに作る。環境変数が欠けていても、追記しない境界と発行そのものは止まらない (依頼のたびに失敗がログに残る)
  • タスクはまとめない (コミットごとに 1 つ)。後のタスクはほとんどが空の発行になるが、1 回の SELECT で終わる

発行 (NotificationResource の POST /notifications/publish)

  • 100 件ずつ別のトランザクションで、残りが無くなるまで発行する。60 秒を過ぎたら止め、残りは次の依頼か Scheduler が送る (書き込みが続いても、Cloud Tasks・Scheduler・Cloud Run の期限より前に返す)
  • 発行に失敗した通知があっても 204 を返す。失敗した通知は outbox に残り、次の依頼か Scheduler が送る (Cloud Tasks の再試行を積み上げない)
  • DB に接続できないなどの想定外の例外は 500 になり、Cloud Tasks が再試行する
  • 同期の発行はスレッドに逃がす。イベントループを塞がず、他のリクエストの処理は止まらない
  • 発行は、リクエストの文脈 (ContextVar に置いたテナントなど) を引き継がない

インフラ

  • キューは同時に 1 本だけ呼ぶ (max_concurrent_dispatches = 1)。発行が重ならず、後のタスクは前のタスクの後に溜まった通知を拾う。Scheduler の発行と重なっても、中継どうしで未発行の通知を分担し、同じ通知を二重に発行しない
  • キューに http_target を設定する。宛先は発行用のエンドポイント (パスまで固定し、ALWAYS で上書きする)、OIDC トークンは発行の SA (「🔐 Worker に届くリクエストの認証」)。tasks.buffer は http_target の無いキューでは使えない
  • Cloud Scheduler のジョブで、1 分ごとに同じ URL へ POST する。OIDC トークンはキューと同じく発行の SA で付ける
  • 宛先は Cloud Run の既定の URL (run.app) にする。内部からの通信だけを受け付ける Worker に Cloud Tasks と Cloud Scheduler が届くのは、同じプロジェクトから既定の URL を呼んだときだけ
  • タスクを投入する API・batch・Worker のサービスアカウントに要るのは、キューの cloudtasks.tasks.create (roles/cloudtasks.enqueuer) だけ。トークンのサービスアカウントへの actAs は要らない (投入する側がトークンを付けないため)

ローカルとテスト

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

🛠️ Other

📦 DI コンテナ

登録方法:

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)),
)

利用方法:

from fastship.di import DI, DIContainer

# `DI_FOR_PY=InMem` なら InMemUnitOfWork のインタンスを取得
# `DI_FOR_PY=` なら SQLAlchemyUnitOfWork のインタンスを取得
unit_of_work = DIContainer.instance().resolve(UnitOfWork)
from injector import inject


class 〇〇ApplicationService:
    @inject
    def __init__(self, 〇〇_repository: 〇〇Repository) -> None: ...
from fastship.common.domain.model import DomainRegistry

〇〇_repository = DomainRegistry.resolve(〇〇Repository)
⚠️ エラー応答 (RFC 9457)

ErrorJson は RFC 9457 の Problem Details を表す。ErrorCode から組み立てる。

  • type は /errors/{コード名} になる。クライアントは type の完全一致で分岐する
  • SystemException.detail はログ用で内部の情報を含みうるため、detail には渡さない

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
  • ValueError / AssertionError のログには、例外の型と送出した場所だけを出す (メッセージには入力値が入りうる)
  • 応答を変えたい例外は、add_exception_handlers(app) の後に app.add_exception_handler で登録する (同じ例外なら後から登録したものが勝つ)。応答は ErrorJson.of(エラーコード, str(request.url)).to_response() で返す
{"type": "/errors/USER_NOT_FOUND", "title": "ユーザーが見つかりません", "status": 404, "instance": "https://api.example.com/users/1"}

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

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


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

✏️ Style Check

uv run ruff format --check . && uv run ruff check . && uv run ty check && uv run deptry . && uv run lint-imports
🪄 lint の設定 (ruff / ty / deptry)

設定は fastship が持たない。テンプレートの pyproject.toml にある設定を、プロジェクトで自由に変える。

  • fastship-py 経由で入る依存 (fastapi / injector / pydantic / pydantic-settings / sqlalchemy) も、import するならプロジェクトの dependencies に直接書く
  • src 直下のモジュールは [tool.deptry] の known_first_party に並べる (並べないと自分のモジュールを未宣言の依存とみなす)
[tool.deptry.per_rule_ignores]
DEP002 = ["uvicorn"]  # import せずに使う依存
🏛 アーキテクチャ規約 (import-linter)

テンプレートの pyproject.toml の [tool.importlinter] が規約を有効にしている。

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

プロジェクト独自の設定や contract も [tool.importlinter] に足す

[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"]

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

core → middleware → port → application → domain → exception の向きにだけ import できる。domain を import できるのは core / application / port.adapter.persistence / port.adapter.service だけ

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

モジュール間の import は ACL アダプター (port.adapter.service.〇〇.adapter) から相手の公開 IF (port.adapter.resource) へだけ

Metadata

Release files for fastship-py 0.20.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fastship-py 0.20.0
File Size Uploaded Provenance Actions
fastship_py-0.20.0.tar.gz 233.8 kB With provenance Details for fastship_py-0.20.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fastship-py 0.20.0
File Interpreter ABI Platform Actions
fastship_py-0.20.0-py3-none-any.whl Python 3 none any Details for fastship_py-0.20.0-py3-none-any.whl

Total release size: 338.7 kB

Release files / fastship_py-0.20.0.tar.gz

Download URL fastship_py-0.20.0.tar.gz
Size 233.8 kB
Tags Source
SHA-256 checksum
How to use checksums
155700e00a9267e559f615d3047080ce3b602ca4d3b4fa473f04c7f68f5e9485
BLAKE2b-256 checksum
How to use checksums
9a18380172784e5d72ede4c763f2063159b4b3504e4982cdfa3121ee66af6c63
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / fastship_py-0.20.0-py3-none-any.whl

Download URL fastship_py-0.20.0-py3-none-any.whl
Size 104.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
31613e82a333d811c6b61a1e803538c53339769bf5f1c39c32d7baaa4c3eb84b
BLAKE2b-256 checksum
How to use checksums
72bea804dfd9a14f9135aace347e2044d3bc8b91700a0043475f6d8e34405afe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for fastship-py 0.20.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fastship_py-0.20.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page