edgesync 0.2.0__tar.gz → 0.3.1__tar.gz

{edgesync-0.2.0 → edgesync-0.3.1}/.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.0 → edgesync-0.3.1}/CHANGELOG.md

@@ -7,6 +7,41 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [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
+
+- `Contributing` and `License` links in the package's `[project.urls]` metadata, so they
+  show up in PyPI's project sidebar alongside Homepage/Repository/Documentation/Changelog.
+- `Issue Tracker` link in `[project.urls]`.
+
+### Fixed
+
+- `README.md` links to `docs/`, `CONTRIBUTING.md`, and `LICENSE` used repo-relative paths,
+  which render correctly on GitHub but break on PyPI (e.g. resolving to
+  `pypi.org/project/edgesync/CONTRIBUTING.md/`) since PyPI renders the README as a
+  standalone page. They're now absolute `github.com` URLs.
+
 ## [0.2.0] - 2026-08-23
 
 ### Added
@@ -47,6 +82,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.2.0...HEAD
+[Unreleased]: https://github.com/adhuldas/EdgeSync/compare/v0.3.1...HEAD
+[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.0 → edgesync-0.3.1}/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.0 → edgesync-0.3.1}/PKG-INFO

@@ -1,11 +1,14 @@
 Metadata-Version: 2.5
 Name: edgesync
-Version: 0.2.0
+Version: 0.3.1
 Summary: Reliable data delivery for unreliable networks.
 Project-URL: Homepage, https://github.com/adhuldas/EdgeSync
 Project-URL: Repository, https://github.com/adhuldas/EdgeSync
 Project-URL: Documentation, https://github.com/adhuldas/EdgeSync/tree/main/docs
 Project-URL: Changelog, https://github.com/adhuldas/EdgeSync/blob/main/CHANGELOG.md
+Project-URL: Issue Tracker, https://github.com/adhuldas/EdgeSync/issues
+Project-URL: Contributing, https://github.com/adhuldas/EdgeSync/blob/main/CONTRIBUTING.md
+Project-URL: License, https://github.com/adhuldas/EdgeSync/blob/main/LICENSE
 Author-email: Adhul Das M K <adhulamz@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
