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

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

@@ -8,6 +8,68 @@ 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.4] - 2026-05-26
+
+### Added
+
+- `auth` module: `ClientCredentialsTokenProvider` — a reusable OAuth2
+  client-credentials token provider that acquires, caches, and
+  refreshes bearer tokens.  Takes an **injected** async HTTP client
+  (structural `HttpClient` Protocol) rather than importing an HTTP
+  library, so the SDK's runtime dependency surface remains
+  `pydantic` + `nats-py`.  Includes `TokenProvider` Protocol,
+  `HttpClient`/`HttpResponse` Protocols, and `TokenAcquisitionError`
+  exception.  Concurrency-safe: concurrent `get_token()` calls near
+  expiry trigger a single re-acquisition under an `asyncio.Lock`.
+- `testkit.FakeTokenEndpoint`: an in-process fake of an OAuth2 token
+  endpoint that satisfies the `HttpClient` Protocol structurally.  Lets
+  tests stage token values, assert caching (call count), exercise
+  refresh-before-expiry, and verify clean failure on error responses.
+
+## [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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lightweb-adapter-sdk
-Version: 0.2.2
+Version: 0.2.4
 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.2 → lightweb_adapter_sdk-0.2.4}/docs/testkit.md

@@ -197,7 +197,90 @@ assert stored.external_id == "alice"
 subsequent calls with the same key update the existing record.
 ``get_app_account`` returns ``None`` for unknown keys.
 
-## Beyond the testkit
+## The fake token endpoint
+
+The ``FakeTokenEndpoint`` class is an in-process fake of an OAuth2
+token endpoint.  It satisfies the ``HttpClient`` Protocol structurally
+so it can be injected into ``ClientCredentialsTokenProvider``.  Adapter
+authors use it to test token acquisition, caching, refresh-before-expiry,
+and clean-failure behaviour.
+
+### Basic usage
+
+```python
+from lightweb_adapter_sdk.testkit import FakeTokenEndpoint
+from lightweb_adapter_sdk.auth import ClientCredentialsTokenProvider
+
+fake = FakeTokenEndpoint(access_token="my-token", expires_in=300)
+
+provider = ClientCredentialsTokenProvider(
+    token_endpoint="https://keycloak.example.com/token",
+    client_id="my-adapter",
+    client_secret="secret",
+    http_client=fake,
+)
+
+token = await provider.get_token()
+assert token == "my-token"
+assert fake.call_count == 1
+```
+
+### Asserting caching
+
+Call ``get_token()`` multiple times — the fake's ``call_count`` stays
+at 1 as long as the token is within its lifetime:
+
+```python
+for _ in range(10):
+    await provider.get_token()
+
+assert fake.call_count == 1  # only one acquisition
+```
+
+### Refresh-before-expiry
+
+Stage a token with a short ``expires_in`` (or use a large
+``refresh_margin_seconds``) to exercise the refresh path:
+
+```python
+fake = FakeTokenEndpoint(access_token="old-token", expires_in=0)
+provider = ClientCredentialsTokenProvider(
+    token_endpoint="...",
+    client_id="...",
+    client_secret="...",
+    http_client=fake,
+    refresh_margin_seconds=1000.0,
+)
+
+await provider.get_token()  # acquires "old-token"
+fake.stage_token("new-token", expires_in=300)
+token = await provider.get_token()  # triggers refresh
+
+assert token == "new-token"
+assert fake.call_count == 2
+```
+
+### Error responses
+
+Stage an error response to verify clean failure:
+
+```python
+fake = FakeTokenEndpoint()
+fake.stage_error(status_code=401)
+provider = ClientCredentialsTokenProvider(
+    token_endpoint="...",
+    client_id="...",
+    client_secret="...",
+    http_client=fake,
+)
+
+from lightweb_adapter_sdk.auth import TokenAcquisitionError
+
+with pytest.raises(TokenAcquisitionError):
+    await provider.get_token()
+```
+
+### Beyond the testkit
 
 The testkit's structural tests verify that an adapter looks like an
 adapter.  They do not verify that the adapter implements the contract

lightweb_adapter_sdk-0.2.4/src/lightweb_adapter_sdk/auth/__init__.py

