Skip to main content

wordval_iot/
codec.rs

1//! 报文编解码 —— 将各协议的原始 payload 归一化为 [`DeviceMessage`]
2//!
3//! 采集插件只负责搬运字节,语义解析交给 [`Codec`]。这样同一套协议插件
4//! 可以按业务需要挂载不同的编解码策略(JSON / CSV 行 / 自定义二进制)。
5
6use crate::types::{DeviceMessage, MetricValue, Protocol};
7use serde::Deserialize;
8use std::sync::Arc;
9
10/// 编解码错误
11#[derive(Debug)]
12pub struct CodecError(pub String);
13
14impl std::fmt::Display for CodecError {
15    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
16        write!(f, "codec 解析失败: {}", self.0)
17    }
18}
19impl std::error::Error for CodecError {}
20
21/// 编解码器:原始字节 → 一条或多条归一化消息
22///
23/// `topic_hint` 为协议层可提供的上下文(如 MQTT topic、TCP 远端地址),
24/// 便于在 payload 未携带 device_id 时回退推断。
25pub trait Codec: Send + Sync {
26    /// 解码一帧数据。返回空 Vec 表示该帧无有效遥测(如心跳)。
27    fn decode(
28        &self,
29        topic_hint: Option<&str>,
30        raw: &[u8],
31        protocol: Protocol,
32    ) -> Result<Vec<DeviceMessage>, CodecError>;
33}
34
35/// 便捷类型别名
36pub type SharedCodec = Arc<dyn Codec>;
37
38/// JSON 编解码器:解析 `{device_id?, device_sn?, metric, value, ts?}` 或其数组
39///
40/// 兼容单对象与对象数组两种形态;`ts` 缺省取当前时刻。
41/// `device_id` 与 `device_sn` 至少其一(网关代传场景只带 `device_sn`,
42/// 由业务层按网关映射解析为平台主键;认证模式下最终以认证身份为准)。
43#[derive(Debug, Default, Clone)]
44pub struct JsonCodec;
45
46#[derive(Deserialize)]
47struct JsonPoint {
48    #[serde(default)]
49    device_id: Option<String>,
50    /// 网关侧子设备序列号:网关代传 payload 用它定位(平台主键由映射解析)
51    #[serde(default)]
52    device_sn: Option<String>,
53    metric: String,
54    value: serde_json::Value,
55    #[serde(default)]
56    ts_millis: Option<i64>,
57}
58
59#[derive(Deserialize)]
60#[serde(untagged)]
61enum JsonPayload {
62    One(JsonPoint),
63    Many(Vec<JsonPoint>),
64}
65
66fn json_value_to_metric(v: &serde_json::Value) -> MetricValue {
67    match v {
68        serde_json::Value::Bool(b) => MetricValue::Bool(*b),
69        serde_json::Value::Number(n) => {
70            if let Some(i) = n.as_i64() {
71                MetricValue::Int(i)
72            } else {
73                MetricValue::Float(n.as_f64().unwrap_or(0.0))
74            }
75        }
76        serde_json::Value::String(s) => MetricValue::Text(s.clone()),
77        other => MetricValue::Text(other.to_string()),
78    }
79}
80
81impl Codec for JsonCodec {
82    fn decode(
83        &self,
84        topic_hint: Option<&str>,
85        raw: &[u8],
86        protocol: Protocol,
87    ) -> Result<Vec<DeviceMessage>, CodecError> {
88        let text = std::str::from_utf8(raw).map_err(|e| CodecError(e.to_string()))?;
89        let trimmed = text.trim();
90        if trimmed.is_empty() {
91            return Ok(vec![]);
92        }
93        let payload: JsonPayload =
94            serde_json::from_str(trimmed).map_err(|e| CodecError(e.to_string()))?;
95        let points = match payload {
96            JsonPayload::One(p) => vec![p],
97            JsonPayload::Many(v) => v,
98        };
99        let now = chrono::Utc::now().timestamp_millis();
100        Ok(points
101            .into_iter()
102            .filter_map(|p| {
103                // 设备标识缺失(无 device_id 也无 device_sn):跳过该点
104                let device_id = p.device_id.or(p.device_sn).unwrap_or_default();
105                if device_id.is_empty() {
106                    return None;
107                }
108                let mut msg = DeviceMessage {
109                    device_id,
110                    device_name: String::new(),
111                    metric: p.metric,
112                    value: json_value_to_metric(&p.value),
113                    ts_millis: p.ts_millis.unwrap_or(now),
114                    protocol,
115                    tenant_id: 0,
116                    msg_id: String::new(),
117                    tags: Default::default(),
118                };
119                if let Some(t) = topic_hint {
120                    msg.tags.insert("topic".into(), t.to_string());
121                }
122                Some(msg)
123            })
124            .collect())
125    }
126}
127
128/// ThingsBoard 风格遥测编解码器:`v1/devices/me/telemetry` / `v1/gateway/telemetry`
129///
130/// 支持的 payload 形态(兼容单对象与数组):
131/// - 键值对:`{"temperature": 21.5, "humidity": 80}` —— 每个键产出一条消息,
132///   `ts` / `ts_millis` 为保留字(时间戳,不产出消息)
133/// - TB 数组元素:`[{"ts": 1710000000000, "values": {"temperature": 21.5}}]`
134/// - 网关代传:`{"deviceSn": "SN-1", "telemetry": {"temperature": 31.2}}`,
135///   `deviceSn` 作为设备标识占位(业务层按网关映射解析为平台主键),
136///   `telemetry` 缺省时平铺键值对(`{"deviceSn": "SN-1", "temperature": 31.2}`)
137/// - 旧版 JsonPoint 格式兼容:`{"device_id": "d1", "metric": "t", "value": 1}`
138///
139/// 设备标识不在此层定位:认证模式下由认证身份注入(直连)/ 网关映射解析(代传)。
140#[derive(Debug, Default, Clone)]
141pub struct TelemetryCodec;
142
143/// 时间戳保留键
144fn is_ts_key(k: &str) -> bool {
145    k == "ts" || k == "ts_millis"
146}
147
148/// 从对象取设备标识(网关代传):`deviceSn` / `device_sn`,兼容驼峰与下划线
149fn sn_of(map: &serde_json::Map<String, serde_json::Value>) -> Option<String> {
150    map.get("deviceSn")
151        .or_else(|| map.get("device_sn"))
152        .and_then(|v| v.as_str())
153        .filter(|s| !s.trim().is_empty())
154        .map(|s| s.to_string())
155}
156
157/// 递归解析一个 JSON 值(数组逐元素分派)为归一化消息
158fn telemetry_of(v: &serde_json::Value, protocol: Protocol) -> Vec<DeviceMessage> {
159    let now = chrono::Utc::now().timestamp_millis();
160    match v {
161        serde_json::Value::Array(items) => items
162            .iter()
163            .flat_map(|it| telemetry_of(it, protocol))
164            .collect(),
165        serde_json::Value::Object(map) => {
166            // 1. 网关代传:deviceSn + telemetry(或平铺键值);设备标识占位后由业务层覆盖
167            if let Some(sn) = sn_of(map) {
168                let mut inner = map.clone();
169                inner.remove("deviceSn");
170                inner.remove("device_sn");
171                let inner = inner
172                    .get("telemetry")
173                    .cloned()
174                    .unwrap_or(serde_json::Value::Object(inner));
175                let mut msgs = telemetry_of(&inner, protocol);
176                for m in msgs.iter_mut() {
177                    m.device_id = sn.clone();
178                }
179                return msgs;
180            }
181            // 2. 旧版 JsonPoint:metric + value(device_id/device_sn 作占位)
182            if let (Some(metric), Some(value)) = (map.get("metric"), map.get("value")) {
183                let device_id = map
184                    .get("device_id")
185                    .or_else(|| map.get("device_sn"))
186                    .and_then(|x| x.as_str())
187                    .unwrap_or_default()
188                    .to_string();
189                let mut msg = DeviceMessage {
190                    device_id,
191                    device_name: String::new(),
192                    metric: metric.as_str().unwrap_or_default().to_string(),
193                    value: json_value_to_metric(value),
194                    ts_millis: map.get("ts_millis").and_then(|x| x.as_i64()).unwrap_or(now),
195                    protocol,
196                    tenant_id: 0,
197                    msg_id: String::new(),
198                    tags: Default::default(),
199                };
200                if let Some(sn) = sn_of(map) {
201                    msg.device_id = sn;
202                }
203                return vec![msg];
204            }
205            // 3. TB 数组元素:ts + values(时间戳注入子消息)
206            if let Some(values) = map.get("values") {
207                let ts = map.get("ts").and_then(|x| x.as_i64()).unwrap_or(now);
208                let mut msgs = telemetry_of(values, protocol);
209                for m in msgs.iter_mut() {
210                    m.ts_millis = ts;
211                }
212                return msgs;
213            }
214            // 4. 键值对:每键一条(跳过时间戳保留字)
215            map.iter()
216                .filter(|(k, _)| !is_ts_key(k))
217                .map(|(k, val)| DeviceMessage {
218                    device_id: String::new(),
219                    device_name: String::new(),
220                    metric: k.clone(),
221                    value: json_value_to_metric(val),
222                    ts_millis: map
223                        .get("ts")
224                        .or_else(|| map.get("ts_millis"))
225                        .and_then(|x| x.as_i64())
226                        .unwrap_or(now),
227                    protocol,
228                    tenant_id: 0,
229                    msg_id: String::new(),
230                    tags: Default::default(),
231                })
232                .collect()
233        }
234        _ => vec![],
235    }
236}
237
238impl Codec for TelemetryCodec {
239    fn decode(
240        &self,
241        topic_hint: Option<&str>,
242        raw: &[u8],
243        protocol: Protocol,
244    ) -> Result<Vec<DeviceMessage>, CodecError> {
245        let text = std::str::from_utf8(raw).map_err(|e| CodecError(e.to_string()))?;
246        let trimmed = text.trim();
247        if trimmed.is_empty() {
248            return Ok(vec![]);
249        }
250        let value: serde_json::Value =
251            serde_json::from_str(trimmed).map_err(|e| CodecError(e.to_string()))?;
252        let mut msgs = telemetry_of(&value, protocol);
253        if let Some(t) = topic_hint {
254            for m in msgs.iter_mut() {
255                m.tags.insert("topic".into(), t.to_string());
256            }
257        }
258        Ok(msgs)
259    }
260}
261
262/// 行/CSV 编解码器:每行 `device_id,metric,value`(值优先按数字解析)
263///
264/// 适合裸 TCP 上报的轻量文本设备。多行会产出多条消息,忽略空行。
265#[derive(Debug, Default, Clone)]
266pub struct LineCodec;
267
268impl Codec for LineCodec {
269    fn decode(
270        &self,
271        topic_hint: Option<&str>,
272        raw: &[u8],
273        protocol: Protocol,
274    ) -> Result<Vec<DeviceMessage>, CodecError> {
275        let text = std::str::from_utf8(raw).map_err(|e| CodecError(e.to_string()))?;
276        let mut out = Vec::new();
277        let now = chrono::Utc::now().timestamp_millis();
278        for line in text.lines() {
279            let line = line.trim();
280            if line.is_empty() {
281                continue;
282            }
283            let parts: Vec<&str> = line.splitn(3, ',').map(str::trim).collect();
284            if parts.len() != 3 {
285                return Err(CodecError(format!(
286                    "期望 'device_id,metric,value' 三段,实际: {line}"
287                )));
288            }
289            let value = parse_scalar(parts[2]);
290            let mut msg = DeviceMessage {
291                device_id: parts[0].to_string(),
292                device_name: String::new(),
293                metric: parts[1].to_string(),
294                value,
295                ts_millis: now,
296                protocol,
297                tenant_id: 0,
298                msg_id: String::new(),
299                tags: Default::default(),
300            };
301            if let Some(t) = topic_hint {
302                msg.tags.insert("peer".into(), t.to_string());
303            }
304            out.push(msg);
305        }
306        Ok(out)
307    }
308}
309
310/// 标量文本解析:整数 → 浮点 → 布尔 → 文本 依次尝试
311///
312/// 供各协议在"payload 只是一个裸值"时复用(如 MQTT 主题携带语义、载荷仅为数值)。
313pub fn parse_scalar(s: &str) -> MetricValue {
314    let s = s.trim();
315    if let Ok(i) = s.parse::<i64>() {
316        return MetricValue::Int(i);
317    }
318    if let Ok(f) = s.parse::<f64>() {
319        return MetricValue::Float(f);
320    }
321    match s.to_ascii_lowercase().as_str() {
322        "true" | "on" => MetricValue::Bool(true),
323        "false" | "off" => MetricValue::Bool(false),
324        _ => MetricValue::Text(s.to_string()),
325    }
326}
327
328#[cfg(test)]
329mod tests {
330    use super::*;
331
332    #[test]
333    fn json_single_and_array() {
334        let c = JsonCodec;
335        let one = c
336            .decode(
337                None,
338                br#"{"device_id":"d1","metric":"t","value":21.5}"#,
339                Protocol::Mqtt,
340            )
341            .unwrap();
342        assert_eq!(one.len(), 1);
343        assert_eq!(one[0].value, MetricValue::Float(21.5));
344
345        let many = c
346            .decode(
347                Some("devices/d1"),
348                br#"[{"device_id":"d1","metric":"a","value":1},{"device_id":"d1","metric":"b","value":true}]"#,
349                Protocol::Http,
350            )
351            .unwrap();
352        assert_eq!(many.len(), 2);
353        assert_eq!(many[0].value, MetricValue::Int(1));
354        assert_eq!(many[1].value, MetricValue::Bool(true));
355        assert_eq!(
356            many[0].tags.get("topic").map(String::as_str),
357            Some("devices/d1")
358        );
359    }
360
361    /// 网关代传格式:无 device_id,仅 device_sn;device_id 用 SN 占位(认证/映射后覆盖)
362    #[test]
363    fn json_gateway_passthrough_sn() {
364        let c = JsonCodec;
365        let msgs = c
366            .decode(
367                Some("prod/gw1/temp"),
368                br#"{"device_sn":"SN-1001","metric":"temp","value":31.2}"#,
369                Protocol::Mqtt,
370            )
371            .unwrap();
372        assert_eq!(msgs.len(), 1);
373        assert_eq!(msgs[0].device_id, "SN-1001");
374        assert_eq!(msgs[0].value, MetricValue::Float(31.2));
375
376        // 数组形态(一条报文携带多子设备多点)
377        let msgs = c
378            .decode(
379                None,
380                br#"[{"device_sn":"SN-1","metric":"a","value":1},{"device_sn":"SN-2","metric":"b","value":"x"}]"#,
381                Protocol::Mqtt,
382            )
383            .unwrap();
384        assert_eq!(msgs.len(), 2);
385        assert_eq!(msgs[1].device_id, "SN-2");
386
387        // 无任何设备标识:跳过(不影响同包其它点)
388        let msgs = c
389            .decode(
390                None,
391                br#"[{"metric":"a","value":1},{"device_id":"d2","metric":"b","value":2}]"#,
392                Protocol::Mqtt,
393            )
394            .unwrap();
395        assert_eq!(msgs.len(), 1);
396        assert_eq!(msgs[0].device_id, "d2");
397    }
398
399    #[test]
400    fn line_codec_multi() {
401        let c = LineCodec;
402        let msgs = c
403            .decode(None, b"s1,temp,25.5\n s1,door,on \n\n", Protocol::Tcp)
404            .unwrap();
405        assert_eq!(msgs.len(), 2);
406        assert_eq!(msgs[0].value, MetricValue::Float(25.5));
407        assert_eq!(msgs[1].value, MetricValue::Bool(true));
408    }
409
410    #[test]
411    fn line_codec_bad_shape() {
412        let c = LineCodec;
413        assert!(c.decode(None, b"only,two", Protocol::Tcp).is_err());
414    }
415
416    #[test]
417    fn telemetry_kv_object() {
418        let c = TelemetryCodec;
419        let msgs = c
420            .decode(
421                Some("v1/devices/me/telemetry"),
422                br#"{"temperature": 21.5, "humidity": 80, "door": true, "ts": 1710000000000}"#,
423                Protocol::Mqtt,
424            )
425            .unwrap();
426        assert_eq!(msgs.len(), 3); // ts 为保留字,不产出消息
427        let find = |metric: &str| msgs.iter().find(|m| m.metric == metric).unwrap();
428        assert_eq!(find("temperature").value, MetricValue::Float(21.5));
429        assert_eq!(find("temperature").ts_millis, 1710000000000);
430        assert_eq!(find("humidity").value, MetricValue::Int(80));
431        assert_eq!(find("door").value, MetricValue::Bool(true));
432        assert_eq!(
433            msgs[0].tags.get("topic").map(String::as_str),
434            Some("v1/devices/me/telemetry")
435        );
436    }
437
438    #[test]
439    fn telemetry_tb_array_ts_values() {
440        let c = TelemetryCodec;
441        let msgs = c
442            .decode(
443                None,
444                br#"[{"ts": 1710000000000, "values": {"a": 1, "b": 2}}]"#,
445                Protocol::Mqtt,
446            )
447            .unwrap();
448        assert_eq!(msgs.len(), 2);
449        assert_eq!(msgs[0].ts_millis, 1710000000000);
450        assert_eq!(msgs[1].metric, "b");
451        assert_eq!(msgs[1].value, MetricValue::Int(2));
452    }
453
454    #[test]
455    fn telemetry_gateway_sn() {
456        let c = TelemetryCodec;
457        // 嵌套 telemetry
458        let msgs = c
459            .decode(
460                None,
461                br#"{"deviceSn": "SN-1001", "telemetry": {"temperature": 31.2}}"#,
462                Protocol::Mqtt,
463            )
464            .unwrap();
465        assert_eq!(msgs.len(), 1);
466        assert_eq!(msgs[0].device_id, "SN-1001");
467        assert_eq!(msgs[0].metric, "temperature");
468        assert_eq!(msgs[0].value, MetricValue::Float(31.2));
469
470        // 平铺键值(无 telemetry 嵌套)+ 数组形态(多子设备)
471        let msgs = c
472            .decode(
473                None,
474                br#"[{"device_sn": "SN-1", "a": 1}, {"deviceSn": "SN-2", "b": "x"}]"#,
475                Protocol::Mqtt,
476            )
477            .unwrap();
478        assert_eq!(msgs.len(), 2);
479        assert_eq!(msgs[0].device_id, "SN-1");
480        assert_eq!(msgs[1].device_id, "SN-2");
481    }
482
483    #[test]
484    fn telemetry_legacy_point() {
485        let c = TelemetryCodec;
486        let msgs = c
487            .decode(
488                None,
489                br#"{"device_id": "d9", "metric": "v", "value": 7}"#,
490                Protocol::Mqtt,
491            )
492            .unwrap();
493        assert_eq!(msgs.len(), 1);
494        assert_eq!(msgs[0].device_id, "d9");
495        assert_eq!(msgs[0].metric, "v");
496        assert_eq!(msgs[0].value, MetricValue::Int(7));
497    }
498}