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
320/// Decode one request.
321///
322/// # Errors
323/// Returns [`WireError`] when the bytes are not a well-formed request of this protocol version.
324pub fn decode_req(buf: &[u8]) -> Result<Req, WireError> {
325    let mut r = Reader { buf, pos: 0 };
326    if r.u8()? != VERSION {
327        return Err(WireError);
328    }
329    let req = match r.u8()? {
330        1 => Req::Open {
331            name: r.str()?,
332            trace: r.u8()? != 0,
333        },
334        2 => Req::Close { conn: r.u32()? },
335        3 => Req::Batch {
336            conn: r.u32()?,
337            sql: r.str()?,
338        },
339        4 => Req::Exec {
340            conn: r.u32()?,
341            sql: r.str()?,
342            params: r.values()?,
343        },
344        5 => Req::Query {
345            conn: r.u32()?,
346            sql: r.str()?,
347            params: r.values()?,
348        },
349        11 => Req::QueryNamed {
350            conn: r.u32()?,
351            sql: r.str()?,
352            params: r.values()?,
353        },
354        6 => Req::Exists { name: r.str()? },
355        7 => Req::List,
356        8 => Req::Delete { name: r.str()? },
357        9 => Req::Export { name: r.str()? },
358        10 => Req::Import {
359            name: r.str()?,
360            bytes: r.bytes()?,
361        },
362        _ => return Err(WireError),
363    };
364    r.done()?;
365    Ok(req)
366}
367
368/// Decode one reply.
369///
370/// # Errors
371/// Returns [`WireError`] when the bytes are not a well-formed reply.
372pub fn decode_reply(buf: &[u8]) -> Result<Reply, WireError> {
373    let mut r = Reader { buf, pos: 0 };
374    let reply = match r.u8()? {
375        0 => Reply::Ok,
376        1 => Reply::Conn(r.u32()?),
377        2 => Reply::Changes(r.u64()?),
378        3 => {
379            let n = r.u32()? as usize;
380            let mut rows = Vec::with_capacity(n.min(1024));
381            for _ in 0..n {
382                rows.push(r.values()?);
383            }
384            Reply::Rows(rows)
385        }
386        4 => Reply::Bool(r.u8()? != 0),
387        5 => {
388            let n = r.u32()? as usize;
389            let mut names = Vec::with_capacity(n.min(1024));
390            for _ in 0..n {
391                names.push(r.str()?);
392            }
393            Reply::Names(names)
394        }
395        6 => Reply::Bytes(r.bytes()?),
396        7 => {
397            let n = r.u32()? as usize;
398            let mut names = Vec::with_capacity(n.min(1024));
399            for _ in 0..n {
400                names.push(r.str()?);
401            }
402            let n = r.u32()? as usize;
403            let mut rows = Vec::with_capacity(n.min(1024));
404            for _ in 0..n {
405                rows.push(r.values()?);
406            }
407            Reply::NamedRows { names, rows }
408        }
409        255 => Reply::Err(r.str()?),
410        _ => return Err(WireError),
411    };
412    r.done()?;
413    Ok(reply)
414}
415
416#[cfg(test)]
417mod tests {
418    use super::*;
419
420    fn round_trip_req(req: Req) {
421        assert_eq!(decode_req(&encode_req(&req)), Ok(req));
422    }
423
424    fn round_trip_reply(reply: Reply) {
425        assert_eq!(decode_reply(&encode_reply(&reply)), Ok(reply));
426    }
427
428    #[test]
429    fn every_request_round_trips() {
430        round_trip_req(Req::Open {
431            name: "Drawing 1.daysketch".into(),
432            trace: false,
433        });
434        round_trip_req(Req::Open {
435            name: "traced.db".into(),
436            trace: true,
437        });
438        round_trip_req(Req::Close { conn: 7 });
439        round_trip_req(Req::Batch {
440            conn: 1,
441            sql: "BEGIN; COMMIT;".into(),
442        });
443        round_trip_req(Req::Exec {
444            conn: 2,
445            sql: "INSERT INTO t VALUES (?, ?, ?, ?, ?)".into(),
446            params: vec![
447                Value::Null,
448                Value::Int(-42),
449                Value::Real(2.5),
450                Value::Text("héllo\u{1f}".into()),
451                Value::Blob(vec![0, 255, 1]),
452            ],
453        });
454        round_trip_req(Req::Query {
455            conn: 3,
456            sql: "SELECT 1".into(),
457            params: vec![],
458        });
459        round_trip_req(Req::Exists { name: "a".into() });
460        round_trip_req(Req::QueryNamed {
461            conn: 3,
462            sql: "SELECT ? AS value".into(),
463            params: vec![Value::Int(7)],
464        });
465        round_trip_req(Req::List);
466        round_trip_req(Req::Delete { name: "a".into() });
467        round_trip_req(Req::Export { name: "a".into() });
468        round_trip_req(Req::Import {
469            name: "a".into(),
470            bytes: vec![1, 2, 3],
471        });
472    }
473
474    #[test]
475    fn every_reply_round_trips() {
476        round_trip_reply(Reply::Ok);
477        round_trip_reply(Reply::Conn(9));
478        round_trip_reply(Reply::Changes(u64::MAX));
479        round_trip_reply(Reply::Rows(vec![
480            vec![Value::Int(1), Value::Text("a".into())],
481            vec![Value::Null, Value::Real(f64::MIN)],
482            vec![],
483        ]));
484        round_trip_reply(Reply::NamedRows {
485            names: vec!["id".into(), "title".into()],
486            rows: vec![vec![Value::Int(7), Value::Text("fixture".into())]],
487        });
488        round_trip_reply(Reply::NamedRows {
489            names: vec!["empty".into()],
490            rows: vec![],
491        });
492        round_trip_reply(Reply::Bool(true));
493        round_trip_reply(Reply::Names(vec!["a.db".into(), "b.db".into()]));
494        round_trip_reply(Reply::Bytes(vec![0; 100_000]));
495        round_trip_reply(Reply::Err("no such table: t".into()));
496    }
497
498    #[test]
499    fn truncated_named_rows_are_rejected() {
500        let bytes = encode_reply(&Reply::NamedRows {
501            names: vec!["fixture".into()],
502            rows: vec![vec![Value::Text("value".into())]],
503        });
504        for cut in 0..bytes.len() {
505            assert_eq!(decode_reply(&bytes[..cut]), Err(WireError));
506        }
507    }
508
509    #[test]
510    fn truncated_and_alien_buffers_are_errors_not_panics() {
511        let good = encode_req(&Req::Exec {
512            conn: 1,
513            sql: "SELECT ?".into(),
514            params: vec![Value::Text("x".into())],
515        });
516        for cut in 0..good.len() {
517            assert_eq!(decode_req(&good[..cut]), Err(WireError), "cut at {cut}");
518        }
519        assert_eq!(decode_req(&[]), Err(WireError));
520        assert_eq!(decode_req(&[VERSION, 99]), Err(WireError));
521        assert_eq!(decode_req(&[9, 1]), Err(WireError), "wrong version");
522        // Trailing garbage is rejected too: a length desync must not pass silently.
523        let mut padded = good.clone();
524        padded.push(0);
525        assert_eq!(decode_req(&padded), Err(WireError));
526        assert_eq!(decode_reply(&[77]), Err(WireError));
527        // A length prefix pointing past the buffer must not allocate or panic.
528        let mut lying = vec![VERSION, 1];
529        lying.extend_from_slice(&u32::MAX.to_le_bytes());
530        assert_eq!(decode_req(&lying), Err(WireError));
531    }
532}