@@ -0,0 +1,42 @@
+"""Auth module — OAuth2 token acquisition for adapters.
+
+This module provides a reusable client-credentials token provider.
+Adapters authenticate to the entitlements service with a Keycloak-issued
+bearer token; acquiring and refreshing that token is shared platform
+plumbing.
+
+Public surface:
+
+- ``TokenProvider`` — structural Protocol (single ``get_token()`` method).
+- ``ClientCredentialsTokenProvider`` — concrete provider that runs the
+  client_credentials grant, caches the token, and refreshes before expiry.
+- ``TokenAcquisitionError`` — raised when token acquisition fails.
+
+Import as::
+
+    from lightweb_adapter_sdk.auth import (
+        ClientCredentialsTokenProvider,
+        TokenAcquisitionError,
+        TokenProvider,
+    )
+
+The SDK takes **no new runtime dependency** in this module — the token
+provider receives its HTTP client via injection (see the
+``HttpClient`` Protocol in ``auth.protocol``).
+"""
+
+from lightweb_adapter_sdk.auth.errors import TokenAcquisitionError
+from lightweb_adapter_sdk.auth.protocol import (
+    HttpClient,
+    HttpResponse,
+    TokenProvider,
+)
+from lightweb_adapter_sdk.auth.provider import ClientCredentialsTokenProvider
+
+__all__ = [
+    "ClientCredentialsTokenProvider",
+    "HttpClient",
+    "HttpResponse",
+    "TokenAcquisitionError",
+    "TokenProvider",
+]

lightweb_adapter_sdk-0.2.4/src/lightweb_adapter_sdk/auth/errors.py

@@ -0,0 +1,16 @@
+"""Authentication error types for the auth module.
+
+See ``docs/contract.md`` for the overall adapter contract.
+"""
+
+from __future__ import annotations
+
+
+class TokenAcquisitionError(Exception):
+    """Raised when the token provider cannot acquire a bearer token.
+
+    Covers non-2xx HTTP responses, missing ``access_token`` in the
+    response body, and transport errors surfaced by the injected HTTP
+    client.  Adapter code should catch this rather than letting a raw
+    HTTP exception propagate.
+    """

lightweb_adapter_sdk-0.2.4/src/lightweb_adapter_sdk/auth/protocol.py

