feat(amgi-pulsar): add Apache Pulsar support

.github/workflows/tests.yml

@@ -56,6 +56,7 @@ jobs:
           - amgi-kafka-event-source-mapping
           - amgi-nats
           - amgi-paho-mqtt
+          - amgi-pulsar
           - amgi-redis
           - amgi-sqs-event-source-mapping
           - amgi-types

.pre-commit-config.yaml

@@ -11,7 +11,7 @@ repos:
     rev: v1.19.1
     hooks:
       - id: mypy
-        additional_dependencies: ["pydantic==2.12.5", "nats-py>=2.10.0", "types-docutils", "types-PyYAML", "sphinx>=7.4.7", "starlette==1.2.1"]
+        additional_dependencies: ["pydantic==2.12.5", "nats-py>=2.10.0", "pulsar-client>=3.13.0", "types-docutils", "types-PyYAML", "sphinx>=7.4.7", "starlette==1.2.1"]
   - repo: https://github.com/PyCQA/autoflake
     rev: v2.3.3
     hooks:

README.md

@@ -202,6 +202,11 @@ The following AMGI servers are currently available:
 - **[amgi-nats](https://pypi.org/project/amgi-nats/)** - Contains [NATS](https://nats.io/) push and pull server
   implementations
 
+### Pulsar
+
+- **[amgi-pulsar](https://pypi.org/project/amgi-pulsar/)** - [Apache Pulsar](https://pulsar.apache.org/) server
+  implementation
+
 ### Redis
 
 - **[amgi-redis](https://pypi.org/project/amgi-redis/)** - [Redis](https://redis.io/) server implementation

docs/specifications/bindings.rst

@@ -9,14 +9,24 @@ A message sent to an application can only contain one protocol in its binding ob
 can include multiple protocol bindings. The server simply ignores the binding if it cannot handle it. This is to allow
 for progressive migrations of an application
 
-*******
+********
  Kafka
-*******
+********
 
 The Kafka binding object has the following key:
 
--  ``message["bindings"]["keys"]`` (:py:obj:`~typing.NotRequired` [ :py:obj:`~typing.Optional` [:py:obj:`bytes` ]]) -
-   The :py:obj:`bytes` of the Kafka key, this can be also be :py:obj:`None`. If missing, it defaults to :py:obj:`None`.
+-  ``message["bindings"]["kafka"]["key"]`` (:py:obj:`~typing.NotRequired` [ :py:obj:`~typing.Optional` [:py:obj:`bytes` ]]) -
+   The :py:obj:`bytes` of the Kafka key, this can also be :py:obj:`None`. If missing, it defaults to :py:obj:`None`.
+
+********
+ Pulsar
+********
+
+The Pulsar binding object has the following key:
+
+-  ``message["bindings"]["pulsar"]["key"]`` (:py:obj:`~typing.NotRequired` [ :py:obj:`~typing.Optional` [:py:obj:`str` ]]) -
+   The :py:obj:`str` of the Pulsar partition key, this can also be :py:obj:`None`. If missing, it defaults to
+   :py:obj:`None`.
 
 .. _asyncapi: https://www.asyncapi.com/en
 

example/README.md

@@ -88,6 +88,25 @@ Or via NATS pull subscriptions with:
 asyncfast run amgi-nats-pull main:app input_channel
 ```
 
+## Pulsar
+
+Run the Pulsar compose file with:
+
+```commandline
+docker compose --file apache-pulsar/docker-compose.yaml up --detach
+```
+
+This includes:
+
+- A Pulsar standalone cluster running on `pulsar://localhost:6650`
+- Pulsar HTTP service ([`http://localhost:8080/`](http://localhost:8080/))
+
+Connect the app via Pulsar with:
+
+```commandline
+asyncfast run amgi-pulsar main:app input_channel
+```
+
 ## SQS
 
 Run the SQS compose file with:

example/apache-pulsar/docker-compose.yaml

@@ -0,0 +1,8 @@
+services:
+  pulsar:
+    image: ghcr.io/asyncfast/apachepulsar/pulsar:4.0.5
+    command: bin/pulsar standalone
+    restart: unless-stopped
+    ports:
+      - "6650:6650"
+      - "8080:8080"

example/pyproject.toml

@@ -17,6 +17,7 @@ dependencies = [
   "amgi-aiokafka",
   "amgi-nats",
   "amgi-paho-mqtt",
+  "amgi-pulsar",
   "asyncfast",
 ]
 
@@ -25,4 +26,5 @@ sources.amgi-aio-pika = { workspace = true }
 sources.amgi-aiokafka = { workspace = true }
 sources.amgi-nats = { workspace = true }
 sources.amgi-paho-mqtt = { workspace = true }
+sources.amgi-pulsar = { workspace = true }
 sources.asyncfast = { workspace = true }

packages/amgi-pulsar/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jack Burridge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/amgi-pulsar/README.md

@@ -0,0 +1,58 @@
+# amgi-pulsar
+
+amgi-pulsar is an [AMGI](https://amgi.readthedocs.io/en/latest/) compatible server project, supporting running AMGI
+applications against [Apache Pulsar](https://pulsar.apache.org/) topics.
+
+The server consumes messages from a shared subscription, which is created if it does not exist. The subscription type
+can be configured with `consumer_type`; `Shared` (the default) provides no ordering guarantees between consumers, while
+`Exclusive`, `Failover` and `KeyShared` are also available. Messages are only acknowledged when the application sends a
+`message.ack` event; a `message.nack` event triggers a redelivery. Messages that remain unacknowledged for longer than
+`unacked_messages_timeout_ms` (30000 by default) are also redelivered.
+
+## Installation
+
+```
+pip install amgi-pulsar==0.47.0
+```
+
+## Example
+
+This example uses [AsyncFast](https://pypi.org/project/asyncfast/):
+
+```python
+from dataclasses import dataclass
+
+from amgi_pulsar import run
+from asyncfast import AsyncFast
+
+app = AsyncFast()
+
+
+@dataclass
+class Order:
+    item_ids: list[str]
+
+
+@app.channel("order.topic")
+async def order_topic(order: Order) -> None:
+    # Makes an order
+    ...
+
+
+if __name__ == "__main__":
+    run(app, "order.topic")
+```
+
+Or the application could be run via the commandline:
+
+```commandline
+asyncfast run amgi-pulsar main:app order.topic
+```
+
+## Contact
+
+For questions or suggestions, please contact [jack.burridge@mail.com](mailto:jack.burridge@mail.com).
+
+## License
+
+Copyright 2025 AMGI

packages/amgi-pulsar/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+build-backend = "uv_build"
+requires = [
+  "uv-build>=0.8.14,<0.9.0",
+]
+
+[project]
+name = "amgi-pulsar"
+version = "0.49.0"
+description = "AMGI Apache Pulsar Server"
+readme = "README.md"
+license = "MIT"
+license-files = [
+  "LICENSE",
+]
+authors = [
+  { name = "jack.burridge", email = "jack.burridge@mail.com" },
+]
+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.49.0",
+  "amgi-types==0.49.0",
+  "pulsar-client>=3.10.0",
+  "typing-extensions>=4.15.0; python_full_version<'3.11'",
+]
+entry-points.amgi_server.amgi-pulsar = "amgi_pulsar:_run_cli"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.4.1",
+  "pytest-asyncio>=1.3.0",
+  "pytest-cov>=7.0.0",
+  "pytest-timeout>=2.4.0",
+  "test-utils",
+  "testcontainers>=4.13.0",
+]
+
+[tool.uv]
+sources.amgi-common.workspace = true
+sources.amgi-types.workspace = true
+sources.test-utils.workspace = true