cog-ha-matter (ADR-116 P3): extract pure publisher-input builder

Adds `runtime::build_publisher_inputs(host, port, privacy, identity)` —
the side-effect-free helper that turns the cog's CLI surface into the
`(MqttConfig, OwnedDiscoveryBuilder)` pair ADR-115's `publisher::spawn`
consumes. Keeps the tokio runtime wiring out of the pure unit so the
mDNS responder + Seed control plane (P4) can build the same inputs
from different sources without going through clap.

8 new tests lock the wire-format invariants:
  * host/port round-trip into MqttConfig
  * privacy_mode propagation (P1 dossier item 7, FDA Jan 2026)
  * discovery_prefix defaults to "homeassistant"
  * discovery carries node_id + sw_version + friendly_name
  * via_device advertises COG_ID (ADR-101/102 device-registry shape)
  * client_id includes node_id (lesson from ADR-115 iter 45-48 session
    takeover post-mortem — two publishers sharing a client_id loop)
  * tls defaults to Off for v1 LAN-only (lock against silent enablement)
  * default_identity carries CARGO_PKG_VERSION + PID for uniqueness

Plus the existing 2 manifest tests → 10/10 green
(`cargo test -p cog-ha-matter --no-default-features --lib`).

Also lands the deep-researcher dossier (`docs/research/ADR-116-ha-...`)
that the ADR §3+§4 reference — it was produced last iter but only the
ADR was committed; this puts the source-of-truth into the tree so the
ADR's "8 sections, 30+ citations" claim is actually verifiable.

