feat(amgi-stomp): add STOMP support

.github/workflows/tests.yml

@@ -58,6 +58,7 @@ jobs:
           - amgi-paho-mqtt
           - amgi-redis
           - amgi-sqs-event-source-mapping
+          - amgi-stomp
           - amgi-types
           - asyncfast
           - asyncfast-avro

.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", "stompman>=3.16.0", "types-docutils", "types-PyYAML", "sphinx>=7.4.7", "starlette==1.2.1"]
   - repo: https://github.com/PyCQA/autoflake
     rev: v2.3.3
     hooks:

.python-versions

@@ -1,5 +1,5 @@
-3.10
 3.11
 3.12
 3.13
 3.14
+3.10

README.md

@@ -206,6 +206,10 @@ The following AMGI servers are currently available:
 
 - **[amgi-redis](https://pypi.org/project/amgi-redis/)** - [Redis](https://redis.io/) server implementation
 
+### STOMP
+
+- **[amgi-stomp](https://pypi.org/project/amgi-stomp/)** - [STOMP](https://stomp.github.io/) server implementation
+
 ### SQS
 
 - **[amgi-aiobotocore](https://pypi.org/project/amgi-aiobotocore/)** - Contains a [SQS](https://aws.amazon.com/sqs/)

docs/specifications/bindings.rst

@@ -18,6 +18,17 @@ 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`.
 
+********
+ STOMP
+********
+
+The STOMP binding object has the following keys:
+
+-  ``message["bindings"]["stomp"]["message_id"]`` - The :py:obj:`str` message id of the STOMP message, assigned by the
+   broker. Useful for deduplication.
+-  ``message["bindings"]["stomp"]["subscription"]`` - The :py:obj:`str` id of the STOMP subscription the message was
+   received on.
+
 .. _asyncapi: https://www.asyncapi.com/en
 
 .. _message bindings object: https://www.asyncapi.com/docs/reference/specification/v3.0.0#messageBindingsObject

example/README.md

@@ -146,3 +146,23 @@ Connect the app via AMQP with:
 ```commandline
 asyncfast run amgi-aio-pika main:app input_channel
 ```
+
+## STOMP
+
+Run the STOMP compose file with:
+
+```commandline
+docker compose --file stomp/docker-compose.yaml up --detach
+```
+
+This includes:
+
+- An ActiveMQ Artemis broker with STOMP enabled, running on `localhost:61613`
+- The Artemis web console ([`http://localhost:8161/console`](http://localhost:8161/console)) logging in with
+  `artemis`/`artemis`
+
+Connect the app via STOMP with:
+
+```commandline
+asyncfast run amgi-stomp main:app input_channel --login artemis --passcode artemis
+```

example/pyproject.toml

@@ -17,6 +17,7 @@ dependencies = [
   "amgi-aiokafka",
   "amgi-nats",
   "amgi-paho-mqtt",
+  "amgi-stomp",
   "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-stomp = { workspace = true }
 sources.asyncfast = { workspace = true }

example/stomp/docker-compose.yaml

@@ -0,0 +1,7 @@
+services:
+  activemq-artemis:
+    image: ghcr.io/asyncfast/apache/activemq-artemis:2.44.0
+    restart: unless-stopped
+    ports:
+      - "61613:61613"
+      - "8161:8161"

packages/amgi-stomp/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-stomp/README.md

@@ -0,0 +1,72 @@
+# amgi-stomp
+
+amgi-stomp is an [AMGI](https://amgi.readthedocs.io/en/latest/) compatible server to run AMGI applications against
+[STOMP](https://stomp.github.io/) brokers using [stompman](https://pypi.org/project/stompman/).
+
+amgi-stomp requires Python 3.11 or greater, as this is the minimum version supported by `stompman`.
+
+## Installation
+
+```
+pip install amgi-stomp==0.47.0
+```
+
+## Example
+
+This example uses [AsyncFast](https://pypi.org/project/asyncfast/):
+
+```python
+from dataclasses import dataclass
+
+from amgi_stomp import run
+from asyncfast import AsyncFast
+
+app = AsyncFast()
+
+
+@dataclass
+class Order:
+    item_ids: list[str]
+
+
+@app.channel("order-queue")
+async def order_queue(order: Order) -> None:
+    # Makes an order
+    ...
+
+
+if __name__ == "__main__":
+    run(app, "order-queue")
+```
+
+Or the application could be run via the commandline:
+
+```commandline
+asyncfast run amgi-stomp main:app order-queue
+```
+
+Messages are consumed with `client-individual` acknowledgement mode. Sending `message.ack` or `message.nack` events
+acknowledges or rejects the current STOMP message. Whether messages that are never acknowledged or are nacked are
+redelivered, dead-lettered, or discarded depends on the broker's configuration.
+
+If an application raises an exception while handling a message, the exception is logged and the message is nacked; what the
+broker does with a nacked message (redeliver, dead-letter, or discard) is broker-specific.
+
+The STOMP protocol metadata of a received message is available in the AMGI message scope:
+`message["bindings"]["stomp"]["message_id"]` and `message["bindings"]["stomp"]["subscription"]`. When using AsyncFast,
+these can be received directly with the `asyncfast.StompMessageId` and `asyncfast.StompSubscription` bindings.
+
+By default, messages are sent without waiting for a broker receipt. Pass a `receipt_timeout` in seconds to `run`,
+`Server`, or `MessageSend` to wait for a receipt confirming the broker processed the SEND frame, at the cost of a broker round-trip. A receipt does
+not by itself make a message durable; persistence is broker-specific. Pass
+`ssl=True` or an `ssl.SSLContext` via the `ssl` parameter of `run` or `Server` to connect over TLS. The `heartbeat`,
+`connect_retry_attempts`, and `connect_retry_interval` parameters expose stompman's heartbeat and connection retry
+options without changing its defaults.
+
+## Contact
+
+For questions or suggestions, please contact [jack.burridge@mail.com](mailto:jack.burridge@mail.com).
+
+## License
+
+Copyright 2025 AMGI

packages/amgi-stomp/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+build-backend = "uv_build"
+requires = [
+  "uv-build>=0.8.14,<0.9.0",
+]
+
+[project]
+name = "amgi-stomp"
+version = "0.49.0"
+description = "AMGI STOMP 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",
+  "stompman>=3.16.0; python_full_version>='3.11'",
+]
+entry-points.amgi_server.amgi-stomp = "amgi_stomp:_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