dosync 0.6.0__tar.gz → 0.6.2__tar.gz

{dosync-0.6.0 → dosync-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dosync
-Version: 0.6.0
+Version: 0.6.2
 Summary: The semantic layer between AI agents and physical devices
 Author-email: Rodrigo Giuliani <rgiuliani@dosync.dev>
 License-Expression: Apache-2.0

{dosync-0.6.0 → dosync-0.6.2}/dosync/__init__.py

@@ -13,5 +13,5 @@ The two numbers move independently on purpose:
   __version__           this implementation of the hub  (semver)
   __protocol_version__  the wire contract other implementations must match
 """
-__version__ = "0.6.0"
+__version__ = "0.6.2"
 __protocol_version__ = "0.4"

{dosync-0.6.0 → dosync-0.6.2}/dosync/adapters/__init__.py

@@ -29,6 +29,25 @@ log = logging.getLogger("dosync.adapters")
 
 # ── Base interface every adapter must implement ───────────────────────────────
 
+def failure_reason(exc: BaseException) -> str:
+    """A reason an operator can act on, even when the exception has no text.
+
+    `error=str(e)` was the pattern in six adapters, and it produced
+    `"error": ""` on real hardware: a WiZ bulb powered off at the wall raised an
+    exception whose `str()` is empty, so the hub reported that the action failed
+    and said nothing else. The log line ended at the colon.
+
+    An exception type is not a diagnosis, but it is not nothing either — and a
+    blank field is strictly worse than "TimeoutError with no message", because
+    the second at least tells the reader where to look.
+    """
+    text = str(exc).strip()
+    if text:
+        return text
+    return (f"{type(exc).__name__} with no message — the device did not "
+            "answer, or answered in a way the adapter could not read.")
+
+
 class DoSyncAdapter(ABC):
     """
     Base interface for physical device adapters.

{dosync-0.6.0 → dosync-0.6.2}/dosync/adapters/homeassistant.py

@@ -41,6 +41,7 @@ if TYPE_CHECKING:
     from ..hub import DoSyncHub
 
 from ..adapters import DoSyncAdapter
+from . import failure_reason
 from ..models import (
     ActionResult, ActuatorSpec, CapabilityManifest,
     CertTier, DeviceAction, DeviceCategory, EventSpec,
@@ -610,7 +611,7 @@ class HABridge(DoSyncAdapter):
                 device_id=action.device_id,
                 action=action.action,
                 success=False,
-                error=str(e),
+                error=failure_reason(e),
             )
 
     async def get_state(self, device_id: str) -> dict | None:

{dosync-0.6.0 → dosync-0.6.2}/dosync/adapters/matter.py

@@ -39,6 +39,7 @@ from typing import Optional
 
 from ..adapters import DoSyncAdapter
 from ..models import ActionResult, DeviceAction, Urgency
+from . import failure_reason
 
 log = logging.getLogger("dosync.adapters.matter")
 
@@ -257,7 +258,7 @@ class MatterAdapter(DoSyncAdapter):
                 action=action.action,
                 success=False,
                 response=None,
-                error=str(e),
+                error=failure_reason(e),
             )
 
     def _call_ha(self, device_type: str,

{dosync-0.6.0 → dosync-0.6.2}/dosync/adapters/mqtt.py

@@ -359,7 +359,7 @@ class MQTTAdapter(DoSyncAdapter):
             log.warning("MQTTAdapter: publish failed for '%s': %s", action.device_id, exc)
             return ActionResult(
                 device_id=action.device_id, action=action.action,
-                success=False, error=str(exc),
+                success=False, error=failure_reason(exc),
             )
 
     # ── Helpers ───────────────────────────────────────────────────────────────

{dosync-0.6.0 → dosync-0.6.2}/dosync/adapters/notifications.py

@@ -199,7 +199,7 @@ class NotificationAdapter(DoSyncAdapter):
             )
             return ActionResult(device_id=action.device_id, action=action.action, success=True, response={'status': 'sent'})
         except Exception as e:
-            return ActionResult(device_id=action.device_id, action=action.action, success=False, error=str(e))
+            return ActionResult(device_id=action.device_id, action=action.action, success=False, error=failure_reason(e))
 
     async def notify(self, intent: str, urgency: str, context: dict,
                      to: str = None) -> bool:

{dosync-0.6.0 → dosync-0.6.2}/dosync/adapters/shelly.py

@@ -34,6 +34,7 @@ from typing import Optional
 
 from ..adapters import DoSyncAdapter
 from ..models import ActionResult, DeviceAction, Urgency
+from . import failure_reason
 
 log = logging.getLogger("dosync.adapters.shelly")
 
