edgesync 0.2.1__tar.gz → 0.3.2__tar.gz

{edgesync-0.2.1 → edgesync-0.3.2}/.github/workflows/release.yml

@@ -2,6 +2,8 @@ name: Release
 
 on:
   push:
+    branches: [main]
+    paths: ["VERSION"]
     tags:
       - "v*.*.*"
 
@@ -42,26 +44,64 @@ jobs:
         if: matrix.python-version == '3.13'
         run: uv run mypy
 
-  check-version:
-    name: verify tag matches VERSION file
+  tag:
+    name: verify / create release tag
     runs-on: ubuntu-latest
     needs: test
+    permissions:
+      contents: write # required to push the tag when triggered by a VERSION bump
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      should_release: ${{ steps.verify_tag.outputs.should_release || steps.create_tag.outputs.should_release }}
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Determine version and existing-tag status
+        id: version
+        run: |
+          VERSION="$(tr -d '[:space:]' < VERSION)"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          if git ls-remote --exit-code --tags origin "refs/tags/v$VERSION" >/dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
 
-      - name: Compare tag to VERSION file
+      - name: Verify tag matches VERSION file
+        id: verify_tag
+        if: startsWith(github.ref, 'refs/tags/')
         run: |
           TAG_VERSION="${GITHUB_REF_NAME#v}"
