ebus-panel-sim 0.3.0__tar.gz → 0.3.1__tar.gz

{ebus_panel_sim-0.3.0 → ebus_panel_sim-0.3.1}/.github/workflows/ci.yaml

@@ -3,8 +3,13 @@ name: CI
 on:
   push:
     branches: [main]
+  # Deliberately unfiltered by base branch. A `branches:` filter here means a PR
+  # targeting anything other than `main` gets no checks at all, silently: the PR
+  # simply reports "no checks reported" and reads as unvalidated rather than
+  # failing. That hides every stacked PR, which is exactly when a second pair of
+  # eyes is worth most. Every other repo in the eBus family already runs
+  # unfiltered; this one was the outlier.
   pull_request:
-    branches: [main]
 
 jobs:
   lint-and-test:

{ebus_panel_sim-0.3.0 → ebus_panel_sim-0.3.1}/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-08-07
+
+### Fixed
+
+- **`Emitter.stop(graceful=False)` now leaves the tree at `$state=lost`, as it always claimed to.** It documented itself as "leaving the LWT to fire `$state=lost`", which cannot happen: a Last Will fires only on an *unclean* disconnect, and `MqttClient.stop()` sends a clean DISCONNECT deliberately, so that an orderly shutdown is not reported to consumers as a crash. The will was therefore suppressed on every teardown, and an ungraceful stop published nothing at all: verified against a real broker, a consumer joining afterwards read the entire retained tree as `ready`, indefinitely. For a simulator this is the mode's whole purpose, since "act like a producer that died" is exactly what a consumer test needs, so the fix makes the behaviour real rather than deleting the promise. The root's `$state=lost` is now published retained before the connection drops, with topic and payload taken from the SDK's own `Device.will()` descriptor so it cannot drift from what a broker-delivered will would have carried. The difference from a real will is timing and delivery, not content: this lands immediately over the live connection, where a broker-delivered will waits on keepalive expiry, so a consumer exercising the *retained* view sees the same thing either way while one exercising live will delivery does not. `clear_retained` is documented as graceful-only, since a producer that died clears nothing.
+
+### Added
+
+- `tests/test_teardown.py`: both teardown modes now have tests, which neither had before. That absence is why a docstring could promise behaviour the code had never performed. Three of the five fail against 0.3.0.
+
 ## [0.3.0] - 2026-08-07
 
 First release published to PyPI, as **`ebus-panel-sim`**.

