bestagon 0.6.0__tar.gz

bestagon-0.6.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: bestagon
+Version: 0.6.0
+Summary: DDD+ES+CQRS framework for python
+Author: Aleksandr Antonov
+Author-email: antonov.o779@gmail.com
+Dynamic: author
+Dynamic: author-email
+Dynamic: summary

bestagon-0.6.0/bestagon/adapters/kurrent.py

@@ -0,0 +1,165 @@
+import asyncio
+import logging
+from dataclasses import dataclass
+from typing import List, Union, Sequence, cast, Tuple
+
+import grpc
+from kurrentdbclient import StreamState, NewEvent, DEFAULT_EXCLUDE_FILTER, AsyncKurrentDBClient, AsyncCatchupSubscription
+from kurrentdbclient.common import DEFAULT_WINDOW_SIZE, DEFAULT_CHECKPOINT_INTERVAL_MULTIPLIER
+from kurrentdbclient.exceptions import NotFoundError
+
+from bestagon.core.event_store import EventStore, SubscriptionParameters, EventStoreSubscription, StreamEvent, \
+    NewStreamEvent
+from bestagon.core.exceptions import IntegrityError
+
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class KurrentDBSubscriptionParameters(SubscriptionParameters):
+    commit_position: Union[int, None] = None
+    from_end: bool = False
+    resolve_links: bool = False
+    filter_exclude: Sequence[str] = DEFAULT_EXCLUDE_FILTER
+    filter_include: Sequence[str] = ()
+    filter_by_stream_name: bool = False
+    include_checkpoints: bool = False
+    window_size: int = DEFAULT_WINDOW_SIZE
+    checkpoint_interval_multiplier: int = DEFAULT_CHECKPOINT_INTERVAL_MULTIPLIER
+    include_caught_up: bool = False
+    include_fell_behind: bool = False
+    timeout: Union[float, None] = None
+    credentials: Union[grpc.CallCredentials, None] = None
+
+
+class AsyncKurrentDBSubscription(EventStoreSubscription):
+    def __init__(self, name: str, parameters: KurrentDBSubscriptionParameters, kdb_subscription: AsyncCatchupSubscription):
+        super().__init__(name=name, parameters=parameters)
+        self._kdb_subscription = kdb_subscription
+
+    async def next_event(self) -> StreamEvent:
+        if not self.running:
+            raise StopAsyncIteration
+
+        event = await anext(self._kdb_subscription)
+        stream_event = StreamEvent(
+            stream_name=event.stream_name,
+            stream_position=event.stream_position,
+            commit_position=event.commit_position,
+            event_type=event.type,
+            payload=event.data,
+            metadata=event.metadata
+        )
+        return stream_event
+
+    async def stop(self) -> None:
+        if self.running:
+            self._running = False
+            await self._kdb_subscription.stop()
+
+
+class AsyncKurrentDBEventStore(EventStore):
+    def __init__(self, client: AsyncKurrentDBClient):
+        super().__init__()
+        self.client = client
+
+    async def append_events(self, stream_name: str, events: Tuple[NewStreamEvent]) -> None:
+        current_version = await self.client.get_current_version(stream_name=stream_name)
+        first_event = events[0]
+        if current_version == StreamState.NO_STREAM:
+            if first_event.stream_position != 0:
+                raise IntegrityError('Failed to append event to non existent stream, events position should start from 0')
+        elif first_event.stream_position <= current_version:
+            raise IntegrityError(f'Failed to append events in stream {stream_name} - event with version {first_event.stream_position} already exists in database')
+
+        new_events = list()
+        for event in events:
+            new_event = NewEvent(
+                type=event.event_type,
+                data=event.payload,
+                metadata=event.metadata
+            )
+            new_events.append(new_event)
+
+        await self.client.append_events(stream_name=stream_name, current_version=current_version, events=new_events)
+
+    async def close(self) -> None:
+        if self. subscriptions:
+            await asyncio.gather(*[sub.stop() for sub in self.subscriptions])
+            logger.info('All subscriptions stopped')
+
+        await self.client.close()
+        logger.info('Event store closed')
+
+    async def connect(self) -> None:
+        await self.client.connect()
+        logger.info('Event store connected')
+
+    async def create_subscription(self, subscription_name: str,
+                                  subscription_parameters: KurrentDBSubscriptionParameters) -> AsyncKurrentDBSubscription:
+        kdb_subscription = await self.client.subscribe_to_all(
+            commit_position=subscription_parameters.commit_position,
+            from_end=subscription_parameters.from_end,
+            resolve_links=subscription_parameters.resolve_links,
+            filter_exclude=subscription_parameters.filter_exclude,
+            filter_include=subscription_parameters.filter_include,
+            filter_by_stream_name=subscription_parameters.filter_by_stream_name,
+            include_checkpoints=subscription_parameters.include_checkpoints,
+            window_size=subscription_parameters.window_size,
+            checkpoint_interval_multiplier=subscription_parameters.checkpoint_interval_multiplier,
+            include_caught_up=subscription_parameters.include_caught_up,
+            include_fell_behind=subscription_parameters.include_fell_behind,
+            timeout=subscription_parameters.timeout,
+            credentials=subscription_parameters.credentials
+        )
+        kdb_subscription = cast(AsyncCatchupSubscription, kdb_subscription)
+
+        subscription = AsyncKurrentDBSubscription(name=subscription_name, parameters=subscription_parameters, kdb_subscription=kdb_subscription)
+        self._subscriptions.append(subscription)
+        return subscription
+
+    async def create_subscription_to_all(self, subscription_name: str, start_position: int) -> 'EventStoreSubscription':
+        params = KurrentDBSubscriptionParameters(commit_position=start_position)
+        sub = await self.create_subscription(subscription_name=subscription_name, subscription_parameters=params)
+        return sub
+
+    async def create_subscription_to_events(self, subscription_name: str, events: List[str],
+                                            start_position: int) -> 'EventStoreSubscription':
+        params = KurrentDBSubscriptionParameters(
+            commit_position=start_position,
+            filter_include=events,
+            filter_by_stream_name=False
+        )
+        sub = await self.create_subscription(subscription_name=subscription_name, subscription_parameters=params)
+        return sub
+
+    async def create_subscription_to_stream(self, subscription_name: str, regex: str, start_position: int) -> EventStoreSubscription:
+        params = KurrentDBSubscriptionParameters(
+            commit_position=start_position,
+            filter_include=[regex],
+            filter_by_stream_name=True
+        )
+        return await self.create_subscription(subscription_name=subscription_name, subscription_parameters=params)
+
+    async def get_stream(self, stream_name: str) -> Tuple[StreamEvent]:
+        events = await self.client.get_stream(stream_name=stream_name)
+        stream_events = list()
+        for event in events:
+            stream_event = StreamEvent(
+                stream_name=stream_name,
+                stream_position=event.stream_position,
+                commit_position=event.commit_position,
+                event_type=event.type,
+                payload=event.data,
+                metadata=event.metadata
+            )
+            stream_events.append(stream_event)
+        return tuple(stream_events)
+
+    async def stream_exists(self, stream_name: str) -> bool:
+        try:
+            events = await self.client.get_stream(stream_name=stream_name, backwards=True, limit=1)
+            return bool(events)
+        except NotFoundError:
+            return False

