amgi-cloudevents 0.40.0__tar.gz

amgi_cloudevents-0.40.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.3
+Name: amgi-cloudevents
+Version: 0.40.0
+Summary: Add your description here
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: amgi-common==0.40.0
+Requires-Dist: amgi-types==0.40.0
+Requires-Dist: cloudevents>=2.1.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: starlette>=1.2.1
+Requires-Dist: typing-extensions>=4.15.0 ; python_full_version < '3.11'
+Requires-Dist: uvicorn>=0.49.0 ; extra == 'uvicorn'
+Requires-Python: >=3.10
+Provides-Extra: uvicorn
+Description-Content-Type: text/markdown
+
+# amgi-cloudevents
+
+CloudEvents HTTP adapter for AMGI applications.
+
+## Installation
+
+```shell
+pip install "amgi-cloudevents[uvicorn]==0.40.0"
+```
+
+## Receiving CloudEvents
+
+```python
+from amgi_cloudevents import run
+from asyncfast import AsyncFast
+
+app = AsyncFast()
+
+
+@app.channel("com.example.event")
+async def handle_event(payload: bytes) -> None: ...
+
+
+if __name__ == "__main__":
+    run(app, host="0.0.0.0", port=8000)
+```
+
+You can also run an app through the AsyncFast CLI entry point:
+
+```shell
+asyncfast run amgi-cloudevents-uvicorn main:app --host 0.0.0.0 --port 8000
+```
+
+If the app sends follow-up messages, provide an outbound CloudEvents endpoint:
+
+```shell
+asyncfast run amgi-cloudevents-uvicorn main:app \
+  --message-send-endpoint https://example.com/events \
+  --message-send-source /orders \
+  --message-send-content-mode binary
+```
+
+`Server` accepts binary or structured CloudEvents on `POST /event` by default.
+CloudEvent attributes and extensions are exposed as AMGI headers. For example,
+`ce-id: event-1` becomes `(b"id", b"event-1")`.
+
+AMGI `message.ack` returns `204 No Content`. AMGI `message.nack` returns `500`
+with the nack message as the response body. Invalid CloudEvents return `400`.
+
+## Sending CloudEvents
+
+```python
+from amgi_cloudevents import MessageSend
+from amgi_cloudevents import Server
+
+message_send = MessageSend(
+    "https://example.com/events",
+    source="/orders",
+    content_mode="binary",
+)
+server = Server(app, message_send=message_send)
+```
+
+`MessageSend` maps AMGI `message.send` events to CloudEvents:
+
+- `event["address"]` becomes the CloudEvent `type`
+- `event["payload"]` becomes the CloudEvent data
+- `event["headers"]` become CloudEvent attributes/extensions
+- `source` defaults to `/amgi-cloudevents`, unless the AMGI headers include
+  `source`
+
+`content_mode` can be `"structured"` or `"binary"`. Structured mode is the
+default.
+
+If `Server` receives an AMGI `message.send` event without a configured
+`message_send`, it raises an error explaining that outbound sending must be
+wired explicitly.

amgi_cloudevents-0.40.0/README.md

@@ -0,0 +1,77 @@
+# amgi-cloudevents
+
+CloudEvents HTTP adapter for AMGI applications.
+
+## Installation
+
+```shell
+pip install "amgi-cloudevents[uvicorn]==0.40.0"
+```
+
+## Receiving CloudEvents
+
+```python
+from amgi_cloudevents import run
+from asyncfast import AsyncFast
+
+app = AsyncFast()
+
+
+@app.channel("com.example.event")
+async def handle_event(payload: bytes) -> None: ...
+
+
+if __name__ == "__main__":
+    run(app, host="0.0.0.0", port=8000)
+```
+
+You can also run an app through the AsyncFast CLI entry point:
+
+```shell
+asyncfast run amgi-cloudevents-uvicorn main:app --host 0.0.0.0 --port 8000
+```
+
+If the app sends follow-up messages, provide an outbound CloudEvents endpoint:
+
+```shell
+asyncfast run amgi-cloudevents-uvicorn main:app \
+  --message-send-endpoint https://example.com/events \
+  --message-send-source /orders \
+  --message-send-content-mode binary
+```
+
+`Server` accepts binary or structured CloudEvents on `POST /event` by default.
+CloudEvent attributes and extensions are exposed as AMGI headers. For example,
+`ce-id: event-1` becomes `(b"id", b"event-1")`.
+
+AMGI `message.ack` returns `204 No Content`. AMGI `message.nack` returns `500`
+with the nack message as the response body. Invalid CloudEvents return `400`.
+
+## Sending CloudEvents
+
+```python
+from amgi_cloudevents import MessageSend
+from amgi_cloudevents import Server
+
+message_send = MessageSend(
+    "https://example.com/events",
+    source="/orders",
+    content_mode="binary",
+)
+server = Server(app, message_send=message_send)
+```
+
+`MessageSend` maps AMGI `message.send` events to CloudEvents:
+
+- `event["address"]` becomes the CloudEvent `type`
+- `event["payload"]` becomes the CloudEvent data
+- `event["headers"]` become CloudEvent attributes/extensions
+- `source` defaults to `/amgi-cloudevents`, unless the AMGI headers include
+  `source`
+
+`content_mode` can be `"structured"` or `"binary"`. Structured mode is the
+default.
+
+If `Server` receives an AMGI `message.send` event without a configured
+`message_send`, it raises an error explaining that outbound sending must be
+wired explicitly.