{ebus_panel_sim-0.3.0 → ebus_panel_sim-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebus-panel-sim
-Version: 0.3.0
+Version: 0.3.1
 Summary: Producer-side Homie publisher with embedded behaviour runtime for the eBus convention
 Project-URL: Homepage, https://ebus.energy
 Project-URL: Repository, https://github.com/electrification-bus/distribution-enclosure-simulator

{ebus_panel_sim-0.3.0 → ebus_panel_sim-0.3.1}/src/ebus_panel_sim/__init__.py

@@ -69,7 +69,7 @@ from ebus_panel_sim.wire.set_router import SetterHandler, SetterRegistry
 # via `[tool.hatch.version]`, and publish.yml refuses to release when the git tag
 # disagrees. Bump it in this one place. Note this is the PACKAGE version and is
 # distinct from the producer-contract version the docstrings above refer to.
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 __all__ = [
     "BESSConfig",

{ebus_panel_sim-0.3.0 → ebus_panel_sim-0.3.1}/src/ebus_panel_sim/emitter.py

@@ -49,7 +49,7 @@ from ebus_panel_sim.snapshot import (
     EbusPvSnapshot,
 )
 from ebus_panel_sim.tick_inputs import TickInputs
-from ebus_panel_sim.wire._sdk_seam import owned_client
+from ebus_panel_sim.wire._sdk_seam import owned_client, publish_will_now
 from ebus_panel_sim.wire.bag_builder import BagBuilder
 from ebus_panel_sim.wire.graph_builder import build_graph
 from ebus_panel_sim.wire.mapping_loader import load_mapping_table
@@ -253,11 +253,27 @@ class Emitter:
         Graceful (default): publish the root's ``$state=disconnected`` then stop
         the shared client (ebus-sdk's bounded teardown; per Homie's
         effective-state rule the root going disconnected covers every child).
-        Non-graceful: stop the client without the disconnected publish, leaving
-        the LWT to fire ``$state=lost``. ``clear_retained`` additionally clears
-        every device's retained values + ``$description`` before disconnecting,
-        for a clean-slate re-run."""
+
+        Non-graceful: leave the tree looking like a producer that died, by
+        publishing the root's ``$state=lost`` retained before dropping the
+        connection. This is what a consumer test wants from a simulator, and it
+        is emphatically NOT what a bare disconnect gives you: the Last Will fires
+        only on an *unclean* disconnect, and every teardown here closes cleanly,
+        so relying on the will would leave the whole retained tree claiming
+        ``ready`` forever. See ``publish_will_now``, which sources the topic and
+        payload from ``Device.will()`` so this cannot drift from the real thing.
+
+        The difference from a real will is timing and delivery, not content: this
+        lands immediately over the live connection, where a broker-delivered will
+        waits on keepalive expiry. A consumer exercising the *retained* view sees
+        the same thing either way; one exercising live will delivery does not.
+
+        ``clear_retained`` additionally clears every device's retained values +
+        ``$description`` before disconnecting, for a clean-slate re-run. It
+        applies to the graceful path only, since a producer that died clears
+        nothing."""
         if not graceful:
+            publish_will_now(self._root)
             client = owned_client(self._root.mqttc)
             if client is not None:
                 client.stop()

{ebus_panel_sim-0.3.0 → ebus_panel_sim-0.3.1}/src/ebus_panel_sim/wire/_sdk_seam.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 from typing import Any
 
 import ebus_sdk
-from ebus_sdk import MqttClient, PropertyDatatype, Unit
+from ebus_sdk import EBUS_HOMIE_MQTT_QOS, MqttClient, PropertyDatatype, Unit
 
 
 def make_property(
@@ -53,3 +53,36 @@ def owned_client(mqttc: object) -> MqttClient | None:
     its owner to stop, which is the behaviour the SDK's contract asks for.
     """
     return mqttc if isinstance(mqttc, MqttClient) else None
+
+
+def publish_will_now(root: ebus_sdk.Device) -> bool:
+    """Publish the root's will payload (``$state=lost``) as a retained message, now.
+
+    A Last Will fires only when the broker sees an UNCLEAN disconnect. Every
+    orderly teardown path here sends a clean DISCONNECT, and ebus-mqtt-client does
+    that deliberately (``MqttClient.stop`` -> ``mqttc.disconnect()``), precisely so
+    a normal shutdown is not reported to consumers as a crash. The consequence is
+    that a simulator asked to *act* like a producer that died cannot get there by
+    letting the will fire: it has to publish the will's own payload itself.
+
+    Topic and payload come from ``Device.will()``, the same descriptor the SDK
+    registers as the LWT, so this cannot drift from what a real will would have
+    delivered.
+
+    QoS deliberately follows the rest of the tree's ``$state`` publishes rather
+    than the ``qos=0`` default the will registration uses: a registered will is
+    delivered by the broker from its own state, whereas this goes out over a live
+    connection that is about to close and has to actually land first.
+
+    Returns True when the broker acknowledged it, False if there is no owned
+    client or the publish did not flush in time.
+    """
+    client = owned_client(root.mqttc)
+    if client is None:
+        return False
+    will = root.will()
+    return bool(
+        client.publish_and_flush(
+            will["topic"], will["payload"], qos=EBUS_HOMIE_MQTT_QOS, retain=True
+        )
+    )

ebus_panel_sim-0.3.1/tests/test_teardown.py

@@ -0,0 +1,73 @@
+"""Teardown semantics: what the retained tree looks like after ``Emitter.stop()``.
+
+Both modes were previously untested. The non-graceful path had documented itself as
+"leaving the LWT to fire ``$state=lost``", which cannot happen: a Last Will fires
+only on an *unclean* disconnect, and ``MqttClient.stop()`` sends a clean DISCONNECT
+(deliberately, so an orderly shutdown is not reported as a crash). Verified against
+a real mosquitto broker before this suite existed: a consumer joining after an
+ungraceful teardown read the whole tree as ``ready``.
+
+These tests pin the observable outcome, the effective retained ``$state`` a
+late-joining consumer sees, rather than the mechanism.
+"""
+
+from __future__ import annotations
+
+from ebus_panel_sim import Emitter
+from ebus_panel_sim.wire.set_router import SetterRegistry
+
+from .conftest import PahoRecorder
+from .test_emitter_public_surface import _manifest
+
+ROOT_STATE = "ebus/5/p1/$state"
+
+
+def _started() -> Emitter:
+    emitter = Emitter(_manifest(), SetterRegistry())
+    emitter.start()
+    return emitter
+
+
+def test_ungraceful_stop_leaves_the_root_lost(rec: PahoRecorder) -> None:
+    """A producer that died must not leave the tree claiming ``ready``."""
+    _started().stop(graceful=False)
+    assert rec.retained[ROOT_STATE] == "lost"
+
+
+def test_graceful_stop_leaves_the_root_disconnected(rec: PahoRecorder) -> None:
+    """An orderly shutdown is a different signal from a crash, and consumers act
+    on the difference: ``disconnected`` is expected, ``lost`` is a fault."""
+    _started().stop(graceful=True)
+    assert rec.retained[ROOT_STATE] == "disconnected"
+
+
+def test_the_two_modes_do_not_agree(rec: PahoRecorder) -> None:
+    """Guards against a future change collapsing the two teardown modes into one.
+
+    Note this test passed before the fix too, for the wrong reason: ungraceful left
+    the root on ``ready``, which does differ from ``disconnected``. The bug was
+    never that the modes agreed, it was that one of them lied. The two tests above
+    are what pin the actual values; this one only pins that they stay distinct."""
+    _started().stop(graceful=False)
+    ungraceful = rec.retained[ROOT_STATE]
+    rec.reset()
+    _started().stop(graceful=True)
+    assert ungraceful != rec.retained[ROOT_STATE]
+
+
+def test_ungraceful_stop_uses_the_sdk_will_descriptor(rec: PahoRecorder) -> None:
+    """The synthesised ``lost`` must be byte-identical to what the broker would
+    have delivered from the registered will, or the simulation is a fiction."""
+    emitter = _started()
+    will = emitter._root.will()
+    emitter.stop(graceful=False)
+    assert rec.retained[will["topic"]] == will["payload"]
+
+
+def test_ungraceful_stop_publishes_lost_retained(rec: PahoRecorder) -> None:
+    """Retained, or a consumer joining after the death sees nothing at all and
+    cannot distinguish a dead producer from one that never existed."""
+    _started().stop(graceful=False)
+    lost = [(t, d, q, r) for (t, d, q, r) in rec.published if t == ROOT_STATE and d == "lost"]
+    assert lost, "no $state=lost publish reached the transport"
+    assert all(retain for (_t, _d, _q, retain) in lost)