bestagon-0.6.0/bestagon/adapters/neo4j_db.py

@@ -0,0 +1,139 @@
+import asyncio
+import logging
+from abc import abstractmethod
+from typing import Tuple
+
+import neo4j
+
+from bestagon.core.checkpoint_store import CheckpointStore, Checkpoint
+from bestagon.core.event_processor import Projection
+
+logger = logging.getLogger(__name__)
+
+
+class Neo4jCheckpointStore(CheckpointStore):
+    def __init__(self, driver: neo4j.AsyncDriver, database_name: str):
+        self.driver = driver
+        self.database_name = database_name
+
+    async def close(self) -> None:
+        pass
+
+    async def delete_checkpoint(self, name: str) -> None:
+        cypher = '''
+        MATCH (c:Checkpoint {name: $name})
+        DETACH DELETE c
+        '''
+        async with self.driver.session(default_access_mode=neo4j.WRITE_ACCESS, database=self.database_name) as sess:
+            await sess.run(cypher, name=name)
+        logger.info(f'Checkpoint {name} deleted')
+
+    async def get_checkpoint(self, name: str) -> Checkpoint:
+        cypher = '''
+        MATCH (c:Checkpoint {name: $name})
+        RETURN c.value
+        '''
+        async with self.driver.session(database=self.database_name, default_access_mode=neo4j.READ_ACCESS) as sess:
+            result = await sess.run(
+                cypher,  # NOQA
+                name=name
+            )
+            value = await result.single()
+            if value is not None:
+                value = value.value()
+            else:
+                value = 0
+
+        checkpoint = Checkpoint(name=name, value=value)
+        return checkpoint
+
+    async def initialize(self) -> None:
+        create_cypher = "CREATE DATABASE $database_name IF NOT EXISTS"
+        async with self.driver.session() as sess:
+            await sess.run(
+                create_cypher,  # NOQA
+                database_name=self.database_name
+            )
+
+        index_cypher = '''
+        CREATE RANGE INDEX checkpoint_name_index
+        IF NOT EXISTS
+        FOR (n:Checkpoint)
+        ON n.name
+        '''
+        async with self.driver.session(database=self.database_name) as sess:
+            await sess.run(index_cypher)  # NOQA
+
+    async def list_checkpoints(self) -> Tuple[Checkpoint, ...]:
+        cypher = '''
+        MATCH (c:Checkpoint)
+        WITH {
+            name: c.name,
+            value: c.value
+        } AS data
+        RETURN data
+        '''
+        async with self.driver.session(default_access_mode=neo4j.READ_ACCESS, database=self.database_name) as sess:
+            result = await sess.run(cypher)
+            data = await result.value()
+        checkpoints = tuple(Checkpoint(**datum) for datum in data)
+        return checkpoints
+
+    async def set_checkpoint(self, checkpoint: Checkpoint) -> None:
+        cypher = '''
+        MERGE (c:Checkpoint {name: $name})
+        SET c.value = $value
+        '''
+
+        async with self.driver.session(database=self.database_name, default_access_mode=neo4j.WRITE_ACCESS) as sess:
+            await sess.run(
+                cypher,  # NOQA
+                name=checkpoint.name,
+                value=checkpoint.value
+            )
+        logger.debug(f'New checkpoint set for {checkpoint.name}: {checkpoint.value}')
+
+
+class Neo4jProjection(Projection):
+    def __init__(self, driver: neo4j.AsyncDriver, checkpoint_store: CheckpointStore):
+        super().__init__(checkpoint_store=checkpoint_store)
+        self.driver = driver
+
+    @property
+    def database_name(self) -> str:
+        return self.get_database_name()
+
+    async def drop(self) -> None:
+        # TODO - indexes
+        logger.info(f'Dropping projection {self.name}...')
+        cypher = '''CREATE OR REPLACE DATABASE $database_name'''
+        check_cypher = '''
+        SHOW DATABASES
+        YIELD name, currentStatus
+        WHERE name = $database_name
+        RETURN currentStatus AS status
+        '''
+        async with self.driver.session() as sess:
+            await sess.run(cypher, database_name=self.database_name)
+
+            logger.info('Checking database created')
+            while True:
+                result = await sess.run(check_cypher, database_name=self.database_name)
+                record = await result.single()
+                status = record.value()
+                if status != 'online':
+                    logger.info('Waiting for database')
+                    await asyncio.sleep(1)
+                else:
+                    logger.info(f'Database created')
+                    break
+
+    @abstractmethod
+    def get_database_name(self) -> str:
+        raise NotImplementedError
+
+    async def initialize(self) -> None:
+        # TODO - indexes
+        cypher = '''CREATE DATABASE $database_name IF NOT EXISTS'''
+        async with self.driver.session() as sess:
+            await sess.run(cypher, database_name=self.database_name)