@@ -305,7 +306,7 @@ class ShellyAdapter(DoSyncAdapter):
                 action=action.action,
                 success=False,
                 response=None,
-                error=str(e),
+                error=failure_reason(e),
             )
 
     async def _execute_http(self, ip: str, gen: int,

{dosync-0.6.0 → dosync-0.6.2}/dosync/adapters/wiz.py

@@ -248,12 +248,22 @@ class WiZAdapter(DoSyncAdapter):
                     success=False,
                     error="WiZ timeout — device unreachable",
                 )
-            log.error("WiZ error %s @ %s: %s", action.device_id, ip, e)
+            # `str(e)` alone is not a reason. pywizlight raises exceptions whose
+            # text is empty — a bulb that was powered off at the wall returned
+            # `success: false, error: ""`, and the log line ended at the colon.
+            # The operator was told the action failed and nothing else, which is
+            # the same failure this project fixed in the verification panel: an
+            # exception carrying no message must not become a blank field.
+            reason = str(e).strip() or (
+                f"{type(e).__name__} with no message — the bulb did not answer. "
+                "It is usually powered off at the wall, on another network, or "
+                "busy with another controller.")
+            log.error("WiZ error %s @ %s: %s", action.device_id, ip, reason)
             return ActionResult(
                 device_id=action.device_id,
                 action=action.action,
                 success=False,
-                error=str(e),
+                error=reason,
             )
 
     async def get_state(self, device_id: str) -> dict | None:

{dosync-0.6.0 → dosync-0.6.2}/dosync/discoverers_ssdp.py

@@ -254,15 +254,25 @@ class SSDPDiscoverer:
         # loops, so discovery behaves the same wherever the hub runs.
         queue: asyncio.Queue = asyncio.Queue()
 
-        def _readable() -> None:
-            try:
-                queue.put_nowait(sock.recvfrom(4096))
-            except (BlockingIOError, InterruptedError):
-                pass
-            except OSError as exc:
-                log.debug("SSDP read on port %s failed: %s", port, exc)
-
-        loop.add_reader(sock.fileno(), _readable)
+        class _Collector(asyncio.DatagramProtocol):
+            """Hands each datagram to the queue the reader below drains."""
+
+            def datagram_received(self, data: bytes, addr) -> None:
+                queue.put_nowait((data, addr))
+
+            def error_received(self, exc: Exception) -> None:
+                log.debug("SSDP socket error on port %s: %s", port, exc)
+
+        # `create_datagram_endpoint` is the one UDP mechanism all three event
+        # loops this hub runs on actually implement. The two before it each
+        # worked on the loop they were written against and raised
+        # NotImplementedError on another: `sock_recvfrom` on uvloop, which
+        # uvicorn[standard] installs on Linux, and then `add_reader` on
+        # Windows, whose ProactorEventLoop has no reader registration for
+        # sockets at all. Both were found in production rather than by the
+        # suite, because the suite runs on one loop and there are three.
+        transport, _ = await loop.create_datagram_endpoint(
+            _Collector, sock=sock)
         deadline = loop.time() + timeout
         try:
             while loop.time() < deadline:
@@ -324,10 +334,7 @@ class SSDPDiscoverer:
                                                      or headers.get("st") or ""),
                 )
         finally:
-            # Both, in this order: a reader left registered on a closed fd
-            # makes the loop spin on a descriptor nobody owns any more.
-            try:
-                loop.remove_reader(sock.fileno())
-            except (OSError, ValueError):
-                pass
-            sock.close()
+            # The transport owns the socket once the endpoint is created —
+            # closing it here closes both, and closing the socket separately
+            # would pull it out from under the loop.
+            transport.close()

{dosync-0.6.0 → dosync-0.6.2}/dosync/server.py

@@ -12,7 +12,8 @@ import json
 import os
 import re
 from fastapi import Depends, FastAPI, HTTPException, Request, WebSocket, WebSocketDisconnect
-from fastapi.responses import FileResponse, HTMLResponse, PlainTextResponse
+from fastapi.responses import (FileResponse, HTMLResponse, JSONResponse,
+                               PlainTextResponse)
 from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel, field_validator
 
@@ -933,7 +934,26 @@ async def lifespan(app: FastAPI):
         log.warning("Could not flush the audit head on shutdown: %s", _fh_e)
     log.info("DoSync Hub shutting down")
 
