eventsourcingdb 0.8.2__py3-none-any.whl

eventsourcingdb/__init__.py

@@ -0,0 +1,2 @@
+from .client import Client as EsdbClient
+from .client_options import ClientOptions as EsdbClientOptions

eventsourcingdb/abstract_base_client.py

@@ -0,0 +1,9 @@
+from abc import ABC, abstractmethod
+from .http_client.http_client import HttpClient
+
+
+class AbstractBaseClient(ABC):
+    @property
+    @abstractmethod
+    def http_client(self) -> HttpClient:
+        raise NotImplementedError()

eventsourcingdb/client.py

@@ -0,0 +1,93 @@
+from collections.abc import AsyncGenerator
+
+from .abstract_base_client import AbstractBaseClient
+from .client_configuration import ClientConfiguration
+from .client_options import ClientOptions
+from .event.event_candidate import EventCandidate
+from .event.event_context import EventContext
+from .handlers.observe_events.observe_events import observe_events
+from .handlers.observe_events.observe_events_options import ObserveEventsOptions
+from .handlers.read_event_types.event_type import EventType
+from .handlers.read_event_types.read_event_types import read_event_types
+from .handlers.register_event_schema.register_event_schema import register_event_schema
+from .http_client.http_client import HttpClient
+from .handlers.ping import ping
+from .handlers.read_events import read_events, ReadEventsOptions
+from .handlers.read_subjects import read_subjects
+from .handlers.store_item import StoreItem
+from .handlers.write_events import Precondition, write_events
+
+
+# pylint: disable=R6007
+# Reason: This class explicitly specifies the return type as None
+# for better readability. Even though it is not necessary,
+# it makes the return type clear without needing to read any
+# documentation or code.
+class Client(AbstractBaseClient):
+    def __init__(
+        self,
+        base_url: str,
+        access_token: str,
+        options: ClientOptions = ClientOptions()
+    ):
+        configuration = ClientConfiguration(
+            base_url=base_url,
+            timeout_seconds=options.timeout_seconds,
+            access_token=access_token,
+            protocol_version=options.protocol_version,
+            max_tries=options.max_tries
+        )
+
+        self.__http_client = HttpClient(configuration)
+
+    async def initialize(self) -> None:
+        await self.__http_client.initialize()
+
+    async def close(self) -> None:
+        await self.__http_client.close()
+
+    @property
+    def http_client(self) -> HttpClient:
+        return self.__http_client
+
+    async def ping(self) -> None:
+        return await ping(self)
+
+    async def read_subjects(
+        self,
+        base_subject: str
+    ) -> AsyncGenerator[str, None]:
+        async for subject in read_subjects(self, base_subject):
+            yield subject
+
+    async def read_events(
+        self,
+        subject: str,
+        options: ReadEventsOptions
+    ) -> AsyncGenerator[StoreItem, None]:
+        async for event in read_events(self, subject, options):
+            yield event
+
+    async def read_event_types(self) -> AsyncGenerator[EventType, None]:
+        async for event_type in read_event_types(self):
+            yield event_type
+
+    async def register_event_schema(self, event_type: str, json_schema: str) -> None:
+        await register_event_schema(self, event_type, json_schema)
+
+    async def observe_events(
+        self,
+        subject: str,
+        options: ObserveEventsOptions
+    ) -> AsyncGenerator[StoreItem, None]:
+        async for event in observe_events(self, subject, options):
+            yield event
+
+    async def write_events(
+        self,
+        event_candidates: list[EventCandidate],
+        preconditions: list[Precondition] = None
+    ) -> list[EventContext]:
+        if preconditions is None:
+            preconditions = []
+        return await write_events(self, event_candidates, preconditions)

eventsourcingdb/client_configuration.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class ClientConfiguration:
+    base_url: str
+    timeout_seconds: int
+    access_token: str
+    protocol_version: str
+    max_tries: int

eventsourcingdb/client_options.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class ClientOptions:
+    timeout_seconds: int = 10
+    protocol_version: str = '1.0.0'
+    max_tries: int = 10

eventsourcingdb/errors/client_error.py

@@ -0,0 +1,6 @@
+from .custom_error import CustomError
+
+
+class ClientError(CustomError):
+    def __init__(self, cause: str):
+        super().__init__(f'Client error occurred: {cause}')

