edgesync 0.3.1__tar.gz → 0.3.3__tar.gz

{edgesync-0.3.1 → edgesync-0.3.3}/CHANGELOG.md

@@ -7,6 +7,28 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-09-13
+
+### Changed
+
+- `aiomqtt` is now a required dependency instead of an optional `mqtt` extra, so
+  `pip install edgesync` alone is enough to use `MQTTTransport`.
+
+## [0.3.2] - 2026-08-24
+
+### Added
+
+- MQTT TLS documentation in `README.md` and `docs/getting-started.md`, covering
+  `tls_params`/`port` usage for TLS connections and client-certificate (mutual TLS) auth, plus
+  test coverage for the `aiomqtt.Client` construction path (both plaintext and TLS), which
+  wasn't previously exercised since existing tests injected a fake client directly.
+
+### Changed
+
+- `README.md`'s Quickstart now includes a full MQTT usage section (previously it only linked
+  out to the getting-started guide), so the MQTT example renders directly on PyPI's project
+  page instead of requiring a click-through to GitHub.
+
 ## [0.3.1] - 2026-08-24
 
 ### Fixed
@@ -82,7 +104,9 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Crash and restart recovery via expired-lease sweeps, safe across concurrent workers and
   processes sharing the same database file.
 
-[Unreleased]: https://github.com/adhuldas/EdgeSync/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/adhuldas/EdgeSync/compare/v0.3.3...HEAD
+[0.3.3]: https://github.com/adhuldas/EdgeSync/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/adhuldas/EdgeSync/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/adhuldas/EdgeSync/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/adhuldas/EdgeSync/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/adhuldas/EdgeSync/compare/v0.2.0...v0.2.1