amgi_cloudevents-0.40.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+build-backend = "uv_build"
+requires = [
+  "uv-build>=0.11.19,<0.12.0",
+]
+
+[project]
+name = "amgi-cloudevents"
+version = "0.40.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+  "amgi-common==0.40.0",
+  "amgi-types==0.40.0",
+  "cloudevents>=2.1.0",
+  "httpx>=0.28.1",
+  "starlette>=1.2.1",
+  "typing-extensions>=4.15.0; python_full_version<'3.11'",
+]
+optional-dependencies.uvicorn = [
+  "uvicorn>=0.49.0",
+]
+entry-points.amgi_server.amgi-cloudevents-uvicorn = "amgi_cloudevents._run:run"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.4.1",
+  "pytest-asyncio>=1.3.0",
+  "pytest-cov>=7.0.0",
+  "pytest-timeout>=2.4.0",
+  "test-utils",
+  "uvicorn>=0.49.0",
+]
+
+[tool.uv]
+sources.amgi-common = { workspace = true }
+sources.amgi-types = { workspace = true }
+sources.test-utils = { workspace = true }

amgi_cloudevents-0.40.0/src/amgi_cloudevents/__init__.py

@@ -0,0 +1,5 @@
+from amgi_cloudevents._message_send import MessageSend
+from amgi_cloudevents._run import run
+from amgi_cloudevents._server import Server
+
+__all__ = ["MessageSend", "Server", "run"]

amgi_cloudevents-0.40.0/src/amgi_cloudevents/_message_send.py

