git.giacomolli.uk - onehouse/blob - doc/driver.rst

   1 ##################
   2  Driver framework
   3 ##################
   4
   5 ``driver.Driver`` supplies ``Run`` and a nonblocking ``Refresh``
   6 request. The runner starts an explicit list, forwards broker reconnect
   7 notifications, and waits for cleanup. A driver returns errors without
   8 logging. The runner logs failures and cancels peers. Cancellation and
   9 closed transports are expected stops only after the worker context
  10 stops. A joined independent failure remains a failure.
  11
  12 ``cmd/onehouse`` supplies an empty driver list. It waits for SIGINT or
  13 SIGTERM and finishes cleanup before exit. No integration or broker runs.
  14
  15 Tests use fake drivers. They do not verify a broker or a physical
  16 device.
  17
  18 ******************
  19  Typed publishing
  20 ******************
  21
  22 ``Publisher`` takes a ``Transport`` with one ``Publish`` operation on
  23 ``protocol.Publication``. No broker client or topic operation belongs in
  24 the framework. Typed methods cover descriptor, availability, reported
  25 values, telemetry, events, and results. Missing message IDs and
  26 observation times use fresh values. Supplied metadata remains subject to
  27 protocol validation.
  28
  29 Equal retained payloads are suppressed. Correlation and causation bypass
  30 suppression. A changed telemetry sample uses QoS 0 without retention.
  31 Its latest complete value supplies a QoS 1 retained reported snapshot at
  32 the five-minute repeat or reconnect, not on every change. Repeats keep
  33 observation times, use fresh IDs, and omit command correlation and
  34 causation. JSON object key order and whitespace do not change equality.
  35 Measurement topics are independent. Boolean reported state does not
  36 repeat unless telemetry marks that point as a measurement. Online
  37 availability repeats every five minutes. Offline availability,
  38 descriptors, and Boolean state repeat on reconnect only. Expiring
  39 values, events, and results are not suppressed or cached.
  40
  41 Run one publisher alongside the integration drivers. Its methods are
  42 safe for concurrent use and copy caller-owned payloads and timestamp
  43 pointers. Each send has a five-second timeout derived from the caller
  44 context. A background send error returns to the runner rather than being
  45 logged by the publisher. Reconnect refresh requests are nonblocking and
  46 coalesce while pending. The cache is memory-only. Tests use a fake
  47 transport and simulated time. They do not verify MQTT acknowledgement or
  48 a broker reconnect.