ddd4py 0.1.0__py3-none-any.whl

ddd4py/__init__.py

@@ -0,0 +1,44 @@
+"""モジュラモノリス + DDD のカーネル。"""
+
+from importlib.metadata import version
+
+from ddd4py.application import ApplicationServiceLifeCycle, UnitOfWork, transactional
+from ddd4py.domain.model import (
+    DomainEvent,
+    DomainEventPublisher,
+    DomainEventSubscriber,
+    DomainRegistry,
+    EventContext,
+)
+from ddd4py.event import EventContextProvider, EventStore, NullEventContextProvider, StoredEvent
+from ddd4py.exception import CoreCode, ErrorCode, ErrorLevel, SystemException
+from ddd4py.module import AppModule, CompositeModule
+from ddd4py.settings import BaseAppSettings, CoreSettings
+
+# バージョンの真実源は pyproject.toml の [project].version 一箇所。
+# 引数は import 名ではなく配布名 (どちらも ddd4py)。
+__version__ = version("ddd4py")
+
+__all__ = [
+    "AppModule",
+    "ApplicationServiceLifeCycle",
+    "BaseAppSettings",
+    "CompositeModule",
+    "CoreCode",
+    "CoreSettings",
+    "DomainEvent",
+    "DomainEventPublisher",
+    "DomainEventSubscriber",
+    "DomainRegistry",
+    "ErrorCode",
+    "ErrorLevel",
+    "EventContext",
+    "EventContextProvider",
+    "EventStore",
+    "NullEventContextProvider",
+    "StoredEvent",
+    "SystemException",
+    "UnitOfWork",
+    "__version__",
+    "transactional",
+]

ddd4py/application/__init__.py

@@ -0,0 +1,9 @@
+from .unit_of_work import UnitOfWork
+from .application_service_life_cycle import ApplicationServiceLifeCycle, transactional
+
+# 入力アダプタ (port.adapter.resource / messaging) はヘキサゴナル契約上 domain を直接 import
+# できないため、アダプタが扱う必要のあるドメインの値オブジェクトは application 経由で公開する。
+# SoT は ddd4py.domain.model.event_context のままで、ここは再輸出のみ。
+from ddd4py.domain.model import EventContext
+
+__all__ = ["ApplicationServiceLifeCycle", "EventContext", "UnitOfWork", "transactional"]

