Skip to main content

pickpoint_nano/
codec.rs

1//! Minimal tracking.v2 client/server codec for HTTP ingest (no uuid crate).
2
3pub const C_TRACK_START: u8 = 0x02;
4pub const C_TRACK_STOP: u8 = 0x03;
5pub const C_LOC: u8 = 0x04;
6
7pub const S_RELOCATE: u8 = 0x81;
8pub const S_TRACK_STARTED: u8 = 0x83;
9pub const S_TRACK_STOPPED: u8 = 0x84;
10pub const S_ACK: u8 = 0x85;
11pub const S_ERROR: u8 = 0x88;
12
13pub const MAX_LOC_POINTS: usize = 100;
14pub const MAX_STRING: usize = 4096;
15
16const PF_TIME: u8 = 1 << 4;
17const LAT_MIN: i32 = -90_000_000;
18const LAT_MAX: i32 = 90_000_000;
19const LON_MIN: i32 = -180_000_000;
20const LON_MAX: i32 = 180_000_000;
21
22#[derive(Debug, Clone, Copy, PartialEq, Eq)]
23pub enum DecodeError {
24    Truncated,
25    Invalid,
26}
27
28#[derive(Debug, Clone, Copy, PartialEq, Eq)]
29#[repr(u8)]
30pub enum ErrorCode {
31    Auth = 1,
32    TrackNotFound = 2,
33    Fenced = 3,
34    TryAgain = 4,
35    Invalid = 5,
36    Unauthorized = 6,
37}
38
39impl ErrorCode {
40    pub fn from_u8(v: u8) -> Option<Self> {
41        Some(match v {
42            1 => Self::Auth,
43            2 => Self::TrackNotFound,
44            3 => Self::Fenced,
45            4 => Self::TryAgain,
46            5 => Self::Invalid,
47            6 => Self::Unauthorized,
48            _ => return None,
49        })
50    }
51}
52
53#[derive(Debug, Clone, PartialEq)]
54pub enum ServerEvt {
55    Relocate {
56        endpoint: String,
57        retry_after_ms: u32,
58    },
59    TrackStarted {
60        track_uid: [u8; 16],
61        metadata: Vec<u8>,
62    },
63    TrackStopped {
64        track_uid: [u8; 16],
65    },
66    Ack {
67        seq: u64,
68    },
69    Error {
70        code: ErrorCode,
71        message: String,
72        track_uid: Option<[u8; 16]>,
73        retry_after_ms: Option<u32>,
74    },
75}
76
77#[derive(Debug, Clone, Copy)]
78pub struct Point {
79    pub lat_micro: i32,
80    pub lon_micro: i32,
81    pub timestamp_ms: i64,
82}
83
84pub fn deg_to_micro(d: f64) -> i32 {
85    (d * 1_000_000.0).round() as i32
86}
87
88pub fn micro_delta_fits(prev_lat: i32, prev_lon: i32, lat: i32, lon: i32) -> bool {
89    let dlat = lat as i64 - prev_lat as i64;
90    let dlon = lon as i64 - prev_lon as i64;
91    dlat >= i16::MIN as i64
92        && dlat <= i16::MAX as i64
93        && dlon >= i16::MIN as i64
94        && dlon <= i16::MAX as i64
95}
96
97struct R<'a>(&'a [u8]);
98
99impl<'a> R<'a> {
100    fn need(&mut self, n: usize) -> Result<&'a [u8], DecodeError> {
101        if self.0.len() < n {
102            return Err(DecodeError::Truncated);
103        }
104        let (head, tail) = self.0.split_at(n);
105        self.0 = tail;
106        Ok(head)
107    }
108    fn u8(&mut self) -> Result<u8, DecodeError> {
109        Ok(self.need(1)?[0])
110    }
111    fn u16(&mut self) -> Result<u16, DecodeError> {
112        Ok(u16::from_le_bytes(self.need(2)?.try_into().unwrap()))
113    }
114    fn u32(&mut self) -> Result<u32, DecodeError> {
115        Ok(u32::from_le_bytes(self.need(4)?.try_into().unwrap()))
116    }
117    fn uuid(&mut self) -> Result<[u8; 16], DecodeError> {
118        Ok(self.need(16)?.try_into().unwrap())
119    }
120    fn uuid_opt(&mut self) -> Result<Option<[u8; 16]>, DecodeError> {
121        let b = self.uuid()?;
122        if b.iter().all(|x| *x == 0) {
123            Ok(None)
124        } else {
125            Ok(Some(b))
126        }
127    }
128    fn str(&mut self) -> Result<String, DecodeError> {
129        let n = self.u16()? as usize;
130        if n > MAX_STRING {
131            return Err(DecodeError::Invalid);
132        }
133        let raw = self.need(n)?;
134        String::from_utf8(raw.to_vec()).map_err(|_| DecodeError::Invalid)
135    }
136    fn bytes(&mut self) -> Result<Vec<u8>, DecodeError> {
137        let n = self.u16()? as usize;
138        if n > MAX_STRING {
139            return Err(DecodeError::Invalid);
140        }
141        Ok(self.need(n)?.to_vec())
142    }
143}
144
145fn put_u8(w: &mut Vec<u8>, v: u8) {
146    w.push(v);
147}
148fn put_u16(w: &mut Vec<u8>, v: u16) {
149    w.extend_from_slice(&v.to_le_bytes());
150}
151fn put_u32(w: &mut Vec<u8>, v: u32) {
152    w.extend_from_slice(&v.to_le_bytes());
153}
154fn put_i16(w: &mut Vec<u8>, v: i16) {
155    w.extend_from_slice(&v.to_le_bytes());
156}
157fn put_i32(w: &mut Vec<u8>, v: i32) {
158    w.extend_from_slice(&v.to_le_bytes());
159}
160fn put_i64(w: &mut Vec<u8>, v: i64) {
161    w.extend_from_slice(&v.to_le_bytes());
162}
163
164pub fn encode_track_start() -> Vec<u8> {
165    let mut w = Vec::new();
166    put_u8(&mut w, C_TRACK_START);
167    put_u8(&mut w, 0);
168    put_u16(&mut w, 0);
169    put_u16(&mut w, 0);
170    w
171}
172
173pub fn encode_track_stop() -> Vec<u8> {
174    vec![C_TRACK_STOP]
175}
176
177fn write_point(w: &mut Vec<u8>, p: &Point, prev: Option<(i32, i32)>) {
178    let mut flags = 0u8;
179    if p.timestamp_ms != 0 {
180        flags |= PF_TIME;
181    }
182    put_u8(w, flags);
183    if let Some((plat, plon)) = prev {
184        put_i16(w, (p.lat_micro - plat) as i16);
185        put_i16(w, (p.lon_micro - plon) as i16);
186    } else {
187        put_i32(w, p.lat_micro);
188        put_i32(w, p.lon_micro);
189    }
190    if p.timestamp_ms != 0 {
191        put_i64(w, p.timestamp_ms);
192    }
193}
194
195/// Loc frames for `points`. `last_seq` is the seq of the last point.
196pub fn encode_loc_frames(last_seq: u64, points: &[Point]) -> Vec<Vec<u8>> {
197    if points.is_empty() {
198        return Vec::new();
199    }
200    let n = points.len() as u64;
201    let first_seq = last_seq + 1 - n;
202    let mut out = Vec::new();
203    let mut i = 0usize;
204    while i < points.len() {
205        let start = i;
206        let mut prev = (points[i].lat_micro, points[i].lon_micro);
207        i += 1;
208        while i < points.len() && (i - start) < MAX_LOC_POINTS {
209            let p = &points[i];
210            if !micro_delta_fits(prev.0, prev.1, p.lat_micro, p.lon_micro) {
211                break;
212            }
213            prev = (p.lat_micro, p.lon_micro);
214            i += 1;
215        }
216        let chunk = &points[start..i];
217        let seq = first_seq + i as u64 - 1;
218        out.push(encode_loc_frame(seq, chunk));
219    }
220    out
221}
222
223fn encode_loc_frame(seq: u64, points: &[Point]) -> Vec<u8> {
224    let mut w = Vec::new();
225    put_u8(&mut w, C_LOC);
226    put_u32(&mut w, seq as u32);
227    put_u8(&mut w, points.len() as u8);
228    let mut prev = None;
229    for p in points {
230        write_point(&mut w, p, prev);
231        prev = Some((p.lat_micro, p.lon_micro));
232    }
233    w
234}
235
236pub fn decode_server_frame(bytes: &[u8]) -> Result<(ServerEvt, usize), DecodeError> {
237    if bytes.is_empty() {
238        return Err(DecodeError::Truncated);
239    }
240    let mut r = R(bytes);
241    let typ = r.u8()?;
242    let evt = match typ {
243        S_RELOCATE => ServerEvt::Relocate {
244            retry_after_ms: r.u32()?,
245            endpoint: r.str()?,
246        },
247        S_TRACK_STARTED => ServerEvt::TrackStarted {
248            track_uid: r.uuid()?,
249            metadata: r.bytes()?,
250        },
251        S_TRACK_STOPPED => ServerEvt::TrackStopped {
252            track_uid: r.uuid()?,
253        },
254        S_ACK => ServerEvt::Ack {
255            seq: r.u32()? as u64,
256        },
257        S_ERROR => {
258            let code = ErrorCode::from_u8(r.u8()?).ok_or(DecodeError::Invalid)?;
259            let retry = r.u32()?;
260            let track_uid = r.uuid_opt()?;
261            let message = r.str()?;
262            ServerEvt::Error {
263                code,
264                message,
265                track_uid,
266                retry_after_ms: if retry == 0 { None } else { Some(retry) },
267            }
268        }
269        0x00 | 0x7F | 0xFF | 0x8C => return Err(DecodeError::Invalid),
270        t if (0x80..=0xFE).contains(&t) => return Err(DecodeError::Invalid),
271        _ => return Err(DecodeError::Invalid),
272    };
273    let consumed = bytes.len() - r.0.len();
274    Ok((evt, consumed))
275}
276
277pub fn decode_server_concat(bytes: &[u8]) -> Result<Vec<ServerEvt>, DecodeError> {
278    let mut rest = bytes;
279    let mut out = Vec::new();
280    while !rest.is_empty() {
281        let (evt, n) = decode_server_frame(rest)?;
282        if n == 0 {
283            return Err(DecodeError::Invalid);
284        }
285        out.push(evt);
286        rest = &rest[n..];
287    }
288    Ok(out)
289}
290
291/// Hyphenated lowercase UUID (16 bytes).
292pub fn format_uuid(b: &[u8; 16]) -> String {
293    fn hex(b: u8, out: &mut String) {
294        const H: &[u8; 16] = b"0123456789abcdef";
295        out.push(H[(b >> 4) as usize] as char);
296        out.push(H[(b & 0x0f) as usize] as char);
297    }
298    let mut s = String::with_capacity(36);
299    for (i, byte) in b.iter().enumerate() {
300        if i == 4 || i == 6 || i == 8 || i == 10 {
301            s.push('-');
302        }
303        hex(*byte, &mut s);
304    }
305    s
306}
307
308pub fn check_coord(lat: i32, lon: i32) -> bool {
309    (LAT_MIN..=LAT_MAX).contains(&lat) && (LON_MIN..=LON_MAX).contains(&lon)
310}