lightweb-adapter-sdk 0.2.2__tar.gz → 0.2.3__tar.gz

{lightweb_adapter_sdk-0.2.2 → lightweb_adapter_sdk-0.2.3}/CHANGELOG.md

@@ -8,6 +8,50 @@ Breaking changes are flagged with `**BREAKING:**` at the start of the entry, eve
 
 The SDK is in 0.x until its contract has been validated by at least one production adapter. Per [`CONVENTIONS.md`](CONVENTIONS.md) §1.3, breaking changes may land in minor (0.X → 0.(X+1)) releases while in 0.x; pin against a specific minor version.
 
+## [0.2.3] - 2026-05-24
+
+### Fixed
+
+- `event_consumer.parser.parse_envelope` now reads the platform's
+  native event-envelope field names — `event_id`, `event_type`,
+  `event_version`, `occurred_at`, `emitted_by` — per
+  `libs/events/schemas/entitlements/_envelope.json` and the entitlements
+  service's `outbox/envelope.py::build_envelope`. It previously read a
+  CloudEvents shape (`id`, `type`, `specversion`, `time`, `source`) that
+  the platform never emits, rejecting every real event at `Missing
+  required field: id`; an adapter consuming the live bus would have
+  nacked/dead-lettered all entitlements events. `member_id` is still
+  sourced from `data.member_id`; `subject` is tolerated and ignored (it
+  is schema-required and always present, but the consumer hook is
+  `data.member_id`, since `subject.id` varies by event type). The
+  `EventEnvelope` type is unchanged — this is a parser-internal fix,
+  non-breaking. The parser docstring, which had incorrectly described
+  the CloudEvents shape as matching the schema, is corrected to the
+  native shape. Surfaced by NextCloud D3 consumer-wiring integration
+  work (integration finding F8).
+- `testkit.FakeEventSource.publish`/`publish_async` now serialize the
+  native envelope shape (matching `build_envelope`: `event_id`,
+  `event_type`, `event_version`, `occurred_at`, `emitted_by`, a member
+  `subject`, `data.member_id`, and `context` as an object). They
+  previously emitted the same CloudEvents shape the parser wrongly read
+  — so the fake producer and the parser were a matched pair that agreed
+  with each other and not with the platform, which is why no test caught
+  F8. Adapter authors testing consumers against `FakeEventSource` now
+  exercise the real on-wire shape. Behavior change to the testkit fake;
+  adapter consumer tests that inspected the published bytes for `id`/
+  `type`/etc. must read the native field names.
+
+### Added
+
+- Raw-bytes parser coverage in `tests/unit/test_event_consumer_conformance.py`
+  (`TestParseEnvelope`): asserts `parse_envelope` reads the native
+  envelope shape and rejects the legacy CloudEvents shape (F8 regression
+  guard), plus a case confirming `member_id` is taken from
+  `data.member_id` rather than `subject.id`. The prior parser tests
+  asserted the CloudEvents shape — they validated the bug rather than
+  catching it. Test payloads are derived from the producer
+  (`build_envelope`) pending a captured real event.
+
 ## [0.2.2] - 2026-05-24
 
 ### Fixed