ddd4py/application/application_service_life_cycle.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import functools
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any, override
+
+from di import DIContainer
+from injector import inject, singleton
+
+from ddd4py.application.unit_of_work import UnitOfWork
+from ddd4py.domain.model import DomainEvent, DomainEventPublisher, DomainEventSubscriber
+from ddd4py.event import EventStore
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+# トランザクション境界のネスト深さ。subscriber の dispatch トランザクション内から listener が
+# `@transactional` な ApplicationService を呼ぶと境界が入れ子になるため、最外の境界だけが
+# commit / rollback するよう深さを追跡する (UoW の start 自体は in_transaction() で join 済み)。
+# ApplicationServiceLifeCycle は singleton のため、実行コンテキストごとの深さは ContextVar に持つ。
+_transaction_depth: ContextVar[int] = ContextVar("ddd4py_transaction_depth", default=0)
+
+
+class _EventStoreSubscriber(DomainEventSubscriber[DomainEvent]):
+    """publish された全ドメインイベントを outbox に追記する購読者。"""
+
+    def __init__(self, event_store: EventStore):
+        self.__event_store = event_store
+
+    @override
+    def subscribed_to_event_type(self) -> type[DomainEvent]:
+        return DomainEvent
+
+    @override
+    def handle_event(self, domain_event: DomainEvent) -> None:
+        self.__event_store.append(domain_event)
+
+
+@singleton
+class ApplicationServiceLifeCycle:
+    """`@transactional` の実体。トランザクション境界とドメインイベント購読の生存期間を握る。"""
+
+    @inject
+    def __init__(self, unit_of_work: UnitOfWork, event_store: EventStore):
+        self.__unit_of_work = unit_of_work
+        self.__event_store = event_store
+
+    def begin(self, is_listening: bool = True) -> None:
+        if is_listening:
+            self.listen()
+        self.__unit_of_work.start()
+        _transaction_depth.set(_transaction_depth.get() + 1)
+
+    def fail(self, exception: Exception | None = None) -> None:
+        """ネスト中の失敗も最外までトランザクション全体を巻き戻す (部分 commit を許さない)。
+
+        内側の fail で深さを 0 に戻すため、伝播後の外側 fail の rollback は新規セッションへの
+        空 rollback となり無害。
+
+        前提: ネスト内の失敗は必ず最外境界まで伝播させること (握り潰し禁止)。内側の例外を catch
+        して処理を続行すると、最外の success() は depth=0 の空 commit となり、副作用も consumed
+        marker も確定しないまま成功扱い (ack) になって配送が静かに失われる。
+        """
+        _transaction_depth.set(0)
+        self.__unit_of_work.rollback()
+        # トランザクション境界を抜ける際に購読者を破棄する。残したまま @transactional の外で
+        # DomainEventPublisher.publish が呼ばれると、EventStore subscriber が UnitOfWork の
+        # セッションに書き込んでしまい、後続処理へトランザクション状態が漏れる。
+        DomainEventPublisher.instance().reset()
+        if exception is not None:
+            raise exception
+
+    def success(self) -> None:
+        depth = _transaction_depth.get()
+        if depth > 1:
+            # ネストした内側の境界は commit せず、最外の境界に委ねる。
+            _transaction_depth.set(depth - 1)
+            return
+        try:
+            self.__unit_of_work.commit()
+        finally:
+            _transaction_depth.set(0)
+            DomainEventPublisher.instance().reset()
+
+    def listen(self) -> None:
+        DomainEventPublisher.instance().reset()
+        DomainEventPublisher.instance().subscribe(_EventStoreSubscriber(self.__event_store))
+
+
+def _dynamic_args(deco_func: Callable[..., Any]) -> Callable[..., Any]:
+    # デコレータは任意のシグネチャの関数を包むため、引数型は本質的に Any になる。
+    def wrapper(*args: Any, **kwargs: Any) -> Callable[..., Any]:  # noqa: ANN401
+        if len(args) != 0 and callable(args[0]):
+            # 第一引数に関数が渡された場合: 引数なしのデコレータとして扱う
+            return functools.wraps(args[0])(deco_func(args[0]))
+
+        def _wrapper(func: Callable[..., Any]) -> Callable[..., Any]:
+            return functools.wraps(func)(deco_func(func, *args, **kwargs))
+
+        return _wrapper
+
+    return wrapper
+
+
+@_dynamic_args
+def transactional[T](method: Callable[..., T], is_listening: bool = True) -> Callable[..., T]:
+    """AOP によるトランザクション管理を行うためのデコレータ"""
+
+    @functools.wraps(method)
+    def handle_transaction(*args: Any, **kwargs: Any) -> T:  # type: ignore[return]  # noqa: ANN401
+        life_cycle: ApplicationServiceLifeCycle = DIContainer.instance().resolve(ApplicationServiceLifeCycle)
+        life_cycle.begin(is_listening)
+        try:
+            _return = method(*args, **kwargs)
+            life_cycle.success()
+        except Exception as e:  # noqa: BLE001
+            life_cycle.fail(e)
+        else:
+            return _return
+
+    return handle_transaction

ddd4py/application/unit_of_work.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import abc
+
+
+class UnitOfWork[T](abc.ABC):
+    """UnitOfWork の抽象クラス。
+
+    UnitOfWork の詳細は以下を参照。
+    https://bliki-ja.github.io/pofeaa/UnitofWork
+    https://learn.microsoft.com/ja-jp/archive/msdn-magazine/2009/june/the-unit-of-work-pattern-and-persistence-ignorance
+
+    UnitOfWork はいくつかの課題を解決する。
+    * 最小の DB トランザクション実行 / SQL クエリ発行により、パフォーマンス問題を解決する
+    * DDD において、ドメインオブジェクトの制御と永続化処理を分離させられる
+    * 異なる DB コネクション、異なるストアへの操作を単一の論理的なトランザクションにまとめられる
+    """
+
+    @abc.abstractmethod
+    def mark(self, instance: T) -> None:
+        """UnitOfWork の追跡対象に追加する。
+
+        self.mark() に指定されたインスタンスは self.persist() にて、更新するインスタンスか
+        新規作成するインスタンスかどうかの判定に用いる。
+        """
+
+    @abc.abstractmethod
+    def persist(self, instance: T) -> None:
+        """永続化対象としてインスタンスを追跡する"""
+
+    @abc.abstractmethod
+    def delete(self, *instances: T) -> None:
+        """削除対象としてインスタンスを追跡する"""
+
+    @abc.abstractmethod
+    def start(self) -> None:
+        """トランザクションを開始する"""
+
+    @abc.abstractmethod
+    def flush(self) -> None:
+        """永続化処理を途中実行する。
+
+        self.commit() とは異なりトランザクションの完了までは行わない。
+        DB から ID が採番される関係上、一度 DB に反映して ID を取得したい場合などに使用する。
+        """
+
+    @abc.abstractmethod
+    def rollback(self) -> None:
+        """ロールバックする"""
+
+    @abc.abstractmethod
+    def commit(self) -> None:
+        """トランザクションをコミットする"""