eventsourcingdb/errors/custom_error.py

@@ -0,0 +1,2 @@
+class CustomError(Exception):
+    pass

eventsourcingdb/errors/internal_error.py

@@ -0,0 +1,6 @@
+from .custom_error import CustomError
+
+
+class InternalError(CustomError):
+    def __init__(self, cause: str):
+        super().__init__(f'Internal error occurred: {cause}')

eventsourcingdb/errors/invalid_parameter_error.py

@@ -0,0 +1,7 @@
+from .custom_error import CustomError
+
+
+class InvalidParameterError(CustomError):
+    def __init__(self, parameter_name: str, reason: str):
+        super().__init__(
+            f'Parameter \'{parameter_name}\' is invalid: {reason}')

eventsourcingdb/errors/server_error.py

@@ -0,0 +1,6 @@
+from .custom_error import CustomError
+
+
+class ServerError(CustomError):
+    def __init__(self, cause: str):
+        super().__init__(f'Server error occurred: {cause}')

eventsourcingdb/errors/validation_error.py

@@ -0,0 +1,6 @@
+from .custom_error import CustomError
+
+
+class ValidationError(CustomError):
+    def __init__(self, cause: str):
+        super().__init__(f'Validation error occurred: {cause}')

eventsourcingdb/event/event.py

@@ -0,0 +1,71 @@
+from datetime import datetime
+from typing import TypeVar
+
+from ..errors.validation_error import ValidationError
+from .event_context import EventContext
+
+Self = TypeVar("Self", bound="Event")
+
+# pylint: disable=R0917
+# Reason: This class is expected to have many parameters
+# due to its business context. Splitting it into smaller
+# methods would increase cognitive load and make the
+# code less readable.
+class Event(EventContext):
+    def __init__(
+        self,
+        data: dict,
+        source: str,
+        subject: str,
+        event_type: str,
+        spec_version: str,
+        event_id: str,
+        time: datetime,
+        data_content_type: str,
+        predecessor_hash: str,
+        trace_parent: str = None,
+        trace_state: str = None
+    ):
+        super().__init__(
+            source,
+            subject,
+            event_type,
+            spec_version,
+            event_id,
+            time,
+            data_content_type,
+            predecessor_hash,
+            trace_parent,
+            trace_state
+        )
+        self.data = data
+
+    @staticmethod
+    def parse(unknown_object: dict) -> Self:
+        event_context = super(Event, Event).parse(unknown_object)
+
+        data = unknown_object.get('data')
+        if not isinstance(data, dict):
+            raise ValidationError(
+                f'Failed to parse data \'{data}\' to object.'
+            )
+
+        return Event(
+            data,
+            event_context.source,
+            event_context.subject,
+            event_context.type,
+            event_context.spec_version,
+            event_context.event_id,
+            event_context.time,
+            event_context.data_content_type,
+            event_context.predecessor_hash,
+            event_context.trace_parent,
+            event_context.trace_state
+        )
+
+    def to_json(self):
+        json = super().to_json()
+        json['data'] = self.data
+
+        return json

eventsourcingdb/event/event_candidate.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass
+
+from .validate_subject import validate_subject
+from .validate_type import validate_type
+
+
+@dataclass
+class EventCandidate:
+    source: str
+    subject: str
+    type: str
+    data: dict
+    trace_parent: str = None
+    trace_state: str = None
+
+    def validate(self) -> None:
+        validate_subject(self.subject)
+        validate_type(self.type)
+
+    def to_json(self):
+        json = {
+            'data': self.data,
+            'source': self.source,
+            'subject': self.subject,
+            'type': self.type
+        }
+
+        if self.trace_parent is not None:
+            json['traceparent'] = self.trace_parent
+        if self.trace_state is not None:
+            json['tracestate'] = self.trace_state
+
+        return json

eventsourcingdb/event/event_context.py