bestagon-0.6.0/bestagon/core/aggregate.py

@@ -0,0 +1,246 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, asdict
+from datetime import datetime, timezone
+from typing import List, Tuple
+
+from bestagon.core.exceptions import AggregateIDMismatch, AggregateVersionError
+
+
+@dataclass(frozen=True)
+class DomainEventMetadata:
+    """
+    DO NOT base business decisions on metadata
+    The correlation_id of a message always references the identifier of the message it originates from (that is, the parent message).
+    The trace_id on the other hand references to the message identifier which started the chain of messages (that is, the root message).
+    """
+    # TODO - add correlation_id
+    # TODO - add trace_id
+    # TODO - ORLY - inherit dict and use getters to get aggregate_id, version etc.
+
+    timestamp: str  # TODO - turn it into field to create automatically  # TODO - also can be called audit_time - just a date and time when event occured
+    aggregate_id: str
+    aggregate_version: int
+    aggregate_type: str
+
+    @staticmethod
+    def create_timestamp() -> str:
+        return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass(frozen=True)
+class DomainEvent:
+    # TODO - make things simple - event should contain metadata and data (separate class)
+    metadata: DomainEventMetadata
+
+    def get_metadata_as_dict(self) -> dict:
+        # TODO - ORLY???
+        return asdict(self.metadata)
+
+    def get_payload(self) -> dict:
+        # TODO - ORLY???
+        payload = asdict(self).copy()
+        payload.pop('metadata')
+        return payload
+
+
+@dataclass(frozen=True)
+class Created(DomainEvent):
+    pass
+
+
+class Aggregate(ABC):
+    """
+    According to Eric Evans book Domain Driven Design: Tackling Complexity in the Heart of Software:
+        An AGGREGATE is a cluster of associated objects that we treat as a unit for the purpose of data changes.
+
+    The class is an implementation of an Event Sourced Aggregate.
+    Each event sourced aggregate contains a set of predefined domain events, which discovered during modelling stage using event storming or other knowledge crunching method.
+
+    # Aggregate creation:
+    Event sourced aggregate starts its life cycle from 'Created' event. The only right way to do it currenty is to define factory method on the aggregate, this method
+    should create necessary event and then use '_create' method to instantiate aggregate.
+
+    For example, imagine you have a ShoppingCart aggregate, according to ubiquitious language of your domain it is 'created', so you can create a factory method, called 'create'
+    for the specified aggregate:
+
+        @classmethod
+        def create(cls, param_1, param_2) -> 'ShoppingCart':
+            metadata = DomainEventMetadata()  # Details omitted for simplicity
+            event = cls.Created(metadata, param_1, param_2)
+            obj = cls._create(event)
+            return obj
+
+    # Consequtive events:
+    In addition to 'Created' event, aggregate can have 0 or more events that can happen after creation of aggregate. Each of these events change aggregate state in some way.
+    For example, if we talk about shopping cart, then we can 'add_item' to it, so there will be a method on aggregate:
+
+        def add_item(command: AddShoppingCartItem) -> None:
+            # First, you perform validation of input parameters (whether it is a command, entity or just a set of parameters)
+            self.validate_command(command)
+
+            # Second, you execute business logic to figure out what have happened
+            # Business logic code in here
+
+            # Third - you create an Event which records what have happened
+            event = self.ItemAdded(
+                metadata=metadata,
+                item_name=command.item_name
+            )
+
+            # Finally - you trigger event to launch change of state process
+            sef.trigger_event(event)
+
+    When you trigger event, the aggregate calls 'mutate' method which validates the event and passes it to 'apply_event' method.
+    This method must know how to change the state of the aggregate and this is your responsibility to make it happen by reimplementing 'apply_event' method.
+    As a rule of thumb there is a simple way to do it:
+
+        def apply_event(event) -> None:
+            # 1. Define routing from event type to event handler
+            routing = {
+                self.ItemAdded: self._when_item_added,
+            }
+
+            event_handler = routing.get(type(event))  # 2. Take the corresponding event handler from routing
+            if event_handler is None:
+                super().apply_event(event)  # Default implementation will raise error if there is no handler
+            else:
+                event_handler(event)  # Handle event
+
+    Event handler should change the state of the aggregate:
+
+        def _when_item_added(event) -> None:
+            self._items.append(event.event_name)
+
+    ACHTUNG - your event handlers MUST NOT contain any business logic, it only should change the state of the aggregate based on what is stated in the event.
+
+    Next step - application module.
+    """
+
+    # TODO - register aggregate type automatically
+    # TODO - event handlers take events as input and change the aggregate state
+    # TODO - command handlers take commands as input, validate business logic and trigger events
+    # TODO - aggregate state changes should occur only in event handlers, NOT command handlers, how to protect aggregate from occasional state change in command handler???
+
+    INITIAL_VERSION = 0
+
+    @dataclass(frozen=True)
+    class Created(Created):
+        """Use it as a base class for Created events"""
+        pass
+
+    @dataclass(frozen=True)
+    class Event(DomainEvent):
+        """Use it as a base class for consequtive events"""
+        pass
+
+    def __init__(self, event: Created):
+        self._aggregate_id = event.metadata.aggregate_id
+        self._aggregate_version = event.metadata.aggregate_version
+        self._aggregate_created_on = datetime.fromisoformat(event.metadata.timestamp)
+        self._aggregate_modified_on = datetime.fromisoformat(event.metadata.timestamp)
+
+        self._pending_events: List[DomainEvent] = list()
+
+    @property
+    def aggregate_created_on(self) -> datetime:
+        """The date and time when the aggregate was created."""
+        return self._aggregate_created_on
+
+    @property
+    def aggregate_id(self) -> str:
+        return self._aggregate_id
+
+    @property
+    def aggregate_modified_on(self) -> datetime:
+        """The date and time when the aggregate was modified."""
+        return self._aggregate_modified_on
+
+    @property
+    def aggregate_type(self) -> str:
+        return self.get_aggregate_type()
+
+    @property
+    def aggregate_version(self) -> int:
+        return self._aggregate_version
+
+    @property
+    def next_version(self) -> int:
+        """Convenience property to get the next version number of aggregate"""
+        return self.aggregate_version + 1
+
+    @property
+    def pending_events(self) -> Tuple[DomainEvent, ...]:
+        return tuple(self._pending_events)
+
+    @classmethod
+    def _create(cls, event: 'Created') -> 'Aggregate':
+        """Actually creates new aggregate. Should be used by factory method implemented on specific aggregate instance."""
+        obj = cls(event=event)
+        obj._pending_events.append(event)
+        return obj
+
+    def apply_event(self, event: DomainEvent) -> None:
+        """
+        Reimplement to provide change of state of the aggregate when event occur.
+        Each event must have the associated event handler.
+        """
+        raise TypeError(f'Unknown Event {type(event)}')
+
+    def clear_events(self) -> None:
+        """Clears all pending events on the Aggregate"""
+        self._pending_events = list()
+
+    def collect_events(self) -> List[DomainEvent]:
+        """Returns the list of pending events in the aggregate and clears pending events"""
+        events = self._pending_events
+        self.clear_events()
+        return events
+
+    @staticmethod
+    @abstractmethod
+    def create_id(*args, **kwargs) -> str:
+        """
+        Reimplement to create ID of the aggregate.
+        Aggregate ID MUST BE UNIQUE accross the same aggregate type.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    @abstractmethod
+    def get_aggregate_type() -> str:
+        """
+        Aggregate type should be defined during modelling stage and MUST NOT BE CHANGED during the entire aggregate lifecycle.
+        It is used by repository to retreive specific aggregate instances and by event store as prefix to event stream.
+        """
+        raise NotImplementedError
+
+    def mutate(self, event: DomainEvent) -> None:
+        """
+        Performs validation of the event and changes the state of the aggregate by calling 'apply_event'.
+        After application of the event modifies the version and modification date of the aggregate.
+
+        Validation:
+            - Event.aggregate_id should be equal to Aggregate.id. Raises AggregateIdError if not.
+            - Event.aggregate_version should be EXACTLY ONE more than Aggregate.version. Raises AggregateVersionError if not.
+        """
+        # Event MUST belong to the aggregate
+        if self.aggregate_id != event.metadata.aggregate_id:
+            raise AggregateIDMismatch(f'ERROR - {event.__class__.__qualname__} aggregate_id does not match Aggregate ID attribute.')
+        # Version of the new event MUST BE EXACTLY ONE MORE than the current aggegate version
+        if (event.metadata.aggregate_version - self.aggregate_version) != 1:
+            raise AggregateVersionError(f'ERROR - event aggregate version should be exactly one more than the aggregate version.')
+
+        # Change the state of Aggregate
+        self.apply_event(event)
+
+        # Record new version and modification date
+        self._aggregate_version = event.metadata.aggregate_version
+        self._aggregate_modified_on = event.metadata.timestamp
+
+    def trigger_event(self, event: Event) -> None:
+        """
+        Should be called whenever new event occur during aggregate lifecycle.
+        Mutates aggregate state and adds event to the list of pending events
+        """
+        self.mutate(event)
+        self._pending_events.append(event)

bestagon-0.6.0/bestagon/core/checkpoint_store.py

@@ -0,0 +1,45 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Tuple
+
+
+@dataclass(frozen=True)
+class Checkpoint:
+    name: str
+    value: int
+
+    def __post_init__(self):
+        if not isinstance(self.name, str):
+            raise TypeError('Checkpoint name should a string')
+        if not self.name:
+            raise ValueError('Checkpoint name should be a non empty string')
+        if not isinstance(self.value, int):
+            raise TypeError('Checkpoint value should be an integer')
+        if self.value < 0:
+            raise ValueError('Checkpoint value should be a positive integer')
+
+
+class CheckpointStore(ABC):
+    @abstractmethod
+    async def close(self) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_checkpoint(self, name: str) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_checkpoint(self, name: str) -> Checkpoint:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def list_checkpoints(self) -> Tuple[Checkpoint, ...]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def set_checkpoint(self, checkpoint: Checkpoint) -> None:
+        raise NotImplementedError