Improve comments and build flags (#167)

Author: Spxg

.github/workflows/test.yml

@@ -116,14 +116,14 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v4
-    - name: Install wasm-pack
-      run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+    - uses: dtolnay/rust-toolchain@1.82.0
+      with:
+        targets: wasm32-unknown-unknown
+        components: rust-src
     - name: Test MSRV
       run: |
-        rustup toolchain install 1.82.0
-        rustup default 1.82.0
-        wasm-pack test --node
-        wasm-pack test --node --features sqlite3mc
+        cargo build --target wasm32-unknown-unknown
+        cargo build --features sqlite3mc --target wasm32-unknown-unknown
 
   test_nodejs:
     strategy:

build.rs

@@ -1,4 +1,5 @@
-const FULL_FEATURED: [&str; 24] = [
+// SQLite compile flags tuned for WASM: no threads/dlopen, keep common extensions.
+const FULL_FEATURED: [&str; 23] = [
     "-DSQLITE_OS_OTHER",
     "-DSQLITE_USE_URI",
     // SQLite is configured for a single-threaded environment, as WebAssembly is single-threaded by default.
@@ -13,7 +14,6 @@ const FULL_FEATURED: [&str; 24] = [
     "-DSQLITE_OMIT_SHARED_CACHE",
     "-DSQLITE_ENABLE_UNLOCK_NOTIFY",
     "-DSQLITE_ENABLE_API_ARMOR",
-    "-DSQLITE_ENABLE_MATH_FUNCTIONS",
     "-DSQLITE_ENABLE_BYTECODE_VTAB",
     "-DSQLITE_ENABLE_DBPAGE_VTAB",
     "-DSQLITE_ENABLE_DBSTAT_VTAB",
@@ -152,6 +152,7 @@ fn bindgen(output: &std::path::PathBuf) {
         // Block deprecated functions that are omitted from the build via the DSQLITE_OMIT_DEPRECATED flag.
         .blocklist_function("sqlite3_profile")
         .blocklist_function("sqlite3_trace")
+        // Exclude UTF-16 entrypoints to keep the WASM surface minimal.
         .blocklist_function(".*16.*")
         .blocklist_function("sqlite3_close_v2")
         .blocklist_function("sqlite3_create_collation")

crates/rsqlite-vfs/src/lib.rs

@@ -266,8 +266,7 @@ pub struct SQLiteVfsFile {
     pub vfs: *mut sqlite3_vfs,
     /// Flags used to open the database.
     pub flags: i32,
-    /// The pointer to the file name.
-    /// If it is a leaked static pointer, you need to drop it manually when xClose it.
+    /// The pointer to the file name (owned by the VFS, freed in xClose).
     pub name_ptr: *const u8,
     /// Length of the file name, on wasm32 platform, usize is u32.
     pub name_length: usize,
@@ -287,7 +286,7 @@ impl SQLiteVfsFile {
     ///
     /// # Safety
     ///
-    /// When xClose, you can free the memory by `drop(Box::from_raw(ptr));`.
+    /// The name is created from a UTF-8 Rust `String` and leaked for SQLite.
     ///
     /// Do not use again after free.
     pub unsafe fn name(&self) -> &'static mut str {
@@ -329,6 +328,7 @@ pub fn register_vfs<IO: SQLiteIoMethods, V: SQLiteVfs<IO>>(
     let name = CString::new(vfs_name).map_err(|_| RegisterVfsError::ToCStr)?;
     let name_ptr = name.into_raw();
 
+    // `name_ptr` and `app_data` are owned by SQLite until the VFS is unregistered.
     let app_data = VfsAppData::new(app_data).leak();
     let vfs = Box::leak(Box::new(V::vfs(name_ptr, app_data.cast())));
     let ret = unsafe { sqlite3_vfs_register(vfs, i32::from(default_vfs)) };
@@ -383,7 +383,7 @@ impl<T> VfsAppData<T> {
 
     /// # Safety
     ///
-    /// You have to make sure the pointer is correct
+    /// Takes ownership of a pointer returned by `leak`.
     pub unsafe fn from_raw(t: *mut Self) -> VfsAppData<T> {
         *Box::from_raw(t)
     }
@@ -836,6 +836,7 @@ pub trait SQLiteIoMethods {
         pFile: *mut sqlite3_file,
         eLock: ::core::ffi::c_int,
     ) -> ::core::ffi::c_int {
+        // No-op: in-memory/WASM VFS does not support file locking.
         unused!((pFile, eLock));
         SQLITE_OK
     }
@@ -844,6 +845,7 @@ pub trait SQLiteIoMethods {
         pFile: *mut sqlite3_file,
         eLock: ::core::ffi::c_int,
     ) -> ::core::ffi::c_int {
+        // No-op: in-memory/WASM VFS does not support file locking.
         unused!((pFile, eLock));
         SQLITE_OK
     }
@@ -888,19 +890,15 @@ pub enum ImportDbError {
 }
 
 /// Simple verification when importing db, and return page size;
+/// This only checks size/header; validate page size via `check_db_and_page_size`.
 pub fn check_import_db(bytes: &[u8]) -> Result<usize, ImportDbError> {
     let length = bytes.len();
 
     if length < 512 || length % 512 != 0 {
         return Err(ImportDbError::InvalidDbSize);
     }
 
-    if SQLITE3_HEADER
-        .as_bytes()
-        .iter()
-        .zip(bytes)
-        .any(|(x, y)| x != y)
-    {
+    if !bytes.starts_with(SQLITE3_HEADER.as_bytes()) {
         return Err(ImportDbError::InvalidHeader);
     }
 

crates/rsqlite-vfs/src/memvfs.rs

@@ -210,6 +210,7 @@ where
 {
     /// Get management tool
     pub fn new() -> Self {
+        // Registers memvfs globally if not already present.
         MemVfsUtil(unsafe { install::<C>() }, PhantomData)
     }
 }
@@ -235,6 +236,7 @@ where
             let mut file = MemFile::Main(MemChunksFile::new(page_size));
             file.write(bytes, 0).unwrap();
             if clear_wal {
+                // Force rollback journal mode by updating the header at offset 18.
                 file.write(&[1, 1], 18).unwrap();
             }
             file

crates/sqlite-wasm-vfs/src/relaxed_idb.rs

@@ -676,10 +676,10 @@ impl SQLiteIoMethods for RelaxedIdbIoMethods {
                 bail!(name.is_null());
                 bail!(value.is_null(), SQLITE_NOTFOUND);
 
-                let key = check_result!(CStr::from_ptr(name).to_str()).to_ascii_lowercase();
-                let value = check_result!(CStr::from_ptr(value).to_str()).to_ascii_lowercase();
+                let key = check_result!(CStr::from_ptr(name).to_str());
+                let value = check_result!(CStr::from_ptr(value).to_str());
 
-                if key == "page_size" {
+                if key.eq_ignore_ascii_case("page_size") {
                     let page_size = check_result!(value.parse::<usize>());
                     if page_size == file.block_size {
                         return SQLITE_OK;
@@ -691,7 +691,9 @@ impl SQLiteIoMethods for RelaxedIdbIoMethods {
                             "page_size cannot be changed".into(),
                         ));
                     }
-                } else if key == "synchronous" && value != "off" {
+                } else if key.eq_ignore_ascii_case("synchronous")
+                    && !value.eq_ignore_ascii_case("off")
+                {
                     return pool.store_err(VfsError::new(
                         SQLITE_ERROR,
                         "relaxed-idb vfs only supports synchronous=off".into(),

src/bindings/mod.rs

@@ -1,4 +1,4 @@
-//! This module is codegen from build.rs
+//! This module is codegen from build.rs. Avoid manual edits.
 
 #[cfg(all(not(feature = "bindgen"), feature = "sqlite3mc"))]
 mod sqlite3mc_bindgen;
@@ -31,17 +31,22 @@ pub fn SQLITE_STATIC() -> sqlite3_destructor_type {
 
 #[must_use]
 pub fn SQLITE_TRANSIENT() -> sqlite3_destructor_type {
-    Some(unsafe { mem::transmute::<isize, unsafe extern "C" fn(*mut core::ffi::c_void)>(-1_isize) })
+    // SQLite uses -1 as a sentinel for "make your own copy".
+    Some(unsafe {
+        mem::transmute::<isize, unsafe extern "C" fn(*mut core::ffi::c_void)>(-1_isize)
+    })
 }
 
 impl Default for sqlite3_vtab {
     fn default() -> Self {
+        // C expects zero-initialized vtab structs.
         unsafe { mem::zeroed() }
     }
 }
 
 impl Default for sqlite3_vtab_cursor {
     fn default() -> Self {
+        // C expects zero-initialized vtab cursor structs.
         unsafe { mem::zeroed() }
     }
 }

src/shim.rs

@@ -19,6 +19,7 @@ impl OsCallback for WasmOsCallback {
         while nanos > 0 {
             let amt = core::cmp::min(i64::MAX as u128, nanos);
             let mut x = 0;
+            // memory_atomic_wait32 returns 2 on timeout; loop until elapsed.
             let val = unsafe { core::arch::wasm32::memory_atomic_wait32(&mut x, 0, amt as i64) };
             debug_assert_eq!(val, 2);
             nanos -= amt;
@@ -30,6 +31,7 @@ impl OsCallback for WasmOsCallback {
 
     fn random(buf: &mut [u8]) {
         fn fallback(buf: &mut [u8]) {
+            // Non-cryptographic fallback when crypto.getRandomValues is unavailable.
             for b in buf {
                 *b = (Math::random() * 255000.0) as u32 as u8;
             }
@@ -92,6 +94,7 @@ fn yday_from_date(date: &Date) -> u32 {
 /// https://github.com/emscripten-core/emscripten/blob/df69e2ccc287beab6f580f33b33e6b5692f5d20b/system/lib/libc/emscripten_internal.h#L42
 ///
 /// https://github.com/sqlite/sqlite-wasm/blob/7c1b309c3bd07d8e6d92f82344108cebbd14f161/sqlite-wasm/jswasm/sqlite3-bundler-friendly.mjs#L3404
+// Mirrors emscripten/sqlite-wasm localtime handling, including DST logic.
 unsafe fn localtime_js(t: c_time_t, tm: *mut tm) {
     let date = Date::new(&Number::from((t * 1000) as f64).into());
 
@@ -105,15 +108,14 @@ unsafe fn localtime_js(t: c_time_t, tm: *mut tm) {
     (*tm).tm_yday = yday_from_date(&date) as _;
 
     let start = Date::new_with_year_month_day(date.get_full_year(), 0, 1);
+    let tz_offset = date.get_timezone_offset();
     let summer_offset =
         Date::new_with_year_month_day(date.get_full_year(), 6, 1).get_timezone_offset();
     let winter_offset = start.get_timezone_offset();
-    (*tm).tm_isdst = i32::from(
-        summer_offset != winter_offset
-            && date.get_timezone_offset() == winter_offset.min(summer_offset),
-    );
+    (*tm).tm_isdst =
+        i32::from(summer_offset != winter_offset && tz_offset == winter_offset.min(summer_offset));
 
-    (*tm).tm_gmtoff = -(date.get_timezone_offset() * 60.0) as _;
+    (*tm).tm_gmtoff = -(tz_offset * 60.0) as _;
 }
 
 /// https://github.com/emscripten-core/emscripten/blob/df69e2ccc287beab6f580f33b33e6b5692f5d20b/system/lib/libc/musl/include/time.h#L40
@@ -179,6 +181,7 @@ pub unsafe extern "C" fn rust_sqlite_wasm_abort() {
 /// See <https://github.com/emscripten-core/emscripten/blob/089590d17eeb705424bf32f8a1afe34a034b4682/system/lib/libc/mktime.c#L28>.
 #[no_mangle]
 pub unsafe extern "C" fn rust_sqlite_wasm_localtime(t: *const c_time_t) -> *mut tm {
+    // Single shared buffer, matches libc behavior; assumes no concurrent callers.
     static mut TM: tm = tm {
         tm_sec: 0,
         tm_min: 0,
@@ -207,13 +210,15 @@ pub unsafe extern "C" fn rust_sqlite_wasm_malloc(size: c_size_t) -> *mut c_void
     if ptr.is_null() {
         return ptr::null_mut();
     }
+    // Store size for free/realloc; pointer returned is offset by ALIGN.
     *ptr.cast::<usize>() = size;
 
     ptr.add(ALIGN).cast()
 }
 
 #[no_mangle]
 pub unsafe extern "C" fn rust_sqlite_wasm_free(ptr: *mut c_void) {
+    // Only accepts pointers allocated by rust_sqlite_wasm_malloc/realloc.
     let ptr: *mut u8 = ptr.sub(ALIGN).cast();
     let size = *(ptr.cast::<usize>());
 
@@ -226,6 +231,7 @@ pub unsafe extern "C" fn rust_sqlite_wasm_realloc(
     ptr: *mut c_void,
     new_size: c_size_t,
 ) -> *mut c_void {
+    // Only accepts pointers allocated by rust_sqlite_wasm_malloc/realloc.
     let ptr: *mut u8 = ptr.sub(ALIGN).cast();
     let size = *(ptr.cast::<usize>());
 

tests/tests/full/sqlite3mc.rs

@@ -7,7 +7,7 @@ use crate::full::{check_result, prepare_simple_db};
 
 unsafe fn set_cipher(cipher: &str, db: *mut sqlite3) {
     let set_cipher = format!("PRAGMA cipher = {cipher};");
-    let c_name = CString::new(set_cipher.clone()).unwrap();
+    let c_name = CString::new(set_cipher).unwrap();
     let ret = sqlite3_exec(
         db,
         c_name.as_ptr().cast(),
@@ -32,7 +32,7 @@ unsafe fn test_memvfs_cipher(cipher: &str) {
     let mut db = std::ptr::null_mut();
     let db_name = format!("test_memvfs_vfs_{cipher}.db");
 
-    let c_name = CString::new(db_name.clone()).unwrap();
+    let c_name = CString::new(db_name.as_str()).unwrap();
     let ret = sqlite3_open_v2(
         c_name.as_ptr().cast(),
         &mut db as *mut _,
@@ -55,7 +55,7 @@ unsafe fn test_memvfs_cipher(cipher: &str) {
     let db2 = util.export_db(&new_db_name).unwrap();
     assert_eq!(db1, db2);
 
-    let c_name = CString::new(db_name.clone()).unwrap();
+    let c_name = CString::new(db_name.as_str()).unwrap();
     let ret = sqlite3_open_v2(
         c_name.as_ptr().cast(),
         &mut db as *mut _,
@@ -85,7 +85,7 @@ async unsafe fn test_relaxed_idb_vfs_cipher(cipher: &str) {
     let mut db = std::ptr::null_mut();
     let db_name = format!("test_relaxed_db_vfs_{cipher}.db");
 
-    let c_name = CString::new(db_name.clone()).unwrap();
+    let c_name = CString::new(db_name.as_str()).unwrap();
     let ret = sqlite3_open_v2(
         c_name.as_ptr().cast(),
         &mut db as *mut _,
@@ -110,7 +110,7 @@ async unsafe fn test_relaxed_idb_vfs_cipher(cipher: &str) {
     assert_eq!(db1, db2);
 
     let mut db = std::ptr::null_mut();
-    let c_name = CString::new(new_db_name).unwrap();
+    let c_name = CString::new(new_db_name.as_str()).unwrap();
     let ret = sqlite3_open_v2(
         c_name.as_ptr().cast(),
         &mut db as *mut _,
@@ -141,7 +141,7 @@ async unsafe fn test_opfs_sah_vfs_cipher(cipher: &str) {
     let mut db = std::ptr::null_mut();
     let db_name = format!("test_opfs_sah_vfs_{cipher}.db");
 
-    let c_name = CString::new(db_name.clone()).unwrap();
+    let c_name = CString::new(db_name.as_str()).unwrap();
     let ret = sqlite3_open_v2(
         c_name.as_ptr().cast(),
         &mut db as *mut _,
@@ -163,7 +163,7 @@ async unsafe fn test_opfs_sah_vfs_cipher(cipher: &str) {
     assert_eq!(db1, db2);
 
     let mut db = std::ptr::null_mut();
-    let c_name = CString::new(new_db_name).unwrap();
+    let c_name = CString::new(new_db_name.as_str()).unwrap();
     let ret = sqlite3_open_v2(
         c_name.as_ptr().cast(),
         &mut db as *mut _,