eventsourcing 9.3.5__py3-none-any.whl → 9.4.0__py3-none-any.whl

eventsourcing/persistence.py

@@ -4,27 +4,18 @@ import json
 import uuid
 from abc import ABC, abstractmethod
 from collections import deque
+from collections.abc import Iterator, Mapping, Sequence
 from dataclasses import dataclass
 from datetime import datetime
 from decimal import Decimal
-from threading import Condition, Event, Lock, Semaphore, Timer
-from time import time
-from types import ModuleType
-from typing import (
-    Any,
-    Dict,
-    Generic,
-    Iterator,
-    List,
-    Mapping,
-    Sequence,
-    Type,
-    TypeVar,
-    Union,
-    cast,
-)
+from queue import Queue
+from threading import Condition, Event, Lock, Semaphore, Thread, Timer
+from time import monotonic, sleep, time
+from types import GenericAlias, ModuleType
+from typing import TYPE_CHECKING, Any, Generic, Union, cast
 from uuid import UUID
-from warnings import warn
+
+from typing_extensions import TypeVar
 
 from eventsourcing.domain import DomainEventProtocol, EventSourcingError
 from eventsourcing.utils import (
@@ -35,11 +26,12 @@ from eventsourcing.utils import (
     strtobool,
 )
 
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
 
 class Transcoding(ABC):
-    """
-    Abstract base class for custom transcodings.
-    """
+    """Abstract base class for custom transcodings."""
 
     type: type
     name: str
@@ -54,20 +46,7 @@ class Transcoding(ABC):
 
 
 class Transcoder(ABC):
-    """
-    Abstract base class for transcoders.
-    """
-
-    def __init__(self) -> None:
-        self.types: Dict[type, Transcoding] = {}
-        self.names: Dict[str, Transcoding] = {}
-
-    def register(self, transcoding: Transcoding) -> None:
-        """
-        Registers given transcoding with the transcoder.
-        """
-        self.types[transcoding.type] = transcoding
-        self.names[transcoding.name] = transcoding
+    """Abstract base class for transcoders."""
 
     @abstractmethod
     def encode(self, obj: Any) -> bytes:
@@ -78,13 +57,16 @@ class Transcoder(ABC):
         """Decodes obj from bytes."""
 
 
+class TranscodingNotRegisteredError(EventSourcingError, TypeError):
+    """Raised when a transcoding isn't registered with JSONTranscoder."""
+
+
 class JSONTranscoder(Transcoder):
-    """
-    Extensible transcoder that uses the Python :mod:`json` module.
-    """
+    """Extensible transcoder that uses the Python :mod:`json` module."""
 
     def __init__(self) -> None:
-        super().__init__()
+        self.types: dict[type, Transcoding] = {}
+        self.names: dict[str, Transcoding] = {}
         self.encoder = json.JSONEncoder(
             default=self._encode_obj,
             separators=(",", ":"),
@@ -92,19 +74,20 @@ class JSONTranscoder(Transcoder):
         )
         self.decoder = json.JSONDecoder(object_hook=self._decode_obj)
 
+    def register(self, transcoding: Transcoding) -> None:
+        """Registers given transcoding with the transcoder."""
+        self.types[transcoding.type] = transcoding
+        self.names[transcoding.name] = transcoding
+
     def encode(self, obj: Any) -> bytes:
-        """
-        Encodes given object as a bytes array.
-        """
+        """Encodes given object as a bytes array."""
         return self.encoder.encode(obj).encode("utf8")
 
     def decode(self, data: bytes) -> Any:
-        """
-        Decodes bytes array as previously encoded object.
-        """
+        """Decodes bytes array as previously encoded object."""
         return self.decoder.decode(data.decode("utf8"))
 
-    def _encode_obj(self, o: Any) -> Dict[str, Any]:
+    def _encode_obj(self, o: Any) -> dict[str, Any]:
         try:
             transcoding = self.types[type(o)]
         except KeyError:
@@ -113,14 +96,14 @@ class JSONTranscoder(Transcoder):
                 "serializable. Please define and register "
                 "a custom transcoding for this type."
             )
-            raise TypeError(msg) from None
+            raise TranscodingNotRegisteredError(msg) from None
         else:
             return {
                 "_type_": transcoding.name,
                 "_data_": transcoding.encode(o),
             }
 
-    def _decode_obj(self, d: Dict[str, Any]) -> Any:
+    def _decode_obj(self, d: dict[str, Any]) -> Any:
         if len(d) == 2:
             try:
                 _type_ = d["_type_"]
@@ -133,14 +116,14 @@ class JSONTranscoder(Transcoder):
                     return d
                 else:
                     try:
-                        transcoding = self.names[cast(str, _type_)]
+                        transcoding = self.names[cast("str", _type_)]
                     except KeyError as e:
                         msg = (
-                            f"Data serialized with name '{cast(str, _type_)}' is not "
+                            f"Data serialized with name '{cast('str', _type_)}' is not "
                             "deserializable. Please register a "
                             "custom transcoding for this type."
                         )