ddd4py/domain/model/__init__.py

@@ -0,0 +1,11 @@
+from .domain_registry import DomainRegistry
+from .event_context import EventContext
+from .domain_event import DomainEvent, DomainEventPublisher, DomainEventSubscriber
+
+__all__ = [
+    "DomainEvent",
+    "DomainEventPublisher",
+    "DomainEventSubscriber",
+    "DomainRegistry",
+    "EventContext",
+]

ddd4py/domain/model/domain_event.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import abc
+import threading
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Self
+
+import pytz
+
+if TYPE_CHECKING:
+    from ddd4py.domain.model.event_context import EventContext
+
+
+@dataclass(init=True, unsafe_hash=True, frozen=True)
+class DomainEvent(abc.ABC):
+    """ドメインイベント"""
+
+    event_version: int
+    occurred_on: datetime = field(default_factory=lambda: datetime.now(pytz.timezone("Asia/Tokyo")))
+
+    def __post_init__(self) -> None:
+        if self.event_version is None or self.event_version < 0:
+            raise ValueError("event_version must be >= 0")
+        if self.occurred_on is None or not isinstance(self.occurred_on, datetime):
+            raise ValueError("occurred_on must be set")
+
+    @property
+    def type(self) -> str:
+        return f"{self.__class__.__name__}.{self.event_version}"
+
+    @abc.abstractmethod
+    def to_dict(self) -> dict:
+        """MQ のペイロードとして送信する JSON 形式の値を指定する"""
+
+    def routing_context(self) -> EventContext | None:
+        """イベントを処理すべき文脈の自己申告。既定 (None) は発生元 (append 時点の文脈)。
+
+        境界をまたぐ副作用を起こすイベントだけが override する。申告すると全購読者が申告先の
+        文脈で処理される点に注意 (発生元でも副作用が要るなら、別イベントに分けること)。
+        """
+        return None
+
+
+class DomainEventPublisher(threading.local):
+    """スレッドローカルなドメインイベントパブリッシャー
+
+    シングルトンのインスタンス自体は共有されるが、内部データは threading.local により
+    スレッドごとに分離される。
+    """
+
+    _instance: DomainEventPublisher | None = None
+    _lock = threading.Lock()
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.__subscribers: set[DomainEventSubscriber] = set()
+
+    @classmethod
+    def instance(cls) -> DomainEventPublisher:
+        """スレッドセーフなシングルトンインスタンス取得"""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = DomainEventPublisher()
+        return cls._instance
+
+    def reset(self) -> Self:
+        self.__subscribers = set()
+        return self
+
+    def publish(self, domain_event: DomainEvent) -> None:
+        for subscriber in self.__subscribers:
+            if isinstance(domain_event, subscriber.subscribed_to_event_type()):
+                subscriber.handle_event(domain_event)
+
+    def subscribe(self, subscriber: DomainEventSubscriber) -> None:
+        self.__subscribers.add(subscriber)
+
+
+class DomainEventSubscriber[T](abc.ABC):
+    """サブスクライバー"""
+
+    @abc.abstractmethod
+    def handle_event(self, domain_event: T) -> None:
+        pass
+
+    @abc.abstractmethod
+    def subscribed_to_event_type(self) -> type[T]:
+        pass

ddd4py/domain/model/domain_registry.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from di import DIContainer
+
+if TYPE_CHECKING:
+    from injector import T
+
+
+class DomainRegistry:
+    """集約 / ドメインサービスから技術実装を解決するための窓口。
+
+    集約がドメインサービスを必要とするとき、application 層に IF を渡させず
+    `DomainRegistry.resolve(EncryptionService)` のように自分で解決する。
+    """
+
+    @staticmethod
+    def resolve(interface: type[T]) -> T:
+        return DIContainer.instance().resolve(interface)

