feat(amgi-paho-mqtt): add message send manager

[TomKimber]

Add Portable Senders support to amgi-paho-mqtt: #72.

This adds a MessageSend async context manager to amgi-paho-mqtt. It handles message.send events on its own paho client and connection instead of reusing the consuming client. It waits for the CONNACK on entry and raises on a broker rejection or a timeout (connect_timeout, default 10s). Each send waits for the broker’s acknowledgement and raises PublishError on failure. The mqtt binding now supports retain as well as qos. With MQTT v5, headers are sent as user properties and content-type maps to the MQTT content type property. MQTT v3.1.1 cannot represent headers, so they are dropped. run() and Server accept an optional message_send manager and connect_timeout.

To share the logic, the asyncio socket, publish and disconnect handling moved out of Server into a _ClientLoop helper that both clients use. It also adds reconnection after unexpected disconnects, which retries every second and logs failures to amgi-paho-mqtt.error. On event loops without add_reader/add_writer, such as the default Proactor loop on Windows, a _SocketWatcher fallback watches the socket from a background thread and runs paho's read and write handlers on the event loop. Previously the package failed on Windows with NotImplementedError. A blocking connect that is abandoned by a timeout or cancellation but later succeeds is now disconnected rather than leaked. The amgi_server entry point now points at a thin _run_cli wrapper, and typing-extensions is added for Python < 3.11. The README has a new “Sending Messages” section, and there are new unit tests plus a broker-backed integration test.

amgi-paho-mqtt is the only gap - Confirmed all other packages have a consistent portable senders implementation.

[read-the-docs-community]

Documentation build overview

📚 AMGI | 🛠️ Build #35127415 | 📁 Comparing d2454ef against latest (7f72e38)

  🔍 Preview build  

3 files changed

± specifications/bindings.html
± specifications/lifespan.html
± specifications/message.html

[Copilot]

🟡 Changes recommended

Connection and publish failures can leave sender initialization or in-flight publishes hanging indefinitely.

1 open finding

• Resolve in-flight publish futures on disconnect · New

What changed in this PR

Adds portable MQTT message-sender support with injectable lifecycle management.

Changes:

• Introduces MessageSend and shared asynchronous MQTT client-loop handling.
• Adds sender injection and a CLI-safe wrapper.
• Adds unit/integration coverage and Python 3.10 typing support.

File	Description
uv.lock	Locks the conditional typing dependency.
test_mqtt_message.py	Tests send dispatch and initialization requirements.
test_mqtt_message_integration.py	Tests sender injection, lifecycle, and CLI execution.
amgi_paho_mqtt/​__init__.py	Implements portable sending and lifecycle integration.
pyproject.toml	Adds typing support and updates the CLI entry point.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

🟡 Changes recommended

Non-cancellable connection workers and unhandled entry cancellation can leak MQTT connections during timeout or shutdown.

3 open findings

• Reconnect worker can reopen MQTT socket after shutdown · New
• Connect timeout can leak a late-created MQTT socket · New
• Cancelled CONNACK wait leaks connected client resources · New

1 resolved since last review

• Resolve in-flight publish futures on disconnect

🧠 Review effort: Balanced

[read-the-docs-community]

Documentation build overview

📚 AsyncFast | 🛠️ Build #35127416 | 📁 Comparing d2454ef against latest (7f72e38)

  🔍 Preview build  

1 file changed

± message_payload.html