Skip to main content

day_sqlite_worker/
protocol.rs

1// Copyright © The Daybrite Project
2// SPDX-License-Identifier: MPL-2.0
3
4//! The statement protocol the main thread speaks to the SQL worker (docs/persistence.md).
5//! Both sides link this module (the day-persistence proxy driver encodes requests and
6//! decodes replies; the worker loop does the reverse), so the wire format cannot drift.
7//! Everything is little-endian, length-prefixed, and version-tagged; the JS shuttle between
8//! them moves opaque bytes and never parses them (oversized replies are chunked JS-side,
9//! invisible here).
10
11/// First byte of every request; bumped only if the format ever changes shape.
12pub const VERSION: u8 = 1;
13
14/// A SQL value on the wire: the same five kinds SQLite itself has.
15#[derive(Clone, Debug, PartialEq)]
16pub enum Value {
17    Null,
18    Int(i64),
19    Real(f64),
20    Text(String),
21    Blob(Vec<u8>),
22}
23
24/// One request from the main thread. Connection ids are worker-assigned.
25#[derive(Clone, Debug, PartialEq)]
26pub enum Req {
27    /// Open (creating if absent) the named database file; answers `Reply::Conn`. `trace`
28    /// installs the engine's statement trace on the connection, logged to the worker page's
29    /// console (`sqlite3_trace_v2`; the driver's `trace_sql` sets it).
30    Open {
31        name: String,
32        trace: bool,
33    },
34    Close {
35        conn: u32,
36    },
37    /// Run semicolon-separated statements that take no parameters and return no rows; answers
38    /// `Reply::Ok`.
39    Batch {
40        conn: u32,
41        sql: String,
42    },
43    /// Run one statement with parameters; answers `Reply::Changes`.
44    Exec {
45        conn: u32,
46        sql: String,
47        params: Vec<Value>,
48    },
49    /// Run one statement with parameters; answers `Reply::Rows`.
50    Query {
51        conn: u32,
52        sql: String,
53        params: Vec<Value>,
54    },
55    /// Run one statement with its column names; answers `Reply::NamedRows`.
56    QueryNamed {
57        conn: u32,
58        sql: String,
59        params: Vec<Value>,
60    },
61    /// Storage-pool verbs, by database name (the file-per-document surface).
62    Exists {
63        name: String,
64    },
65    List,
66    Delete {
67        name: String,
68    },
69    /// The database's bytes as a plain SQLite file image; answers `Reply::Bytes`.
70    Export {
71        name: String,
72    },
73    /// Write a SQLite file image under `name` (replacing any prior content).
74    Import {
75        name: String,
76        bytes: Vec<u8>,
77    },
78}
79
80/// The worker's answer. `Err` carries the SQLite (or pool) message.
81#[derive(Clone, Debug, PartialEq)]
82pub enum Reply {
83    Ok,
84    NamedRows {
85        names: Vec<String>,
86        rows: Vec<Vec<Value>>,
87    },
88    Conn(u32),
89    Changes(u64),
90    Rows(Vec<Vec<Value>>),
91    Bool(bool),
92    Names(Vec<String>),
93    Bytes(Vec<u8>),
94    Err(String),
95}
96
97// --- encoding ------------------------------------------------------------------------------
98
99fn put_str(buf: &mut Vec<u8>, s: &str) {
100    buf.extend_from_slice(&(s.len() as u32).to_le_bytes());
101    buf.extend_from_slice(s.as_bytes());
102}
103
104fn put_bytes(buf: &mut Vec<u8>, b: &[u8]) {
105    buf.extend_from_slice(&(b.len() as u32).to_le_bytes());
106    buf.extend_from_slice(b);
107}
108
109fn put_value(buf: &mut Vec<u8>, v: &Value) {
110    match v {
111        Value::Null => buf.push(0),
112        Value::Int(i) => {
113            buf.push(1);
114            buf.extend_from_slice(&i.to_le_bytes());
115        }
116        Value::Real(r) => {
117            buf.push(2);
118            buf.extend_from_slice(&r.to_le_bytes());
119        }
120        Value::Text(t) => {
121            buf.push(3);
122            put_str(buf, t);
123        }
124        Value::Blob(b) => {
125            buf.push(4);
126            put_bytes(buf, b);
127        }
128    }
129}
130
131fn put_values(buf: &mut Vec<u8>, vs: &[Value]) {
132    buf.extend_from_slice(&(vs.len() as u32).to_le_bytes());
133    for v in vs {
134        put_value(buf, v);
135    }
136}
137
138pub fn encode_req(req: &Req) -> Vec<u8> {
139    let mut buf = vec![VERSION];
140    match req {
141        Req::Open { name, trace } => {
142            buf.push(1);
143            put_str(&mut buf, name);
144            buf.push(u8::from(*trace));
145        }
146        Req::Close { conn } => {
147            buf.push(2);
148            buf.extend_from_slice(&conn.to_le_bytes());
149        }
150        Req::Batch { conn, sql } => {
151            buf.push(3);
152            buf.extend_from_slice(&conn.to_le_bytes());
153            put_str(&mut buf, sql);
154        }
155        Req::Exec { conn, sql, params } => {
156            buf.push(4);
157            buf.extend_from_slice(&conn.to_le_bytes());
158            put_str(&mut buf, sql);
159            put_values(&mut buf, params);
160        }
161        Req::Query { conn, sql, params } => {
162            buf.push(5);
163            buf.extend_from_slice(&conn.to_le_bytes());
164            put_str(&mut buf, sql);
165            put_values(&mut buf, params);
166        }
167        Req::QueryNamed { conn, sql, params } => {
168            buf.push(11);
169            buf.extend_from_slice(&conn.to_le_bytes());
170            put_str(&mut buf, sql);
171            put_values(&mut buf, params);
172        }
173        Req::Exists { name } => {
174            buf.push(6);
175            put_str(&mut buf, name);
176        }
177        Req::List => buf.push(7),
178        Req::Delete { name } => {
179            buf.push(8);
180            put_str(&mut buf, name);
181        }
182        Req::Export { name } => {
183            buf.push(9);
184            put_str(&mut buf, name);
185        }
186        Req::Import { name, bytes } => {
187            buf.push(10);
188            put_str(&mut buf, name);
189            put_bytes(&mut buf, bytes);
190        }
191    }
192    buf
193}
194
195pub fn encode_reply(reply: &Reply) -> Vec<u8> {
196    let mut buf = Vec::new();
197    match reply {
198        Reply::Ok => buf.push(0),
199        Reply::Conn(id) => {
200            buf.push(1);
201            buf.extend_from_slice(&id.to_le_bytes());
202        }
203        Reply::Changes(n) => {
204            buf.push(2);
205            buf.extend_from_slice(&n.to_le_bytes());
206        }
207        Reply::Rows(rows) => {
208            buf.push(3);
209            buf.extend_from_slice(&(rows.len() as u32).to_le_bytes());
210            for row in rows {
211                put_values(&mut buf, row);
212            }
213        }
214        Reply::NamedRows { names, rows } => {
215            buf.push(7);
216            buf.extend_from_slice(&(names.len() as u32).to_le_bytes());
217            for name in names {
218                put_str(&mut buf, name);
219            }
220            buf.extend_from_slice(&(rows.len() as u32).to_le_bytes());
221            for row in rows {
222                put_values(&mut buf, row);
223            }
224        }
225        Reply::Bool(b) => {
226            buf.push(4);
227            buf.push(u8::from(*b));
228        }
229        Reply::Names(names) => {
230            buf.push(5);
231            buf.extend_from_slice(&(names.len() as u32).to_le_bytes());
232            for n in names {
233                put_str(&mut buf, n);
234            }
235        }
236        Reply::Bytes(b) => {
237            buf.push(6);
238            put_bytes(&mut buf, b);
239        }
240        Reply::Err(msg) => {
241            buf.push(255);
242            put_str(&mut buf, msg);
243        }
244    }
245    buf
246}
247
248// --- decoding ------------------------------------------------------------------------------
249
250/// A truncated or malformed buffer. Both sides treat it as a protocol bug, not user error.
251#[derive(Clone, Debug, PartialEq)]
252pub struct WireError;
253
254struct Reader<'a> {
255    buf: &'a [u8],
256    pos: usize,
257}
258
259impl<'a> Reader<'a> {
260    fn take(&mut self, n: usize) -> Result<&'a [u8], WireError> {
261        let end = self.pos.checked_add(n).ok_or(WireError)?;
262        if end > self.buf.len() {
263            return Err(WireError);
264        }
265        let s = &self.buf[self.pos..end];
266        self.pos = end;
267        Ok(s)
268    }
269    fn u8(&mut self) -> Result<u8, WireError> {
270        Ok(self.take(1)?[0])
271    }
272    fn u32(&mut self) -> Result<u32, WireError> {
273        Ok(u32::from_le_bytes(self.take(4)?.try_into().unwrap()))
274    }
275    fn u64(&mut self) -> Result<u64, WireError> {
276        Ok(u64::from_le_bytes(self.take(8)?.try_into().unwrap()))
277    }
278    fn i64(&mut self) -> Result<i64, WireError> {
279        Ok(i64::from_le_bytes(self.take(8)?.try_into().unwrap()))
280    }
281    fn f64(&mut self) -> Result<f64, WireError> {
282        Ok(f64::from_le_bytes(self.take(8)?.try_into().unwrap()))
283    }
284    fn str(&mut self) -> Result<String, WireError> {
285        let len = self.u32()? as usize;
286        let bytes = self.take(len)?;
287        String::from_utf8(bytes.to_vec()).map_err(|_| WireError)
288    }
289    fn bytes(&mut self) -> Result<Vec<u8>, WireError> {
290        let len = self.u32()? as usize;
291        Ok(self.take(len)?.to_vec())
292    }
293    fn value(&mut self) -> Result<Value, WireError> {
294        Ok(match self.u8()? {
295            0 => Value::Null,
296            1 => Value::Int(self.i64()?),
297            2 => Value::Real(self.f64()?),
298            3 => Value::Text(self.str()?),
299            4 => Value::Blob(self.bytes()?),
300            _ => return Err(WireError),
301        })
302    }
303    fn values(&mut self) -> Result<Vec<Value>, WireError> {
304        let n = self.u32()? as usize;
305        let mut vs = Vec::with_capacity(n.min(1024));
306        for _ in 0..n {
307            vs.push(self.value()?);
308        }
309        Ok(vs)
310    }
311    fn done(&self) -> Result<(), WireError> {
312        if self.pos == self.buf.len() {
313            Ok(())
314        } else {
315            Err(WireError)
316        }
317    }
318}
319
320pub fn decode_req(buf: &[u8]) -> Result<Req, WireError> {
321    let mut r = Reader { buf, pos: 0 };
322    if r.u8()? != VERSION {
323        return Err(WireError);
324    }
325    let req = match r.u8()? {
326        1 => Req::Open {
327            name: r.str()?,
328            trace: r.u8()? != 0,
329        },
330        2 => Req::Close { conn: r.u32()? },
331        3 => Req::Batch {
332            conn: r.u32()?,
333            sql: r.str()?,
334        },
335        4 => Req::Exec {
336            conn: r.u32()?,
337            sql: r.str()?,
338            params: r.values()?,
339        },
340        5 => Req::Query {
341            conn: r.u32()?,
342            sql: r.str()?,
343            params: r.values()?,
344        },
345        11 => Req::QueryNamed {
346            conn: r.u32()?,
347            sql: r.str()?,
348            params: r.values()?,
349        },
350        6 => Req::Exists { name: r.str()? },
351        7 => Req::List,
352        8 => Req::Delete { name: r.str()? },
353        9 => Req::Export { name: r.str()? },
354        10 => Req::Import {
355            name: r.str()?,
356            bytes: r.bytes()?,
357        },
358        _ => return Err(WireError),
359    };
360    r.done()?;
361    Ok(req)
362}
363
364pub fn decode_reply(buf: &[u8]) -> Result<Reply, WireError> {
365    let mut r = Reader { buf, pos: 0 };
366    let reply = match r.u8()? {
367        0 => Reply::Ok,
368        1 => Reply::Conn(r.u32()?),
369        2 => Reply::Changes(r.u64()?),
370        3 => {
371            let n = r.u32()? as usize;
372            let mut rows = Vec::with_capacity(n.min(1024));
373            for _ in 0..n {
374                rows.push(r.values()?);
375            }
376            Reply::Rows(rows)
377        }
378        4 => Reply::Bool(r.u8()? != 0),
379        5 => {
380            let n = r.u32()? as usize;
381            let mut names = Vec::with_capacity(n.min(1024));
382            for _ in 0..n {
383                names.push(r.str()?);
384            }
385            Reply::Names(names)
386        }
387        6 => Reply::Bytes(r.bytes()?),
388        7 => {
389            let n = r.u32()? as usize;
390            let mut names = Vec::with_capacity(n.min(1024));
391            for _ in 0..n {
392                names.push(r.str()?);
393            }
394            let n = r.u32()? as usize;
395            let mut rows = Vec::with_capacity(n.min(1024));
396            for _ in 0..n {
397                rows.push(r.values()?);
398            }
399            Reply::NamedRows { names, rows }
400        }
401        255 => Reply::Err(r.str()?),
402        _ => return Err(WireError),
403    };
404    r.done()?;
405    Ok(reply)
406}
407
408#[cfg(test)]
409mod tests {
410    use super::*;
411
412    fn round_trip_req(req: Req) {
413        assert_eq!(decode_req(&encode_req(&req)), Ok(req));
414    }
415
416    fn round_trip_reply(reply: Reply) {
417        assert_eq!(decode_reply(&encode_reply(&reply)), Ok(reply));
418    }
419
420    #[test]
421    fn every_request_round_trips() {
422        round_trip_req(Req::Open {
423            name: "Drawing 1.daysketch".into(),
424            trace: false,
425        });
426        round_trip_req(Req::Open {
427            name: "traced.db".into(),
428            trace: true,
429        });
430        round_trip_req(Req::Close { conn: 7 });
431        round_trip_req(Req::Batch {
432            conn: 1,
433            sql: "BEGIN; COMMIT;".into(),
434        });
435        round_trip_req(Req::Exec {
436            conn: 2,
437            sql: "INSERT INTO t VALUES (?, ?, ?, ?, ?)".into(),
438            params: vec![
439                Value::Null,
440                Value::Int(-42),
441                Value::Real(2.5),
442                Value::Text("héllo\u{1f}".into()),
443                Value::Blob(vec![0, 255, 1]),
444            ],
445        });
446        round_trip_req(Req::Query {
447            conn: 3,
448            sql: "SELECT 1".into(),
449            params: vec![],
450        });
451        round_trip_req(Req::Exists { name: "a".into() });
452        round_trip_req(Req::QueryNamed {
453            conn: 3,
454            sql: "SELECT ? AS value".into(),
455            params: vec![Value::Int(7)],
456        });
457        round_trip_req(Req::List);
458        round_trip_req(Req::Delete { name: "a".into() });
459        round_trip_req(Req::Export { name: "a".into() });
460        round_trip_req(Req::Import {
461            name: "a".into(),
462            bytes: vec![1, 2, 3],
463        });
464    }
465
466    #[test]
467    fn every_reply_round_trips() {
468        round_trip_reply(Reply::Ok);
469        round_trip_reply(Reply::Conn(9));
470        round_trip_reply(Reply::Changes(u64::MAX));
471        round_trip_reply(Reply::Rows(vec![
472            vec![Value::Int(1), Value::Text("a".into())],
473            vec![Value::Null, Value::Real(f64::MIN)],
474            vec![],
475        ]));
476        round_trip_reply(Reply::NamedRows {
477            names: vec!["id".into(), "title".into()],
478            rows: vec![vec![Value::Int(7), Value::Text("fixture".into())]],
479        });
480        round_trip_reply(Reply::NamedRows {
481            names: vec!["empty".into()],
482            rows: vec![],
483        });
484        round_trip_reply(Reply::Bool(true));
485        round_trip_reply(Reply::Names(vec!["a.db".into(), "b.db".into()]));
486        round_trip_reply(Reply::Bytes(vec![0; 100_000]));
487        round_trip_reply(Reply::Err("no such table: t".into()));
488    }
489
490    #[test]
491    fn truncated_named_rows_are_rejected() {
492        let bytes = encode_reply(&Reply::NamedRows {
493            names: vec!["fixture".into()],
494            rows: vec![vec![Value::Text("value".into())]],
495        });
496        for cut in 0..bytes.len() {
497            assert_eq!(decode_reply(&bytes[..cut]), Err(WireError));
498        }
499    }
500
501    #[test]
502    fn truncated_and_alien_buffers_are_errors_not_panics() {
503        let good = encode_req(&Req::Exec {
504            conn: 1,
505            sql: "SELECT ?".into(),
506            params: vec![Value::Text("x".into())],
507        });
508        for cut in 0..good.len() {
509            assert_eq!(decode_req(&good[..cut]), Err(WireError), "cut at {cut}");
510        }
511        assert_eq!(decode_req(&[]), Err(WireError));
512        assert_eq!(decode_req(&[VERSION, 99]), Err(WireError));
513        assert_eq!(decode_req(&[9, 1]), Err(WireError), "wrong version");
514        // Trailing garbage is rejected too: a length desync must not pass silently.
515        let mut padded = good.clone();
516        padded.push(0);
517        assert_eq!(decode_req(&padded), Err(WireError));
518        assert_eq!(decode_reply(&[77]), Err(WireError));
519        // A length prefix pointing past the buffer must not allocate or panic.
520        let mut lying = vec![VERSION, 1];
521        lying.extend_from_slice(&u32::MAX.to_le_bytes());
522        assert_eq!(decode_req(&lying), Err(WireError));
523    }
524}