python-event-sourcery 0.4.0a13__tar.gz → 0.4.0a15__tar.gz

{python_event_sourcery-0.4.0a13 → python_event_sourcery-0.4.0a15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-event-sourcery
-Version: 0.4.0a13
+Version: 0.4.0a15
 Summary: 
 License: MIT
 Author: Your Name
@@ -19,4 +19,5 @@ Requires-Dist: SQLAlchemy (>=2.0) ; extra == "sqlalchemy"
 Requires-Dist: django (>=4,<6) ; extra == "django"
 Requires-Dist: esdbclient (>=1.0b3) ; extra == "esdb"
 Requires-Dist: more-itertools
+Requires-Dist: psycopg2-binary (>2,<3)
 Requires-Dist: pydantic (>=2.0,<3)

{python_event_sourcery-0.4.0a13 → python_event_sourcery-0.4.0a15}/event_sourcery/event_store/__init__.py

@@ -1,30 +1,31 @@
 __all__ = [
+    "DEFAULT_TENANT",
+    "NO_VERSIONING",
     "Backend",
     "BackendFactory",
+    "Context",
     "Dispatcher",
     "Entry",
     "Event",
-    "Context",
     "EventRegistry",
     "EventStore",
     "ExplicitVersioning",
     "InMemoryBackendFactory",
     "Listener",
-    "WrappedEvent",
-    "NO_VERSIONING",
     "Position",
     "RawEvent",
     "Recorded",
     "RecordedRaw",
     "StreamId",
     "StreamUUID",
+    "TenantId",
     "TransactionalBackend",
     "Versioning",
+    "WrappedEvent",
     "exceptions",
     "factory",
     "interfaces",
     "subscription",
-    "TenantId",
 ]
 
 from event_sourcery.event_store import exceptions, factory, interfaces, subscription
@@ -48,7 +49,7 @@ from event_sourcery.event_store.factory import (
 )
 from event_sourcery.event_store.in_memory import InMemoryBackendFactory
 from event_sourcery.event_store.stream_id import StreamId, StreamUUID
-from event_sourcery.event_store.tenant_id import TenantId
+from event_sourcery.event_store.tenant_id import DEFAULT_TENANT, TenantId
 from event_sourcery.event_store.versioning import (
     NO_VERSIONING,
     ExplicitVersioning,

python_event_sourcery-0.4.0a15/event_sourcery/event_store/event/__init__.py

@@ -0,0 +1,32 @@
+__all__ = [
+    "Context",
+    "DataSubject",
+    "Encrypted",
+    "Encryption",
+    "Entry",
+    "Event",
+    "EventRegistry",
+    "Position",
+    "RawEvent",
+    "Recorded",
+    "RecordedRaw",
+    "Serde",
+    "WrappedEvent",
+]
+
+
+from event_sourcery.event_store.event._dto import (
+    Context,
+    DataSubject,
+    Encrypted,
+    Entry,
+    Event,
+    Position,
+    RawEvent,
+    Recorded,
+    RecordedRaw,
+    WrappedEvent,
+)
+from event_sourcery.event_store.event._encryption import Encryption
+from event_sourcery.event_store.event._registry import EventRegistry
+from event_sourcery.event_store.event._serde import Serde

python_event_sourcery-0.4.0a13/event_sourcery/event_store/event/dto.py → python_event_sourcery-0.4.0a15/event_sourcery/event_store/event/_dto.py

@@ -1,14 +1,16 @@
 import dataclasses
+from dataclasses import dataclass
 from datetime import datetime, timezone
-from typing import Any, ClassVar, Generic, TypeAlias, TypeVar
+from typing import Any, Generic, TypeAlias, TypeVar
 from uuid import UUID, uuid4
 
 from pydantic import BaseModel
 
-from event_sourcery.event_store.event.registry import EventRegistry
 from event_sourcery.event_store.stream_id import StreamId
 from event_sourcery.event_store.tenant_id import DEFAULT_TENANT, TenantId
 
+DataSubject = object()
+
 
 @dataclasses.dataclass(frozen=True)
 class RawEvent(BaseModel):
@@ -16,8 +18,8 @@ class RawEvent(BaseModel):
     stream_id: StreamId
     created_at: datetime
     name: str
-    data: dict
-    context: dict
+    data: dict[str, Any]
+    context: dict[str, Any]
     version: int | None = None
 
 
@@ -41,11 +43,6 @@ class Event(BaseModel, extra="forbid"):
     ```
     """
 
-    __registry__: ClassVar = EventRegistry()
-
-    def __init_subclass__(cls, **kwargs: Any) -> None:
-        cls.__registry__.add(cls)
-
 
 TEvent = TypeVar("TEvent", bound=Event)
 
@@ -86,11 +83,55 @@ class WrappedEvent(Generic[TEvent]):
 
 @dataclasses.dataclass(frozen=True)
 class Entry:
-    wrapped_event: WrappedEvent
+    wrapped_event: WrappedEvent[Event]
     stream_id: StreamId
 
 
 @dataclasses.dataclass(frozen=True)
 class Recorded(Entry):
+    """DTO containing events saved in the event store.
+
+    It contains position of the event in the event store and tenant id.
+    """
+
     position: Position
     tenant_id: TenantId = DEFAULT_TENANT
+
+
+@dataclass(frozen=True)
+class Encrypted:
+    """Field annotation for marking event fields that should be encrypted.
+
+    This annotation is used in combination with DataSubject to implement
+    crypto-shredding, allowing for GDPR-compliant data removal in event-sourced systems.
+
+    Args:
+        mask_value: Value to display when the data is shredded (deleted).
+                    Must match the field type.
+        subject_field: Optional. Name of the field containing the subject ID for this
+                      encrypted field. If not provided, the field marked with
+                      DataSubject will be used.
+
+    Example:
+        ```python
+        class UserRegistered(Event):
+            user_id: Annotated[str, DataSubject]
+            email: Annotated[str, Encrypted(mask_value="[REDACTED]")]
+            # Custom subject field
+            other_data: Annotated[
+                str,
+                Encrypted(
+                    mask_value="[HIDDEN]",
+                    subject_field="alternative_id",
+                ),
+            ]
+        ```
+
+    Note:
+        - Every event with encrypted fields must have exactly one DataSubject field.
+        - The mask_value type must match the field type.
+        - After shredding, the field will always return its mask_value.
+    """
+
+    mask_value: Any
+    subject_field: str | None = None

python_event_sourcery-0.4.0a15/event_sourcery/event_store/event/_encryption.py

@@ -0,0 +1,135 @@
+import json
+from collections import UserDict
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+from pydantic import BaseModel
+from typing_extensions import Self
+
+from event_sourcery.event_store.event._registry import EventRegistry
+from event_sourcery.event_store.exceptions import KeyNotFoundError, NoSubjectIdFound
+from event_sourcery.event_store.interfaces import (
+    EncryptionKeyStorageStrategy,
+    EncryptionStrategy,
+)
+from event_sourcery.event_store.stream_id import StreamId
+from event_sourcery.event_store.tenant_id import TenantId
+
+
+class NoEncryptionStrategy(EncryptionStrategy):
+    def encrypt(self, data: Any, key: bytes) -> str:
+        raise NotImplementedError("NoEncryptionStrategy does not support encryption.")
+
+    def decrypt(self, data: str, key: bytes) -> Any:
+        raise NotImplementedError("NoEncryptionStrategy does not support decryption.")
+
+
+class NoKeyStorageStrategy(EncryptionKeyStorageStrategy):
+    def get(self, subject_id: str) -> bytes | None:
+        raise NotImplementedError(
+            "NoKeyStorageStrategy does not support key retrieval."
+        )
+
+    def store(self, subject_id: str, key: bytes) -> None:
+        raise NotImplementedError("NoKeyStorageStrategy does not support key storage.")
+
+    def delete(self, subject_id: str) -> None:
+        raise NotImplementedError("NoKeyStorageStrategy does not support key deletion.")
+
+    def scoped_for_tenant(self, tenant_id: TenantId) -> Self:
+        return self
+
+
+class NestedDict(UserDict):
+    def __getitem__(self, item: str) -> Any:
+        match item.split(".", 1):
+            case [prefix, key]:
+                return NestedDict(self.data[prefix])[key]
+            case _:
+                return self.data[item]
+
+    def __setitem__(self, item: str, value: Any) -> None:
+        match item.rsplit(".", 1):
+            case [prefix, key]:
+                self[prefix][key] = value
+            case _:
+                self.data[item] = value
+
+
+@dataclass
+class Encryption:
+    """
+    Integrates encryption logic and key management.
+    Uses the KeyStorageStrategy and EncryptionStrategy interfaces.
+    Responsible for:
+      - Retrieving the key for a given subject_id
+      - Encrypting and decrypting data
+      - Masking data when the key is not available (crypto-shredding)
+      - Processing event encryption/decryption with field annotations
+    """
+
+    registry: EventRegistry = field(default_factory=EventRegistry)
+    strategy: EncryptionStrategy = field(default_factory=NoEncryptionStrategy)
+    key_storage: EncryptionKeyStorageStrategy = field(
+        default_factory=NoKeyStorageStrategy
+    )
+
+    def encrypt(self, event: BaseModel, stream_id: StreamId) -> dict[str, Any]:
+        event_type = type(event)
+        data = NestedDict(event.model_dump(mode="json"))
+        for field_name in self.registry.encrypted_fields(of=event_type).keys():
+            subject_field = self.registry.subject_filed(field_name, of=event_type)
+            subject_id = (
+                subject_field and getattr(event, subject_field)
+            ) or stream_id.name
+
+            if subject_id is None:
+                raise NoSubjectIdFound(stream_id)
+            data[field_name] = self._encrypt_value(data[field_name], subject_id)
+        return data.data
+
+    def decrypt(
+        self,
+        event_type: type[BaseModel],
+        raw: dict[str, Any],
+        stream_id: StreamId,
+    ) -> dict[str, Any]:
+        data = NestedDict(raw)
+        encrypted_fields = self.registry.encrypted_fields(of=event_type)
+        for field_name, encrypted_config in encrypted_fields.items():
+            subject_field = self.registry.subject_filed(field_name, of=event_type)
+            subject_id = data[subject_field] if subject_field else stream_id.name or ""
+            data[field_name] = self._decrypt_value(
+                data[field_name],
+                subject_id,
+                encrypted_config.mask_value,
+            )
+        return data.data
+
+    def _decrypt_value(self, value: str, subject_id: str, mask_value: Any) -> Any:
+        key = self.key_storage.get(subject_id)
+        if key is None:
+            return mask_value
+        decrypted = self.strategy.decrypt(value, key)
+
+        try:
+            return json.loads(decrypted)
+        except (json.JSONDecodeError, TypeError):
+            return decrypted
+
+    def _encrypt_value(self, value: Any, subject_id: str) -> str:
+        key = self.key_storage.get(subject_id)
+        if key is None:
+            raise KeyNotFoundError(subject_id)
+        match value:
+            case str():
+                serialized = value
+            case _:
+                serialized = json.dumps(value)
+        return self.strategy.encrypt(serialized, key)
+
+    def shred(self, subject_id: str) -> None:
+        self.key_storage.delete(subject_id)
+
+    def scoped_for_tenant(self, tenant_id: TenantId) -> Self:
+        return replace(self, key_storage=self.key_storage.scoped_for_tenant(tenant_id))

python_event_sourcery-0.4.0a15/event_sourcery/event_store/event/_registry.py

@@ -0,0 +1,104 @@
+import inspect
+from typing import Annotated, TypeAlias, get_args, get_origin, get_type_hints
+
+from pydantic import BaseModel
+
+from event_sourcery.event_store.event._dto import DataSubject, Encrypted, Event
+from event_sourcery.event_store.exceptions import (
+    ClassModuleUnavailable,
+    DuplicatedEvent,
+)
+
+TEvent: TypeAlias = BaseModel
+
+
+def event_name(cls: type) -> str:
+    if name := getattr(cls, "__event_name__", ""):
+        return name
+
+    event_module = inspect.getmodule(cls)
+    if event_module is None:  # pragma: no cover
+        raise ClassModuleUnavailable
+    return f"{event_module.__name__}.{cls.__qualname__}"
+
+
+def get_encrypted_fields(of: type) -> dict[str, Encrypted]:
+    fields = {}
+    for field, hint in get_type_hints(of, include_extras=True).items():
+        if isinstance(hint, type):
+            fields.update(
+                {
+                    f"{field}.{nested}": encrypted
+                    for nested, encrypted in get_encrypted_fields(hint).items()
+                }
+            )
+        elif get_origin(hint) is Annotated:
+            _, *metadata = get_args(hint)
+            encrypted = next((m for m in metadata if isinstance(m, Encrypted)), None)
+            if encrypted:
+                fields[field] = encrypted
+    return fields
+
+
+def get_data_subject_filed(of: type[BaseModel]) -> str | None:
+    return next(
+        (
+            field_name
+            for field_name, field_info in of.model_fields.items()
+            if DataSubject in field_info.metadata
+        ),
+        None,
+    )
+
+
+class EventRegistry:
+    """Keeps mappings between event types and their names.
+
+    Normally, there is no need to use it directly. If one needs to have multiple
+    registries or wants more granular control, they can pass an instance
+    of EventRegistry to BackendFactory."""
+
+    def __init__(self) -> None:
+        self._types_to_names: dict[type[TEvent], str] = {}
+        self._names_to_types: dict[str, type[TEvent]] = {}
+        self._encrypted_fields: dict[type[TEvent], dict[str, Encrypted]] = {}
+        self._subject_fields: dict[type[TEvent], str] = {}
+        self._register_defined_events()
+
+    def _register_defined_events(self) -> None:
+        for event_type in Event.__subclasses__():
+            event_type not in self._types_to_names and self.add(event_type)
+
+    def add(self, event: type[TEvent]) -> type[TEvent]:
+        """Add event subclass to the registry."""
+        if event in self._types_to_names:
+            raise DuplicatedEvent(f"Duplicated Event detected! {event}")
+
+        name = event_name(event)
+        if name in self._names_to_types:
+            raise DuplicatedEvent(f"Duplicated Event name detected! {name}")
+
+        self._types_to_names[event] = name
+        self._names_to_types[name] = event
+        self._encrypted_fields[event] = get_encrypted_fields(of=event)
+        subject_field = get_data_subject_filed(of=event)
+        if subject_field is not None:
+            self._subject_fields[event] = subject_field
+        return event  # for use as a decorator
+
+    def type_for_name(self, name: str) -> type[TEvent]:
+        if name not in self._names_to_types:
+            self._register_defined_events()
+        return self._names_to_types[name]
+
+    def name_for_type(self, event: type[TEvent]) -> str:
+        if event not in self._types_to_names:
+            self._register_defined_events()
+        return self._types_to_names[event]
+
+    def encrypted_fields(self, of: type[TEvent]) -> dict[str, Encrypted]:
+        return self._encrypted_fields[of]
+
+    def subject_filed(self, for_field: str, of: type[TEvent]) -> str | None:
+        metadata = self._encrypted_fields[of].get(for_field)
+        return (metadata and metadata.subject_field) or self._subject_fields.get(of)

python_event_sourcery-0.4.0a13/event_sourcery/event_store/event/serde.py → python_event_sourcery-0.4.0a15/event_sourcery/event_store/event/_serde.py

@@ -1,23 +1,31 @@
 import dataclasses
 from collections.abc import Mapping, Sequence
-from dataclasses import dataclass
 from typing import cast
 
-from event_sourcery.event_store.event.dto import (
+from event_sourcery.event_store.event._dto import (
     Context,
-    Event,
     RawEvent,
     Recorded,
     RecordedRaw,
     WrappedEvent,
 )
-from event_sourcery.event_store.event.registry import EventRegistry
+from event_sourcery.event_store.event._encryption import Encryption
+from event_sourcery.event_store.event._registry import EventRegistry
 from event_sourcery.event_store.stream_id import StreamId
+from event_sourcery.event_store.tenant_id import TenantId
 
 
-@dataclass(repr=False, frozen=True)
 class Serde:
     registry: EventRegistry
+    encryption: Encryption
+
+    def __init__(
+        self,
+        registry: EventRegistry,
+        encryption: Encryption | None = None,
+    ) -> None:
+        self.registry = registry
+        self.encryption = encryption or Encryption(registry)
 
     def deserialize(self, event: RawEvent) -> WrappedEvent:
         event_as_dict = dataclasses.asdict(event)
@@ -27,9 +35,16 @@ class Serde:
         context = event_as_dict.pop("context", {})
         event_as_dict["context"] = Context(**context)
         event_type = self.registry.type_for_name(event.name)
+
+        processed_data = self.encryption.decrypt(
+            event_type,
+            dict(data),
+            event.stream_id,
+        )
+
         return WrappedEvent[event_type](  # type: ignore[valid-type]
             **event_as_dict,
-            event=event_type(**data),
+            event=event_type(**processed_data),
         )
 
     def deserialize_many(self, events: Sequence[RawEvent]) -> list[WrappedEvent]:
@@ -48,14 +63,13 @@ class Serde:
         event: WrappedEvent,
         stream_id: StreamId,
     ) -> RawEvent:
-        model = cast(Event, event.event)
         return RawEvent(
             uuid=event.uuid,
             stream_id=stream_id,
             created_at=event.created_at,
             version=event.version,
             name=self.registry.name_for_type(type(event.event)),
-            data=model.model_dump(mode="json"),
+            data=self.encryption.encrypt(event.event, stream_id),
             context=event.context.model_dump(mode="json"),
         )
 
@@ -63,3 +77,6 @@ class Serde:
         self, events: Sequence[WrappedEvent], stream_id: StreamId
     ) -> list[RawEvent]:
         return [self.serialize(event, stream_id) for event in events]
+
+    def scoped_for_tenant(self, tenant_id: TenantId) -> "Serde":
+        return Serde(self.registry, self.encryption.scoped_for_tenant(tenant_id))

{python_event_sourcery-0.4.0a13 → python_event_sourcery-0.4.0a15}/event_sourcery/event_store/event_store.py

@@ -206,5 +206,5 @@ class EventStore:
         """
         return EventStore(
             storage_strategy=self._storage_strategy.scoped_for_tenant(tenant_id),
-            serde=self._serde,
+            serde=self._serde.scoped_for_tenant(tenant_id),
         )

{python_event_sourcery-0.4.0a13 → python_event_sourcery-0.4.0a15}/event_sourcery/event_store/exceptions.py

@@ -47,3 +47,17 @@ class ClassModuleUnavailable(Exception):
 
 class DuplicatedEvent(Exception):
     pass
+
+
+class PrivacyError(EventStoreException):
+    pass
+
+
+@dataclass
+class KeyNotFoundError(PrivacyError):
+    subject_id: str
+
+
+@dataclass
+class NoSubjectIdFound(PrivacyError):
+    stream_id: UUID

{python_event_sourcery-0.4.0a13 → python_event_sourcery-0.4.0a15}/event_sourcery/event_store/factory.py

@@ -9,6 +9,8 @@ from event_sourcery.event_store.dispatcher import Dispatcher
 from event_sourcery.event_store.event import EventRegistry, RawEvent, RecordedRaw, Serde
 from event_sourcery.event_store.event_store import EventStore
 from event_sourcery.event_store.interfaces import (
+    EncryptionKeyStorageStrategy,
+    EncryptionStrategy,
     OutboxFiltererStrategy,
     OutboxStorageStrategy,
 )
@@ -55,3 +57,11 @@ class BackendFactory(abc.ABC):
     @abc.abstractmethod
     def without_outbox(self, filterer: OutboxFiltererStrategy = no_filter) -> Self:
         pass
+
+    @abc.abstractmethod
+    def with_encryption(
+        self,
+        strategy: EncryptionStrategy,
+        key_storage: EncryptionKeyStorageStrategy,
+    ) -> Self:
+        pass

{python_event_sourcery-0.4.0a13 → python_event_sourcery-0.4.0a15}/event_sourcery/event_store/in_memory.py

@@ -2,7 +2,7 @@ import time
 from collections.abc import Generator, Iterator
 from contextlib import AbstractContextManager, contextmanager
 from copy import copy
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from datetime import timedelta
 from operator import getitem
 
@@ -11,12 +11,17 @@ from typing_extensions import Self
 
 from event_sourcery.event_store import (
     Dispatcher,
-    Event,
     EventRegistry,
     EventStore,
     subscription,
 )
-from event_sourcery.event_store.event import Position, RawEvent, RecordedRaw, Serde
+from event_sourcery.event_store.event import (
+    Encryption,
+    Position,
+    RawEvent,
+    RecordedRaw,
+    Serde,
+)
 from event_sourcery.event_store.exceptions import ConcurrentStreamWriteError
 from event_sourcery.event_store.factory import (
     BackendFactory,
@@ -25,6 +30,8 @@ from event_sourcery.event_store.factory import (
     no_filter,
 )
 from event_sourcery.event_store.interfaces import (
+    EncryptionKeyStorageStrategy,
+    EncryptionStrategy,
     OutboxFiltererStrategy,
     OutboxStorageStrategy,
     StorageStrategy,
@@ -100,7 +107,7 @@ class InMemorySubscription(Iterator[list[RecordedRaw]]):
             record = self._pop_record()
             if record is not None:
                 batch.append(record)
-            time.sleep(0.1)
+            time.sleep(0.01)
             if time.monotonic() - start > self._timelimit.total_seconds():
                 break
 
@@ -311,7 +318,7 @@ class Config(BaseModel):
 class InMemoryBackendFactory(BackendFactory):
     """Lightweight in-memory backend factory for testing and development."""
 
-    serde = Serde(Event.__registry__)
+    serde = Serde(EventRegistry())
 
     _config: Config = field(default_factory=Config)
     _storage: Storage = field(default_factory=Storage)
@@ -357,3 +364,37 @@ class InMemoryBackendFactory(BackendFactory):
     def without_outbox(self, filterer: OutboxFiltererStrategy = no_filter) -> Self:
         self._outbox_strategy = None
         return self
+
+    def with_encryption(
+        self,
+        strategy: EncryptionStrategy,
+        key_storage: EncryptionKeyStorageStrategy,
+    ) -> Self:
+        registry = self.serde.registry
+        self.serde = Serde(
+            registry,
+            encryption=Encryption(
+                registry=registry,
+                strategy=strategy,
+                key_storage=key_storage,
+            ),
+        )
+        return self
+
+
+@dataclass
+class InMemoryKeyStorage(EncryptionKeyStorageStrategy):
+    _keys: dict[tuple[TenantId, str], bytes] = field(default_factory=dict)
+    _tenant_id: TenantId = DEFAULT_TENANT
+
+    def get(self, subject_id: str) -> bytes | None:
+        return self._keys.get((self._tenant_id, subject_id))
+
+    def store(self, subject_id: str, key: bytes) -> None:
+        self._keys[(self._tenant_id, subject_id)] = key
+
+    def delete(self, subject_id: str) -> None:
+        self._keys.pop((self._tenant_id, subject_id), None)
+
+    def scoped_for_tenant(self, tenant_id: TenantId) -> Self:
+        return replace(self, _tenant_id=tenant_id)

{python_event_sourcery-0.4.0a13 → python_event_sourcery-0.4.0a15}/event_sourcery/event_store/interfaces.py

@@ -2,12 +2,13 @@ import abc
 from collections.abc import Iterator
 from contextlib import AbstractContextManager
 from datetime import timedelta
-from typing import Protocol
+from typing import Any, Protocol
 
 from typing_extensions import Self
 
 from event_sourcery.event_store.event import Position, RawEvent, RecordedRaw
 from event_sourcery.event_store.stream_id import StreamId
+from event_sourcery.event_store.tenant_id import TenantId
 from event_sourcery.event_store.versioning import Versioning
 
 
@@ -86,3 +87,31 @@ class StorageStrategy(abc.ABC):
     @abc.abstractmethod
     def scoped_for_tenant(self, tenant_id: str) -> Self:
         pass
+
+
+class EncryptionKeyStorageStrategy(abc.ABC):
+    @abc.abstractmethod
+    def get(self, subject_id: str) -> bytes | None:
+        pass
+
+    @abc.abstractmethod
+    def store(self, subject_id: str, key: bytes) -> None:
+        pass
+
+    @abc.abstractmethod
+    def delete(self, subject_id: str) -> None:
+        pass
+
+    @abc.abstractmethod
+    def scoped_for_tenant(self, tenant_id: TenantId) -> Self:
+        pass
+
+
+class EncryptionStrategy(abc.ABC):
+    @abc.abstractmethod
+    def encrypt(self, data: Any, key: bytes) -> str:
+        pass
+
+    @abc.abstractmethod
+    def decrypt(self, data: str, key: bytes) -> Any:
+        pass