{edgesync-0.3.1 → edgesync-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: edgesync
-Version: 0.3.1
+Version: 0.3.3
 Summary: Reliable data delivery for unreliable networks.
 Project-URL: Homepage, https://github.com/adhuldas/EdgeSync
 Project-URL: Repository, https://github.com/adhuldas/EdgeSync
@@ -25,10 +25,9 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Distributed Computing
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: aiomqtt<3,>=2.5
 Requires-Dist: aiosqlite>=0.20
 Requires-Dist: httpx>=0.27
-Provides-Extra: mqtt
-Requires-Dist: aiomqtt<3,>=2.5; extra == 'mqtt'
 Description-Content-Type: text/markdown
 
 # EdgeSync
@@ -94,6 +93,67 @@ That's it: `publish()` durably persists the message and returns as soon as it's
 background worker delivers it, retrying with exponential backoff on failure, without the
 caller needing to stay connected or wait for the network.
 
+## MQTT
+
+Publishing to MQTT instead of HTTP is the same pattern with a different transport:
+
+```python
+import asyncio
+from edgesync import EdgeSync
+from edgesync.transports.mqtt import MQTTTransport
+
+
+async def main():
+    async with EdgeSync(
+        database="edgesync.db",
+        destinations={
+            "telemetry": MQTTTransport(
+                "broker.example.com",
+                "devices/device-001/telemetry",
+                qos=1,
+                username="device-001",
+                password="...",
+            ),
+        },
+        default_destination="telemetry",
+    ) as sync:
+        await sync.publish({"temperature": 28.5})
+
+
+asyncio.run(main())
+```
+
+`MQTTTransport` only accepts QoS 1 or 2 — QoS 0 publishes are never acknowledged by the
+broker, so there'd be no way to tell a successful delivery from a lost one, which would break
+EdgeSync's at-least-once guarantee. Unlike `HTTPTransport`, MQTT holds a persistent broker
+connection: `EdgeSync.start()` still won't raise if the broker is unreachable (data keeps
+queuing locally either way), and the transport automatically reconnects on the next delivery
+attempt after a dropped connection or failed publish.
+
+**TLS**: by default `MQTTTransport` connects in plaintext on port `1883`. To connect over
+TLS, pass `tls_params` (an `aiomqtt.TLSParameters`) and switch to the broker's TLS port,
+conventionally `8883`:
+
+```python
+import aiomqtt
+from edgesync.transports.mqtt import MQTTTransport
+
+MQTTTransport(
+    "broker.example.com",
+    "devices/device-001/telemetry",
+    port=8883,
+    tls_params=aiomqtt.TLSParameters(
+        ca_certs="/etc/ssl/certs/ca-certificates.crt",
+    ),
+)
+```
+
+`TLSParameters` also accepts `certfile` / `keyfile` for client-certificate (mutual TLS)
+authentication. Omit `tls_params` entirely for an unencrypted connection, e.g. a broker on a
+trusted local network or a local development/test setup. See the
+[MQTT section of the getting-started guide](https://github.com/adhuldas/EdgeSync/blob/main/docs/getting-started.md#mqtt)
+for further detail.
+
 ## Usage with FastAPI, Flask, and plain asyncio
 
 EdgeSync is async-native, so it's most at home in an `asyncio` app or an async framework like

{edgesync-0.3.1 → edgesync-0.3.3}/README.md

@@ -61,6 +61,67 @@ That's it: `publish()` durably persists the message and returns as soon as it's
 background worker delivers it, retrying with exponential backoff on failure, without the
 caller needing to stay connected or wait for the network.
 
+## MQTT
+
+Publishing to MQTT instead of HTTP is the same pattern with a different transport:
+
+```python
+import asyncio
+from edgesync import EdgeSync
+from edgesync.transports.mqtt import MQTTTransport
+
+
+async def main():
+    async with EdgeSync(
+        database="edgesync.db",
+        destinations={
+            "telemetry": MQTTTransport(
+                "broker.example.com",
+                "devices/device-001/telemetry",
+                qos=1,
+                username="device-001",
+                password="...",
+            ),
+        },
+        default_destination="telemetry",
+    ) as sync:
+        await sync.publish({"temperature": 28.5})
+
+
+asyncio.run(main())
+```
+
+`MQTTTransport` only accepts QoS 1 or 2 — QoS 0 publishes are never acknowledged by the
+broker, so there'd be no way to tell a successful delivery from a lost one, which would break
+EdgeSync's at-least-once guarantee. Unlike `HTTPTransport`, MQTT holds a persistent broker
+connection: `EdgeSync.start()` still won't raise if the broker is unreachable (data keeps
+queuing locally either way), and the transport automatically reconnects on the next delivery
+attempt after a dropped connection or failed publish.
+
+**TLS**: by default `MQTTTransport` connects in plaintext on port `1883`. To connect over
+TLS, pass `tls_params` (an `aiomqtt.TLSParameters`) and switch to the broker's TLS port,
+conventionally `8883`:
+
+```python
+import aiomqtt
+from edgesync.transports.mqtt import MQTTTransport
+
+MQTTTransport(
+    "broker.example.com",
+    "devices/device-001/telemetry",
+    port=8883,
+    tls_params=aiomqtt.TLSParameters(
+        ca_certs="/etc/ssl/certs/ca-certificates.crt",
+    ),
+)
+```
+
+`TLSParameters` also accepts `certfile` / `keyfile` for client-certificate (mutual TLS)
+authentication. Omit `tls_params` entirely for an unencrypted connection, e.g. a broker on a
+trusted local network or a local development/test setup. See the
+[MQTT section of the getting-started guide](https://github.com/adhuldas/EdgeSync/blob/main/docs/getting-started.md#mqtt)
+for further detail.
+
 ## Usage with FastAPI, Flask, and plain asyncio
 
 EdgeSync is async-native, so it's most at home in an `asyncio` app or an async framework like

edgesync-0.3.3/VERSION

@@ -0,0 +1 @@
+0.3.3

{edgesync-0.3.1 → edgesync-0.3.3}/docs/getting-started.md

@@ -126,31 +126,30 @@ than HTTP.
 
 ## MQTT
 
-Install the optional extra first:
-
-```bash
-pip install edgesync[mqtt]
-```
-
 ```python
+import asyncio
 from edgesync import EdgeSync
 from edgesync.transports.mqtt import MQTTTransport
 
-sync = EdgeSync(
-    database="edgesync.db",
-    destinations={
-        "telemetry": MQTTTransport(
-            "broker.example.com",
-            "devices/device-001/telemetry",
-            qos=1,
-            username="device-001",
-            password="...",
-        ),
-    },
-    default_destination="telemetry",
-)
 
-await sync.publish({"temperature": 28.5})
+async def main():
+    async with EdgeSync(
+        database="edgesync.db",
+        destinations={
+            "telemetry": MQTTTransport(
+                "broker.example.com",
+                "devices/device-001/telemetry",
+                qos=1,
+                username="device-001",
+                password="...",
+            ),
+        },
+        default_destination="telemetry",
+    ) as sync:
+        await sync.publish({"temperature": 28.5})
+
+
+asyncio.run(main())
 ```
 
 `MQTTTransport` only accepts QoS 1 or 2 — QoS 0 publishes are never acknowledged by the
@@ -160,6 +159,31 @@ connection: `EdgeSync.start()` still won't raise if the broker is unreachable (d
 queuing locally either way), and the transport automatically reconnects on the next delivery
 attempt after a dropped connection or failed publish.
 