@@ -0,0 +1,120 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TypeVar
+
+from ..errors.internal_error import InternalError
+from ..errors.validation_error import ValidationError
+from .validate_subject import validate_subject
+from .validate_type import validate_type
+
+Self = TypeVar("Self", bound="EventContext")
+
+
+@dataclass
+class EventContext:
+    source: str
+    subject: str
+    type: str
+    spec_version: str
+    event_id: str
+    time: datetime
+    data_content_type: str
+    predecessor_hash: str
+    trace_parent: str = None
+    trace_state: str = None
+
+    @staticmethod
+    def parse(unknown_object: dict) -> Self:
+        source = unknown_object.get('source')
+        if not isinstance(source, str):
+            raise ValidationError(
+                f'Failed to parse source \'{source}\' to string.')
+
+        subject = unknown_object.get('subject')
+        if not isinstance(subject, str):
+            raise ValidationError(
+                f'Failed to parse subject \'{subject}\' to string.')
+        validate_subject(subject)
+
+        event_type = unknown_object.get('type')
+        if not isinstance(event_type, str):
+            raise ValidationError(
+                f'Failed to parse event_type \'{event_type}\' to string.')
+        validate_type(event_type)
+
+        spec_version = unknown_object.get('specversion')
+        if not isinstance(spec_version, str):
+            raise ValidationError(
+                f'Failed to parse spec_version \'{spec_version}\' to string.')
+
+        event_id = unknown_object.get('id')
+        if not isinstance(event_id, str):
+            raise ValidationError(
+                f'Failed to parse event_id \'{event_id}\' to string.')
+
+        time = unknown_object.get('time')
+        if not isinstance(time, str):
+            raise ValidationError(
+                f'Failed to parse time \'{time}\' to datetime.')
+
+        rest, sub_seconds = time.split('.')
+        sub_seconds = f'{sub_seconds[:6]:06}'
+        try:
+            time = datetime.fromisoformat(f'{rest}.{sub_seconds}')
+        except ValueError as value_error:
+            raise ValidationError(
+                f'Failed to parse time \'{time}\' to datetime.') from value_error
+        except Exception as other_error:
+            raise InternalError(str(other_error)) from other_error
+
+        data_content_type = unknown_object.get('datacontenttype')
+        if not isinstance(data_content_type, str):
+            raise ValidationError(
+                f'Failed to parse data_content_type \'{data_content_type}\' to string.')
+
+        predecessor_hash = unknown_object.get('predecessorhash')
+        if not isinstance(predecessor_hash, str):
+            raise ValidationError(
+                f'Failed to parse predecessor_hash \'{predecessor_hash}\' to string.')
+
+        trace_parent = unknown_object.get('traceparent')
+        if trace_parent is not None and not isinstance(trace_parent, str):
+            raise ValidationError(
+                f'Failed to parse trace_parent \'{trace_parent}\' to string.')
+
+        trace_state = unknown_object.get('tracestate')
+        if trace_state is not None and not isinstance(trace_state, str):
+            raise ValidationError(
+                f'Failed to parse trace_state \'{trace_state}\' to string.')
+
+        return EventContext(
+            source=source,
+            subject=subject,
+            type=event_type,
+            spec_version=spec_version,
+            event_id=event_id,
+            time=time,
+            data_content_type=data_content_type,
+            predecessor_hash=predecessor_hash,
+            trace_parent=trace_parent,
+            trace_state=trace_state,
+        )
+
+    def to_json(self):
+        json = {
+            'specversion': self.spec_version,
+            'id': self.event_id,
+            'time': self.time.isoformat(sep='T'),
+            'source': self.source,
+            'subject': self.subject,
+            'type': self.type,
+            'datacontenttype': self.data_content_type,
+            'predecessorhash': self.predecessor_hash
+        }
+
+        if self.trace_parent is not None:
+            json['traceparent'] = self.trace_parent
+        if self.trace_state is not None:
+            json['tracestate'] = self.trace_state
+
+        return json

eventsourcingdb/event/source.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+
+from ..event.event_candidate import EventCandidate
+
+
+# pylint: disable=R0917
+# Reason: This class is expected to have many parameters
+# due to its business context. Splitting it into smaller
+# methods would increase cognitive load and make the
+# code less readable.
+@dataclass
+class Source:
+    source: str
+
+    def new_event(
+        self,
+        subject: str,
+        event_type: str,
+        data: dict,
+        trace_parent: str = None,
+        trace_state: str = None
+    ) -> EventCandidate:
+        return EventCandidate(
+            self.source,
+            subject,
+            event_type,
+            data,
+            trace_parent,
+            trace_state
+        )