@@ -24,13 +27,15 @@ 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
 
 [![CI](https://github.com/adhuldas/EdgeSync/actions/workflows/ci.yml/badge.svg)](https://github.com/adhuldas/EdgeSync/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/edgesync.svg)](https://pypi.org/project/edgesync/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/adhuldas/EdgeSync/blob/main/LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
 
 A lightweight Python library for reliable data delivery from edge applications to cloud
@@ -52,7 +57,7 @@ solves this with a durable store-and-forward architecture:
 5. Pending data survives process crashes and device restarts.
 
 EdgeSync provides **at-least-once** delivery, not exactly-once — see
-[docs/reliability.md](docs/reliability.md) for the exact guarantee and how to build
+[docs/reliability.md](https://github.com/adhuldas/EdgeSync/blob/main/docs/reliability.md) for the exact guarantee and how to build
 idempotent consumers on top of it.
 
 ## Install
@@ -114,7 +119,7 @@ async def telemetry(payload: dict):
 
 Flask is synchronous, so it needs a small bridge to run EdgeSync's event loop on a background
 thread rather than spinning up a new loop per request. See
-[docs/integrations.md](docs/integrations.md) for the full FastAPI, Flask, and plain-`asyncio`
+[docs/integrations.md](https://github.com/adhuldas/EdgeSync/blob/main/docs/integrations.md) for the full FastAPI, Flask, and plain-`asyncio`
 guide, including the ready-to-use Flask bridge.
 
 ## Features
@@ -127,17 +132,17 @@ 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`.
 
 ## Documentation
 
-- [Getting started](docs/getting-started.md)
-- [Using EdgeSync with FastAPI, Flask, and plain asyncio](docs/integrations.md)
-- [Reliability & delivery guarantees](docs/reliability.md)
-- [Storage design](docs/storage.md)
+- [Getting started](https://github.com/adhuldas/EdgeSync/blob/main/docs/getting-started.md)
+- [Using EdgeSync with FastAPI, Flask, and plain asyncio](https://github.com/adhuldas/EdgeSync/blob/main/docs/integrations.md)
+- [Reliability & delivery guarantees](https://github.com/adhuldas/EdgeSync/blob/main/docs/reliability.md)
+- [Storage design](https://github.com/adhuldas/EdgeSync/blob/main/docs/storage.md)
 
 ## Development
 
@@ -148,8 +153,8 @@ uv run ruff check .
 uv run mypy
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
+See [CONTRIBUTING.md](https://github.com/adhuldas/EdgeSync/blob/main/CONTRIBUTING.md) for the full workflow.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/adhuldas/EdgeSync/blob/main/LICENSE).

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

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/adhuldas/EdgeSync/actions/workflows/ci.yml/badge.svg)](https://github.com/adhuldas/EdgeSync/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/edgesync.svg)](https://pypi.org/project/edgesync/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/adhuldas/EdgeSync/blob/main/LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
 
 A lightweight Python library for reliable data delivery from edge applications to cloud
@@ -24,7 +24,7 @@ solves this with a durable store-and-forward architecture:
 5. Pending data survives process crashes and device restarts.
 
 EdgeSync provides **at-least-once** delivery, not exactly-once — see
-[docs/reliability.md](docs/reliability.md) for the exact guarantee and how to build
+[docs/reliability.md](https://github.com/adhuldas/EdgeSync/blob/main/docs/reliability.md) for the exact guarantee and how to build
 idempotent consumers on top of it.
 
 ## Install
@@ -86,7 +86,7 @@ async def telemetry(payload: dict):
 
 Flask is synchronous, so it needs a small bridge to run EdgeSync's event loop on a background
 thread rather than spinning up a new loop per request. See
-[docs/integrations.md](docs/integrations.md) for the full FastAPI, Flask, and plain-`asyncio`
+[docs/integrations.md](https://github.com/adhuldas/EdgeSync/blob/main/docs/integrations.md) for the full FastAPI, Flask, and plain-`asyncio`
 guide, including the ready-to-use Flask bridge.
 
 ## Features
@@ -99,17 +99,17 @@ 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`.
 
 ## Documentation
 
-- [Getting started](docs/getting-started.md)
-- [Using EdgeSync with FastAPI, Flask, and plain asyncio](docs/integrations.md)
-- [Reliability & delivery guarantees](docs/reliability.md)
-- [Storage design](docs/storage.md)
+- [Getting started](https://github.com/adhuldas/EdgeSync/blob/main/docs/getting-started.md)
+- [Using EdgeSync with FastAPI, Flask, and plain asyncio](https://github.com/adhuldas/EdgeSync/blob/main/docs/integrations.md)
+- [Reliability & delivery guarantees](https://github.com/adhuldas/EdgeSync/blob/main/docs/reliability.md)
+- [Storage design](https://github.com/adhuldas/EdgeSync/blob/main/docs/storage.md)
 
 ## Development
 
@@ -120,8 +120,8 @@ uv run ruff check .
 uv run mypy
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
+See [CONTRIBUTING.md](https://github.com/adhuldas/EdgeSync/blob/main/CONTRIBUTING.md) for the full workflow.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/adhuldas/EdgeSync/blob/main/LICENSE).

edgesync-0.3.1/VERSION

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

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

@@ -124,6 +124,42 @@ 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.
+
 ## Inspecting the queue
 
 ```python

edgesync-0.3.1/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.0 → edgesync-0.3.1}/pyproject.toml

@@ -25,11 +25,17 @@ 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"
 Documentation = "https://github.com/adhuldas/EdgeSync/tree/main/docs"
 Changelog = "https://github.com/adhuldas/EdgeSync/blob/main/CHANGELOG.md"
+"Issue Tracker" = "https://github.com/adhuldas/EdgeSync/issues"
+Contributing = "https://github.com/adhuldas/EdgeSync/blob/main/CONTRIBUTING.md"
+License = "https://github.com/adhuldas/EdgeSync/blob/main/LICENSE"
 
 [dependency-groups]
 dev = [

edgesync-0.3.1/tests/integration/test_mqtt_transport.py

@@ -0,0 +1,151 @@
+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

{edgesync-0.2.0 → edgesync-0.3.1}/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.0/VERSION

@@ -1 +0,0 @@
-0.2.0