ddd4py/domain/model/event_context.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class EventContext:
+    """StoredEvent / Notification に刻印される実行文脈。
+
+    カーネルは「文脈が何であるか」を知らない。知っているのは 2 つだけ:
+
+    - `partition_key`: subscriber がイベントを処理する境界を解決するためのキー。
+      マルチテナントなら App / テナントの識別子、単一テナントなら既定値のまま。
+    - `payload`: 受信側が文脈を復元するのに必要な全情報 (JSON 化可能なこと)。
+
+    利用側は自分の語彙 (App / Pool / Organization など) をこの 2 値に翻訳して渡す。
+    カーネルに業務語彙を持ち込まないための境界がここ。
+    """
+
+    DEFAULT_PARTITION_KEY = "default"
+
+    partition_key: str = DEFAULT_PARTITION_KEY
+    payload: dict = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.partition_key:
+            raise ValueError("partition_key must not be empty")

ddd4py/event/__init__.py

@@ -0,0 +1,5 @@
+from .stored_event import StoredEvent
+from .event_store import EventStore
+from .event_context_provider import EventContextProvider, NullEventContextProvider
+
+__all__ = ["EventContextProvider", "EventStore", "NullEventContextProvider", "StoredEvent"]

ddd4py/event/event_context_provider.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import abc
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, override
+
+from ddd4py.domain.model import EventContext
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from contextlib import AbstractContextManager
+
+    from ddd4py.domain.model import DomainEvent
+
+
+class EventContextProvider(abc.ABC):
+    """アンビエントな実行文脈の読み書きを担う唯一のポート。
+
+    - `current()`: いま処理中の文脈を読む (outbox への刻印時に使う)
+    - `bind()`: 受信した文脈を確立する (inbox の dispatch 時に使う)
+
+    マルチテナントなアプリは「いま処理中のテナント / プレーン」を返す実装を DI 登録する。
+    単一テナントなら `NullEventContextProvider` のままでよい。
+
+    カーネルが実行文脈そのもの (リクエストスコープの ContextVar 等) を持たないのは、
+    文脈の語彙が利用側ごとに違うため。カーネルは「刻印する / 確立する」ことだけを知っている。
+    """
+
+    @abc.abstractmethod
+    def current(self) -> EventContext:
+        """いま処理中の実行文脈を返す"""
+
+    @abc.abstractmethod
+    def bind(self, context: EventContext) -> AbstractContextManager[None]:
+        """受信した文脈を、ブロックの間だけ確立する"""
+
+    def context_of(self, domain_event: DomainEvent) -> EventContext:
+        """イベントに刻印する文脈を決める。
+
+        既定は発生元 (append 時点の文脈)。境界をまたぐイベントだけが
+        `DomainEvent.routing_context()` で処理先を自己申告し、それが優先される。
+        """
+        return domain_event.routing_context() or self.current()
+
+
+class NullEventContextProvider(EventContextProvider):
+    """単一テナント / 単一プレーン向けの既定実装。文脈を持たず、常に既定値を返す。"""
+
+    @override
+    def current(self) -> EventContext:
+        return EventContext()
+
+    @override
+    @contextmanager
+    def bind(self, context: EventContext) -> Iterator[None]:
+        yield

ddd4py/event/event_store.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import abc
+from typing import TYPE_CHECKING, Self
+
+if TYPE_CHECKING:
+    from ddd4py.domain.model import DomainEvent
+    from ddd4py.event.stored_event import StoredEvent
+
+
+class EventStore(abc.ABC):
+    """outbox。`@transactional` の内側で DomainEvent を StoredEvent として追記する。"""
+
+    @abc.abstractmethod
+    def all_stored_events_between(self, from_stored_event_id: int, to_stored_event_id: int) -> list[StoredEvent]:
+        pass
+
+    @abc.abstractmethod
+    def all_stored_events_since(self, stored_event_id: int) -> list[StoredEvent]:
+        pass
+
+    @abc.abstractmethod
+    def append(self, domain_event: DomainEvent) -> Self:
+        pass

