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