+class _UTF8JSONResponse(JSONResponse):
+    """`application/json; charset=utf-8`, said out loud rather than assumed.
+
+    JSON is UTF-8 by definition and FastAPI therefore omits the charset — which
+    is correct and, for one widely used client, useless. Windows PowerShell 5.1
+    falls back to Latin-1 when a response does not declare one, so an operator
+    following this project's own Windows instructions saw
+    `read-only status query â device has no sensors` where an em dash belonged,
+    and would see the same for every accented character a deployment uses in a
+    device name.
+
+    Being right about the specification while a reader gets mojibake is the
+    kind of correctness this project has decided is not worth much.
+    """
+
+    media_type = "application/json; charset=utf-8"
+
+
 app = FastAPI(
+    default_response_class=_UTF8JSONResponse,
     title="DoSync Hub",
     description=(
         "DoSync Protocol — REST API\n\n"
@@ -2480,7 +2500,8 @@ async def scan_devices(auth: str = Depends(require_auth)):
             found.extend(await discover_wiz(timeout=5.0))
             searched.append("wiz (udp broadcast)")
         except Exception as e:
-            log.info("WiZ scan did not run: %s", e)
+            logging.getLogger("dosync.server").info(
+                "WiZ scan did not run: %s", e)
             skipped.append("wiz (udp broadcast)")
     else:
         skipped.append("wiz (udp broadcast — pywizlight not installed)")
@@ -2497,7 +2518,8 @@ async def scan_devices(auth: str = Depends(require_auth)):
             found.extend(await adapter.discover(timeout=5.0))
             searched.append(name)
         except Exception as e:
-            log.warning("Discovery via %s did not run: %s: %s",
+            logging.getLogger("dosync.server").warning(
+                "Discovery via %s did not run: %s: %s",
                         name, type(e).__name__, e)
             skipped.append(f"{name} — failed: {type(e).__name__}")
 
@@ -2516,7 +2538,8 @@ async def scan_devices(auth: str = Depends(require_auth)):
             # transport absent from BOTH, so a reader could not tell it had
             # been attempted at all — and the adapter loop above still does
             # exactly that, which is the same defect waiting to be noticed.
-            log.warning("Discovery via %s did not run: %s: %s",
+            logging.getLogger("dosync.server").warning(
+                "Discovery via %s did not run: %s: %s",
                         discoverer.name, type(e).__name__, e)
             skipped.append(f"{label} — failed: {type(e).__name__}")
 

{dosync-0.6.0 → dosync-0.6.2}/dosync.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dosync
-Version: 0.6.0
+Version: 0.6.2
 Summary: The semantic layer between AI agents and physical devices
 Author-email: Rodrigo Giuliani <rgiuliani@dosync.dev>
 License-Expression: Apache-2.0

{dosync-0.6.0 → dosync-0.6.2}/tests/test_adapters.py

@@ -166,3 +166,66 @@ def test_ha_bridge_skips_all_wiz_entities():
     m = bridge._state_to_manifest(
         {"entity_id": "light.ambient_strip", "attributes": {}, "state": "on"})
     assert m is not None and m.device_id == "ha-light-ambient_strip"
+
+
+# ── An action that failed must say why (2026-08-29) ────────────────────────
+
+def test_a_failure_with_no_message_still_reports_a_reason():
+    """`"error": ""` came back from real hardware.
+
+    A WiZ bulb powered off at the wall raised an exception whose `str()` is
+    empty. Six adapters did `error=str(e)`, so the hub reported
+    `success: false, error: ""` and the log line ended at the colon — the
+    operator was told the action failed and nothing else.
+
+    An exception type is not a diagnosis, but a blank field is strictly worse:
+    the type at least says where to look.
+    """
+    from dosync.adapters import failure_reason
+
+    class Silent(Exception):
+        def __str__(self) -> str:
+            return ""
+
+    reason = failure_reason(Silent())
+    assert reason, "a failure with no message still yields nothing"
+    assert "Silent" in reason, "the exception type is not named"
+    assert "did not answer" in reason
+
+    # A real message is passed through untouched.
+    assert failure_reason(ValueError("connection refused")) == "connection refused"
+
+
+def test_no_adapter_puts_a_bare_exception_into_the_error_field():
+    """The pattern was in six adapters at once, so a shared helper replaced it
+    rather than six separate patches — and this keeps the seventh from
+    reintroducing it."""
+    from pathlib import Path
+
+    repo = Path(__file__).resolve().parent.parent
+    import ast
+
+    offenders = []
+    for path in (repo / "dosync" / "adapters").glob("*.py"):
+        source = path.read_text(encoding="utf-8")
+        # Parsed, not grepped. Scanning the text tripped on the helper's own
+        # docstring, which quotes the pattern to explain what it replaces —
+        # the fourth time today a check has failed on the prose justifying it.
+        tree = ast.parse(source)
+        docstrings = set()
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.Module, ast.ClassDef,
+                                 ast.FunctionDef, ast.AsyncFunctionDef)):
+                doc = ast.get_docstring(node, clean=False)
+                if doc:
+                    docstrings.update(doc.splitlines())
+        for i, line in enumerate(source.splitlines(), 1):
+            stripped = line.strip()
+            if stripped.startswith("#") or line in docstrings or stripped in {
+                    d.strip() for d in docstrings}:
+                continue
+            if "error=str(e)" in stripped or "error=str(exc)" in stripped:
+                offenders.append(f"{path.name}:{i}")
+    assert not offenders, (
+        "these adapters put a raw exception into the error field, which is the "
+        f"empty string for some libraries: {offenders}. Use failure_reason().")

{dosync-0.6.0 → dosync-0.6.2}/tests/test_server.py

@@ -199,3 +199,21 @@ def test_the_shipped_gpio_adapter_uses_the_current_endpoint():
     src = (REPO / "gpio_adapter.py").read_text()
     assert 'hub_post("/v1/intent/async"' in src
     assert 'hub_post("/v1/intent"' not in src
+
+
+def test_json_responses_declare_utf8():
+    """`read-only status query â device has no sensors to read`.
+
+    That is what a Windows operator saw following this project's own
+    instructions. JSON is UTF-8 by definition, so FastAPI omits the charset —
+    correct, and useless for Windows PowerShell 5.1, which falls back to
+    Latin-1 when a response does not declare one. Every em dash and every
+    accented character in a device name arrives mangled.
+
+    The README documents `Invoke-RestMethod` as the way to call this API from
+    Windows, so the tool it recommends was the one showing broken text.
+    """
+    response = client.get("/v1/status")
+    assert "charset=utf-8" in response.headers.get("content-type", "").lower(), (
+        "JSON responses do not declare their charset, so clients that guess "
+        "wrongly — PowerShell 5.1 among them — mangle every non-ASCII byte")

{dosync-0.6.0 → dosync-0.6.2}/tests/test_transport_discoverers.py

@@ -594,3 +594,57 @@ def test_a_discoverer_that_fails_is_never_reported_as_searched():
     # a reader unable to tell it had been attempted.
     assert scan.count("failed: {type(e).__name__}") >= 2, \
         "a failing discoverer or adapter still vanishes from both lists"
+
+
+def test_ssdp_uses_the_one_udp_mechanism_every_loop_implements():
+    """Two fixes in a row each worked on the loop they were written against.
+
+    `sock_recvfrom` worked on stock asyncio and raised NotImplementedError on
+    uvloop, which `uvicorn[standard]` installs — SSDP was dead in production for
+    days while every test passed. The replacement, `add_reader`, worked on both
+    of those and raised NotImplementedError on Windows, whose ProactorEventLoop
+    has no reader registration for sockets: a clean install could not scan at
+    all.
+
+    `create_datagram_endpoint` is defined on `BaseEventLoop`, which every loop
+    here inherits, rather than on the abstract base where the other two are
+    stubs that raise. The suite runs on one loop and there are three, so the
+    mechanism has to be one that cannot vary.
+    """
+    source = (REPO / "dosync" / "discoverers_ssdp.py").read_text(encoding="utf-8")
+    assert "create_datagram_endpoint" in source, \
+        "SSDP does not use the UDP mechanism all three event loops implement"
+    # Executable lines only. The comments explain WHY the other two mechanisms
+    # are unusable and name them to do it — scanning the whole file made this
+    # trip on the very text that documents the fix, which is the third time
+    # today a check has failed on the prose that justifies it.
+    code = "\n".join(l for l in source.splitlines()
+                     if l.strip() and not l.lstrip().startswith("#"))
+    for loop_specific in ("add_reader", "sock_recvfrom"):
+        assert f"loop.{loop_specific}(" not in code, \
+            f"SSDP still calls loop.{loop_specific}, which raises " \
+            "NotImplementedError on at least one loop this hub runs on"
+
+
+def test_the_scan_error_handler_does_not_itself_raise():
+    """The handler written to record a failed discoverer was broken.
+
+    `log.warning(...)` in `server.py`, where no name `log` exists — every other
+    line there calls `logging.getLogger("dosync.server")`. So a discoverer
+    raising turned into `NameError` inside the `except` block, and a failure the
+    code was written to absorb became a 500 that took the whole scan down.
+
+    It had been latent since before this handler existed: the previous version
+    called `log.info` on the same lines and was never reached, because until
+    Windows no discoverer had failed in production.
+    """
+    source = (REPO / "dosync" / "server.py").read_text(encoding="utf-8")
+    scan = source[source.index('@app.get("/v1/discovery/scan"'):]
+    scan = scan[:scan.index("\n@app.")]
+    for line in scan.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            continue
+        assert not stripped.startswith("log."), (
+            f"the scan calls a bare `log` that server.py does not define — "
+            f"this raises NameError from inside an except block: {stripped[:60]}")