eventsourcingdb/event/validate_subject.py

@@ -0,0 +1,13 @@
+import re
+
+from ..errors.validation_error import ValidationError
+
+WORD_PATTERN = '[0-9A-Za-z_-]+'
+SUBJECT_PATTERN = f'^/({WORD_PATTERN}/)*({WORD_PATTERN}/?)?$'
+
+
+def validate_subject(subject: str) -> None:
+    if re.search(SUBJECT_PATTERN, subject) is None:
+        raise ValidationError(
+            f'Failed to validate subject: \'{subject}\' must be an absolute, slash-separated path.'
+        )

eventsourcingdb/event/validate_type.py

@@ -0,0 +1,12 @@
+import re
+
+from ..errors.validation_error import ValidationError
+
+TYPE_PATTERN = r'^[0-9A-Za-z_-]{2,}\.(?:[0-9A-Za-z_-]+\.)+[0-9A-Za-z_-]+$'
+
+
+def validate_type(event_type: str) -> None:
+    if re.search(TYPE_PATTERN, event_type) is None:
+        raise ValidationError(
+            f'Failed to validate type: \'{event_type}\' must be a reverse domain name.'
+        )

eventsourcingdb/handlers/is_heartbeat.py

@@ -0,0 +1,7 @@
+from typing import Any
+
+HEARTBEAT_TYPE = 'heartbeat'
+
+
+def is_heartbeat(message: Any) -> bool:
+    return isinstance(message, dict) and message.get('type') == HEARTBEAT_TYPE

eventsourcingdb/handlers/is_item.py

@@ -0,0 +1,16 @@
+from typing import Any
+
+ITEM_TYPE = 'item'
+
+
+def is_item(message: Any) -> bool:
+    if not isinstance(message, dict) or message.get('type') != ITEM_TYPE:
+        return False
+
+    payload = message.get('payload')
+
+    return (
+        isinstance(payload, dict)
+        and isinstance(payload.get('event'), dict)
+        and isinstance(payload.get('hash'), str)
+    )

eventsourcingdb/handlers/is_stream_error.py

@@ -0,0 +1,12 @@
+from typing import Any
+
+ERROR_TYPE = 'error'
+
+
+def is_stream_error(message: Any) -> bool:
+    if not isinstance(message, dict) or message.get('type') != ERROR_TYPE:
+        return False
+
+    payload = message.get('payload')
+
+    return isinstance(payload, dict) and isinstance(payload.get('error'), str)

eventsourcingdb/handlers/observe_events/__init__.py

@@ -0,0 +1,4 @@
+from .observe_events import observe_events
+from .observe_events_options import ObserveEventsOptions
+from .observe_from_latest_event import ObserveFromLatestEvent
+from .if_event_is_missing_during_observe import IfEventIsMissingDuringObserve

eventsourcingdb/handlers/observe_events/if_event_is_missing_during_observe.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class IfEventIsMissingDuringObserve(str, Enum):
+    WAIT_FOR_EVENT = 'wait-for-event'
+    READ_EVERYTHING = 'read-everything'

eventsourcingdb/handlers/observe_events/observe_events.py