+### TLS
+
+By default `MQTTTransport` connects in plaintext on port `1883`. To connect over TLS, pass
+`tls_params` (an `aiomqtt.TLSParameters`, re-exported from the underlying `paho-mqtt` client)
+and switch to the broker's TLS port, conventionally `8883`:
+
+```python
+import aiomqtt
+from edgesync.transports.mqtt import MQTTTransport
+
+MQTTTransport(
+    "broker.example.com",
+    "devices/device-001/telemetry",
+    port=8883,
+    tls_params=aiomqtt.TLSParameters(
+        ca_certs="/etc/ssl/certs/ca-certificates.crt",
+    ),
+)
+```
+
+`TLSParameters` also accepts `certfile` / `keyfile` for client-certificate (mutual TLS)
+authentication — see [aiomqtt's documentation](https://aiomqtt.bo3hm.com) for the full set of
+options. Omit `tls_params` entirely for an unencrypted connection, e.g. when talking to a
+broker on a trusted local network or in a local development/test setup.
+
 ## Inspecting the queue
 
 ```python

{edgesync-0.3.1 → edgesync-0.3.3}/edgesync/transports/mqtt.py

@@ -1,7 +1,5 @@
 """MQTT transport backed by ``aiomqtt``.
 
-Requires the optional ``aiomqtt`` dependency: ``pip install edgesync[mqtt]``.
-
 Unlike :class:`~edgesync.transports.http.HTTPTransport`, MQTT is a stateful,
 persistent connection rather than a per-request protocol, which shapes two
 design decisions here:
@@ -22,18 +20,13 @@ from __future__ import annotations
 import contextlib
 import json
 
+import aiomqtt
+
 from edgesync.logging import logger
 from edgesync.models.delivery import DeliveryResult
 from edgesync.models.message import Message
 from edgesync.transports.base import Transport
 
-try:
-    import aiomqtt
-except ImportError as exc:  # pragma: no cover - exercised only without the extra installed
-    raise ImportError(
-        "MQTTTransport requires the 'aiomqtt' package. Install it with: pip install edgesync[mqtt]"
-    ) from exc
-
 
 class MQTTTransport(Transport):
     """Publish messages as JSON payloads to a fixed MQTT topic.

{edgesync-0.3.1 → edgesync-0.3.3}/pyproject.toml

@@ -23,11 +23,9 @@ classifiers = [
 dependencies = [
     "httpx>=0.27",
     "aiosqlite>=0.20",
+    "aiomqtt>=2.5,<3",
 ]
 
-[project.optional-dependencies]
-mqtt = ["aiomqtt>=2.5,<3"]
-
 [project.urls]
 Homepage = "https://github.com/adhuldas/EdgeSync"
 Repository = "https://github.com/adhuldas/EdgeSync"

{edgesync-0.3.1 → edgesync-0.3.3}/tests/integration/test_mqtt_transport.py

@@ -149,3 +149,47 @@ async def test_close_after_failed_start_does_not_disconnect() -> None:
     await transport.start()
     await transport.close()
     assert fake.disconnect_calls == 0
+
+
+async def test_start_without_tls_params_constructs_plaintext_client(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    captured: dict[str, object] = {}
+
+    class RecordingClient(FakeMQTTClient):
+        def __init__(self, hostname: str, port: int, **kwargs: object) -> None:
+            super().__init__()
+            captured["hostname"] = hostname
+            captured["port"] = port
+            captured.update(kwargs)
+
+    monkeypatch.setattr(aiomqtt, "Client", RecordingClient)
+
+    transport = MQTTTransport("broker.invalid", "telemetry")
+    await transport.start()
+
+    assert captured["hostname"] == "broker.invalid"
+    assert captured["port"] == 1883
+    assert captured["tls_params"] is None
+
+
+async def test_start_with_tls_params_constructs_tls_client(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    captured: dict[str, object] = {}
+
+    class RecordingClient(FakeMQTTClient):
+        def __init__(self, hostname: str, port: int, **kwargs: object) -> None:
+            super().__init__()
+            captured["hostname"] = hostname
+            captured["port"] = port
+            captured.update(kwargs)
+
+    monkeypatch.setattr(aiomqtt, "Client", RecordingClient)
+
+    tls_params = aiomqtt.TLSParameters(ca_certs="/etc/ssl/certs/ca-certificates.crt")
+    transport = MQTTTransport("broker.invalid", "telemetry", port=8883, tls_params=tls_params)
+    await transport.start()
+
+    assert captured["port"] == 8883
+    assert captured["tls_params"] is tls_params

{edgesync-0.3.1 → edgesync-0.3.3}/uv.lock

@@ -270,15 +270,11 @@ toml = [
 name = "edgesync"
 source = { editable = "." }
 dependencies = [
+    { name = "aiomqtt" },
     { name = "aiosqlite" },
     { name = "httpx" },
 ]
 
-[package.optional-dependencies]
-mqtt = [
-    { name = "aiomqtt" },
-]
-
 [package.dev-dependencies]
 dev = [
     { name = "mypy" },
@@ -291,11 +287,10 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "aiomqtt", marker = "extra == 'mqtt'", specifier = ">=2.5,<3" },
+    { name = "aiomqtt", specifier = ">=2.5,<3" },
     { name = "aiosqlite", specifier = ">=0.20" },
     { name = "httpx", specifier = ">=0.27" },
 ]
-provides-extras = ["mqtt"]
 
 [package.metadata.requires-dev]
 dev = [

edgesync-0.3.1/VERSION

@@ -1 +0,0 @@
-0.3.1