ddd4py/event/stored_event.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import datetime
+
+    from ddd4py.domain.model import DomainEvent, EventContext
+
+# `<発行元モジュール>.<ドメインイベントのクラス名>.<イベントバージョン>`
+# 各部は Python 識別子 (unicode 可)。"." で 3 分割できることが不変条件なので、区切り文字と
+# 空白の混入だけを弾く。ユビキタス言語をそのままクラス名にする言語 (日本語等) を排除しない。
+_TYPE_PATTERN = re.compile(r"[^\W\d]\w*\.[^\W\d]\w*\.\d+")
+
+
+@dataclass(init=True, frozen=True)
+class StoredEvent:
+    """トランザクショナル outbox の 1 行。集約の更新と同一トランザクションで永続化される。"""
+
+    event_id: int | None
+    type: str
+    event_body: dict
+    occurred_on: datetime.datetime
+    # イベントを処理すべき境界のキー (既定は発生元)。subscriber がこのキーで処理文脈を解決するため、
+    # イベントは処理先を自己記述する。境界をまたぐイベントは routing_context() の申告値で上書きされる。
+    partition_key: str
+    context: dict
+
+    def __post_init__(self) -> None:
+        # fullmatch で全体一致を要求し、末尾改行・余剰文字の混入を弾く。
+        if _TYPE_PATTERN.fullmatch(self.type) is None:
+            raise ValueError(
+                f"Invalid event type: '{self.type}'. "
+                "Expected format: '<publisher>.<DomainEventClassName>.<version>'.",
+            )
+        if not self.partition_key:
+            raise ValueError("partition_key must not be empty")
+
+    @property
+    def publisher(self) -> str:
+        return self.type.split(".")[0]
+
+    @property
+    def event_type(self) -> str:
+        """`{ドメインイベントのクラス名}.{イベントバージョン番号}` を返す"""
+        return ".".join(self.type.split(".")[1:])
+
+    @property
+    def version(self) -> int:
+        return int(self.type.split(".")[2])
+
+    @staticmethod
+    def new(event_id: int | None, domain_event: DomainEvent, context: EventContext) -> StoredEvent:
+        return StoredEvent(
+            event_id,
+            f"{domain_event.__module__.split('.')[0]}.{domain_event.type}",
+            domain_event.to_dict(),
+            domain_event.occurred_on,
+            context.partition_key,
+            context.payload,
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, StoredEvent):
+            return False
+        if self.event_id is None or other.event_id is None:
+            return False
+        return self.event_id == other.event_id
+
+    def __hash__(self) -> int:
+        # 採番前 (event_id is None) でも set / dict に入れられること。
+        return hash(("StoredEvent", self.event_id))

ddd4py/exception/__init__.py

@@ -0,0 +1,4 @@
+from .error_code import CoreCode, ErrorCode, ErrorLevel
+from .system_exception import SystemException
+
+__all__ = ["CoreCode", "ErrorCode", "ErrorLevel", "SystemException"]

ddd4py/exception/error_code.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import logging
+from enum import Enum
+from http import HTTPStatus
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+logger = logging.getLogger(__name__)
+
+
+class ErrorLevel(Enum):
+    WARN = ("WARN", logger.warning)
+    ERROR = ("ERROR", logger.error)
+    CRITICAL = ("CRITICAL", logger.critical)
+
+    def __init__(self, level: str, logging_: Callable[[str], None]):
+        self.level = level
+        self.__logging = logging_
+
+    def to_logger(self, error_code: ErrorCode, detail: str) -> None:
+        self.__logging(f"[Code] {error_code.name} [Message] {error_code.message} [Detail] {detail}")
+
+
+class ErrorCode(Enum):
+    """業務エラーの分類。利用側プロジェクトはこれを継承して自分のコード体系を定義する。
+
+    継承先の例:
+        class AuthorityCode(ErrorCode):
+            USER_NOT_FOUND = ("ユーザーが見つかりません", ErrorLevel.WARN, HTTPStatus.NOT_FOUND)
+    """
+
+    def __init__(self, message: str, error_level: ErrorLevel, http_status: HTTPStatus):
+        self.message = message
+        self.error_level = error_level
+        self.http_status = http_status
+
+    def log(self, detail: str) -> None:
+        self.error_level.to_logger(self, detail)
+
+
+class CoreCode(ErrorCode):
+    """カーネル自身が送出するエラー。業務エラーは利用側が ErrorCode を継承して定義する。"""
+
+    CORE_1000 = ("想定外の原因エラーが発生しました", ErrorLevel.ERROR, HTTPStatus.INTERNAL_SERVER_ERROR)
+    # 実行文脈 (テナント境界など) が未解決のままデータアクセスしようとした防衛発火 (fail-closed)。
+    # 汎用の 1000 と分けることで、監視で境界違反の発火だけを切り分けてカウントできる。
+    CORE_1001 = ("実行文脈が未解決のため処理を拒否しました", ErrorLevel.ERROR, HTTPStatus.INTERNAL_SERVER_ERROR)

ddd4py/exception/system_exception.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ddd4py.exception.error_code import ErrorCode
+
+
+class SystemException(RuntimeError):
+    def __init__(self, error_code: ErrorCode, detail: str):
+        super().__init__(f"{error_code.name}: {detail}")
+        self.error_code = error_code
+        self.detail = detail
+
+    def logging(self) -> None:
+        self.error_code.log(self.detail)