@@ -0,0 +1,145 @@
+"""Protocols for the auth module.
+
+This module defines two structural Protocols:
+
+- ``HttpClient`` — a narrow interface describing the async HTTP client
+  the token provider calls (a single ``post`` method).
+- ``TokenProvider`` — the public surface of a token provider, a single
+  ``get_token`` method.
+
+Both are ``@runtime_checkable`` structural Protocols, not base classes.
+See ``src/lightweb_adapter_sdk/event_consumer/protocol.py`` for the
+house style.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Awaitable, Callable, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class HttpClient(Protocol):
+    """Narrow structural Protocol for the injected async HTTP client.
+
+    This is a structural Protocol, not a base class.  Any async HTTP
+    client whose ``post`` method matches the signature below satisfies
+    the contract — the SDK does not import ``httpx`` or any other
+    HTTP library.
+
+    The provider calls exactly one method on the injected client:
+    ``post(url, data={...})`` with form-encoded body, expecting a
+    response with ``.status_code`` and ``.json()``.
+    """
+
+    async def post(
+        self,
+        url: str,
+        *,
+        data: dict[str, str],
+    ) -> HttpResponse:
+        """Send a form-encoded POST and return the response.
+
+        The caller passes ``data={"grant_type": "client_credentials", ...}``
+        and reads ``response.json()["access_token"]`` on success.
+        """
+
+
+@runtime_checkable
+class HttpResponse(Protocol):
+    """Response shape returned by ``HttpClient.post``.
+
+    Structural Protocol — any object with these attributes satisfies
+    the contract regardless of its concrete type.
+    """
+
+    @property
+    def status_code(self) -> int:
+        """HTTP status code (e.g. 200, 401, 500)."""
+
+    def json(self) -> dict[str, Any]:
+        """Parse and return the response body as a dict.
+
+        Returns a mixed-type dict — the Keycloak token endpoint
+        returns ``access_token`` (str), ``expires_in`` (int), etc.
+        """
+
+    def raise_for_status(self) -> None:
+        """Raise an exception for non-2xx status codes."""
+
+
+@runtime_checkable
+class TokenProvider(Protocol):
+    """Protocol defining the token-provider contract.
+
+    This is a structural Protocol, not a base class.  Adapter authors
+    can type against this interface without depending on the concrete
+    implementation.
+
+    The single method ``get_token()`` returns a bearer token string.
+    Implementations are responsible for caching and refreshing as
+    needed.
+    """
+
+    async def get_token(self) -> str:
+        """Return a valid bearer token string.
+
+        Implementations cache the token and refresh it before expiry.
+        On acquisition failure, a ``TokenAcquisitionError`` is raised
+        rather than returning an empty or invalid token.
+        """
+
+
+class _RefreshGuard:
+    """Internal helper: ensures only one refresh runs at a time.
+
+    Wraps an async acquisition callable with an ``asyncio.Lock`` so
+    that concurrent callers near expiry trigger a single re-acquire
+    rather than a stampede.
+    """
+
+    def __init__(
+        self,
+        acquire: Callable[[], Awaitable[tuple[str, float]]],
+        refresh_margin: float,
+    ) -> None:
+        self._acquire = acquire
+        self._margin = refresh_margin
+        self._lock = asyncio.Lock()
+        self._token: str | None = None
+        self._expires_at: float = 0.0
+
+    @property
+    def token(self) -> str | None:
+        return self._token
+
+    @property
+    def expires_at(self) -> float:
+        return self._expires_at
+
+    def is_expired(self) -> bool:
+        """Return True if the cached token is gone or past the refresh margin."""
+        if self._token is None:
+            return True
+        return time.monotonic() >= self._expires_at - self._margin
+
+    async def get_or_refresh(self) -> str:
+        """Return cached token or acquire a new one (with lock guard)."""
+        if not self.is_expired():
+            assert self._token is not None
+            return self._token
+
+        async with self._lock:
+            # Double-check after acquiring the lock — another caller may
+            # have refreshed while we waited.  Use actual expiry (not
+            # margin-adjusted) because the margin is for the fast-path
+            # outside the lock; inside the lock we just need to know if
+            # the token is still actually valid.
+            if self._token is not None and self._expires_at > time.monotonic():
+                return self._token
+
+            token, expires_in = await self._acquire()
+            self._token = token
+            self._expires_at = time.monotonic() + expires_in
+            return token

lightweb_adapter_sdk-0.2.4/src/lightweb_adapter_sdk/auth/provider.py

@@ -0,0 +1,128 @@
+"""Client-credentials token provider.
+
+Acquires and caches OAuth2 bearer tokens via the client_credentials
+grant.  Tokens are refreshed before expiry to avoid handing out
+near-expired tokens to downstream requests.
+
+See ``docs/contract.md`` for the overall adapter contract.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from lightweb_adapter_sdk.auth.errors import TokenAcquisitionError
+from lightweb_adapter_sdk.auth.protocol import (
+    HttpClient,
+    TokenProvider,
+    _RefreshGuard,
+)
+
+# Default expires_in fallback when the token endpoint omits the field.
+# Keycloak defaults to 300s (5 min); this mirrors that convention.
+_DEFAULT_EXPIRES_IN_SECONDS: float = 300.0
+
+
+class ClientCredentialsTokenProvider(TokenProvider):
+    """OAuth2 client-credentials token provider.
+
+    Constructs bearer tokens by POSTing form-encoded credentials to an
+    OAuth2 token endpoint.  The acquired token is cached and returned
+    on subsequent ``get_token()`` calls until it is within
+    ``refresh_margin_seconds`` of expiry, at which point a new token
+    is acquired.
+
+    The provider takes an **injected** async HTTP client rather than
+    importing an HTTP library directly, keeping the SDK's runtime
+    dependency surface at ``pydantic`` + ``nats-py``.  Any async HTTP
+    client whose ``post`` method matches the ``HttpClient`` Protocol
+    (a single ``post(url, data={...})`` returning an object with
+    ``.status_code``, ``.json()``) is accepted.
+
+    Concurrency: ``get_token()`` is safe for concurrent callers.  When
+    the cached token is expired, a single re-acquisition is performed
+    under an ``asyncio.Lock``; all concurrent callers wait for and
+    receive the same refreshed token.
+
+    Args:
+        token_endpoint: The OAuth2 token endpoint URL.
+        client_id: The client identifier.
+        client_secret: The client secret.
+        http_client: An injected async HTTP client satisfying the
+            ``HttpClient`` Protocol.
+        refresh_margin_seconds: Seconds before expiry to trigger a
+            refresh.  The default is ``30.0`` — this covers the common
+            case where a token has a ~5-minute lifetime and a downstream
+            request may take several seconds; handing back a token with
+            < 30 s remaining would cause latent failures.  Tune this
+            value if your token lifetime or request latency profile
+            differs.
+    """
+
+    def __init__(
+        self,
+        token_endpoint: str,
+        client_id: str,
+        client_secret: str,
+        http_client: HttpClient,
+        refresh_margin_seconds: float = 30.0,
+    ) -> None:
+        self._endpoint = token_endpoint
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._http_client = http_client
+        self._margin = refresh_margin_seconds
+        self._guard: _RefreshGuard | None = None
+        self._init_lock = asyncio.Lock()
+
+    async def _acquire(self) -> tuple[str, float]:
+        """POST the client_credentials grant and return (token, expires_in)."""
+        try:
+            resp = await self._http_client.post(
+                self._endpoint,
+                data={
+                    "grant_type": "client_credentials",
+                    "client_id": self._client_id,
+                    "client_secret": self._client_secret,
+                },
+            )
+        except Exception as exc:
+            raise TokenAcquisitionError(
+                f"HTTP request to token endpoint failed: {exc}"
+            ) from exc
+
+        if resp.status_code < 200 or resp.status_code >= 300:
+            raise TokenAcquisitionError(
+                f"Token endpoint returned status {resp.status_code}"
+            )
+
+        body = resp.json()
+        token = body.get("access_token")
+        if not token:
+            raise TokenAcquisitionError("Token response missing 'access_token' field")
+        expires_in: float = float(body.get("expires_in", _DEFAULT_EXPIRES_IN_SECONDS))
+        return (token, expires_in)
+
+    async def get_token(self) -> str:
+        """Return a valid bearer token, acquiring or refreshing as needed.
+
+        On first call, acquires a token via the client_credentials grant.
+        On subsequent calls, returns the cached token unless it is within
+        ``refresh_margin_seconds`` of expiry — then re-acquires.
+
+        Raises:
+            TokenAcquisitionError: If the token endpoint returns a
+                non-2xx response, the response body lacks
+                ``access_token``, or a transport error occurs.
+        """
+        if self._guard is None:
+            async with self._init_lock:
+                # Double-check after acquiring the init lock — another
+                # concurrent caller may have created the guard while we
+                # waited.
+                if self._guard is None:
+                    self._guard = _RefreshGuard(
+                        self._acquire,
+                        self._margin,
+                    )
+        return await self._guard.get_or_refresh()