-                        raise TypeError(msg) from e
+                        raise TranscodingNotRegisteredError(msg) from e
                     else:
                         return transcoding.decode(_data_)
         else:
@@ -148,9 +131,7 @@ class JSONTranscoder(Transcoder):
 
 
 class UUIDAsHex(Transcoding):
-    """
-    Transcoding that represents :class:`UUID` objects as hex values.
-    """
+    """Transcoding that represents :class:`UUID` objects as hex values."""
 
     type = UUID
     name = "uuid_hex"
@@ -164,9 +145,7 @@ class UUIDAsHex(Transcoding):
 
 
 class DecimalAsStr(Transcoding):
-    """
-    Transcoding that represents :class:`Decimal` objects as strings.
-    """
+    """Transcoding that represents :class:`Decimal` objects as strings."""
 
     type = Decimal
     name = "decimal_str"
@@ -179,9 +158,7 @@ class DecimalAsStr(Transcoding):
 
 
 class DatetimeAsISO(Transcoding):
-    """
-    Transcoding that represents :class:`datetime` objects as ISO strings.
-    """
+    """Transcoding that represents :class:`datetime` objects as ISO strings."""
 
     type = datetime
     name = "datetime_iso"
@@ -196,70 +173,55 @@ class DatetimeAsISO(Transcoding):
 
 @dataclass(frozen=True)
 class StoredEvent:
-    """
-    Frozen dataclass that represents :class:`~eventsourcing.domain.DomainEvent`
+    """Frozen dataclass that represents :class:`~eventsourcing.domain.DomainEvent`
     objects, such as aggregate :class:`~eventsourcing.domain.Aggregate.Event`
     objects and :class:`~eventsourcing.domain.Snapshot` objects.
-
-    Constructor parameters:
-
-    :param UUID originator_id: ID of the originating aggregate
-    :param int originator_version: version of the originating aggregate
-    :param str topic: topic of the domain event object class
-    :param bytes state: serialised state of the domain event object
     """
 
     originator_id: uuid.UUID
+    """ID of the originating aggregate."""
     originator_version: int
+    """Position in an aggregate sequence."""
     topic: str
+    """Topic of a domain event object class."""
     state: bytes
+    """Serialised state of a domain event object."""
 
 
 class Compressor(ABC):
-    """
-    Base class for compressors.
-    """
+    """Base class for compressors."""
 
     @abstractmethod
     def compress(self, data: bytes) -> bytes:
-        """
-        Compress bytes.
-        """
+        """Compress bytes."""
 
     @abstractmethod
     def decompress(self, data: bytes) -> bytes:
-        """
-        Decompress bytes.
-        """
+        """Decompress bytes."""
 
 
 class Cipher(ABC):
-    """
-    Base class for ciphers.
-    """
+    """Base class for ciphers."""
 
     @abstractmethod
     def __init__(self, environment: Environment):
-        """
-        Initialises cipher with given environment.
-        """
+        """Initialises cipher with given environment."""
 
     @abstractmethod
     def encrypt(self, plaintext: bytes) -> bytes:
-        """
-        Return ciphertext for given plaintext.
-        """
+        """Return ciphertext for given plaintext."""
 
     @abstractmethod
     def decrypt(self, ciphertext: bytes) -> bytes:
-        """
-        Return plaintext for given ciphertext.
-        """
+        """Return plaintext for given ciphertext."""
+
+
+class MapperDeserialisationError(EventSourcingError, ValueError):
+    """Raised when deserialization fails in a Mapper."""
 
 
 class Mapper:
-    """
-    Converts between domain event objects and :class:`StoredEvent` objects.
+    """Converts between domain event objects and :class:`StoredEvent` objects.
 
     Uses a :class:`Transcoder`, and optionally a cryptographic cipher and compressor.
     """
@@ -275,9 +237,7 @@ class Mapper:
         self.cipher = cipher
 
     def to_stored_event(self, domain_event: DomainEventProtocol) -> StoredEvent:
-        """
-        Converts the given domain event to a :class:`StoredEvent` object.
-        """
+        """Converts the given domain event to a :class:`StoredEvent` object."""
         topic = get_topic(domain_event.__class__)
         event_state = domain_event.__dict__.copy()
         originator_id = event_state.pop("originator_id")
@@ -297,25 +257,24 @@ class Mapper:
             state=stored_state,
         )
 
