edgesync 0.3.1__tar.gz → 0.3.2__tar.gz

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

@@ -7,6 +7,21 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [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 +97,8 @@ 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.2...HEAD
+[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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: edgesync
-Version: 0.3.1
+Version: 0.3.2
 Summary: Reliable data delivery for unreliable networks.
 Project-URL: Homepage, https://github.com/adhuldas/EdgeSync
 Project-URL: Repository, https://github.com/adhuldas/EdgeSync
@@ -94,6 +94,68 @@ 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
+
+Install the optional extra first:
+
+```bash
+pip install edgesync[mqtt]
+```
+
+Publishing to MQTT instead of HTTP is the same pattern with a different transport:
+
+```python
+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})
+```
+
+`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.2}/README.md

@@ -61,6 +61,68 @@ 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
+
+Install the optional extra first:
+
+```bash
+pip install edgesync[mqtt]
+```
+
+Publishing to MQTT instead of HTTP is the same pattern with a different transport:
+
+```python
+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})
+```
+
+`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.2/VERSION

@@ -0,0 +1 @@
+0.3.2

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

@@ -160,6 +160,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.2}/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/VERSION

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