-          FILE_VERSION="$(tr -d '[:space:]' < VERSION)"
-          if [ "$TAG_VERSION" != "$FILE_VERSION" ]; then
-            echo "::error::tag v$TAG_VERSION does not match VERSION file ($FILE_VERSION)"
+          if [ "$TAG_VERSION" != "${{ steps.version.outputs.version }}" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match VERSION file (${{ steps.version.outputs.version }})"
             exit 1
           fi
+          echo "should_release=true" >> "$GITHUB_OUTPUT"
+
+      - name: Create and push release tag
+        id: create_tag
+        if: github.ref == 'refs/heads/main' && steps.version.outputs.exists == 'false'
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag "v$VERSION"
+          git push origin "v$VERSION"
+          echo "should_release=true" >> "$GITHUB_OUTPUT"
+
+      - name: Skip (VERSION unchanged / tag already released)
+        if: github.ref == 'refs/heads/main' && steps.version.outputs.exists == 'true'
+        run: |
+          echo "::notice::v${{ steps.version.outputs.version }} already tagged/released; skipping publish."
+          echo "should_release=false" >> "$GITHUB_OUTPUT"
 
   build:
     name: build distributions
     runs-on: ubuntu-latest
-    needs: check-version
+    needs: tag
+    if: needs.tag.outputs.should_release == 'true'
     steps:
       - uses: actions/checkout@v4
 
@@ -107,7 +147,7 @@ jobs:
   github-release:
     name: create GitHub release
     runs-on: ubuntu-latest
-    needs: publish-pypi
+    needs: [tag, publish-pypi]
     permissions:
       contents: write # required to create the GitHub release
     steps:
@@ -122,7 +162,7 @@ jobs:
       - name: Extract CHANGELOG section for this version
         id: changelog
         run: |
-          VERSION="$(tr -d '[:space:]' < VERSION)"
+          VERSION="${{ needs.tag.outputs.version }}"
           NOTES_FILE="$(mktemp)"
           awk -v ver="$VERSION" '
             $0 ~ "^## \\[" ver "\\]" { found=1; next }
@@ -134,11 +174,11 @@ jobs:
             exit 1
           fi
           echo "notes_file=$NOTES_FILE" >> "$GITHUB_OUTPUT"
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
 
       - name: Create GitHub release
         uses: softprops/action-gh-release@v2
         with:
-          name: EdgeSync v${{ steps.changelog.outputs.version }}
+          tag_name: v${{ needs.tag.outputs.version }}
+          name: EdgeSync v${{ needs.tag.outputs.version }}
           body_path: ${{ steps.changelog.outputs.notes_file }}
           files: dist/*

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

@@ -7,6 +7,41 @@ 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
+
+- The release workflow's `should_release` job output was never actually set (it read from
+  the wrong step), so `build distributions`, `publish to PyPI`, and `create GitHub release`
+  were silently skipped on every run, including 0.3.0's. 0.3.0's tag and changes are
+  unaffected; this release exists solely to get the pipeline publishing again.
+
+## [0.3.0] - 2026-08-24
+
+### Added
+
+- `MQTTTransport` (`edgesync.transports.mqtt`), an optional MQTT destination backed by
+  `aiomqtt` (`pip install edgesync[mqtt]`). Only QoS 1/2 are accepted, since QoS 0 publishes
+  are never acknowledged by the broker and can't support at-least-once delivery. The
+  connection reconnects automatically after a dropped connection or failed publish, and
+  `start()` never raises if the broker is unreachable, consistent with EdgeSync's guarantee
+  that local queuing works independent of destination availability.
+
 ## [0.2.1] - 2026-08-24
 
 ### Added
@@ -62,7 +97,10 @@ 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.2.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
 [0.2.0]: https://github.com/adhuldas/EdgeSync/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/adhuldas/EdgeSync/releases/tag/v0.1.0

{edgesync-0.2.1 → edgesync-0.3.2}/CONTRIBUTING.md

@@ -62,18 +62,28 @@ New behavior should come with a test in the appropriate tier. Reliability-sensit
 ## Releasing
 
 `VERSION` (repo root) is the single source of truth for the package version — it's read by
-`pyproject.toml` (via Hatchling) and by `edgesync.__version__` at runtime. To cut a release:
+`pyproject.toml` (via Hatchling) and by `edgesync.__version__` at runtime. Releasing is
+**automatic**: to cut a release, just
 
 1. Bump the version in `VERSION` (no `v` prefix, e.g. `0.2.0`).
 2. Move the `[Unreleased]` entries in `CHANGELOG.md` under a new `## [0.2.0] - YYYY-MM-DD`
-   heading.
-3. Commit those two changes.
-4. Tag the commit and push the tag: `git tag v0.2.0 && git push origin v0.2.0`.
-
-Pushing a `vX.Y.Z` tag triggers `.github/workflows/release.yml`, which runs the full test
-suite, verifies the tag matches `VERSION`, builds the sdist/wheel, and publishes to PyPI via
-Trusted Publishing. If that version is already on PyPI (e.g. the workflow is re-run), the
-publish step is skipped rather than failing.
+   heading — this section becomes the GitHub release notes, so make sure it's accurate.
+3. Commit those two changes and push to `main`.
+
+Pushing a commit that changes `VERSION` on `main` triggers `.github/workflows/release.yml`,
+which runs the full test suite, tags the commit `vX.Y.Z`, builds the sdist/wheel, publishes
+to PyPI via Trusted Publishing, and creates a GitHub release with notes pulled from the
+matching `CHANGELOG.md` section. If a tag for that version already exists (e.g. the workflow
+re-runs on an unrelated push, or the `VERSION` file is reverted), the whole pipeline is
+skipped rather than re-publishing.
+
+**Because of this, any commit that changes `VERSION` on `main` publishes to PyPI** — there's
+no separate confirmation step. Double-check `VERSION` and the `CHANGELOG.md` entry before
+pushing.
+
+You can still trigger a release manually the old way (`git tag vX.Y.Z && git push origin
+vX.Y.Z`) — useful if `VERSION` was already bumped but the automatic run failed for an
+unrelated reason (e.g. a transient PyPI outage).
 
 ## Reporting bugs
 

{edgesync-0.2.1 → edgesync-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: edgesync
-Version: 0.2.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
@@ -27,6 +27,8 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 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
@@ -92,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
@@ -130,8 +194,8 @@ guide, including the ready-to-use Flask bridge.
   inspection instead of being silently dropped.
 - **Multiple destinations** — route different message types to different endpoints or
   transports.
-- **Pluggable transports** — ships with an HTTP transport; implement `Transport` for anything
-  else (MQTT, gRPC, a message broker, ...).
+- **Pluggable transports** — ships with HTTP and MQTT transports; implement `Transport` for
+  anything else (gRPC, a message broker, ...).
 - **Bounded storage** — configurable queue capacity with a choice of overflow policies.
 - **Async-native** — built on `asyncio` and `httpx`.
 

{edgesync-0.2.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
@@ -99,8 +161,8 @@ guide, including the ready-to-use Flask bridge.
   inspection instead of being silently dropped.
 - **Multiple destinations** — route different message types to different endpoints or
   transports.
-- **Pluggable transports** — ships with an HTTP transport; implement `Transport` for anything
-  else (MQTT, gRPC, a message broker, ...).
+- **Pluggable transports** — ships with HTTP and MQTT transports; implement `Transport` for
+  anything else (gRPC, a message broker, ...).
 - **Bounded storage** — configurable queue capacity with a choice of overflow policies.
 - **Async-native** — built on `asyncio` and `httpx`.
 

edgesync-0.3.2/VERSION

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

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

@@ -124,6 +124,67 @@ await sync.publish({"level": "critical"}, destination="alerts")
 Implement the `Transport` ABC (`start`, `deliver`, `close`) to deliver over something other
 than HTTP.
 
+## MQTT
+
+Install the optional extra first:
+
+```bash
+pip install edgesync[mqtt]
+```
+
+```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`, 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.2/edgesync/transports/mqtt.py

@@ -0,0 +1,134 @@
+"""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:
+
+- ``start()`` never raises if the broker is unreachable. Failing hard would
+  contradict EdgeSync's whole premise -- an edge app must still boot and
+  accept ``publish()`` calls into the durable queue even if the destination
+  is down at startup. The first ``deliver()`` call (re)connects on demand,
+  and any failure is reported as a retryable :class:`DeliveryResult` so the
+  worker retries with backoff like any other transient failure.
+- A publish failure tears the connection down (rather than leaving it half
+  broken) so the *next* delivery attempt starts from a clean reconnect
+  instead of repeatedly hitting the same stale, disconnected client.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+
+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.
+
+    Only QoS 1 and 2 are accepted: QoS 0 ("at most once") is never
+    acknowledged by the broker, so there'd be no way to distinguish success
+    from failure and EdgeSync's at-least-once guarantee couldn't be upheld.
+    """
+
+    def __init__(
+        self,
+        hostname: str,
+        topic: str,
+        *,
+        port: int = 1883,
+        qos: int = 1,
+        username: str | None = None,
+        password: str | None = None,
+        client_id: str | None = None,
+        tls_params: aiomqtt.TLSParameters | None = None,
+        timeout: float = 30.0,
+        client: aiomqtt.Client | None = None,
+    ) -> None:
+        if qos not in (1, 2):
+            raise ValueError(
+                f"qos must be 1 or 2 for at-least-once delivery (got {qos}); "
+                "QoS 0 publishes are never acknowledged by the broker"
+            )
+
+        self._topic = topic
+        self._qos = qos
+        self._timeout = timeout
+        self._external_client = client
+        self._client: aiomqtt.Client | None = None
+        self._connected = False
+        self._hostname = hostname
+        self._port = port
+        self._username = username
+        self._password = password
+        self._client_id = client_id
+        self._tls_params = tls_params
+
+    async def start(self) -> None:
+        if self._client is not None:
+            return
+        self._client = self._external_client or aiomqtt.Client(
+            self._hostname,
+            self._port,
+            username=self._username,
+            password=self._password,
+            identifier=self._client_id,
+            tls_params=self._tls_params,
+        )
+        await self._try_connect()
+
+    async def close(self) -> None:
+        if self._client is not None and self._connected:
+            with contextlib.suppress(aiomqtt.MqttError):
+                await self._client.__aexit__(None, None, None)
+        self._client = None
+        self._connected = False
+
+    async def deliver(self, message: Message) -> DeliveryResult:
+        if self._client is None:
+            raise RuntimeError("MQTTTransport.start() must be called before deliver()")
+
+        if not self._connected and not await self._try_connect():
+            return DeliveryResult.retryable_failure("mqtt broker unreachable")
+
+        payload = json.dumps(message.payload).encode("utf-8")
+        try:
+            await self._client.publish(
+                self._topic,
+                payload=payload,
+                qos=self._qos,
+                timeout=self._timeout,
+            )
+        except aiomqtt.MqttError as exc:
+            await self._disconnect_after_error()
+            return DeliveryResult.retryable_failure(f"mqtt error: {exc}")
+
+        return DeliveryResult.success_result()
+
+    async def _try_connect(self) -> bool:
+        assert self._client is not None
+        try:
+            await self._client.__aenter__()
+        except aiomqtt.MqttError as exc:
+            logger.warning("MQTTTransport: broker connection failed: %s", exc)
+            return False
+        self._connected = True
+        return True
+
+    async def _disconnect_after_error(self) -> None:
+        self._connected = False
+        assert self._client is not None
+        with contextlib.suppress(aiomqtt.MqttError):
+            await self._client.__aexit__(None, None, None)

{edgesync-0.2.1 → edgesync-0.3.2}/pyproject.toml

@@ -25,6 +25,9 @@ dependencies = [
     "aiosqlite>=0.20",
 ]
 
+[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.2/tests/integration/test_mqtt_transport.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import json
+
+import aiomqtt
+import pytest
+
+from edgesync.models.delivery import DeliveryOutcome
+from edgesync.transports.mqtt import MQTTTransport
+from tests.fixtures.factories import make_message
+
+
+class FakeMQTTClient:
+    """A minimal double for ``aiomqtt.Client``'s connection/publish lifecycle."""
+
+    def __init__(self, *, fail_connect: bool = False) -> None:
+        self.fail_connect = fail_connect
+        self.connect_calls = 0
+        self.disconnect_calls = 0
+        self.published: list[tuple[str, bytes, int, float | None]] = []
+        self._publish_side_effect: Exception | None = None
+
+    def fail_next_publish(self, exc: Exception) -> None:
+        self._publish_side_effect = exc
+
+    async def __aenter__(self) -> FakeMQTTClient:
+        self.connect_calls += 1
+        if self.fail_connect:
+            raise aiomqtt.MqttError("connection refused")
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        self.disconnect_calls += 1
+
+    async def publish(
+        self, topic: str, payload: bytes, qos: int, *, timeout: float | None = None
+    ) -> None:
+        if self._publish_side_effect is not None:
+            exc, self._publish_side_effect = self._publish_side_effect, None
+            raise exc
+        self.published.append((topic, payload, qos, timeout))
+
+
+@pytest.mark.parametrize("qos", [0, 3, -1])
+async def test_rejects_qos_that_is_not_1_or_2(qos: int) -> None:
+    with pytest.raises(ValueError, match="qos must be 1 or 2"):
+        MQTTTransport("broker.invalid", "telemetry", qos=qos, client=FakeMQTTClient())
+
+
+async def test_deliver_before_start_raises() -> None:
+    transport = MQTTTransport("broker.invalid", "telemetry", client=FakeMQTTClient())
+    with pytest.raises(RuntimeError):
+        await transport.deliver(make_message())
+
+
+async def test_close_without_start_is_safe() -> None:
+    transport = MQTTTransport("broker.invalid", "telemetry", client=FakeMQTTClient())
+    await transport.close()  # must not raise
+
+
+async def test_start_connects_client() -> None:
+    fake = FakeMQTTClient()
+    transport = MQTTTransport("broker.invalid", "telemetry", client=fake)
+    await transport.start()
+    assert fake.connect_calls == 1
+
+
+async def test_start_does_not_raise_when_broker_unreachable() -> None:
+    fake = FakeMQTTClient(fail_connect=True)
+    transport = MQTTTransport("broker.invalid", "telemetry", client=fake)
+    await transport.start()  # must not raise
+
+
+async def test_deliver_retries_connection_when_broker_was_unreachable_at_start() -> None:
+    fake = FakeMQTTClient(fail_connect=True)
+    transport = MQTTTransport("broker.invalid", "telemetry", client=fake)
+    await transport.start()
+    assert fake.connect_calls == 1
+
+    result = await transport.deliver(make_message())
+    assert result.retryable
+    assert fake.connect_calls == 2
+    assert fake.published == []
+
+
+async def test_deliver_success() -> None:
+    fake = FakeMQTTClient()
+    transport = MQTTTransport("broker.invalid", "telemetry", client=fake)
+    await transport.start()
+    result = await transport.deliver(make_message(payload={"temperature": 28.5}))
+    assert result.success
+
+
+async def test_deliver_publishes_json_payload_to_configured_topic() -> None:
+    fake = FakeMQTTClient()
+    transport = MQTTTransport("broker.invalid", "sensors/device-001", client=fake)
+    await transport.start()
+    await transport.deliver(make_message(payload={"temperature": 28.5}))
+    topic, payload, _qos, _timeout = fake.published[0]
+    assert topic == "sensors/device-001"
+    assert json.loads(payload) == {"temperature": 28.5}
+
+
+async def test_deliver_uses_configured_qos() -> None:
+    fake = FakeMQTTClient()
+    transport = MQTTTransport("broker.invalid", "telemetry", qos=2, client=fake)
+    await transport.start()
+    await transport.deliver(make_message())
+    _topic, _payload, qos, _timeout = fake.published[0]
+    assert qos == 2
+
+
+async def test_deliver_mqtt_error_is_retryable() -> None:
+    fake = FakeMQTTClient()
+    transport = MQTTTransport("broker.invalid", "telemetry", client=fake)
+    await transport.start()
+    fake.fail_next_publish(aiomqtt.MqttError("broker went away"))
+
+    result = await transport.deliver(make_message())
+    assert result.retryable
+    assert result.outcome is DeliveryOutcome.RETRYABLE_FAILURE
+
+
+async def test_deliver_reconnects_after_publish_error() -> None:
+    fake = FakeMQTTClient()
+    transport = MQTTTransport("broker.invalid", "telemetry", client=fake)
+    await transport.start()
+    fake.fail_next_publish(aiomqtt.MqttError("broker went away"))
+
+    await transport.deliver(make_message())
+    assert fake.disconnect_calls == 1
+
+    result = await transport.deliver(make_message())
+    assert result.success
+    assert fake.connect_calls == 2
+
+
+async def test_close_disconnects_started_client() -> None:
+    fake = FakeMQTTClient()
+    transport = MQTTTransport("broker.invalid", "telemetry", client=fake)
+    await transport.start()
+    await transport.close()
+    assert fake.disconnect_calls == 1
+
+
+async def test_close_after_failed_start_does_not_disconnect() -> None:
+    fake = FakeMQTTClient(fail_connect=True)
+    transport = MQTTTransport("broker.invalid", "telemetry", client=fake)
+    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.2.1 → edgesync-0.3.2}/uv.lock

@@ -6,6 +6,19 @@ resolution-markers = [
     "python_full_version < '3.15'",
 ]
 
+[[package]]
+name = "aiomqtt"
+version = "2.5.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "paho-mqtt" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/70/44/cfc58272783a11729462dc6df5adbfeabd084f840f609054ac772ae98c19/aiomqtt-2.5.1.tar.gz", hash = "sha256:25a0a47d157e8f158d2da1110ea4786c0615518751e94f7b04976c977a8ff20d", size = 86641, upload-time = "2026-03-05T18:28:56.421Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/01/9e/5089fa596220bf0dc73deeb23db27904e4b3504986caf08571f6f5cb84a8/aiomqtt-2.5.1-py3-none-any.whl", hash = "sha256:fd58c3593160e4d475d90ce911cdfc4239cd64de96b0ba22edf6c86bd7afa278", size = 16051, upload-time = "2026-03-05T18:28:55.14Z" },
+]
+
 [[package]]
 name = "aiosqlite"
 version = "0.22.1"
@@ -261,6 +274,11 @@ dependencies = [
     { name = "httpx" },
 ]
 
+[package.optional-dependencies]
+mqtt = [
+    { name = "aiomqtt" },
+]
+
 [package.dev-dependencies]
 dev = [
     { name = "mypy" },
@@ -273,9 +291,11 @@ dev = [
 
 [package.metadata]
 requires-dist = [
+    { name = "aiomqtt", marker = "extra == 'mqtt'", specifier = ">=2.5,<3" },
     { name = "aiosqlite", specifier = ">=0.20" },
     { name = "httpx", specifier = ">=0.27" },
 ]
+provides-extras = ["mqtt"]
 
 [package.metadata.requires-dev]
 dev = [
@@ -569,6 +589,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/63/34/ba1c580383c9eada3711951fef0795c80b829a078d72188184bcab9dd527/packaging-26.3-py3-none-any.whl", hash = "sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c", size = 129956, upload-time = "2026-08-04T18:15:27.159Z" },
 ]
 
+[[package]]
+name = "paho-mqtt"
+version = "2.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/39/15/0a6214e76d4d32e7f663b109cf71fb22561c2be0f701d67f93950cd40542/paho_mqtt-2.1.0.tar.gz", hash = "sha256:12d6e7511d4137555a3f6ea167ae846af2c7357b10bc6fa4f7c3968fc1723834", size = 148848, upload-time = "2024-04-29T19:52:55.591Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c4/cb/00451c3cf31790287768bb12c6bec834f5d292eaf3022afc88e14b8afc94/paho_mqtt-2.1.0-py3-none-any.whl", hash = "sha256:6db9ba9b34ed5bc6b6e3812718c7e06e2fd7444540df2455d2c51bd58808feee", size = 67219, upload-time = "2024-04-29T19:52:48.345Z" },
+]
+
 [[package]]
 name = "pathspec"
 version = "1.1.1"

edgesync-0.2.1/VERSION

@@ -1 +0,0 @@
-0.2.1