-    def from_domain_event(self, domain_event: DomainEventProtocol) -> StoredEvent:
-        warn(
-            "'from_domain_event()' is deprecated, use 'to_stored_event()' instead",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-        return self.to_stored_event(domain_event)
-
     def to_domain_event(self, stored_event: StoredEvent) -> DomainEventProtocol:
-        """
-        Converts the given :class:`StoredEvent` to a domain event object.
-        """
+        """Converts the given :class:`StoredEvent` to a domain event object."""
         stored_state = stored_event.state
-        if self.cipher:
-            stored_state = self.cipher.decrypt(stored_state)
-        if self.compressor:
-            stored_state = self.compressor.decompress(stored_state)
-        event_state: Dict[str, Any] = self.transcoder.decode(stored_state)
+        try:
+            if self.cipher:
+                stored_state = self.cipher.decrypt(stored_state)
+            if self.compressor:
+                stored_state = self.compressor.decompress(stored_state)
+            event_state: dict[str, Any] = self.transcoder.decode(stored_state)
+        except Exception as e:
+            msg = (
+                f"Failed to deserialise state of stored event with "
+                f"topic '{stored_event.topic}', "
+                f"originator_id '{stored_event.originator_id}' and "
+                f"originator_version {stored_event.originator_version}: {e}"
+            )
+            raise MapperDeserialisationError(msg) from e
+
         event_state["originator_id"] = stored_event.originator_id
         event_state["originator_version"] = stored_event.originator_version
         cls = resolve_topic(stored_event.topic)
@@ -331,42 +290,34 @@ class Mapper:
 
 
 class RecordConflictError(EventSourcingError):
-    """
-    Legacy exception, replaced with IntegrityError.
-    """
+    """Legacy exception, replaced with IntegrityError."""
 
 
 class PersistenceError(EventSourcingError):
-    """
-    The base class of the other exceptions in this module.
+    """The base class of the other exceptions in this module.
 
     Exception class names follow https://www.python.org/dev/peps/pep-0249/#exceptions
     """
 
 
 class InterfaceError(PersistenceError):
-    """
-    Exception raised for errors that are related to the database
+    """Exception raised for errors that are related to the database
     interface rather than the database itself.
     """
 
 
 class DatabaseError(PersistenceError):
-    """
-    Exception raised for errors that are related to the database.
-    """
+    """Exception raised for errors that are related to the database."""
 
 
 class DataError(DatabaseError):
-    """
-    Exception raised for errors that are due to problems with the
+    """Exception raised for errors that are due to problems with the
     processed data like division by zero, numeric value out of range, etc.
     """
 
 
 class OperationalError(DatabaseError):
-    """
-    Exception raised for errors that are related to the database's
+    """Exception raised for errors that are related to the database's
     operation and not necessarily under the control of the programmer,
     e.g. an unexpected disconnect occurs, the data source name is not
     found, a transaction could not be processed, a memory allocation
@@ -375,50 +326,49 @@ class OperationalError(DatabaseError):
 
 
 class IntegrityError(DatabaseError, RecordConflictError):
-    """
-    Exception raised when the relational integrity of the
+    """Exception raised when the relational integrity of the
     database is affected, e.g. a foreign key check fails.
     """
 
 
 class InternalError(DatabaseError):
-    """
-    Exception raised when the database encounters an internal
+    """Exception raised when the database encounters an internal
     error, e.g. the cursor is not valid anymore, the transaction
     is out of sync, etc.
     """
 
 
 class ProgrammingError(DatabaseError):
-    """
-    Exception raised for database programming errors, e.g. table
+    """Exception raised for database programming errors, e.g. table
     not found or already exists, syntax error in the SQL statement,
     wrong number of parameters specified, etc.
     """
 
 
 class NotSupportedError(DatabaseError):
-    """
-    Exception raised in case a method or database API was used
+    """Exception raised in case a method or database API was used
     which is not supported by the database, e.g. calling the
     rollback() method on a connection that does not support
     transaction or has transactions turned off.
     """
 
 
-class AggregateRecorder(ABC):
-    """
-    Abstract base class for recorders that record and
-    retrieve stored events for domain model aggregates.
-    """
+class WaitInterruptedError(PersistenceError):
+    """Raised when waiting for a tracking record is interrupted."""
+
+
+class Recorder:
+    pass
+
+
+class AggregateRecorder(Recorder, ABC):
+    """Abstract base class for inserting and selecting stored events."""
 
     @abstractmethod
     def insert_events(
-        self, stored_events: List[StoredEvent], **kwargs: Any
+        self, stored_events: list[StoredEvent], **kwargs: Any
     ) -> Sequence[int] | None:
-        """
-        Writes stored events into database.
-        """
+        """Writes stored events into database."""
 
     @abstractmethod
     def select_events(
@@ -429,90 +379,148 @@ class AggregateRecorder(ABC):
         lte: int | None = None,
         desc: bool = False,
         limit: int | None = None,
-    ) -> List[StoredEvent]:
-        """
-        Reads stored events from database.
-        """
+    ) -> list[StoredEvent]:
+        """Reads stored events from database."""
 
 
 @dataclass(frozen=True)
 class Notification(StoredEvent):
-    """
-    Frozen dataclass that represents domain event notifications.
-    """
+    """Frozen dataclass that represents domain event notifications."""
 
     id: int
+    """Position in an application sequence."""
 
 
 class ApplicationRecorder(AggregateRecorder):
-    """
-    Abstract base class for recorders that record and
-    retrieve stored events for domain model aggregates.
-
-    Extends the behaviour of aggregate recorders by
-    recording aggregate events in a total order that
-    allows the stored events also to be retrieved
-    as event notifications.
+    """Abstract base class for recording events in both aggregate
+    and application sequences.
     """
 
     @abstractmethod
     def select_notifications(
         self,
-        start: int,
+        start: int | None,
         limit: int,
         stop: int | None = None,
         topics: Sequence[str] = (),
-    ) -> List[Notification]:
-        """
-        Returns a list of event notifications
-        from 'start', limited by 'limit' and
-        optionally by 'stop'.
+        *,
+        inclusive_of_start: bool = True,
+    ) -> list[Notification]:
+        """Returns a list of Notification objects representing events from an
+        application sequence. If `inclusive_of_start` is True (the default),
+        the returned Notification objects will have IDs greater than or equal
+        to `start` and less than or equal to `stop`. If `inclusive_of_start`
+        is False, the Notification objects will have IDs greater than `start`
+        and less than or equal to `stop`.
         """
 
     @abstractmethod
-    def max_notification_id(self) -> int:
+    def max_notification_id(self) -> int | None:
+        """Returns the largest notification ID in an application sequence,
+        or None if no stored events have been recorded.
         """
-        Returns the maximum notification ID.
+
+    @abstractmethod
+    def subscribe(
+        self, gt: int | None = None, topics: Sequence[str] = ()
+    ) -> Subscription[ApplicationRecorder]:
+        """Returns an iterator of Notification objects representing events from an
+        application sequence.
+
+        The iterator will block after the last recorded event has been yielded, but
+        will then continue yielding newly recorded events when they are recorded.
+
+        Notifications will have IDs greater than the optional `gt` argument.
         """
 
 
-class ProcessRecorder(ApplicationRecorder):
+class TrackingRecorder(Recorder, ABC):
+    """Abstract base class for recorders that record tracking
+    objects atomically with other state.
     """
-    Abstract base class for recorders that record and
-    retrieve stored events for domain model aggregates.
 
-    Extends the behaviour of applications recorders by
-    recording aggregate events with tracking information
-    that records the position of a processed event
-    notification in a notification log.
-    """
+    @abstractmethod
+    def insert_tracking(self, tracking: Tracking) -> None:
+        """Records a tracking object."""
 
     @abstractmethod
-    def max_tracking_id(self, application_name: str) -> int:
-        """
-        Returns the largest notification ID across all tracking records
-        for the named application. Returns zero if there are no tracking
-        records.
+    def max_tracking_id(self, application_name: str) -> int | None:
+        """Returns the largest notification ID across all recorded tracking objects
+        for the named application, or None if no tracking objects have been recorded.
         """
 
     @abstractmethod
-    def has_tracking_id(self, application_name: str, notification_id: int) -> bool:
-        """
-        Returns true if a tracking record with the given application name
-        and notification ID exists, otherwise returns false.
+    def has_tracking_id(
+        self, application_name: str, notification_id: int | None
+    ) -> bool:
+        """Returns True if a tracking object with the given application name
+        and notification ID has been recorded, and True if given notification_id is
+        None, otherwise returns False.
         """
 
+    def wait(
+        self,
+        application_name: str,
+        notification_id: int | None,
+        timeout: float = 1.0,
+        interrupt: Event | None = None,
+    ) -> None:
+        """Block until a tracking object with the given application name and a
+        notification ID greater than equal to the given value has been recorded.
+
+        Polls max_tracking_id() with exponential backoff until the timeout
+        is reached, or until the optional interrupt event is set.
+
+        The timeout argument should be a floating point number specifying a
+        timeout for the operation in seconds (or fractions thereof). The default
+        is 1.0 seconds.
+
+        Raises TimeoutError if the timeout is reached.
+
+        Raises WaitInterruptError if the `interrupt` is set before `timeout` is reached.
+        """
+        deadline = monotonic() + timeout
+        sleep_interval_ms = 100.0
+        max_sleep_interval_ms = 800.0
+        while True:
+            max_tracking_id = self.max_tracking_id(application_name)
+            if notification_id is None or (
+                max_tracking_id is not None and max_tracking_id >= notification_id
+            ):
+                break
+            if interrupt:
+                if interrupt.wait(timeout=sleep_interval_ms / 1000):
+                    raise WaitInterruptedError
+            else:
+                sleep(sleep_interval_ms / 1000)
+            remaining = deadline - monotonic()
+            if remaining < 0:
+                msg = (
+                    f"Timed out waiting for notification {notification_id} "
+                    f"from application '{application_name}' to be processed"
+                )
+                raise TimeoutError(msg)
+            sleep_interval_ms = min(
+                sleep_interval_ms * 2, remaining * 1000, max_sleep_interval_ms
+            )
+
+
+class ProcessRecorder(TrackingRecorder, ApplicationRecorder, ABC):
+    pass
+
 
 @dataclass(frozen=True)
 class Recording:
+    """Represents the recording of a domain event."""
+
     domain_event: DomainEventProtocol
+    """The domain event that has been recorded."""
     notification: Notification
+    """A Notification that represents the domain event in the application sequence."""
 
 
 class EventStore:
-    """
-    Stores and retrieves domain events.
-    """
+    """Stores and retrieves domain events."""
 
     def __init__(
         self,
@@ -524,10 +532,8 @@ class EventStore:
 
     def put(
         self, domain_events: Sequence[DomainEventProtocol], **kwargs: Any
-    ) -> List[Recording]:
-        """
-        Stores domain events in aggregate sequence.
-        """
+    ) -> list[Recording]:
+        """Stores domain events in aggregate sequence."""
         stored_events = list(map(self.mapper.to_stored_event, domain_events))
         recordings = []
         notification_ids = self.recorder.insert_events(stored_events, **kwargs)
@@ -557,9 +563,7 @@ class EventStore:
         desc: bool = False,
         limit: int | None = None,
     ) -> Iterator[DomainEventProtocol]:
-        """
-        Retrieves domain events from aggregate sequence.
-        """
+        """Retrieves domain events from aggregate sequence."""
         return map(
             self.mapper.to_domain_event,
             self.recorder.select_events(
@@ -572,32 +576,40 @@ class EventStore:
         )
 
 
-TInfrastructureFactory = TypeVar(
-    "TInfrastructureFactory", bound="InfrastructureFactory"
+TTrackingRecorder = TypeVar(
+    "TTrackingRecorder", bound=TrackingRecorder, default=TrackingRecorder
 )
 
 
-class InfrastructureFactory(ABC):
-    """
-    Abstract base class for infrastructure factories.
-    """
+class InfrastructureFactoryError(EventSourcingError):
+    """Raised when an infrastructure factory cannot be created."""
+
+
+class InfrastructureFactory(ABC, Generic[TTrackingRecorder]):
+    """Abstract base class for infrastructure factories."""
 
     PERSISTENCE_MODULE = "PERSISTENCE_MODULE"
+    TRANSCODER_TOPIC = "TRANSCODER_TOPIC"
     MAPPER_TOPIC = "MAPPER_TOPIC"
     CIPHER_TOPIC = "CIPHER_TOPIC"
     COMPRESSOR_TOPIC = "COMPRESSOR_TOPIC"
     IS_SNAPSHOTTING_ENABLED = "IS_SNAPSHOTTING_ENABLED"
+    APPLICATION_RECORDER_TOPIC = "APPLICATION_RECORDER_TOPIC"
+    TRACKING_RECORDER_TOPIC = "TRACKING_RECORDER_TOPIC"
+    PROCESS_RECORDER_TOPIC = "PROCESS_RECORDER_TOPIC"
 
     @classmethod
     def construct(
-        cls: Type[TInfrastructureFactory], env: Environment
-    ) -> TInfrastructureFactory:
-        """
-        Constructs concrete infrastructure factory for given
+        cls: type[InfrastructureFactory[TTrackingRecorder]],
+        env: Environment | None = None,
+    ) -> InfrastructureFactory[TTrackingRecorder]:
+        """Constructs concrete infrastructure factory for given
         named application. Reads and resolves persistence
         topic from environment variable 'PERSISTENCE_MODULE'.
         """
-        factory_cls: Type[InfrastructureFactory]
+        factory_cls: type[InfrastructureFactory[TTrackingRecorder]]
+        if env is None:
+            env = Environment()
         topic = (
             env.get(
                 cls.PERSISTENCE_MODULE,
@@ -614,26 +626,33 @@ class InfrastructureFactory(ABC):
             or "eventsourcing.popo"
         )
         try:
-            obj: Type[InfrastructureFactory] | ModuleType = resolve_topic(topic)
+            obj: type[InfrastructureFactory[TTrackingRecorder]] | ModuleType = (
+                resolve_topic(topic)
+            )
         except TopicError as e:
             msg = (
                 "Failed to resolve persistence module topic: "
                 f"'{topic}' from environment "
                 f"variable '{cls.PERSISTENCE_MODULE}'"
             )
-            raise OSError(msg) from e
+            raise InfrastructureFactoryError(msg) from e
 
         if isinstance(obj, ModuleType):
             # Find the factory in the module.
-            factory_classes: List[Type[InfrastructureFactory]] = [
-                member
-                for member in obj.__dict__.values()
+            factory_classes: list[type[InfrastructureFactory[TTrackingRecorder]]] = []
+            for member in obj.__dict__.values():
                 if (
                     member is not InfrastructureFactory
-                    and isinstance(member, type)
-                    and issubclass(member, InfrastructureFactory)
-                )
-            ]
+                    and isinstance(member, type)  # Look for classes...
+                    and isinstance(member, type)  # Look for classes...
+                    and not isinstance(
+                        member, GenericAlias
+                    )  # Issue with Python 3.9 and 3.10.
+                    and issubclass(member, InfrastructureFactory)  # Ignore base class.
+                    and member not in factory_classes  # Forgive aliases.
+                ):
+                    factory_classes.append(member)
+
             if len(factory_classes) == 1:
                 factory_cls = factory_classes[0]
             else:
@@ -641,45 +660,51 @@ class InfrastructureFactory(ABC):
                     f"Found {len(factory_classes)} infrastructure factory classes in"
                     f" '{topic}', expected 1."
                 )
-                raise AssertionError(msg)
+                raise InfrastructureFactoryError(msg)
         elif isinstance(obj, type) and issubclass(obj, InfrastructureFactory):
             factory_cls = obj
         else:
-            msg = f"Not an infrastructure factory class or module: {topic}"
-            raise AssertionError(msg)
-        return cast(TInfrastructureFactory, factory_cls(env=env))
+            msg = (
+                f"Topic '{topic}' didn't resolve to a persistence module "
+                f"or infrastructure factory class: {obj}"
+            )
+            raise InfrastructureFactoryError(msg)
+        return factory_cls(env=env)
 
     def __init__(self, env: Environment):
-        """
-        Initialises infrastructure factory object with given application name.
-        """
+        """Initialises infrastructure factory object with given application name."""
         self.env = env
 
     def transcoder(
         self,
     ) -> Transcoder:
-        """
-        Constructs a transcoder.
-        """
-        # TODO: Implement support for TRANSCODER_TOPIC.
-        return JSONTranscoder()
+        """Constructs a transcoder."""
+        transcoder_topic = self.env.get(self.TRANSCODER_TOPIC)
+        if transcoder_topic:
+            transcoder_class: type[Transcoder] = resolve_topic(transcoder_topic)
+        else:
+            transcoder_class = JSONTranscoder
+        return transcoder_class()
 
     def mapper(
-        self, transcoder: Transcoder, mapper_class: Type[Mapper] = Mapper
+        self,
+        transcoder: Transcoder | None = None,
+        mapper_class: type[Mapper] | None = None,
     ) -> Mapper:
-        """
-        Constructs a mapper.
-        """
-        # TODO: Implement support for MAPPER_TOPIC.
+        """Constructs a mapper."""
+        if mapper_class is None:
+            mapper_topic = self.env.get(self.MAPPER_TOPIC)
+            mapper_class = resolve_topic(mapper_topic) if mapper_topic else Mapper
+
+        assert isinstance(mapper_class, type) and issubclass(mapper_class, Mapper)
         return mapper_class(
-            transcoder=transcoder,
+            transcoder=transcoder or self.transcoder(),
             cipher=self.cipher(),
             compressor=self.compressor(),
         )
 
     def cipher(self) -> Cipher | None:
-        """
-        Reads environment variables 'CIPHER_TOPIC'
+        """Reads environment variables 'CIPHER_TOPIC'
         and 'CIPHER_KEY' to decide whether or not
         to construct a cipher.
         """
@@ -690,20 +715,19 @@ class InfrastructureFactory(ABC):
             cipher_topic = default_cipher_topic
 
         if cipher_topic:
-            cipher_cls: Type[Cipher] = resolve_topic(cipher_topic)
+            cipher_cls: type[Cipher] = resolve_topic(cipher_topic)
             cipher = cipher_cls(self.env)
 
         return cipher
 
     def compressor(self) -> Compressor | None:
-        """
-        Reads environment variable 'COMPRESSOR_TOPIC' to
+        """Reads environment variable 'COMPRESSOR_TOPIC' to
         decide whether or not to construct a compressor.
         """
         compressor: Compressor | None = None
         compressor_topic = self.env.get(self.COMPRESSOR_TOPIC)
         if compressor_topic:
-            compressor_cls: Type[Compressor] | Compressor = resolve_topic(
+            compressor_cls: type[Compressor] | Compressor = resolve_topic(
                 compressor_topic
             )
             if isinstance(compressor_cls, type):
@@ -712,49 +736,49 @@ class InfrastructureFactory(ABC):
                 compressor = compressor_cls
         return compressor
 
-    @staticmethod
-    def event_store(**kwargs: Any) -> EventStore:
-        """
-        Constructs an event store.
-        """
-        return EventStore(**kwargs)
+    def event_store(
+        self,
+        mapper: Mapper | None = None,
+        recorder: AggregateRecorder | None = None,
+    ) -> EventStore:
+        """Constructs an event store."""
+        return EventStore(
+            mapper=mapper or self.mapper(),
+            recorder=recorder or self.application_recorder(),
+        )
 
     @abstractmethod
     def aggregate_recorder(self, purpose: str = "events") -> AggregateRecorder:
-        """
-        Constructs an aggregate recorder.
-        """
+        """Constructs an aggregate recorder."""
 
     @abstractmethod
     def application_recorder(self) -> ApplicationRecorder:
-        """
-        Constructs an application recorder.
-        """
+        """Constructs an application recorder."""
+
+    @abstractmethod
+    def tracking_recorder(
+        self, tracking_recorder_class: type[TTrackingRecorder] | None = None
+    ) -> TTrackingRecorder:
+        """Constructs a tracking recorder."""
 
     @abstractmethod
     def process_recorder(self) -> ProcessRecorder:
-        """
-        Constructs a process recorder.
-        """
+        """Constructs a process recorder."""
 
     def is_snapshotting_enabled(self) -> bool:
-        """
-        Decides whether or not snapshotting is enabled by
+        """Decides whether or not snapshotting is enabled by
         reading environment variable 'IS_SNAPSHOTTING_ENABLED'.
         Snapshotting is not enabled by default.
         """
         return strtobool(self.env.get(self.IS_SNAPSHOTTING_ENABLED, "no"))
 
     def close(self) -> None:
-        """
-        Closes any database connections, or anything else that needs closing.
-        """
+        """Closes any database connections, and anything else that needs closing."""
 
 
 @dataclass(frozen=True)
 class Tracking:
-    """
-    Frozen dataclass representing the position of a domain
+    """Frozen dataclass representing the position of a domain
     event :class:`Notification` in an application's notification log.
     """
 
@@ -841,20 +865,15 @@ TConnection = TypeVar("TConnection", bound=Connection[Any])
 
 
 class ConnectionPoolClosedError(EventSourcingError):
-    """
-    Raised when using a connection pool that is already closed.
-    """
+    """Raised when using a connection pool that is already closed."""
 
 
 class ConnectionNotFromPoolError(EventSourcingError):
-    """
-    Raised when putting a connection in the wrong pool.
-    """
+    """Raised when putting a connection in the wrong pool."""
 
 
 class ConnectionUnavailableError(OperationalError, TimeoutError):
-    """
-    Raised when a request to get a connection from a
+    """Raised when a request to get a connection from a
     connection pool times out.
     """
 
@@ -870,8 +889,7 @@ class ConnectionPool(ABC, Generic[TConnection]):
         pre_ping: bool = False,
         mutually_exclusive_read_write: bool = False,
     ) -> None:
-        """
-        Initialises a new connection pool.
+        """Initialises a new connection pool.
 
         The 'pool_size' argument specifies the maximum number of connections
         that will be put into the pool when connections are returned. The
@@ -906,7 +924,7 @@ class ConnectionPool(ABC, Generic[TConnection]):
         self.max_age = max_age
         self.pre_ping = pre_ping
         self._pool: deque[TConnection] = deque()
-        self._in_use: Dict[int, TConnection] = {}
+        self._in_use: dict[int, TConnection] = {}
         self._get_semaphore = Semaphore()
         self._put_condition = Condition()
         self._no_readers = Condition()
@@ -922,9 +940,7 @@ class ConnectionPool(ABC, Generic[TConnection]):
 
     @property
     def num_in_use(self) -> int:
-        """
-        Indicates the total number of connections currently in use.
-        """
+        """Indicates the total number of connections currently in use."""
         with self._put_condition:
             return self._num_in_use
 
@@ -934,9 +950,7 @@ class ConnectionPool(ABC, Generic[TConnection]):
 
     @property
     def num_in_pool(self) -> int:
-        """
-        Indicates the number of connections currently in the pool.
-        """
+        """Indicates the number of connections currently in the pool."""
         with self._put_condition:
             return self._num_in_pool
 
@@ -955,8 +969,7 @@ class ConnectionPool(ABC, Generic[TConnection]):
     def get_connection(
         self, timeout: float | None = None, is_writer: bool | None = None
     ) -> TConnection:
-        """
-        Issues connections, or raises ConnectionPoolExhausted error.
+        """Issues connections, or raises ConnectionPoolExhausted error.
         Provides "fairness" on attempts to get connections, meaning that
         connections are issued in the same order as they are requested.
 
@@ -1040,8 +1053,7 @@ class ConnectionPool(ABC, Generic[TConnection]):
             raise ConnectionUnavailableError(msg)
 
     def _get_connection(self, timeout: float = 0.0) -> TConnection:
-        """
-        Gets or creates connections from pool within given
+        """Gets or creates connections from pool within given
         time, otherwise raises a "pool exhausted" error.
 
         Waits for connections to be returned if the pool
@@ -1108,8 +1120,7 @@ class ConnectionPool(ABC, Generic[TConnection]):
             return conn
 
     def put_connection(self, conn: TConnection) -> None:
-        """
-        Returns connections to the pool, or closes connection
+        """Returns connections to the pool, or closes connection
         if the pool is full.
 
         Unlocks write lock after writer has returned, and
@@ -1118,7 +1129,6 @@ class ConnectionPool(ABC, Generic[TConnection]):
         Notifies waiters when connections have been returned,
         and when there are no longer any readers.
         """
-
         # Start forgetting if this connection was for reading or writing.
         is_writer, conn.is_writer = conn.is_writer, None
 
@@ -1165,8 +1175,7 @@ class ConnectionPool(ABC, Generic[TConnection]):
 
     @abstractmethod
     def _create_connection(self) -> TConnection:
-        """
-        Create a new connection.
+        """Create a new connection.
 
         Subclasses should implement this method by
         creating a database connection of the type
@@ -1174,9 +1183,7 @@ class ConnectionPool(ABC, Generic[TConnection]):
         """
 
     def close(self) -> None:
-        """
-        Close the connection pool.
-        """
+        """Close the connection pool."""
         with self._put_condition:
             if self._closed:
                 return
@@ -1197,3 +1204,121 @@ class ConnectionPool(ABC, Generic[TConnection]):
 
     def __del__(self) -> None:
         self.close()
+
+
+TApplicationRecorder_co = TypeVar(
+    "TApplicationRecorder_co", bound=ApplicationRecorder, covariant=True
+)
+
+
+class Subscription(Iterator[Notification], Generic[TApplicationRecorder_co]):
+    def __init__(
+        self,
+        recorder: TApplicationRecorder_co,
+        gt: int | None = None,
+        topics: Sequence[str] = (),
+    ) -> None:
+        self._recorder = recorder
+        self._last_notification_id = gt
+        self._topics = topics
+        self._has_been_entered = False
+        self._has_been_stopped = False
+
+    def __enter__(self) -> Self:
+        if self._has_been_entered:
+            msg = "Already entered subscription context manager"
+            raise ProgrammingError(msg)
+        self._has_been_entered = True
+        return self
+
+    def __exit__(self, *args: object, **kwargs: Any) -> None:
+        if not self._has_been_entered:
+            msg = "Not already entered subscription context manager"
+            raise ProgrammingError(msg)
+        self.stop()
+
+    def stop(self) -> None:
+        """Stops the subscription."""
+        self._has_been_stopped = True
+
+    def __iter__(self) -> Self:
+        return self
+
+    @abstractmethod
+    def __next__(self) -> Notification:
+        """Returns the next Notification object in the application sequence."""
+
+
+class ListenNotifySubscription(Subscription[TApplicationRecorder_co]):
+    def __init__(
+        self,
+        recorder: TApplicationRecorder_co,
+        gt: int | None = None,
+        topics: Sequence[str] = (),
+    ) -> None:
+        super().__init__(recorder=recorder, gt=gt, topics=topics)
+        self._select_limit = 500
+        self._notifications: list[Notification] = []
+        self._notifications_index: int = 0
+        self._notifications_queue: Queue[list[Notification]] = Queue(maxsize=10)
+        self._has_been_notified = Event()
+        self._thread_error: BaseException | None = None
+        self._pull_thread = Thread(target=self._loop_on_pull)
+        self._pull_thread.start()
+
+    def __exit__(self, *args: object, **kwargs: Any) -> None:
+        super().__exit__(*args, **kwargs)
+        self._pull_thread.join()
+
+    def stop(self) -> None:
+        """Stops the subscription."""
+        super().stop()
+        self._notifications_queue.put([])
+        self._has_been_notified.set()
+
+    def __next__(self) -> Notification:
+        # If necessary, get a new list of notifications from the recorder.
+        if (
+            self._notifications_index == len(self._notifications)
+            and not self._has_been_stopped
+        ):
+            self._notifications = self._notifications_queue.get()
+            self._notifications_index = 0
+
+        # Stop the iteration if necessary, maybe raise thread error.
+        if self._has_been_stopped or not self._notifications:
+            if self._thread_error is not None:
+                raise self._thread_error
+            raise StopIteration
+
+        # Return a notification from previously obtained list.
+        notification = self._notifications[self._notifications_index]
+        self._notifications_index += 1
+        return notification
+
+    def _loop_on_pull(self) -> None:
+        try:
+            self._pull()  # Already recorded events.
+            while not self._has_been_stopped:
+                self._has_been_notified.wait()
+                self._pull()  # Newly recorded events.
+        except BaseException as e:
+            if self._thread_error is None:
+                self._thread_error = e
+            self.stop()
+
+    def _pull(self) -> None:
+        while not self._has_been_stopped:
+            self._has_been_notified.clear()
+            notifications = self._recorder.select_notifications(
+                start=self._last_notification_id or 0,
+                limit=self._select_limit,
+                topics=self._topics,
+                inclusive_of_start=False,
+            )
+            if len(notifications) > 0:
+                # print("Putting", len(notifications), "notifications into queue")
+                self._notifications_queue.put(notifications)
+                self._last_notification_id = notifications[-1].id
+            if len(notifications) < self._select_limit:
+                break