Skip to main content

day_persistence/
rusqlite_driver.rs

1// Copyright © The Daybrite Project
2// SPDX-License-Identifier: MPL-2.0
3
4//! The built-in driver. On native targets the engine is rusqlite, chosen by cargo feature:
5//! `bundled` (the default), `system` (link the OS's libsqlite3), or `cipher` (SQLCipher with
6//! vendored crypto). On web-dom the engine is day-sqlite-worker: `:memory:` databases run
7//! in-process, and file databases are proxied synchronously to the day-sql worker, which
8//! holds them on real OPFS (see the web module at the end of this file). One driver type,
9//! recompiled; not a crate per engine.
10
11use std::rc::Rc;
12
13#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
14use rusqlite::Connection;
15
16#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
17type InitHook = Rc<dyn Fn(&Connection)>;
18
19use crate::{
20    Capabilities, DbError, DbErrorKind, Location, OpenOptions, Row, Secret, SqliteConnection,
21    SqliteDriver, Value,
22};
23
24/// The built-in SQLite driver. `Sqlite::at(path)` or `Sqlite::memory()`, then builder options.
25/// A statement-trace sink (`Sqlite::trace_sql`).
26type TraceFn = Rc<dyn Fn(&str)>;
27
28pub struct Sqlite {
29    opts: OpenOptions,
30    /// Runs against the raw rusqlite connection right after open, to register a custom SQL
31    /// function, load an extension, or set a PRAGMA. The framework neither knows nor cares.
32    /// Native only: the web engine lives in the day-sql worker, out of closure reach.
33    #[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
34    init: Option<InitHook>,
35    /// The statement-trace sink (`trace_sql`).
36    trace: Option<TraceFn>,
37}
38
39impl Sqlite {
40    fn from_opts(opts: OpenOptions) -> Self {
41        Sqlite {
42            opts,
43            #[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
44            init: None,
45            trace: None,
46        }
47    }
48    pub fn at(path: impl Into<std::path::PathBuf>) -> Self {
49        Sqlite::from_opts(OpenOptions::new(Location::File(path.into())))
50    }
51    pub fn memory() -> Self {
52        Sqlite::from_opts(OpenOptions::new(Location::Memory))
53    }
54    #[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
55    /// The database named `name` in the per-app data directory, created if missing. The
56    /// directory follows the day-part-filesystem root rules (docs/fs.md): `DAY_DATA_DIR` when the
57    /// host passes one (the Android and OpenHarmony hosts do), the platform's app-data
58    /// convention otherwise, and a `day-db/` leaf of its own beside day-part-filesystem' `day-fs/`.
59    /// `name` is a file name, not a path. Errs where no such directory exists (web has no
60    /// filesystem; keep a wasm build on [`Sqlite::memory`] or its own driver).
61    pub fn app_data(name: impl AsRef<str>) -> Result<Self, DbError> {
62        let name = name.as_ref();
63        if name.is_empty() || name.contains(['/', '\\']) || name.contains("..") {
64            return Err(DbError::new(
65                DbErrorKind::Unsupported,
66                format!("app_data takes a file name, not a path: {name:?}"),
67            ));
68        }
69        let dir = Self::app_data_dir()?;
70        std::fs::create_dir_all(&dir)
71            .map_err(|e| DbError::driver(format!("creating {}: {e}", dir.display())))?;
72        Ok(Sqlite::at(dir.join(name)))
73    }
74    /// The database key (feature `cipher`; other builds refuse it at open, loudly).
75    pub fn key(mut self, key: Secret) -> Self {
76        self.opts.key = Some(key);
77        self
78    }
79    /// Accept a file written by an older SQLCipher generation (`PRAGMA cipher_migrate`).
80    pub fn cipher_migrate(mut self) -> Self {
81        self.opts.cipher_migrate = true;
82        self
83    }
84    pub fn wal(mut self, on: bool) -> Self {
85        self.opts.wal = on;
86        self
87    }
88    /// The directory [`Sqlite::app_data`] resolves into, for apps that manage their document
89    /// files there (numbering "Drawing 2", importing a picked file). Created lazily by
90    /// `app_data`; this accessor only resolves it.
91    #[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
92    pub fn app_data_dir() -> Result<std::path::PathBuf, DbError> {
93        app_data_root()
94    }
95
96    /// A per-connection hook over the raw rusqlite connection: the escape valve for loadable
97    /// extensions, custom functions, and PRAGMAs this crate does not model. Native only.
98    #[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
99    pub fn with_init(mut self, f: impl Fn(&Connection) + 'static) -> Self {
100        self.init = Some(Rc::new(f));
101        self
102    }
103
104    /// Per-statement SQL tracing through the engine's own facility (`sqlite3_trace_v2` with
105    /// `SQLITE_TRACE_STMT`): `f` sees every statement this connection executes (migrations,
106    /// autosave flushes, live-query `SELECT`s, maintenance) with bound parameters expanded by
107    /// the engine itself. Wire it to a logger in debug builds:
108    ///
109    /// ```ignore
110    /// let driver = Sqlite::app_data("trips.db")?;
111    /// let driver = if cfg!(debug_assertions) {
112    ///     driver.trace_sql(|sql| log::trace!("sql: {sql}"))
113    /// } else {
114    ///     driver
115    /// };
116    /// ```
117    ///
118    /// The trace installs after any `PRAGMA key`, so a cipher key never reaches the sink. On
119    /// web-dom a file database's engine runs in the day-sql worker, out of closure reach:
120    /// there the statements log to the browser console (`[day-sql]` lines in devtools) and
121    /// `f` is not called. `:memory:` databases call `f` on every target.
122    pub fn trace_sql(mut self, f: impl Fn(&str) + 'static) -> Self {
123        self.trace = Some(Rc::new(f));
124        self
125    }
126}
127
128impl SqliteDriver for Sqlite {
129    type Connection = RusqliteConn;
130
131    /// The proxy open: `:memory:` runs in-process (no file I/O exists in that engine shape);
132    /// a file database opens inside the day-sql worker over the synchronous channel.
133    #[cfg(all(target_family = "wasm", target_os = "unknown"))]
134    fn open(self) -> Result<RusqliteConn, DbError> {
135        use day_sqlite_worker::protocol::{Reply as WReply, Req as WReq};
136        if self.opts.key.is_some() {
137            return Err(DbError::new(
138                DbErrorKind::Unsupported,
139                "this build has no encryption — the web engine does not include SQLCipher",
140            ));
141        }
142        let conn = match &self.opts.location {
143            Location::Memory => {
144                let mut conn = day_sqlite_worker::Connection::open_memory()
145                    .map_err(|e| DbError::driver(e.to_string()))?;
146                if let Some(f) = &self.trace {
147                    let f = f.clone();
148                    conn.trace_stmt(Box::new(move |sql| f(sql)));
149                }
150                WebConn::Memory(conn)
151            }
152            Location::File(p) => {
153                let name = p.to_string_lossy().into_owned();
154                match web::channel::call(&WReq::Open {
155                    name,
156                    trace: self.trace.is_some(),
157                })? {
158                    WReply::Conn(id) => WebConn::Remote(id),
159                    other => return Err(web::unexpected(other)),
160                }
161            }
162        };
163        let mut conn = RusqliteConn { conn };
164        if self.opts.foreign_keys {
165            conn.execute("PRAGMA foreign_keys = ON", &[])?;
166        }
167        Ok(conn)
168    }
169
170    #[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
171    fn open(self) -> Result<RusqliteConn, DbError> {
172        let conn = match &self.opts.location {
173            Location::Memory => Connection::open_in_memory(),
174            Location::File(p) => Connection::open(p),
175        }
176        .map_err(|e| DbError::driver(e.to_string()))?;
177
178        if let Some(key) = &self.opts.key {
179            #[cfg(feature = "cipher")]
180            {
181                // PRAGMA key takes no bound parameter; single-quote-escape the literal.
182                let quoted = key.reveal().replace('\'', "''");
183                conn.execute_batch(&format!("PRAGMA key = '{quoted}';"))
184                    .map_err(|e| DbError::driver(e.to_string()))?;
185                if self.opts.cipher_migrate {
186                    let _ = conn.execute_batch("PRAGMA cipher_migrate;");
187                }
188            }
189            #[cfg(not(feature = "cipher"))]
190            {
191                let _ = key;
192                return Err(DbError::new(
193                    DbErrorKind::Unsupported,
194                    "this build has no encryption — enable the `cipher` feature",
195                ));
196            }
197        }
198
199        // A wrong (or missing) key surfaces on the first real read, not at PRAGMA time. Probe
200        // now so the caller gets BadKey at open instead of a raw engine error later. Only the
201        // cipher build maps the failure to BadKey; a plaintext build's unreadable file is
202        // corruption, not a key problem.
203        #[cfg(feature = "cipher")]
204        if conn
205            .prepare("SELECT count(*) FROM sqlite_master")
206            .and_then(|mut s| s.query_row([], |_| Ok(())))
207            .is_err()
208        {
209            return Err(DbError::new(
210                DbErrorKind::BadKey,
211                "the database would not open with this key",
212            ));
213        }
214
215        // Trace after the key PRAGMA above (a cipher key must never reach the sink) and
216        // before everything else, so the remaining setup PRAGMAs log too.
217        let trace = self
218            .trace
219            .as_ref()
220            .map(|f| install_sql_trace(&conn, f.clone()));
221
222        // `day_fold`: Rust's full-Unicode `to_lowercase` as a scalar SQL function, so
223        // case-insensitive predicates compile to SQL that selects exactly the rows the
224        // in-memory fold would (SQLite's own `lower()` folds ASCII only). Deterministic, so
225        // the planner may hoist and index it.
226        {
227            use rusqlite::functions::FunctionFlags;
228            conn.create_scalar_function(
229                "day_fold",
230                1,
231                FunctionFlags::SQLITE_UTF8 | FunctionFlags::SQLITE_DETERMINISTIC,
232                |ctx| {
233                    let folded = match ctx.get_raw(0) {
234                        rusqlite::types::ValueRef::Text(t) => {
235                            Some(String::from_utf8_lossy(t).to_lowercase())
236                        }
237                        _ => None,
238                    };
239                    Ok(folded)
240                },
241            )
242            .map_err(|e| DbError::driver(format!("registering day_fold: {e}")))?;
243        }
244
245        conn.busy_timeout(std::time::Duration::from_millis(
246            self.opts.busy_timeout_ms as u64,
247        ))
248        .map_err(|e| DbError::driver(e.to_string()))?;
249        if self.opts.foreign_keys {
250            conn.execute_batch("PRAGMA foreign_keys = ON;")
251                .map_err(|e| DbError::driver(e.to_string()))?;
252        }
253        #[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
254        if self.opts.wal && matches!(self.opts.location, Location::File(_)) {
255            conn.execute_batch("PRAGMA journal_mode = WAL;")
256                .map_err(|e| DbError::driver(e.to_string()))?;
257        }
258        if let Some(init) = &self.init {
259            init(&conn);
260        }
261        Ok(RusqliteConn {
262            conn,
263            _trace: trace,
264        })
265    }
266
267    fn capabilities(&self) -> Capabilities {
268        #[cfg(all(target_family = "wasm", target_os = "unknown"))]
269        {
270            Capabilities {
271                // A file database is durable when the day-sql worker holds it on OPFS: the
272                // worker fsyncs before each reply, so a commit that returned has landed. No
273                // channel (a host serving without cross-origin isolation) = no file databases
274                // at all: reported here, refused loudly at open.
275                durable: matches!(self.opts.location, Location::File(_)) && web::channel::ready(),
276                encryption: false,
277                wal: false,
278                // day-sqlite-worker pins FTS5 and R*Tree into its build.
279                full_text_search: true,
280                rtree: true,
281                external_changes: false,
282                // The web engine runs in the day-sql worker, out of reach of a Rust closure
283                // registration, so folded predicates take the exact fallback path instead.
284                unicode_fold: false,
285            }
286        }
287        #[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
288        {
289            Capabilities {
290                durable: matches!(self.opts.location, Location::File(_)),
291                encryption: cfg!(feature = "cipher"),
292                wal: true,
293                // The bundled builds compile FTS5/R*Tree in; a system libsqlite3 may or may
294                // not, and claiming what we have not verified would be a lie the schema layer
295                // acts on.
296                full_text_search: cfg!(any(feature = "bundled", feature = "cipher")),
297                rtree: cfg!(any(feature = "bundled", feature = "cipher")),
298                // `PRAGMA data_version` is core SQLite: another connection's committed writes
299                // are detectable on any file database. A memory database has no second
300                // connection to detect.
301                external_changes: matches!(self.opts.location, Location::File(_)),
302                // `day_fold` registers at open on every native connection.
303                unicode_fold: true,
304            }
305        }
306    }
307}
308
309/// The `day-db/` sibling of day-part-filesystem' root: same resolution order, its own leaf, so the
310/// database never collides with other day state in the directory.
311#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
312fn app_data_root() -> Result<std::path::PathBuf, DbError> {
313    use std::path::PathBuf;
314    let no_dir = || {
315        DbError::new(
316            DbErrorKind::Unsupported,
317            "no per-app data directory on this target",
318        )
319    };
320    if let Some(dir) = std::env::var_os("DAY_DATA_DIR")
321        && !dir.is_empty()
322    {
323        return Ok(PathBuf::from(dir).join("day-db"));
324    }
325    #[cfg(any(target_os = "macos", target_os = "ios"))]
326    {
327        std::env::var_os("HOME")
328            .map(|home| {
329                PathBuf::from(home)
330                    .join("Library/Application Support/day")
331                    .join("day-db")
332            })
333            .ok_or_else(no_dir)
334    }
335    #[cfg(target_os = "windows")]
336    {
337        std::env::var_os("APPDATA")
338            .map(|app| PathBuf::from(app).join("day").join("day-db"))
339            .ok_or_else(no_dir)
340    }
341    #[cfg(not(any(target_os = "macos", target_os = "ios", target_os = "windows")))]
342    {
343        if let Some(dir) = std::env::var_os("XDG_DATA_HOME")
344            && !dir.is_empty()
345        {
346            return Ok(PathBuf::from(dir).join("day").join("day-db"));
347        }
348        std::env::var_os("HOME")
349            .map(|home| PathBuf::from(home).join(".local/share/day").join("day-db"))
350            .ok_or_else(no_dir)
351    }
352}
353
354#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
355pub struct RusqliteConn {
356    conn: Connection,
357    /// Keeps the installed trace closure alive as long as the engine may call it (the box's
358    /// heap address is what `sqlite3_trace_v2` holds). Dropped after `conn` closes.
359    _trace: Option<Box<TraceFn>>,
360}
361
362/// Install the engine's per-statement trace on a raw connection handle. rusqlite's own
363/// `trace_v2` takes a plain fn pointer, so the closure rides the C-level context instead.
364#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
365fn install_sql_trace(conn: &Connection, f: TraceFn) -> Box<TraceFn> {
366    use rusqlite::ffi;
367    unsafe extern "C" fn cb(
368        ev: std::ffi::c_uint,
369        ctx: *mut std::ffi::c_void,
370        p: *mut std::ffi::c_void,
371        x: *mut std::ffi::c_void,
372    ) -> std::ffi::c_int {
373        if ev != ffi::SQLITE_TRACE_STMT || ctx.is_null() {
374            return 0;
375        }
376        // SAFETY: ctx is the connection's boxed trace closure (returned below and stored on
377        // RusqliteConn), alive until after the connection closes; day's connections are
378        // single-threaded, so the callback never races the closure.
379        let f = unsafe { &*(ctx as *const TraceFn) };
380        unsafe {
381            let expanded = ffi::sqlite3_expanded_sql(p.cast());
382            if !expanded.is_null() {
383                if let Ok(s) = std::ffi::CStr::from_ptr(expanded).to_str() {
384                    f(s);
385                }
386                ffi::sqlite3_free(expanded.cast());
387            } else if !x.is_null() {
388                // The engine could not expand (OOM, or a trigger frame): unexpanded text.
389                if let Ok(s) = std::ffi::CStr::from_ptr(x.cast()).to_str() {
390                    f(s);
391                }
392            }
393        }
394        0
395    }
396    let boxed = Box::new(f);
397    let ctx = &*boxed as *const TraceFn as *mut std::ffi::c_void;
398    // SAFETY: the handle is this connection's own; ctx points into `boxed`, whose heap slot
399    // outlives the connection via RusqliteConn::_trace.
400    unsafe {
401        ffi::sqlite3_trace_v2(conn.handle(), ffi::SQLITE_TRACE_STMT, Some(cb), ctx);
402    }
403    boxed
404}
405
406/// The web connection: in-process for `:memory:`, a worker connection id for files.
407#[cfg(all(target_family = "wasm", target_os = "unknown"))]
408enum WebConn {
409    Memory(day_sqlite_worker::Connection),
410    Remote(u32),
411}
412
413#[cfg(all(target_family = "wasm", target_os = "unknown"))]
414pub struct RusqliteConn {
415    conn: WebConn,
416}
417
418#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
419fn to_sql(v: &Value) -> rusqlite::types::Value {
420    use rusqlite::types::Value as R;
421    match v {
422        Value::Null => R::Null,
423        Value::Int(i) => R::Integer(*i),
424        Value::Real(f) => R::Real(*f),
425        Value::Text(t) => R::Text(t.clone()),
426        Value::Blob(b) => R::Blob(b.clone()),
427    }
428}
429
430#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
431fn from_sql(v: rusqlite::types::ValueRef<'_>) -> Value {
432    use rusqlite::types::ValueRef as R;
433    match v {
434        R::Null => Value::Null,
435        R::Integer(i) => Value::Int(i),
436        R::Real(f) => Value::Real(f),
437        R::Text(t) => Value::Text(String::from_utf8_lossy(t).into_owned()),
438        R::Blob(b) => Value::Blob(b.to_vec()),
439    }
440}
441
442#[cfg(all(target_family = "wasm", target_os = "unknown"))]
443impl SqliteConnection for RusqliteConn {
444    fn execute_batch(&mut self, sql: &str) -> Result<(), DbError> {
445        use day_sqlite_worker::protocol::{Reply as WReply, Req as WReq};
446        match &self.conn {
447            WebConn::Memory(c) => c
448                .execute_batch(sql)
449                .map_err(|e| DbError::driver(format!("{e} in `{sql}`"))),
450            WebConn::Remote(id) => match web::channel::call(&WReq::Batch {
451                conn: *id,
452                sql: sql.to_owned(),
453            })? {
454                WReply::Ok => Ok(()),
455                other => Err(web::unexpected(other)),
456            },
457        }
458    }
459
460    fn execute(&mut self, sql: &str, params: &[Value]) -> Result<u64, DbError> {
461        use day_sqlite_worker::protocol::{Reply as WReply, Req as WReq};
462        match &self.conn {
463            WebConn::Memory(c) => c
464                .execute(sql, &web::to_wire(params))
465                .map_err(|e| DbError::driver(format!("{e} in `{sql}`"))),
466            WebConn::Remote(id) => match web::channel::call(&WReq::Exec {
467                conn: *id,
468                sql: sql.to_string(),
469                params: web::to_wire(params),
470            })? {
471                WReply::Changes(n) => Ok(n),
472                other => Err(web::unexpected(other)),
473            },
474        }
475    }
476
477    fn query(
478        &mut self,
479        sql: &str,
480        params: &[Value],
481        row: &mut dyn FnMut(&dyn Row),
482    ) -> Result<(), DbError> {
483        use day_sqlite_worker::protocol::{Reply as WReply, Req as WReq};
484        match &self.conn {
485            WebConn::Memory(c) => c
486                .query(sql, &web::to_wire(params), &mut |r| {
487                    let vals: Vec<Value> = r.into_iter().map(web::from_wire).collect();
488                    row(&vals);
489                })
490                .map_err(|e| DbError::driver(format!("{e} in `{sql}`"))),
491            WebConn::Remote(id) => match web::channel::call(&WReq::Query {
492                conn: *id,
493                sql: sql.to_string(),
494                params: web::to_wire(params),
495            })? {
496                WReply::Rows(rows) => {
497                    for r in rows {
498                        let vals: Vec<Value> = r.into_iter().map(web::from_wire).collect();
499                        row(&vals);
500                    }
501                    Ok(())
502                }
503                other => Err(web::unexpected(other)),
504            },
505        }
506    }
507    fn query_named(
508        &mut self,
509        sql: &str,
510        params: &[Value],
511        row: &mut dyn FnMut(&[String], &dyn Row),
512    ) -> Result<(), DbError> {
513        use day_sqlite_worker::protocol::{Reply as WReply, Req as WReq};
514        match &self.conn {
515            WebConn::Memory(c) => c
516                .query_named(sql, &web::to_wire(params), &mut |names, r| {
517                    let vals: Vec<Value> = r.into_iter().map(web::from_wire).collect();
518                    row(names, &vals);
519                })
520                .map(|_| ())
521                .map_err(|e| DbError::driver(format!("{e} in `{sql}`"))),
522            WebConn::Remote(id) => match web::channel::call(&WReq::QueryNamed {
523                conn: *id,
524                sql: sql.to_owned(),
525                params: web::to_wire(params),
526            })? {
527                WReply::NamedRows { names, rows } => {
528                    for r in rows {
529                        let vals: Vec<Value> = r.into_iter().map(web::from_wire).collect();
530                        row(&names, &vals);
531                    }
532                    Ok(())
533                }
534                other => Err(web::unexpected(other)),
535            },
536        }
537    }
538}
539
540/// A dropped remote connection closes its worker side, best effort, like a file handle.
541#[cfg(all(target_family = "wasm", target_os = "unknown"))]
542impl Drop for RusqliteConn {
543    fn drop(&mut self) {
544        if let WebConn::Remote(id) = self.conn {
545            let _ = web::channel::call(&day_sqlite_worker::protocol::Req::Close { conn: id });
546        }
547    }
548}
549
550#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
551impl SqliteConnection for RusqliteConn {
552    fn execute(&mut self, sql: &str, params: &[Value]) -> Result<u64, DbError> {
553        // Cached, not re-prepared: the fold emits RUNS of identical SQL (one INSERT shape per
554        // table, one DELETE, one UPDATE per changed column set), so a bulk flush would
555        // otherwise re-parse the same statement thousands of times.
556        let mut stmt = self
557            .conn
558            .prepare_cached(sql)
559            .map_err(|e| DbError::driver(format!("{e} in `{sql}`")))?;
560        let bound = rusqlite::params_from_iter(params.iter().map(to_sql));
561        stmt.execute(bound)
562            .map(|n| n as u64)
563            .map_err(|e| DbError::driver(format!("{e} in `{sql}`")))
564    }
565
566    fn query(
567        &mut self,
568        sql: &str,
569        params: &[Value],
570        row: &mut dyn FnMut(&dyn Row),
571    ) -> Result<(), DbError> {
572        let mut stmt = self
573            .conn
574            .prepare_cached(sql)
575            .map_err(|e| DbError::driver(format!("{e} in `{sql}`")))?;
576        let bound = rusqlite::params_from_iter(params.iter().map(to_sql));
577        let mut rows = stmt
578            .query(bound)
579            .map_err(|e| DbError::driver(format!("{e} in `{sql}`")))?;
580        loop {
581            match rows.next() {
582                Ok(Some(r)) => {
583                    let n = r.as_ref().column_count();
584                    let vals: Vec<Value> = (0..n)
585                        .map(|i| r.get_ref(i).map(from_sql).unwrap_or(Value::Null))
586                        .collect();
587                    row(&vals);
588                }
589                Ok(None) => break,
590                Err(e) => return Err(DbError::driver(e.to_string())),
591            }
592        }
593        Ok(())
594    }
595
596    fn execute_batch(&mut self, sql: &str) -> Result<(), DbError> {
597        self.conn
598            .execute_batch(sql)
599            .map_err(|e| DbError::driver(format!("{e} in batch")))
600    }
601
602    fn query_named(
603        &mut self,
604        sql: &str,
605        params: &[Value],
606        row: &mut dyn FnMut(&[String], &dyn Row),
607    ) -> Result<(), DbError> {
608        let mut stmt = self
609            .conn
610            .prepare(sql)
611            .map_err(|e| DbError::driver(format!("{e} in `{sql}`")))?;
612        let names: Vec<String> = stmt.column_names().iter().map(|s| s.to_string()).collect();
613        let bound = rusqlite::params_from_iter(params.iter().map(to_sql));
614        let mut rows = stmt
615            .query(bound)
616            .map_err(|e| DbError::driver(format!("{e} in `{sql}`")))?;
617        loop {
618            match rows.next() {
619                Ok(Some(r)) => {
620                    let n = r.as_ref().column_count();
621                    let vals: Vec<Value> = (0..n)
622                        .map(|i| r.get_ref(i).map(from_sql).unwrap_or(Value::Null))
623                        .collect();
624                    row(&names, &vals);
625                }
626                Ok(None) => break,
627                Err(e) => return Err(DbError::driver(e.to_string())),
628            }
629        }
630        Ok(())
631    }
632}
633
634// ---------------------------------------------------------------------------
635// The web leg (wasm32-unknown-unknown): the synchronous channel to the day-sql worker.
636//
637// OPFS's only random-access synchronous API (`createSyncAccessHandle`) exists solely in
638// dedicated workers, so the engine runs in day-sqlite-worker's day-sql worker (the same wasm
639// module, instantiated there) and this side is a proxy. Each call encodes one request in
640// day-sqlite-worker's protocol, hands it to that crate's channel, and the main thread blocks
641// the few microseconds until the worker's reply lands back through the SharedArrayBuffer.
642// Fully synchronous from Rust's point of view, fully durable at commit, one code path with
643// every other platform. The channel needs cross-origin isolation (COOP/COEP; `day launch`
644// serves it, see docs/web.md); without it File opens fail loudly and capabilities say
645// durable: false.
646// ---------------------------------------------------------------------------
647
648#[cfg(all(target_family = "wasm", target_os = "unknown"))]
649mod web {
650    use super::*;
651    use day_sqlite_worker::protocol::{self, Reply as WReply, Req as WReq, Value as WValue};
652
653    pub(super) mod channel {
654        use super::*;
655
656        pub(crate) fn ready() -> bool {
657            day_sqlite_worker::channel::ready()
658        }
659
660        /// One round trip. Worker-reported SQL errors come back as [`DbError`]s here, so
661        /// callers only ever match the success variants.
662        pub(crate) fn call(req: &WReq) -> Result<WReply, DbError> {
663            let Some(reply) = day_sqlite_worker::channel::call(&protocol::encode_req(req)) else {
664                return Err(DbError::new(
665                    DbErrorKind::Unsupported,
666                    "no SQL worker — file databases on the web need the day-sql worker, \
667                     which needs cross-origin isolation (COOP/COEP headers; docs/web.md)",
668                ));
669            };
670            match protocol::decode_reply(&reply) {
671                Ok(WReply::Err(m)) => Err(DbError::driver(m)),
672                Ok(r) => Ok(r),
673                Err(_) => Err(DbError::driver("malformed reply from the SQL worker")),
674            }
675        }
676    }
677
678    pub(super) fn unexpected(r: WReply) -> DbError {
679        DbError::driver(format!("unexpected SQL worker reply: {r:?}"))
680    }
681
682    pub(super) fn to_wire(params: &[Value]) -> Vec<WValue> {
683        params
684            .iter()
685            .map(|v| match v {
686                Value::Null => WValue::Null,
687                Value::Int(i) => WValue::Int(*i),
688                Value::Real(r) => WValue::Real(*r),
689                Value::Text(t) => WValue::Text(t.clone()),
690                Value::Blob(b) => WValue::Blob(b.clone()),
691            })
692            .collect()
693    }
694
695    pub(super) fn from_wire(v: WValue) -> Value {
696        match v {
697            WValue::Null => Value::Null,
698            WValue::Int(i) => Value::Int(i),
699            WValue::Real(r) => Value::Real(r),
700            WValue::Text(t) => Value::Text(t),
701            WValue::Blob(b) => Value::Blob(b),
702        }
703    }
704
705    /// The origin's database pool: names in, bytes out, OPFS underneath. The document
706    /// surface a file-per-document app needs on the web: numbering a fresh drawing,
707    /// importing an Open… pick, exporting a download.
708    #[derive(Clone)]
709    pub struct WebStorage;
710
711    impl WebStorage {
712        pub fn exists(&self, name: &str) -> bool {
713            matches!(
714                channel::call(&WReq::Exists {
715                    name: name.to_string()
716                }),
717                Ok(WReply::Bool(true))
718            )
719        }
720
721        /// Every database name in the pool.
722        pub fn list(&self) -> Vec<String> {
723            match channel::call(&WReq::List) {
724                Ok(WReply::Names(names)) => names,
725                _ => Vec::new(),
726            }
727        }
728
729        /// The database's bytes: a plain SQLite file image, downloadable as a file. Flush
730        /// (`ModelContainer::save`) first for an image that includes this turn's edits.
731        pub fn export_db(&self, name: &str) -> Result<Vec<u8>, DbError> {
732            match channel::call(&WReq::Export {
733                name: name.to_string(),
734            })? {
735                WReply::Bytes(b) => Ok(b),
736                other => Err(unexpected(other)),
737            }
738        }
739
740        /// Write a SQLite file image under `name` (an Open… flow's landing). A connection
741        /// still open on that name is stale afterwards; close (drop) it before importing.
742        pub fn import_db(&self, name: &str, bytes: &[u8]) -> Result<(), DbError> {
743            match channel::call(&WReq::Import {
744                name: name.to_string(),
745                bytes: bytes.to_vec(),
746            })? {
747                WReply::Ok => Ok(()),
748                other => Err(unexpected(other)),
749            }
750        }
751
752        pub fn delete_db(&self, name: &str) {
753            let _ = channel::call(&WReq::Delete {
754                name: name.to_string(),
755            });
756        }
757    }
758
759    impl Sqlite {
760        /// The pool surface, when the worker channel is up.
761        pub fn web_storage() -> Result<WebStorage, DbError> {
762            if channel::ready() {
763                Ok(WebStorage)
764            } else {
765                Err(DbError::new(
766                    DbErrorKind::Unsupported,
767                    "no SQL worker — file databases on the web need cross-origin isolation \
768                     (COOP/COEP headers; docs/web.md)",
769                ))
770            }
771        }
772    }
773}
774
775#[cfg(all(target_family = "wasm", target_os = "unknown"))]
776pub use web::WebStorage;