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.
  49
  50 *******************
  51  Command ownership
  52 *******************
  53
  54 ``NewRouter`` takes the explicit IDs of command-capable devices. It
  55 supplies protocol subscriptions and one 64-entry FIFO per device. Each
  56 entry holds one single command or one ordered batch. Intake parses a
  57 delivery once through ``protocol.Parse``. A malformed or expired member
  58 rejects the whole batch. Retained commands and commands for unowned
  59 devices are errors. A full queue waits for space, cancellation, or the
  60 earliest member expiry. Each device has one queue consumer. It checks
  61 physical ownership, capability access, and expiry again before work.
  62 Read-only devices have no queue.
  63
  64 ``NewLedger`` creates a ledger for one device. The consumer checks
  65 ``Lookup`` before a physical action, and stores its result with
  66 ``Remember`` before the first publication attempt. A duplicate reuses
  67 the first status, reason, message ID, and observation time. It performs
  68 no second action. This also applies after a failed result send. Pass the
  69 returned ``ResultRecord`` fields to ``Publisher.Result`` unchanged.
  70 Records are safe from caller mutation.
  71
  72 The ledger retains 256 results in insertion order per device. Lookup
  73 does not extend their age. It is not a reservation for concurrent
  74 physical actions. The single queue consumer provides that exclusion. The
  75 ledger is memory-only. Eviction or process restart removes duplicate
  76 protection for that record. Pending physical confirmation and
  77 device-specific command safety belong to the integration. Fake tests
  78 verify queue order, backpressure, expiry, per-device bounds, and stable
  79 duplicate replay without device I/O.