commit ae64a69f3c5275451c8383cc8b390fbeb5175f1aa77e3d1bc85c678cb9466763 from: Tracey Emery date: Tue Nov 17 16:59:49 2026 UTC let a snowflake sink act as the sparkplug b primary host A snowflake block takes an optional "primary host" id, defaulting to the sink's name. While the sink's virtual connection is up the broker keeps a retained spBv1.0/STATE/ message with online true; when the sink goes down, or the daemon stops cleanly, it is replaced by online false carrying the same timestamp, as the specification asks of a host's will. An edge node configured with a Primary Host ID, such as Ignition MQTT Transmission, publishes nothing until it sees that message and stores and forwards while the host is offline. Without it the sink never saw a birth. commit - b8519ffa73911b2294da61966f7c242b056d591f4d45f93a070429155c4a765d commit + ae64a69f3c5275451c8383cc8b390fbeb5175f1aa77e3d1bc85c678cb9466763 blob - d26f4e17a0c3e03bd3ad94c5495a809eb91684be63756b7349ca8a8bad80b27e blob + 19ce7d4e24960189292e841cdf2b452d305157e0e4d5bcb588309b2c3dd66273 --- mqttd/bridge.c +++ mqttd/bridge.c @@ -29,6 +29,7 @@ #include #include #include +#include #include #include @@ -48,6 +49,7 @@ static void bridge_schedule(struct bridge *); static void bridge_reconnect_cb(int, short, void *); static void bridge_ping_cb(int, short, void *); static void bridge_drop(struct bridge *, const char *); +static void bridge_sink_state(struct bridge *, int); static void bridge_send_connect(struct bridge *); static void bridge_send_subscribe(struct bridge *); static int bridge_map_in(struct bridge *, const char *, size_t, char *, @@ -93,6 +95,7 @@ bridge_config_recv(struct imsg *imsg) memcpy(&br->conf, imsg->data, sizeof(br->conf)); br->conf.name[sizeof(br->conf.name) - 1] = '\0'; br->conf.host[sizeof(br->conf.host) - 1] = '\0'; + br->conf.primary_host[sizeof(br->conf.primary_host) - 1] = '\0'; br->conf.client_id[sizeof(br->conf.client_id) - 1] = '\0'; br->conf.username[sizeof(br->conf.username) - 1] = '\0'; br->conf.password[sizeof(br->conf.password) - 1] = '\0'; @@ -347,14 +350,67 @@ bridge_conn_closed(struct bconn *bc) if (br == NULL || br->conn != bc) return; br->conn = NULL; - if (br->state == BRIDGE_UP) + if (br->state == BRIDGE_UP) { log_info("event=bridge-down bridge=\"%s\" remote=%s " "reason=\"connection closed\"", br->conf.name, br->conf.host); + bridge_sink_state(br, 0); + } bridge_schedule(br); } +/* + * A sink stands in for a Sparkplug Host Application: while its virtual + * connection is up the broker keeps a retained STATE message saying so, + * which is what an edge node configured with this Primary Host ID waits + * for before it publishes. The offline message repeats the timestamp of + * the online one, as the specification asks of a host's will, so an + * edge node can tell a stale offline from a current one. + */ static void +bridge_sink_state(struct bridge *br, int online) +{ + struct message *m; + struct timeval tv; + char topic[MQTTD_MAXTEXT], payload[64]; + int n; + + if (!br->conf.sink || br->conf.primary_host[0] == '\0') + return; + if (online) { + gettimeofday(&tv, NULL); + br->state_ts = (uint64_t)tv.tv_sec * 1000 + tv.tv_usec / 1000; + } + n = snprintf(topic, sizeof(topic), MQTTD_SPARKPLUG_PREFIX "STATE/%s", + br->conf.primary_host); + if (n < 0 || (size_t)n >= sizeof(topic)) + return; + n = snprintf(payload, sizeof(payload), + "{\"online\":%s,\"timestamp\":%llu}", online ? "true" : "false", + (unsigned long long)br->state_ts); + if ((m = message_new((const uint8_t *)topic, strlen(topic), + (const uint8_t *)payload, n, 1, 1)) == NULL) { + log_warn("%s: message_new", __func__); + return; + } + broker_route(m); + message_unref(m); + log_info("event=sparkplug-state sink=\"%s\" host=\"%s\" online=%s", + br->conf.name, br->conf.primary_host, online ? "true" : "false"); +} + +/* a clean shutdown leaves every sink's host offline in the last snapshot */ +void +bridge_shutdown(void) +{ + struct bridge *br; + + TAILQ_FOREACH(br, &broker_env->bridges, entry) + if (br->state == BRIDGE_UP) + bridge_sink_state(br, 0); +} + +static void bridge_ping_cb(int fd, short event, void *arg) { struct bridge *br = arg; @@ -431,6 +487,7 @@ bridge_packet(struct bconn *bc, uint8_t type, uint8_t br->since = time(NULL); log_info("event=bridge-up bridge=\"%s\" remote=%s version=%d", br->conf.name, br->conf.host, br->conf.version); + bridge_sink_state(br, 1); bridge_send_subscribe(br); session_resume(br->session); /* keepalive 0 (sinks) means no pinging and no timeout */ blob - 18bd283bec46709cfcdcc3b9c2cfc2af046694d7b2dfc6234faa78f0259ef4f1 blob + 7525fb5a39e3e3b6dcc79bff72b2a71ca8626de678672d5e2679f8af685d1dd9 --- mqttd/broker.c +++ mqttd/broker.c @@ -310,6 +310,9 @@ broker_shutdown(void) { int n; + /* sinks go offline first so the last snapshot carries their will */ + bridge_shutdown(); + /* the last snapshot must reach storage before the pipe closes */ db_snapshot_sync(); blob - 569a53fd9609ac3c09d9218a8c2c2db072255b9b9aa8b718ead5fdee87d1cb62 blob + bba6d57c50560df0126e6431b30349957063b0a76b9fe61e416d01c6f5f44655 --- mqttd/broker.h +++ mqttd/broker.h @@ -153,6 +153,7 @@ struct bridge { uint16_t sub_pid; uint8_t state; time_t since; + uint64_t state_ts; /* last STATE online, ms */ uint64_t msgs_in; uint64_t msgs_out; }; @@ -328,6 +329,7 @@ void bridge_conn_open(struct bconn *, uint32_t); int bridge_packet(struct bconn *, uint8_t, uint8_t, const uint8_t *, size_t); void bridge_conn_closed(struct bconn *); +void bridge_shutdown(void); int bridge_map_out(struct bridge *, const char *, size_t, char *, size_t); void bridge_ctl_show(struct imsg *, struct imsgev *); blob - 3fd239245b477c9df343fe91b4d23f849e9cecd795ca1758d39945798e0b4028 blob + 748bdf4acadfacba3c5c61fd8c86e958b7bc0fc67e8a6fdc7cc043bdad0471d3 --- mqttd/examples/etc/mqttd.conf +++ mqttd/examples/etc/mqttd.conf @@ -94,6 +94,7 @@ sparkplug aware yes # setup. Messages queue locally while Snowflake is unreachable. #snowflake "warehouse" { # account "myorg-myaccount" +# primary host "MQTT_SNOW_HOST" # user "MQTT_INGEST" # role "INGEST" # warehouse "INGEST_WH" blob - 0c3eb7fa9ed2ccc51118e6d91519e7254acfe5f6d4ee3b1e0a59735f62b94796 blob + 1e2cb276e6ff573b2a24c4eb69643a3045e182c517a989f3f67f29a8f5116d94 --- mqttd/mqttd.c +++ mqttd/mqttd.c @@ -172,7 +172,8 @@ proc_privdrop_dir(const char *title, const char *dir) fatal("unknown user %s", MQTTD_USER); if (chroot(dir != NULL ? dir : pw->pw_dir) == -1) - fatal("%s: chroot %s", __func__, dir != NULL ? dir : pw->pw_dir); + fatal("%s: chroot %s", __func__, dir != NULL ? dir : + pw->pw_dir); if (chdir("/") == -1) fatal("%s: chdir(\"/\")", __func__); blob - cb80f87240723b2fd9d016483baff07d4b03ede0fdcebc98cbe0d7906bb08cf8 blob + d62955118e502ed546c4e3cd004abcf48cfea203b74f13d8f0453009e12d724b --- mqttd/mqttd.conf.5 +++ mqttd/mqttd.conf.5 @@ -502,6 +502,27 @@ The default is 60. .It Ic topic Ar pattern Oo Ic qos Ar number Oc Op Ic local Ar prefix A topic filter to sink, QoS 0 or 1. At least one is required. +.It Ic primary host Ar id +Announce the sink as a Sparkplug B Host Application under +.Ar id . +While the sink is up the broker keeps a retained +.Pa spBv1.0/STATE/ Ns Ar id +message whose payload says +.Ql online +true; when the sink goes down, or the daemon shuts down cleanly, it is +replaced by one saying false with the same timestamp. +An edge node configured with this Primary Host ID, such as an Ignition +MQTT Transmission module, publishes nothing until it sees the online +message and stores and forwards while the host is offline, so an outage +long enough to close the sink is bridged on the edge instead of in +.Ic max queued . +The id is a single topic level. +The default is the sink's name. +Deny client publishes below +.Pa spBv1.0/STATE/ +in the +.Ic acl +so no client can forge it. .El .Pp Snowflake certificates: account endpoints live under wildcard blob - a7de620c1a192d8e54208be6dd227c9fb49875c475a5a6a0bb210e277182030f blob + f4a4b7a06650d22afbbb6f2fd84c7b58ed3015cf9deb254ce4d0cb1332e44dd2 --- mqttd/mqttd.h +++ mqttd/mqttd.h @@ -386,6 +386,7 @@ struct bridge_config { uint32_t proc; uint8_t sink; char name[MQTTD_MAXNAME]; + char primary_host[MQTTD_MAXNAME]; char host[MQTTD_MAXHOST]; struct sockaddr_storage ss; in_port_t port; blob - 66ec6f49d0fb8c02811cef9c217b2eb27fd965a6463b8f09021cade5b040bc79 blob + a3e260430c29ffb1d26c36690cbe3f7e6f584440a81085fc910618c04438852c --- mqttd/parse.y +++ mqttd/parse.y @@ -130,7 +130,7 @@ typedef struct { %token BOTH BRIDGE CA CERTIFICATE CIPHERS CLIENT CLIENTS CRL DENY DHE ECDHE %token ERROR EXEC EXPIRY FAILURES FLUSH HOST IN INCLUDE INFLIGHT INTERVAL %token KEEPALIVE KEY LISTEN LOCAL MAX NAME NO NOVERIFY OCSP ON OPTIONAL OUT -%token PACKET PASSWORD PATH PERSISTENCE PF PORT PREFORK PROTOCOLS PROXY +%token PACKET PASSWORD PATH PERSISTENCE PF PORT PREFORK PRIMARY PROTOCOLS PROXY %token PUBLISH QOS QUEUED RATE REMOTE RETAIN ROLE SERVERNAME SESSION SIZE %token SNOWFLAKE SPARKPLUG SUBSCRIBE SYS TABLE TIMEOUT TLS TOPIC USER VERSION %token WAREHOUSE WEBSOCKET WITHIN WORKERS YES @@ -1000,6 +1000,8 @@ snowflake : SNOWFLAKE STRING { b->conf.tls = 1; b->snow->id = b->conf.id; strlcpy(b->snow->name, $2, sizeof(b->snow->name)); + strlcpy(b->conf.primary_host, $2, + sizeof(b->conf.primary_host)); b->snow->port = htons(443); b->snow->batch = MQTTD_SNOW_DEFAULT_BATCH; b->snow->flush = MQTTD_SNOW_DEFAULT_FLUSH; @@ -1136,6 +1138,19 @@ snowopt : ACCOUNT STRING { } cur_bridge->conf.max_queued = $3; } + | PRIMARY HOST STRING { + /* a Sparkplug host id is a single topic level */ + if (strpbrk($3, "/+#") != NULL) { + yyerror("invalid snowflake primary host: %s", + $3); + free($3); + YYERROR; + } + if (snow_set(cur_bridge->conf.primary_host, + sizeof(cur_bridge->conf.primary_host), $3, + "primary host") == -1) + YYERROR; + } | TIMEOUT NUMBER { if ($2 < 1 || $2 > 3600) { yyerror("invalid snowflake timeout: %lld", $2); @@ -1313,6 +1328,7 @@ lookup(char *s) { "pf", PF }, { "port", PORT }, { "prefork", PREFORK }, + { "primary", PRIMARY }, { "protocols", PROTOCOLS }, { "proxy", PROXY }, { "publish", PUBLISH },