Merge pull request #826 from fkie-cad/dev-logevent-class-implementation

Dev logevent class implementation

- implement LogEvent class as subclass of Event with support for original, extra_data, and metadata attributes
- ensure consistent state behavior by helper-based wrapping of next_state() to enforce transition validation

Author: kaya-david

CHANGELOG.md

@@ -6,6 +6,8 @@
 ### Features
 
 ### Improvements
+
+* add LogEvent class
 * implement abstract Event class to encapsulate event data, processing state, warnings, and errors
 * integrate dotted field handling methods directly into Event, enabling structured field access and manipulation
 * support event identity and hashability based on data, allowing usage in sets and as dictionary keys

logprep/ng/events/__init__.py

@@ -0,0 +1,105 @@
+"""Concrete Log Event implementation"""
+
+from types import MethodType
+from typing import Any
+
+from logprep.ng.abc.event import Event, EventMetadata
+from logprep.ng.event_state import EventState, EventStateType
+
+
+class LogEvent(Event):
+    """Concrete log event class with additional attribute and constraints."""
+
+    __slots__: tuple[str, ...] = (
+        "original",
+        "extra_data",
+        "metadata",
+        "_state",
+        "_origin_state_next_state_fn",
+    )
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        data: dict[str, Any],
+        *,
+        original: bytes,
+        extra_data: list[Event] | None = None,
+        metadata: EventMetadata | None = None,
+        state: EventState | None = None,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        data : dict[str, Any]
+            The main data payload for the event.
+        original : bytes
+            The raw representation of the event (e.g., as received from Kafka).
+        extra_data : list[Event], optional
+            Sub-events that were derived or caused by this event
+        metadata : EventMetadata, optional
+            Structured metadata for the event.
+        state : EventState, optional
+            Optional existing EventState to initialize from (e.g. deserialization).
+
+        Examples
+        --------
+        >>> e1 = Event({"msg": "hello"})
+        >>> e2 = Event({"msg": "world"})
+        >>> le = LogEvent({"msg": "parent"}, original=b'raw', extra_data=[e1, e2])
+        >>> isinstance(le.state, EventState)
+        True
+        """
+
+        self.original = original
+        self.extra_data = extra_data if extra_data else []
+        self.metadata = metadata
+
+        self._state: EventState = EventState() if state is None else state
+
+        super().__init__(data=data, state=self._state)
+
+        # Wrap original next_state with validation logic
+        self._origin_state_next_state_fn = MethodType(EventState.next_state, self._state)
+        self._state.next_state = self._next_state_validation_helper
+
+    @property
+    def state(self) -> EventState:
+        """Return the current EventState instance."""
+
+        return self._state
+
+    @state.setter
+    def state(self, value: EventState) -> None:
+        """
+        Prevent assignment of a DELIVERED state if not all extra_data events are DELIVERED.
+
+        Parameters
+        ----------
+        value : EventState
+            The state to assign.
+
+        Raises
+        ------
+        ValueError
+            If value.state is DELIVERED but any sub-event is not DELIVERED.
+        """
+        self._validate_state(value.current_state)
+        self._state = value
+
+        # Wrap next_state again if needed
+        self._origin_state_next_state_fn = self._state.next_state
+        self._state.next_state = self._next_state_validation_helper
+
+    def _next_state_validation_helper(
+        self, *, success: bool | None = None
+    ) -> EventStateType | None:
+        new_state: EventStateType = self._origin_state_next_state_fn(success=success)
+        self._validate_state(new_state)
+        return new_state
+
+    def _validate_state(self, state_type: EventStateType) -> None:
+        if state_type == EventStateType.DELIVERED:
+            if not all(e.state.current_state == EventStateType.DELIVERED for e in self.extra_data):
+                raise ValueError(
+                    "Cannot assign DELIVERED state: not all extra_data events are DELIVERED."
+                )

logprep/ng/events/log_event.py

@@ -0,0 +1,107 @@
+# pylint: disable=missing-docstring
+# pylint: disable=protected-access
+# pylint: disable=too-few-public-methods
+# pylint: disable=redefined-slots-in-subclass
+
+from unittest.mock import Mock
+
+import pytest
+
+from logprep.ng.abc.event import Event
+from logprep.ng.event_state import EventState, EventStateType
+from logprep.ng.events.log_event import LogEvent
+
+
+class DummyEvent(Event):
+    __slots__ = Event.__slots__
+
+
+def test_log_event_initializes_correctly() -> None:
+    log_event = LogEvent(data={"foo": "bar"}, original=b"raw")
+
+    assert isinstance(log_event.state, EventState)
+    assert log_event.original == b"raw"
+    assert not log_event.extra_data
+    assert log_event.metadata is None
+
+    assert callable(log_event._origin_state_next_state_fn)
+    assert log_event.state.next_state != log_event._origin_state_next_state_fn
+
+
+def test_log_event_preserves_state_on_init() -> None:
+    state = EventState()
+    state.current_state = EventStateType.STORED_IN_OUTPUT
+    log_event = LogEvent(data={"msg": "payload"}, original=b"event", state=state)
+
+    assert log_event.state.current_state is EventStateType.STORED_IN_OUTPUT
+
+
+def test_log_event_transition_to_delivered_succeeds_if_all_extra_data_delivered() -> None:
+    child1 = DummyEvent({"c1": 1})
+    child2 = DummyEvent({"c2": 2})
+    child1.state.current_state = EventStateType.DELIVERED
+    child2.state.current_state = EventStateType.DELIVERED
+
+    log_event = LogEvent(
+        data={"parent": "yes"},
+        original=b"...",
+        extra_data=[child1, child2],
+    )
+    log_event.state.current_state = EventStateType.STORED_IN_OUTPUT
+
+    log_event.state.next_state(success=True)
+    assert log_event.state.current_state == EventStateType.DELIVERED
+
+
+def test_log_event_transition_to_next_state_excluding_delivered() -> None:
+
+    log_event = LogEvent(
+        data={"parent": "yes"},
+        original=b"...",
+        extra_data=[],
+    )
+    log_event.state.current_state = EventStateType.PROCESSING
+
+    log_event.state.next_state(success=True)
+    assert log_event.state.current_state == EventStateType.PROCESSED
+
+
+def test_log_event_transition_to_delivered_fails_if_extra_data_not_delivered() -> None:
+    child1 = DummyEvent({"c1": 1})
+    child2 = DummyEvent({"c2": 2})
+    child1.state.current_state = EventStateType.DELIVERED
+    child2.state.current_state = EventStateType.FAILED
+
+    log_event = LogEvent(data={"parent": "e"}, original=b"...", extra_data=[child1, child2])
+    log_event.state.current_state = EventStateType.STORED_IN_OUTPUT
+
+    with pytest.raises(ValueError, match="not all extra_data events are DELIVERED"):
+        log_event.state.next_state(success=True)
+
+
+def test_log_event_direct_state_assignment_succeeds_if_all_extra_data_delivered() -> None:
+    child = DummyEvent({"child": "ok"})
+    child.state.current_state = EventStateType.DELIVERED
+    log_event = LogEvent(data={"parent": "x"}, original=b"...", extra_data=[child])
+    new_state = EventState()
+    new_state.current_state = EventStateType.DELIVERED
+    log_event.state = new_state
+
+    assert log_event.state.current_state is EventStateType.DELIVERED
+
+
+def test_next_state_validation_helper_returns_new_state_with_mock():
+    sub_event = Mock(spec=Event)
+    sub_event.state.current_state = EventStateType.DELIVERED
+
+    log_event = LogEvent(
+        data={"msg": "parent"},
+        original=b"raw",
+        extra_data=[sub_event],
+    )
+
+    log_event._origin_state_next_state_fn = Mock(return_value=EventStateType.DELIVERED)
+
+    result = log_event._next_state_validation_helper(success=True)
+
+    assert result == EventStateType.DELIVERED