@@ -0,0 +1,67 @@
+import sys
+from types import TracebackType
+from typing import Literal
+
+import httpx
+from amgi_types import MessageSendEvent
+from cloudevents.v1.conversion import to_binary
+from cloudevents.v1.conversion import to_structured
+from cloudevents.v1.http import CloudEvent
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+ContentMode = Literal["binary", "structured"]
+
+
+def _decode_headers(headers: list[tuple[bytes, bytes]]) -> dict[str, str]:
+    try:
+        return {key.decode(): value.decode() for key, value in headers}
+    except UnicodeDecodeError as exc:
+        raise ValueError("CloudEvent attributes must be UTF-8 encoded") from exc
+
+
+class MessageSend:
+    def __init__(
+        self,
+        event_endpoint: str,
+        *,
+        source: str = "/amgi-cloudevents",
+        content_mode: ContentMode = "structured",
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._client = client or httpx.AsyncClient()
+        self._close_client = client is None
+        self._event_endpoint = event_endpoint
+        self._source = source
+        self._content_mode = content_mode
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        if self._close_client:
+            await self._client.aclose()
+
+    async def __call__(self, event: MessageSendEvent) -> None:
+        attributes = _decode_headers(list(event["headers"]))
+        attributes["source"] = attributes.get("source", self._source)
+        attributes["type"] = event["address"]
+
+        cloud_event = CloudEvent(attributes, event.get("payload"))
+        if self._content_mode == "binary":
+            headers, body = to_binary(cloud_event)
+        else:
+            headers, body = to_structured(cloud_event)
+
+        response = await self._client.post(
+            self._event_endpoint, headers=headers, content=body
+        )
+        response.raise_for_status()

amgi_cloudevents-0.40.0/src/amgi_cloudevents/_run.py

@@ -0,0 +1,27 @@
+from amgi_cloudevents._message_send import ContentMode
+from amgi_cloudevents._message_send import MessageSend
+from amgi_cloudevents._server import Server
+from amgi_types import AMGIApplication
+
+
+def run(
+    app: AMGIApplication,
+    host: str = "0.0.0.0",
+    port: int = 8000,
+    path: str = "/event",
+    message_send_endpoint: str | None = None,
+    message_send_source: str = "/amgi-cloudevents",
+    message_send_content_mode: ContentMode = "structured",
+) -> None:
+    import uvicorn
+
+    message_send = (
+        MessageSend(
+            message_send_endpoint,
+            source=message_send_source,
+            content_mode=message_send_content_mode,
+        )
+        if message_send_endpoint is not None
+        else None
+    )
+    uvicorn.run(Server(app, path=path, message_send=message_send), host=host, port=port)

amgi_cloudevents-0.40.0/src/amgi_cloudevents/_server.py

@@ -0,0 +1,159 @@
+from collections.abc import AsyncIterator
+from collections.abc import Awaitable
+from collections.abc import Callable
+from collections.abc import Mapping
+from contextlib import asynccontextmanager
+from types import TracebackType
+from typing import Any
+from typing import AsyncContextManager
+
+from amgi_common import Lifespan
+from amgi_types import AMGIApplication
+from amgi_types import AMGIReceiveEvent
+from amgi_types import AMGISendEvent
+from amgi_types import MessageScope
+from amgi_types import MessageSendEvent
+from cloudevents.v1.exceptions import GenericException as CloudEventException
+from cloudevents.v1.http import from_http
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.routing import Route
+from starlette.status import HTTP_204_NO_CONTENT
+from starlette.status import HTTP_400_BAD_REQUEST
+from starlette.status import HTTP_500_INTERNAL_SERVER_ERROR
+
+_MessageSendT = Callable[[MessageSendEvent], Awaitable[None]]
+_MessageSendManagerT = AsyncContextManager[_MessageSendT]
+
+
+class MissingMessageSend:
+    async def __aenter__(self) -> _MessageSendT:
+        return self._send
+
+    async def _send(self, event: MessageSendEvent) -> None:
+        raise RuntimeError(
+            "CloudEvents message.send is not configured. Pass message_send to Server "
+            "to allow AMGI handlers to send follow-up messages."
+        )
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        pass
+
+
+class Send:
+    def __init__(self, message_send: _MessageSendT) -> None:
+        self._message_send = message_send
+        self.acknowledged = False
+        self.nack_message: str | None = None
+
+    async def __call__(self, event: AMGISendEvent) -> None:
+        if event["type"] == "message.ack":
+            self.acknowledged = True
+        elif event["type"] == "message.nack":
+            self.nack_message = event["message"]
+        elif event["type"] == "message.send":
+            await self._message_send(event)
+
+
+async def receive() -> AMGIReceiveEvent:
+    raise RuntimeError("Receive should not be called")
+
+
+def bytes_unmarshaller(content: None | str | bytes) -> bytes | None:
+    if content is None:
+        return None
+    if isinstance(content, bytes):
+        return content
+    return content.encode()
+
+
+def _encode_header_value(value: Any) -> bytes:
+    if isinstance(value, bytes):
+        return value
+    return str(value).encode()
+
+
+def _encode_headers(attributes: Mapping[str, Any]) -> list[tuple[bytes, bytes]]:
+    return [
+        (name.encode(), _encode_header_value(value))
+        for name, value in attributes.items()
+    ]
+
+
+class Server(Starlette):
+    def __init__(
+        self,
+        app: AMGIApplication,
+        path: str = "/event",
+        message_send: _MessageSendManagerT | None = None,
+    ) -> None:
+        self._app = app
+        self._state: dict[str, Any] = {}
+        self._message_send_context = message_send or MissingMessageSend()
+        self._message_send: _MessageSendT | None = None
+        super().__init__(
+            routes=[Route(path, self._route, methods=["POST"])], lifespan=self._lifespan
+        )
+
+    @asynccontextmanager
+    async def _lifespan(self, _server: Starlette) -> AsyncIterator[None]:
+        async with self._message_send_context as message_send:
+            self._message_send = message_send
+            async with Lifespan(self._app, self._state):
+                yield
+            self._message_send = None
+
+    async def _call_app(self, scope: MessageScope) -> Send:
+        if self._message_send is None:
+            async with self._message_send_context as message_send:
+                send = Send(message_send)
+                await self._app(scope, receive, send)
+                return send
+
+        send = Send(self._message_send)
+        await self._app(scope, receive, send)
+        return send
+
+    def _response(self, send: Send) -> Response:
+        if send.nack_message is not None:
+            return Response(
+                send.nack_message, status_code=HTTP_500_INTERNAL_SERVER_ERROR
+            )
+        if send.acknowledged:
+            return Response(status_code=HTTP_204_NO_CONTENT)
+        return Response(status_code=HTTP_204_NO_CONTENT)
+
+    async def _route(self, request: Request) -> Response:
+        try:
+            cloud_event = from_http(
+                request.headers,
+                await request.body(),
+                data_unmarshaller=bytes_unmarshaller,
+            )
+        except CloudEventException as exc:
+            return Response(str(exc), status_code=HTTP_400_BAD_REQUEST)
+
+        attributes = cloud_event.get_attributes()
+        address = attributes["type"]
+        if not isinstance(address, str):
+            return Response(
+                "CloudEvent type attribute must be a string",
+                status_code=HTTP_400_BAD_REQUEST,
+            )
+
+        scope: MessageScope = {
+            "type": "message",
+            "amgi": {"version": "2.0", "spec_version": "2.0"},
+            "address": address,
+            "headers": _encode_headers(attributes),
+            "payload": cloud_event.get_data(),
+            "state": self._state.copy(),
+        }
+        send = await self._call_app(scope)
+        return self._response(send)