{lightweb_adapter_sdk-0.2.2 → lightweb_adapter_sdk-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lightweb-adapter-sdk
-Version: 0.2.2
+Version: 0.2.3
 Summary: Published Python SDK for the Lightweb adapter contract
 Project-URL: Homepage, https://github.com/lightweb/adapter-sdk
 Project-URL: Repository, https://github.com/lightweb/adapter-sdk

lightweb_adapter_sdk-0.2.3/src/lightweb_adapter_sdk/event_consumer/parser.py

@@ -0,0 +1,119 @@
+"""Envelope parser: raw JetStream payload → EventEnvelope.
+
+The platform publishes JetStream messages as JSON in the entitlements
+event-envelope shape (per ``libs/events/schemas/entitlements/_envelope.json``,
+Conventions §4.3, emitted by the entitlements service's
+``outbox/envelope.py::build_envelope``):
+
+.. code-block:: json
+
+   {
+       "event_id": "evt_<base58>",
+       "event_type": "entitlements.<entity>.<verb>",
+       "event_version": "1.0",
+       "occurred_at": "2026-05-17T12:00:00Z",
+       "emitted_by": "service:entitlements",
+       "subject": {"type": "member", "id": "mem_..."},
+       "data": {"member_id": "mem_...", ...},
+       "context": {...}
+   }
+
+This module parses that shape into the SDK's ``EventEnvelope``,
+flattening ``data.member_id`` to the top level and omitting ``subject``
+and ``data`` (beyond ``member_id``). ``subject`` is tolerated and
+ignored — the platform always emits it (the schema requires it), but
+the consumer's hook is ``data.member_id``, not ``subject.id`` (subject's
+``id`` varies by event type: member_id for member events, subscription_id
+for subscription events, etc.).
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+from lightweb_adapter_sdk.types import EventEnvelope
+
+
+class ParseError(ValueError):
+    """The raw payload could not be parsed into an EventEnvelope."""
+
+
+def parse_envelope(raw_payload: bytes) -> EventEnvelope:
+    """Parse a raw JetStream message payload into an ``EventEnvelope``.
+
+    Args:
+        raw_payload: The raw bytes from JetStream, expected to be
+            UTF-8 encoded JSON matching the entitlements event-envelope
+            schema (``_envelope.json``).
+
+    Returns:
+        A fully-populated ``EventEnvelope``.
+
+    Raises:
+        ParseError: If the payload is not valid JSON, is missing
+            required fields, or has an unexpected shape.
+    """
+    try:
+        data = json.loads(raw_payload)
+    except (json.JSONDecodeError, TypeError) as exc:
+        raise ParseError(f"Payload is not valid JSON: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise ParseError(
+            f"Payload must be a JSON object, got {type(data).__name__}"
+        )
+
+    # Required top-level fields, per _envelope.json. ``subject`` and
+    # ``data`` are also schema-required but handled separately below
+    # (subject is tolerated-and-ignored; data is read for member_id).
+    for field in (
+        "event_id",
+        "event_type",
+        "event_version",
+        "occurred_at",
+        "emitted_by",
+    ):
+        if field not in data:
+            raise ParseError(f"Missing required field: {field}")
+
+    # data.member_id is the source for EventEnvelope.member_id.
+    if "data" not in data or not isinstance(data["data"], dict):
+        raise ParseError("Missing or invalid 'data' field")
+    if "member_id" not in data["data"]:
+        raise ParseError("Missing 'data.member_id' field")
+
+    member_id = data["data"]["member_id"]
+    if not isinstance(member_id, str):
+        raise ParseError(
+            f"'data.member_id' must be a string, got {type(member_id).__name__}"
+        )
+
+    # context is optional and preserved when present. The producer emits
+    # an empty object ``{}`` (not null) when there is no context; both an
+    # empty dict and an absent/None context are accepted here.
+    context = data.get("context")
+    if context is not None and not isinstance(context, dict):
+        raise ParseError("'context' must be an object when present")
+
+    # occurred_at — accept ISO-8601 strings (the producer emits with a
+    # trailing 'Z'; datetime.fromisoformat handles 'Z' on Python 3.11+).
+    occurred_at_str = data["occurred_at"]
+    try:
+        occurred_at = datetime.fromisoformat(occurred_at_str)
+        if occurred_at.tzinfo is None:
+            occurred_at = occurred_at.replace(tzinfo=timezone.utc)
+    except (ValueError, TypeError) as exc:
+        raise ParseError(
+            f"Invalid 'occurred_at' field: {occurred_at_str!r}: {exc}"
+        ) from exc
+
+    return EventEnvelope(
+        event_id=data["event_id"],
+        event_type=data["event_type"],
+        event_version=data["event_version"],
+        occurred_at=occurred_at,
+        emitted_by=data["emitted_by"],
+        member_id=member_id,
+        context=context,
+    )

{lightweb_adapter_sdk-0.2.2 → lightweb_adapter_sdk-0.2.3}/src/lightweb_adapter_sdk/testkit/fake_event_source.py

@@ -4,6 +4,17 @@ Provides ``FakeEventSource``, an in-process fake that publishes
 ``EventEnvelope`` instances as raw JetStream-style JSON bytes,
 allowing tests to drive event consumer behavior without a real
 NATS/JetStream connection.
+
+The published bytes match the platform's native event-envelope shape
+(per ``libs/events/schemas/entitlements/_envelope.json`` and the
+entitlements service's ``build_envelope``): ``event_id``, ``event_type``,
+``event_version``, ``occurred_at``, ``emitted_by``, ``subject``,
+``data`` (carrying ``member_id``), and ``context``. This is the shape
+``parse_envelope`` consumes, so a round-trip publish→handle_event
+exercises the real parse path. (Prior to 0.2.3 this fake emitted a
+CloudEvents shape — ``id``/``type``/``specversion``/``time``/``source``
+— matching a parser that read the same wrong shape; neither matched the
+platform. See CHANGELOG 0.2.3 / integration finding F8.)
 """
 
 from __future__ import annotations
@@ -23,6 +34,10 @@ class FakeEventSource:
     callbacks (consumers).  Events are stored internally for inspection
     and can be published synchronously or asynchronously.
 
+    The serialized bytes use the platform's native envelope shape so
+    that consumers exercising ``parse_envelope`` see exactly what the
+    entitlements service emits.
+
     Args:
         subject: The subject name this fake source publishes to
             (e.g. ``"entitlements.member.>"``).
@@ -47,6 +62,28 @@ class FakeEventSource:
         self._sequence += 1
         return f"evt-fake-{self._sequence:04d}"
 
+    def _serialize(self, envelope: EventEnvelope) -> bytes:
+        """Serialize an ``EventEnvelope`` to the platform's native shape.
+
+        Mirrors the entitlements service's ``build_envelope`` output:
+        native field names, a member ``subject`` derived from
+        ``member_id`` (the consumer ignores ``subject`` but the real
+        envelope always carries it), ``member_id`` nested under
+        ``data``, and ``context`` as an object (``{}`` when empty,
+        matching the producer, which never emits null).
+        """
+        payload_dict: dict[str, Any] = {
+            "event_id": envelope.event_id,
+            "event_type": envelope.event_type,
+            "event_version": envelope.event_version,
+            "occurred_at": envelope.occurred_at.isoformat(),
+            "emitted_by": envelope.emitted_by,
+            "subject": {"type": "member", "id": envelope.member_id},
+            "data": {"member_id": envelope.member_id},
+            "context": envelope.context if envelope.context is not None else {},
+        }
+        return json.dumps(payload_dict).encode("utf-8")
+
     def publish(self, envelope: EventEnvelope) -> bytes:
         """Publish an event envelope as raw JSON bytes.
 
@@ -58,18 +95,7 @@ class FakeEventSource:
         Returns:
             The raw JSON bytes that were published.
         """
-        payload_dict = {
-            "id": envelope.event_id,
-            "type": envelope.event_type,
-            "specversion": envelope.event_version,
-            "time": envelope.occurred_at.isoformat(),
-            "source": envelope.emitted_by,
-            "data": {"member_id": envelope.member_id},
-        }
-        if envelope.context is not None:
-            payload_dict["context"] = envelope.context
-
-        raw = json.dumps(payload_dict).encode("utf-8")
+        raw = self._serialize(envelope)
         self._published.append((envelope, raw))
 
         for consumer in self._consumers:
@@ -88,18 +114,7 @@ class FakeEventSource:
         Returns:
             The raw JSON bytes that were published.
         """
-        payload_dict = {
-            "id": envelope.event_id,
-            "type": envelope.event_type,
-            "specversion": envelope.event_version,
-            "time": envelope.occurred_at.isoformat(),
-            "source": envelope.emitted_by,
-            "data": {"member_id": envelope.member_id},
-        }
-        if envelope.context is not None:
-            payload_dict["context"] = envelope.context
-
-        raw = json.dumps(payload_dict).encode("utf-8")
+        raw = self._serialize(envelope)
         self._published.append((envelope, raw))
 
         for consumer in self._consumers:

lightweb_adapter_sdk-0.2.2/src/lightweb_adapter_sdk/event_consumer/parser.py

@@ -1,94 +0,0 @@
-"""Envelope parser: raw JetStream payload → EventEnvelope.
-
-The platform publishes JetStream messages as JSON with the following
-shape (per ``libs/events/schemas/entitlements/_envelope.json``):
-
-.. code-block:: json
-
-   {
-       "id": "<event-id>",
-       "type": "entitlements.<entity>.<verb>",
-       "specversion": "1.0",
-       "time": "2026-05-17T12:00:00Z",
-       "source": "service:entitlements",
-       "subject": {"type": "member", "id": "mem_..."},
-       "data": {"member_id": "mem_...", ...},
-       "context": {"trace_context": "..."}
-   }
-
-This module parses that shape into the SDK's ``EventEnvelope``,
-flattening ``data.member_id`` to the top level and omitting ``subject``
-and ``data`` (beyond ``member_id``).
-"""
-
-from __future__ import annotations
-
-import json
-from datetime import datetime, timezone
-
-from lightweb_adapter_sdk.types import EventEnvelope
-
-
-class ParseError(ValueError):
-    """The raw payload could not be parsed into an EventEnvelope."""
-
-
-def parse_envelope(raw_payload: bytes) -> EventEnvelope:
-    """Parse a raw JetStream message payload into an ``EventEnvelope``.
-
-    Args:
-        raw_payload: The raw bytes from JetStream, expected to be
-            UTF-8 encoded JSON matching the platform envelope schema.
-
-    Returns:
-        A fully-populated ``EventEnvelope``.
-
-    Raises:
-        ParseError: If the payload is not valid JSON, is missing
-            required fields, or has an unexpected shape.
-    """
-    try:
-        data = json.loads(raw_payload)
-    except (json.JSONDecodeError, TypeError) as exc:
-        raise ParseError(f"Payload is not valid JSON: {exc}") from exc
-
-    # Required top-level fields
-    for field in ("id", "type", "specversion", "time", "source"):
-        if field not in data:
-            raise ParseError(f"Missing required field: {field}")
-
-    # data.member_id is the source for EventEnvelope.member_id
-    if "data" not in data or not isinstance(data["data"], dict):
-        raise ParseError("Missing or invalid 'data' field")
-    if "member_id" not in data["data"]:
-        raise ParseError("Missing 'data.member_id' field")
-
-    member_id = data["data"]["member_id"]
-    if not isinstance(member_id, str):
-        raise ParseError(
-            f"'data.member_id' must be a string, got {type(member_id).__name__}"
-        )
-
-    # context is optional but preserved when present
-    context = data.get("context")
-    if context is not None and not isinstance(context, dict):
-        raise ParseError("'context' must be an object when present")
-
-    # Parse time — accept ISO-8601 strings
-    time_str = data["time"]
-    try:
-        occurred_at = datetime.fromisoformat(time_str)
-        if occurred_at.tzinfo is None:
-            occurred_at = occurred_at.replace(tzinfo=timezone.utc)
-    except (ValueError, TypeError) as exc:
-        raise ParseError(f"Invalid 'time' field: {time_str}: {exc}") from exc
-
-    return EventEnvelope(
-        event_id=data["id"],
-        event_type=data["type"],
-        event_version=data["specversion"],
-        occurred_at=occurred_at,
-        emitted_by=data["source"],
-        member_id=member_id,
-        context=context,
-    )