@@ -0,0 +1,85 @@
+import json
+from collections.abc import AsyncGenerator
+from http import HTTPStatus
+
+from ..is_heartbeat import is_heartbeat
+from ..is_item import is_item
+from ..is_stream_error import is_stream_error
+from ..parse_raw_message import parse_raw_message
+from ...abstract_base_client import AbstractBaseClient
+from ...errors.custom_error import CustomError
+from ...errors.internal_error import InternalError
+from ...errors.invalid_parameter_error import InvalidParameterError
+from ...errors.server_error import ServerError
+from ...errors.validation_error import ValidationError
+from ...event.event import Event
+from ...event.validate_subject import validate_subject
+from ..store_item import StoreItem
+from .observe_events_options import ObserveEventsOptions
+from ...http_client.response import Response
+
+# pylint: disable=R6007
+# Reason: This method explicitly specifies the return type as None
+# for better readability. Even though it is not necessary,
+# it makes the return type clear without needing to read any
+# documentation or code.
+async def observe_events(
+    client: AbstractBaseClient,
+    subject: str,
+    options: ObserveEventsOptions
+) -> AsyncGenerator[StoreItem, None]:
+    try:
+        validate_subject(subject)
+    except ValidationError as validation_error:
+        raise InvalidParameterError('subject', str(validation_error)) from validation_error
+    except Exception as other_error:
+        raise InternalError(str(other_error)) from other_error
+
+    try:
+        options.validate()
+    except ValidationError as validation_error:
+        raise InvalidParameterError('options', str(validation_error)) from validation_error
+    except Exception as other_error:
+        raise InternalError(str(other_error)) from other_error
+
+    request_body = json.dumps({
+        'subject': subject,
+        'options': options.to_json()
+    })
+
+    response: Response
+    try:
+        response = await client.http_client.post(
+            path='/api/observe-events',
+            request_body=request_body,
+        )
+    except CustomError as custom_error:
+        raise custom_error
+    except Exception as other_error:
+        raise InternalError(str(other_error)) from other_error
+
+    with response:
+        if response.status_code != HTTPStatus.OK:
+            raise ServerError(
+                f'Unexpected response status: '
+                f'{response.status_code} {HTTPStatus(response.status_code).phrase}'
+            )
+        async for raw_message in response.body:
+            message = parse_raw_message(raw_message)
+
+            if is_heartbeat(message):
+                continue
+
+            if is_stream_error(message):
+                raise ServerError(f'{message["payload"]["error"]}.')
+
+            if is_item(message):
+                event = Event.parse(message['payload']['event'])
+
+                yield StoreItem(event, message['payload']['hash'])
+                continue
+
+            raise ServerError(
+                f'Failed to read events, an unexpected stream item was received: '
+                f'{message}.'
+            )

eventsourcingdb/handlers/observe_events/observe_events_options.py

@@ -0,0 +1,55 @@
+from dataclasses import dataclass
+
+from ...errors.validation_error import ValidationError
+from ...event.validate_subject import validate_subject
+from ...event.validate_type import validate_type
+from ...util.is_non_negativ_integer import is_non_negative_integer
+from .observe_from_latest_event import ObserveFromLatestEvent
+
+
+@dataclass
+class ObserveEventsOptions:
+    recursive: bool
+    lower_bound_id: str | None = None
+    from_latest_event: ObserveFromLatestEvent | None = None
+
+    def validate(self) -> None:
+        if self.lower_bound_id is not None and not is_non_negative_integer(self.lower_bound_id):
+            raise ValidationError(
+                'ReadEventOptions are invalid: lower_bound_id must be 0 or greater.'
+            )
+
+        if self.from_latest_event is not None:
+            if self.lower_bound_id is not None:
+                raise ValidationError(
+                    'ReadEventsOptions are invalid: '
+                    'lowerBoundId and fromLatestEvent are mutually exclusive'
+                )
+
+            try:
+                validate_subject(self.from_latest_event.subject)
+            except ValidationError as validation_error:
+                raise ValidationError(
+                    f'ReadEventsOptions are invalid: '
+                    f'Failed to validate \'from_latest_event\': {str(validation_error)}'
+                ) from validation_error
+
+            try:
+                validate_type(self.from_latest_event.type)
+            except ValidationError as validation_error:
+                raise ValidationError(
+                    f'ReadEventsOptions are invalid: '
+                    f'Failed to validate \'from_latest_event\': {str(validation_error)}'
+                ) from validation_error
+
+    def to_json(self):
+        json = {
+            'recursive': self.recursive
+        }
+
+        if self.lower_bound_id is not None:
+            json['lowerBoundId'] = self.lower_bound_id
+        if self.from_latest_event is not None:
+            json['fromLatestEvent'] = self.from_latest_event.to_json()
+
+        return json

eventsourcingdb/handlers/observe_events/observe_from_latest_event.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+
+from .if_event_is_missing_during_observe import IfEventIsMissingDuringObserve
+
+
+@dataclass
+class ObserveFromLatestEvent:
+    subject: str
+    type: str
+    if_event_is_missing: IfEventIsMissingDuringObserve
+
+    def to_json(self):
+        return {
+            'subject': self.subject,
+            'type': self.type,
+            'ifEventIsMissing': self.if_event_is_missing
+        }