lightweb_adapter_sdk-0.2.4/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.4}/src/lightweb_adapter_sdk/testkit/__init__.py

@@ -8,6 +8,11 @@ Import from this module to test your adapter during development:
 - ``FakeEntitlementsService``: an in-process fake of the platform's
   entitlements service for staging state in tests that drive
   ``apply()`` or ``reconcile()``.
+- ``FakeEventSource``: an in-process fake of the JetStream event source
+  for testing event consumers.
+- ``FakeTokenEndpoint``: an in-process fake of an OAuth2 token endpoint
+  for testing the auth provider's token acquisition, caching, and
+  refresh-before-expiry behaviour.
 
 Adapter authors re-export the test functions in their own
 ``tests/test_structural.py`` and provide an ``adapter_under_test``
@@ -18,6 +23,7 @@ See docs/testkit.md for full usage instructions.
 
 from lightweb_adapter_sdk.testkit.fake_entitlements import FakeEntitlementsService
 from lightweb_adapter_sdk.testkit.fake_event_source import FakeEventSource
+from lightweb_adapter_sdk.testkit.fake_token_endpoint import FakeTokenEndpoint
 from lightweb_adapter_sdk.testkit.structural import (
     test_capabilities_returns_well_shaped,
     test_health_is_callable,
@@ -28,6 +34,7 @@ from lightweb_adapter_sdk.testkit.structural import (
 __all__ = [
     "FakeEntitlementsService",
     "FakeEventSource",
+    "FakeTokenEndpoint",
     "test_satisfies_protocol",
     "test_capabilities_returns_well_shaped",
     "test_health_is_callable",

{lightweb_adapter_sdk-0.2.2 → lightweb_adapter_sdk-0.2.4}/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.4/src/lightweb_adapter_sdk/testkit/fake_token_endpoint.py

@@ -0,0 +1,145 @@
+"""Fake token endpoint for testing the auth provider.
+
+Provides ``FakeTokenEndpoint``, an in-process fake that satisfies the
+``HttpClient`` Protocol structurally.  Tests use it to stage token
+responses, assert caching behaviour, and exercise refresh-before-expiry
+and clean-failure paths.
+
+See docs/testkit.md for usage instructions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+import asyncio
+
+class _FakeResponse:
+    """In-memory response returned by ``FakeTokenEndpoint.post``.
+
+    Structural match for ``httpx.Response`` as consumed by the provider:
+    ``.status_code``, ``.json()``, ``.raise_for_status()``.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        body: dict[str, Any],
+    ) -> None:
+        self._status_code = status_code
+        self._body = body
+
+    @property
+    def status_code(self) -> int:
+        return self._status_code
+
+    def json(self) -> dict[str, Any]:
+        return dict(self._body)
+
+    def raise_for_status(self) -> None:
+        if self._status_code < 200 or self._status_code >= 300:
+            raise RuntimeError(f"HTTP {self._status_code}: {self._body}")
+
+
+class FakeTokenEndpoint:
+    """In-process fake of an OAuth2 token endpoint.
+
+    Satisfies the ``HttpClient`` Protocol structurally so it can be
+    injected into ``ClientCredentialsTokenProvider``.  Each call to
+    ``post`` returns a canned token response (or error) determined by
+    the staged state.
+
+    Tests use this to:
+    - Stage the token value(s) it returns and the ``expires_in``.
+    - Count how many times it was called (to assert caching).
+    - Return a near-expiry / expired token so a test can assert
+      refresh-before-expiry triggers re-acquisition.
+    - Return an error response (non-2xx / missing ``access_token``)
+      so a test can assert clean failure.
+
+    Args:
+        access_token: The token value returned by ``post``.
+        expires_in: Seconds until expiry (default 300).
+        status_code: HTTP status code to return (default 200).
+    """
+
+    def __init__(
+        self,
+        access_token: str = "fake-token-00000000000000000000000000000000",
+        expires_in: int = 300,
+        status_code: int = 200,
+    ) -> None:
+        self._access_token = access_token
+        self._expires_in = expires_in
+        self._status_code = status_code
+        self._call_count = 0
+
+    async def post(
+        self,
+        url: str,
+        *,
+        data: dict[str, str],
+    ) -> _FakeResponse:
+        """Return the staged token response and increment the call count.
+
+        Args:
+            url: The token endpoint URL (ignored; the fake accepts any URL).
+            data: The form-encoded data sent by the provider
+                (grant_type, client_id, client_secret).
+
+        Returns:
+            A ``_FakeResponse`` with the staged status code and body.
+        """
+        await asyncio.sleep(0)
+        self._call_count += 1
+        body: dict[str, Any] = {
+            "access_token": self._access_token,
+            "token_type": "Bearer",
+            "expires_in": self._expires_in,
+        }
+        return _FakeResponse(self._status_code, body)
+
+    @property
+    def call_count(self) -> int:
+        """Number of times ``post`` was called."""
+        return self._call_count
+
+    def stage_token(
+        self,
+        access_token: str,
+        expires_in: int = 300,
+    ) -> None:
+        """Stage a new token value and expiry for the next ``post`` call.
+
+        Args:
+            access_token: The token string to return.
+            expires_in: Seconds until expiry (default 300).
+        """
+        self._access_token = access_token
+        self._expires_in = expires_in
+
+    def stage_error(
+        self,
+        status_code: int = 401,
+        error_body: dict[str, Any] | None = None,
+    ) -> None:
+        """Stage an error response for the next ``post`` call.
+
+        Args:
+            status_code: HTTP status code (e.g. 401, 500).
+            error_body: Optional body dict (defaults to
+                ``{"error": "invalid_client"}``).
+        """
+        self._status_code = status_code
+        self._access_token = ""
+        self._expires_in = 0
+        if error_body is not None:
+            self._error_body = error_body
+        else:
+            self._error_body = {"error": "invalid_client"}
+
+    def reset(self) -> None:
+        """Reset call count and restore default token."""
+        self._call_count = 0
+        self.stage_token("fake-token-00000000000000000000000000000000")
+        self._expires_in = 300
+        self._status_code = 200

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,
-    )