P3 status in the ADR phase table flipped from "pending" to "in progress"
with the helper named; next iter tokio::spawns publisher::run(...) in
main.rs and registers the mDNS responder.

Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
ruv
2026-05-23 17:55:17 -04:00
parent 56265023dc
commit 5723f505b7
5 changed files with 681 additions and 23 deletions
Generated
+136 -22
View File
@@ -929,6 +929,22 @@ version = "1.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3a822ea5bc7590f9d40f1ba12c0dc3c2760f3482c6984db1573ad11031420831"
[[package]]
name = "cog-ha-matter"
version = "0.3.0"
dependencies = [
"clap",
"serde",
"serde_json",
"tempfile",
"thiserror 1.0.69",
"tokio",
"tracing",
"tracing-subscriber",
"wifi-densepose-hardware",
"wifi-densepose-sensing-server",
]
[[package]]
name = "cog-person-count"
version = "0.3.0"
@@ -1505,7 +1521,7 @@ dependencies = [
"libc",
"option-ext",
"redox_users 0.5.2",
"windows-sys 0.59.0",
"windows-sys 0.61.2",
]
[[package]]
@@ -1726,7 +1742,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
dependencies = [
"libc",
"windows-sys 0.59.0",
"windows-sys 0.61.2",
]
[[package]]
@@ -3098,7 +3114,7 @@ dependencies = [
"hyper 0.14.32",
"rustls 0.21.12",
"tokio",
"tokio-rustls",
"tokio-rustls 0.24.1",
]
[[package]]
@@ -3134,7 +3150,7 @@ dependencies = [
"libc",
"percent-encoding",
"pin-project-lite",
"socket2 0.5.10",
"socket2 0.6.2",
"tokio",
"tower-service",
"tracing",
@@ -3395,7 +3411,7 @@ checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
dependencies = [
"hermit-abi",
"libc",
"windows-sys 0.59.0",
"windows-sys 0.61.2",
]
[[package]]
@@ -4102,10 +4118,10 @@ dependencies = [
"libc",
"log",
"openssl",
"openssl-probe",
"openssl-probe 0.2.1",
"openssl-sys",
"schannel",
"security-framework",
"security-framework 3.7.0",
"security-framework-sys",
"tempfile",
]
@@ -4296,7 +4312,7 @@ version = "0.50.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5"
dependencies = [
"windows-sys 0.59.0",
"windows-sys 0.61.2",
]
[[package]]
@@ -4661,6 +4677,12 @@ dependencies = [
"syn 2.0.117",
]
[[package]]
name = "openssl-probe"
version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d05e27ee213611ffe7d6348b942e8f942b37114c00cc03cec254295a4a17852e"
[[package]]
name = "openssl-probe"
version = "0.2.1"
@@ -4725,7 +4747,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7d8fae84b431384b68627d0f9b3b1245fcf9f46f6c0e3dc902e9dce64edd1967"
dependencies = [
"libc",
"windows-sys 0.45.0",
"windows-sys 0.61.2",
]
[[package]]
@@ -5469,7 +5491,7 @@ dependencies = [
"quinn-udp",
"rustc-hash",
"rustls 0.23.37",
"socket2 0.5.10",
"socket2 0.6.2",
"thiserror 2.0.18",
"tokio",
"tracing",
@@ -5508,9 +5530,9 @@ dependencies = [
"cfg_aliases",
"libc",
"once_cell",
"socket2 0.5.10",
"socket2 0.6.2",
"tracing",
"windows-sys 0.59.0",
"windows-sys 0.60.2",
]
[[package]]
@@ -5875,14 +5897,14 @@ dependencies = [
"percent-encoding",
"pin-project-lite",
"rustls 0.21.12",
"rustls-pemfile",
"rustls-pemfile 1.0.4",
"serde",
"serde_json",
"serde_urlencoded",
"sync_wrapper 0.1.2",
"system-configuration",
"tokio",
"tokio-rustls",
"tokio-rustls 0.24.1",
"tower-service",
"url",
"wasm-bindgen",
@@ -6109,6 +6131,24 @@ dependencies = [
"smallvec",
]
[[package]]
name = "rumqttc"
version = "0.24.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e1568e15fab2d546f940ed3a21f48bbbd1c494c90c99c4481339364a497f94a9"
dependencies = [
"bytes",
"flume",
"futures-util",
"log",
"rustls-native-certs 0.7.3",
"rustls-pemfile 2.2.0",
"rustls-webpki 0.102.8",
"thiserror 1.0.69",
"tokio",
"tokio-rustls 0.25.0",
]
[[package]]
name = "rustc-hash"
version = "2.1.1"
@@ -6148,7 +6188,7 @@ dependencies = [
"errno",
"libc",
"linux-raw-sys",
"windows-sys 0.59.0",
"windows-sys 0.61.2",
]
[[package]]
@@ -6163,6 +6203,20 @@ dependencies = [
"sct",
]
[[package]]
name = "rustls"
version = "0.22.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bf4ef73721ac7bcd79b2b315da7779d8fc09718c6b3d2d1b2d94850eb8c18432"
dependencies = [
"log",
"ring",
"rustls-pki-types",
"rustls-webpki 0.102.8",
"subtle",
"zeroize",
]
[[package]]
name = "rustls"
version = "0.23.37"
@@ -6178,16 +6232,29 @@ dependencies = [
"zeroize",
]
[[package]]
name = "rustls-native-certs"
version = "0.7.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e5bfb394eeed242e909609f56089eecfe5fda225042e8b171791b9c95f5931e5"
dependencies = [
"openssl-probe 0.1.6",
"rustls-pemfile 2.2.0",
"rustls-pki-types",
"schannel",
"security-framework 2.11.1",
]
[[package]]
name = "rustls-native-certs"
version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "612460d5f7bea540c490b2b6395d8e34a953e52b491accd6c86c8164c5932a63"
dependencies = [
"openssl-probe",
"openssl-probe 0.2.1",
"rustls-pki-types",
"schannel",
"security-framework",
"security-framework 3.7.0",
]
[[package]]
@@ -6199,6 +6266,15 @@ dependencies = [
"base64 0.21.7",
]
[[package]]
name = "rustls-pemfile"
version = "2.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dce314e5fee3f39953d46bb63bb8a46d40c2f8fb7cc5a3b6cab2bde9721d6e50"
dependencies = [
"rustls-pki-types",
]
[[package]]
name = "rustls-pki-types"
version = "1.14.0"
@@ -6221,13 +6297,13 @@ dependencies = [
"log",
"once_cell",
"rustls 0.23.37",
"rustls-native-certs",
"rustls-native-certs 0.8.3",
"rustls-platform-verifier-android",
"rustls-webpki 0.103.13",
"security-framework",
"security-framework 3.7.0",
"security-framework-sys",
"webpki-root-certs",
"windows-sys 0.59.0",
"windows-sys 0.61.2",
]
[[package]]
@@ -6246,6 +6322,17 @@ dependencies = [
"untrusted",
]
[[package]]
name = "rustls-webpki"
version = "0.102.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "64ca1bc8749bd4cf37b5ce386cc146580777b4e8572c7b97baf22c83f444bee9"
dependencies = [
"ring",
"rustls-pki-types",
"untrusted",
]
[[package]]
name = "rustls-webpki"
version = "0.103.13"
@@ -6548,6 +6635,19 @@ dependencies = [
"untrusted",
]
[[package]]
name = "security-framework"
version = "2.11.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "897b2245f0b511c87893af39b033e5ca9cce68824c4d7e7630b5a1d339658d02"
dependencies = [
"bitflags 2.11.0",
"core-foundation 0.9.4",
"core-foundation-sys",
"libc",
"security-framework-sys",
]
[[package]]
name = "security-framework"
version = "3.7.0"
@@ -7650,7 +7750,7 @@ dependencies = [
"getrandom 0.4.1",
"once_cell",
"rustix",
"windows-sys 0.59.0",
"windows-sys 0.61.2",
]
[[package]]
@@ -7843,6 +7943,17 @@ dependencies = [
"tokio",
]
[[package]]
name = "tokio-rustls"
version = "0.25.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "775e0c0f0adb3a2f22a00c4745d728b479985fc15ee7ca6a2608388c5569860f"
dependencies = [
"rustls 0.22.4",
"rustls-pki-types",
"tokio",
]
[[package]]
name = "tokio-serial"
version = "5.4.5"
@@ -9125,9 +9236,12 @@ dependencies = [
"axum",
"chrono",
"clap",
"criterion",
"futures-util",
"midstreamer-attractor",
"midstreamer-temporal-compare",
"proptest",
"rumqttc",
"ruvector-mincut",
"serde",
"serde_json",
@@ -9270,7 +9384,7 @@ version = "0.1.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
dependencies = [
"windows-sys 0.48.0",
"windows-sys 0.61.2",
]
[[package]]
+1
View File
@@ -27,6 +27,7 @@
//! discipline rules (see `docs/ADR-110-BRANCH-STATE.md`).
pub mod manifest;
pub mod runtime;
/// Cog identifier used in Seed's app-registry.json + the manifest.
pub const COG_ID: &str = "ha-matter";
+185
View File
@@ -0,0 +1,185 @@
//! `runtime` — pure builders that turn the cog's small CLI surface
//! into the shapes ADR-115's `publisher::spawn` consumes.
//!
//! Kept side-effect-free so the tests don't need a tokio runtime, and
//! so the cog's mDNS responder / control plane (P4) can build the
//! same inputs from a different source (Seed control config, JSON
//! POST) without going through `clap`.
//!
//! Per the ADR-115 integration-test post-mortem (iter 45-48 of the
//! ADR-110 sprint), the MQTT `client_id` MUST be unique per process —
//! reusing a client_id causes the broker to disconnect the previous
//! session and the new publisher reconnects in a loop. We derive
//! `client_id` from the caller-supplied `node_id` for that reason.
//!
//! P3 of ADR-116: this module produces the input pair; the binary
//! wires the actual `tokio::spawn(publisher::run(...))` next iter.
//!
//! The publisher inputs are intentionally typed in *this* crate, so
//! the cog's tests and the `--print-manifest` path can exercise the
//! builder without pulling in the rumqttc event loop.
use wifi_densepose_sensing_server::mqtt::{
config::{MqttConfig, PublishRates, TlsConfig},
publisher::OwnedDiscoveryBuilder,
DEFAULT_DISCOVERY_PREFIX, MANUFACTURER,
};
/// Caller-supplied identity for the cog instance. Filled in by the
/// cog runtime from the mDNS hostname / Seed control plane in
/// production; threaded as a parameter so tests can build inputs
/// without touching the environment.
#[derive(Debug, Clone)]
pub struct CogIdentity {
/// Stable node identifier — appears in MQTT topics, HA device
/// registry, mDNS service name. Must be ASCII-safe; the cog
/// runtime is responsible for sanitising user input.
pub node_id: String,
/// Human-readable name surfaced in the HA UI.
pub friendly_name: String,
/// SemVer of the cog binary. Surfaces as the HA device `sw_version`.
pub sw_version: String,
}
impl CogIdentity {
/// Default identity used when the cog runs standalone (no Seed
/// control plane). Uses the PID for uniqueness so two cog
/// instances on the same host don't fight over the same MQTT
/// session — same trick the ADR-115 publisher uses.
pub fn default_for_build() -> Self {
Self {
node_id: format!("cog-ha-matter-{}", std::process::id()),
friendly_name: "Cognitum Seed — HA cog".into(),
sw_version: env!("CARGO_PKG_VERSION").into(),
}
}
}
/// The pair ADR-115's `publisher::spawn` needs. Owned so we can move
/// the whole thing into a `tokio::spawn` closure without lifetime
/// gymnastics.
#[derive(Debug, Clone)]
pub struct PublisherInputs {
pub config: MqttConfig,
pub discovery: OwnedDiscoveryBuilder,
}
/// Build the publisher inputs from the cog's small CLI surface.
///
/// Pure function — no I/O, no env reads. The caller wraps `config`
/// in an `Arc` before handing it to `publisher::spawn`.
pub fn build_publisher_inputs(
mqtt_host: &str,
mqtt_port: u16,
privacy_mode: bool,
identity: CogIdentity,
) -> PublisherInputs {
let config = MqttConfig {
host: mqtt_host.to_string(),
port: mqtt_port,
username: None,
password: None,
client_id: format!("{}-{}", super::COG_ID, identity.node_id),
discovery_prefix: DEFAULT_DISCOVERY_PREFIX.to_string(),
tls: TlsConfig::Off,
refresh_secs: 60,
rates: PublishRates::default(),
publish_pose: false,
privacy_mode,
};
let discovery = OwnedDiscoveryBuilder {
discovery_prefix: DEFAULT_DISCOVERY_PREFIX.to_string(),
node_id: identity.node_id,
node_friendly_name: Some(identity.friendly_name),
sw_version: identity.sw_version,
model: format!("{MANUFACTURER} cog-ha-matter"),
via_device: Some(super::COG_ID.to_string()),
};
PublisherInputs { config, discovery }
}
#[cfg(test)]
mod tests {
use super::*;
fn id() -> CogIdentity {
CogIdentity {
node_id: "seed-7".into(),
friendly_name: "test-seed".into(),
sw_version: "0.0.1-test".into(),
}
}
#[test]
fn host_and_port_round_trip_into_mqtt_config() {
let out = build_publisher_inputs("10.0.0.5", 8883, false, id());
assert_eq!(out.config.host, "10.0.0.5");
assert_eq!(out.config.port, 8883);
}
#[test]
fn privacy_mode_propagates_to_mqtt_config() {
let on = build_publisher_inputs("h", 1883, true, id());
let off = build_publisher_inputs("h", 1883, false, id());
assert!(on.config.privacy_mode);
assert!(!off.config.privacy_mode);
}
#[test]
fn discovery_prefix_defaults_to_homeassistant() {
let out = build_publisher_inputs("h", 1883, false, id());
assert_eq!(out.config.discovery_prefix, DEFAULT_DISCOVERY_PREFIX);
assert_eq!(out.discovery.discovery_prefix, DEFAULT_DISCOVERY_PREFIX);
}
#[test]
fn discovery_carries_identity_fields() {
let out = build_publisher_inputs("h", 1883, false, id());
assert_eq!(out.discovery.node_id, "seed-7");
assert_eq!(out.discovery.sw_version, "0.0.1-test");
assert_eq!(out.discovery.node_friendly_name.as_deref(), Some("test-seed"));
}
#[test]
fn via_device_advertises_cog_id() {
// ADR-101 / ADR-102: every cog must surface its `id` as the
// HA device's `via_device` so the appliance shows up as the
// bridge — fires a named test instead of silently breaking
// the device-registry shape.
let out = build_publisher_inputs("h", 1883, false, id());
assert_eq!(out.discovery.via_device.as_deref(), Some(super::super::COG_ID));
}
#[test]
fn client_id_includes_node_id_for_session_uniqueness() {
// Lesson from the ADR-115 integration-test post-mortem: two
// publishers sharing a `client_id` fight over the broker
// session and one reconnects forever. The cog must derive
// `client_id` from `node_id` so multi-Seed deployments don't
// collide.
let out = build_publisher_inputs("h", 1883, false, id());
assert!(out.config.client_id.contains("seed-7"));
assert!(out.config.client_id.starts_with(super::super::COG_ID));
}
#[test]
fn tls_defaults_to_off_for_v1_lan_only() {
// v1 ships LAN-only (no broker on the open internet); TLS
// wiring lands in v0.8 alongside Matter Bridge per ADR-116
// §4. Lock the default so a future refactor surfaces a
// named test instead of silently enabling TLS.
let out = build_publisher_inputs("h", 1883, false, id());
assert!(matches!(out.config.tls, TlsConfig::Off));
}
#[test]
fn default_identity_carries_pkg_version_and_pid() {
let identity = CogIdentity::default_for_build();
assert_eq!(identity.sw_version, env!("CARGO_PKG_VERSION"));
assert!(identity.node_id.starts_with("cog-ha-matter-"));
// Friendly name is non-empty so HA's device card has a label.
assert!(!identity.friendly_name.is_empty());
}
}