Skip to main content

absurder_sql/
utils.rs

1use crate::types::DatabaseError;
2use wasm_bindgen::prelude::*;
3
4// Utility functions for the SQLite IndexedDB library
5
6// ============================================================================
7// DATABASE NAME NORMALIZATION - SINGLE SOURCE OF TRUTH
8// ============================================================================
9//
10// CRITICAL: All database name normalization MUST use this function.
11// This ensures GLOBAL_STORAGE keys, IndexedDB keys, VFS filenames, and
12// Database.name all use the same format.
13//
14// The canonical format is: "{name}.db" (always with .db suffix)
15//
16// Used by:
17// - Database::new() in lib.rs
18// - VFS xOpen in vfs/indexeddb_vfs.rs
19// - import_from_file, sync_internal, etc.
20//
21// DO NOT duplicate this logic elsewhere. If you need to normalize a db name,
22// use this function.
23// ============================================================================
24
25/// Normalize database name to canonical format with .db extension.
26///
27/// This is the SINGLE SOURCE OF TRUTH for database name normalization.
28/// All code that stores or retrieves data by database name MUST use this
29/// function to ensure consistency.
30///
31/// # Arguments
32/// * `name` - Raw database name (with or without .db extension)
33///
34/// # Returns
35/// Normalized name with .db extension (e.g., "mydb" -> "mydb.db")
36///
37/// # Example
38/// ```rust
39/// use absurder_sql::utils::normalize_db_name;
40///
41/// assert_eq!(normalize_db_name("mydb"), "mydb.db");
42/// assert_eq!(normalize_db_name("mydb.db"), "mydb.db");
43/// ```
44#[inline]
45pub fn normalize_db_name(name: &str) -> String {
46    if name.ends_with(".db") {
47        name.to_string()
48    } else {
49        format!("{}.db", name)
50    }
51}
52
53#[wasm_bindgen]
54extern "C" {
55    #[wasm_bindgen(js_namespace = console)]
56    fn log(s: &str);
57}
58
59/// Memory information for the current system
60#[derive(Debug, Clone)]
61pub struct MemoryInfo {
62    /// Available memory in bytes
63    pub available_bytes: u64,
64    /// Total system memory in bytes (if available)
65    pub total_bytes: Option<u64>,
66    /// Used memory in bytes (if available)
67    pub used_bytes: Option<u64>,
68}
69
70/// Log a message to the browser console
71pub fn console_log(message: &str) {
72    log(message);
73}
74
75/// Format bytes as a human-readable string
76pub fn format_bytes(bytes: usize) -> String {
77    const UNITS: &[&str] = &["B", "KB", "MB", "GB"];
78    const THRESHOLD: f64 = 1024.0;
79
80    if bytes == 0 {
81        return "0 B".to_string();
82    }
83
84    let mut size = bytes as f64;
85    let mut unit_index = 0;
86
87    while size >= THRESHOLD && unit_index < UNITS.len() - 1 {
88        size /= THRESHOLD;
89        unit_index += 1;
90    }
91
92    if unit_index == 0 {
93        format!("{} {}", bytes, UNITS[unit_index])
94    } else {
95        format!("{:.1} {}", size, UNITS[unit_index])
96    }
97}
98
99/// Generate a unique identifier
100pub fn generate_id() -> String {
101    let timestamp = js_sys::Date::now() as u64;
102    let random = (js_sys::Math::random() * 1000000.0) as u32;
103    format!("{}_{}", timestamp, random)
104}
105
106/// Validate SQL query for security
107pub fn validate_sql(sql: &str) -> Result<(), String> {
108    let sql_lower = sql.to_lowercase();
109
110    // Basic security checks
111    let dangerous_keywords = ["drop", "delete", "truncate", "alter"];
112
113    for keyword in dangerous_keywords {
114        if sql_lower.contains(keyword) {
115            return Err(format!(
116                "Potentially dangerous SQL keyword detected: {}",
117                keyword
118            ));
119        }
120    }
121
122    Ok(())
123}
124
125/// Check available memory on the current system
126///
127/// Returns memory information if available, None if memory info cannot be determined.
128///
129/// # Platform Support
130/// - **Native (Linux)**: Reads /proc/meminfo for available memory
131/// - **Native (macOS)**: Uses sysctl for memory statistics
132/// - **Native (Windows)**: Uses GlobalMemoryStatusEx
133/// - **WASM/Browser**: Uses Performance.memory API if available (Chrome/Edge)
134///
135/// # Returns
136/// - `Some(MemoryInfo)` with available and optionally total/used memory
137/// - `None` if memory information is unavailable
138///
139/// # Example
140/// ```rust
141/// use absurder_sql::utils::check_available_memory;
142///
143/// if let Some(mem_info) = check_available_memory() {
144///     println!("Available memory: {} bytes", mem_info.available_bytes);
145/// }
146/// ```
147pub fn check_available_memory() -> Option<MemoryInfo> {
148    #[cfg(target_arch = "wasm32")]
149    {
150        // WASM/Browser environment - try to use Performance.memory API
151        check_memory_wasm()
152    }
153
154    #[cfg(not(target_arch = "wasm32"))]
155    {
156        // Native environment - use platform-specific APIs
157        check_memory_native()
158    }
159}
160
161/// Check memory in WASM/browser environment
162#[cfg(target_arch = "wasm32")]
163fn check_memory_wasm() -> Option<MemoryInfo> {
164    // WASM/Browser environment - return conservative estimates
165    //
166    // WASM linear memory is limited to 4GB max, but browsers typically
167    // impose lower limits. We use 2GB as a safe conservative estimate
168    // for available memory to prevent OOM errors.
169    //
170    // Note: Performance.memory API is Chrome-only and non-standard,
171    // so we provide a conservative estimate instead.
172
173    let estimated_total: u64 = 2 * 1024 * 1024 * 1024; // 2GB total estimate
174    let estimated_available: u64 = 1536 * 1024 * 1024; // 1.5GB available estimate
175    let estimated_used: u64 = estimated_total - estimated_available;
176
177    log::debug!(
178        "WASM memory estimate (conservative): {} MB available, {} MB total",
179        estimated_available / (1024 * 1024),
180        estimated_total / (1024 * 1024)
181    );
182
183    Some(MemoryInfo {
184        available_bytes: estimated_available,
185        total_bytes: Some(estimated_total),
186        used_bytes: Some(estimated_used),
187    })
188}
189
190/// Check memory in native environment
191#[cfg(not(target_arch = "wasm32"))]
192fn check_memory_native() -> Option<MemoryInfo> {
193    #[cfg(target_os = "linux")]
194    {
195        check_memory_linux()
196    }
197
198    #[cfg(target_os = "macos")]
199    {
200        check_memory_macos()
201    }
202
203    #[cfg(target_os = "windows")]
204    {
205        check_memory_windows()
206    }
207
208    #[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
209    {
210        // Unsupported platform - return conservative estimate
211        None
212    }
213}
214
215/// Check memory on Linux by reading /proc/meminfo
216#[cfg(target_os = "linux")]
217fn check_memory_linux() -> Option<MemoryInfo> {
218    use std::fs;
219
220    let meminfo = fs::read_to_string("/proc/meminfo").ok()?;
221
222    let mut mem_available = None;
223    let mut mem_total = None;
224
225    for line in meminfo.lines() {
226        if line.starts_with("MemAvailable:") {
227            mem_available = line
228                .split_whitespace()
229                .nth(1)
230                .and_then(|s| s.parse::<u64>().ok())
231                .map(|kb| kb * 1024); // Convert KB to bytes
232        } else if line.starts_with("MemTotal:") {
233            mem_total = line
234                .split_whitespace()
235                .nth(1)
236                .and_then(|s| s.parse::<u64>().ok())
237                .map(|kb| kb * 1024); // Convert KB to bytes
238        }
239
240        if mem_available.is_some() && mem_total.is_some() {
241            break;
242        }
243    }
244
245    let available_bytes = mem_available?;
246    let total = mem_total;
247    let used = total.map(|t| t.saturating_sub(available_bytes));
248
249    Some(MemoryInfo {
250        available_bytes,
251        total_bytes: total,
252        used_bytes: used,
253    })
254}
255
256/// Check memory on macOS using sysctl
257#[cfg(target_os = "macos")]
258fn check_memory_macos() -> Option<MemoryInfo> {
259    use std::process::Command;
260
261    // Get total memory
262    let vm_stat_output = Command::new("vm_stat").output().ok()?;
263    let vm_stat_str = String::from_utf8_lossy(&vm_stat_output.stdout);
264
265    let mut page_size = 4096u64; // Default page size
266    let mut pages_free = 0u64;
267    let mut pages_inactive = 0u64;
268
269    for line in vm_stat_str.lines() {
270        if line.contains("page size of") {
271            if let Some(size_str) = line.split("page size of ").nth(1) {
272                if let Some(size) = size_str.split_whitespace().next() {
273                    page_size = size.parse().unwrap_or(4096);
274                }
275            }
276        } else if line.starts_with("Pages free:") {
277            pages_free = line
278                .split(':')
279                .nth(1)
280                .and_then(|s| s.trim().trim_end_matches('.').parse().ok())
281                .unwrap_or(0);
282        } else if line.starts_with("Pages inactive:") {
283            pages_inactive = line
284                .split(':')
285                .nth(1)
286                .and_then(|s| s.trim().trim_end_matches('.').parse().ok())
287                .unwrap_or(0);
288        }
289    }
290
291    let available_bytes = (pages_free + pages_inactive) * page_size;
292
293    // Get total memory
294    let total_output = Command::new("sysctl").arg("hw.memsize").output().ok()?;
295
296    let total_str = String::from_utf8_lossy(&total_output.stdout);
297    let total_bytes = total_str
298        .split(':')
299        .nth(1)
300        .and_then(|s| s.trim().parse().ok());
301
302    Some(MemoryInfo {
303        available_bytes,
304        total_bytes,
305        used_bytes: total_bytes.map(|t| t.saturating_sub(available_bytes)),
306    })
307}
308
309/// Check memory on Windows using GlobalMemoryStatusEx
310#[cfg(target_os = "windows")]
311fn check_memory_windows() -> Option<MemoryInfo> {
312    use std::mem;
313
314    #[repr(C)]
315    struct MemoryStatusEx {
316        dw_length: u32,
317        dw_memory_load: u32,
318        ull_total_phys: u64,
319        ull_avail_phys: u64,
320        ull_total_page_file: u64,
321        ull_avail_page_file: u64,
322        ull_total_virtual: u64,
323        ull_avail_virtual: u64,
324        ull_avail_extended_virtual: u64,
325    }
326
327    unsafe extern "system" {
328        unsafe fn GlobalMemoryStatusEx(lp_buffer: *mut MemoryStatusEx) -> i32;
329    }
330
331    unsafe {
332        let mut mem_status: MemoryStatusEx = mem::zeroed();
333        mem_status.dw_length = mem::size_of::<MemoryStatusEx>() as u32;
334
335        if GlobalMemoryStatusEx(&mut mem_status) == 0 {
336            return None;
337        }
338
339        let available_bytes = mem_status.ull_avail_phys;
340        let total_bytes = mem_status.ull_total_phys;
341        let used_bytes = total_bytes.saturating_sub(available_bytes);
342
343        Some(MemoryInfo {
344            available_bytes,
345            total_bytes: Some(total_bytes),
346            used_bytes: Some(used_bytes),
347        })
348    }
349}
350
351/// Estimate memory requirement for exporting a database
352///
353/// Calculates the estimated memory needed to export a database of given size.
354/// Includes overhead for:
355/// - Database content buffer
356/// - Intermediate block buffers
357/// - SQLite header and metadata
358/// - Safety margin
359///
360/// # Arguments
361/// * `database_size_bytes` - Size of the database to export
362///
363/// # Returns
364/// Estimated memory requirement in bytes (typically 1.5x-2x database size)
365///
366/// # Example
367/// ```rust
368/// use absurder_sql::utils::estimate_export_memory_requirement;
369///
370/// let db_size = 100 * 1024 * 1024; // 100MB
371/// let required_memory = estimate_export_memory_requirement(db_size);
372/// println!("Estimated memory needed: {} bytes", required_memory);
373/// ```
374pub fn estimate_export_memory_requirement(database_size_bytes: u64) -> u64 {
375    // Memory requirement breakdown:
376    // 1. Database content: database_size_bytes (1x)
377    // 2. Block read buffers: ~10-20MB for batch reads
378    // 3. Intermediate concatenation: ~database_size_bytes * 0.5 (worst case)
379    // 4. Safety margin: 20%
380
381    const BLOCK_BUFFER_SIZE: u64 = 20 * 1024 * 1024; // 20MB for block buffers
382    const OVERHEAD_MULTIPLIER: f64 = 1.5; // 50% overhead for intermediate buffers
383    const SAFETY_MARGIN: f64 = 1.2; // 20% safety margin
384
385    let base_requirement = database_size_bytes as f64 * OVERHEAD_MULTIPLIER;
386    let with_buffers = base_requirement + BLOCK_BUFFER_SIZE as f64;
387    let with_safety = with_buffers * SAFETY_MARGIN;
388
389    with_safety as u64
390}
391
392/// Validate that sufficient memory is available for export operation
393///
394/// Checks if the system has enough available memory to safely export
395/// a database of the given size. Returns an error if insufficient memory
396/// is available.
397///
398/// # Arguments
399/// * `database_size_bytes` - Size of the database to export
400///
401/// # Returns
402/// * `Ok(())` - Sufficient memory is available
403/// * `Err(DatabaseError)` - Insufficient memory or cannot determine availability
404///
405/// # Example
406/// ```rust
407/// use absurder_sql::utils::validate_memory_for_export;
408///
409/// let db_size = 100 * 1024 * 1024; // 100MB
410/// match validate_memory_for_export(db_size) {
411///     Ok(_) => println!("Sufficient memory available"),
412///     Err(e) => eprintln!("Memory check failed: {}", e.message),
413/// }
414/// ```
415pub fn validate_memory_for_export(database_size_bytes: u64) -> Result<(), DatabaseError> {
416    let required_memory = estimate_export_memory_requirement(database_size_bytes);
417
418    match check_available_memory() {
419        Some(mem_info) => {
420            if mem_info.available_bytes < required_memory {
421                let available_mb = mem_info.available_bytes as f64 / (1024.0 * 1024.0);
422                let required_mb = required_memory as f64 / (1024.0 * 1024.0);
423
424                return Err(DatabaseError::new(
425                    "INSUFFICIENT_MEMORY",
426                    &format!(
427                        "Insufficient memory for export. Available: {:.1} MB, Required: {:.1} MB. \
428                        Consider using streaming export with smaller chunk sizes or closing other applications.",
429                        available_mb, required_mb
430                    ),
431                ));
432            }
433
434            // Memory is sufficient
435            log::info!(
436                "Memory check passed: {} MB available, {} MB required for export",
437                mem_info.available_bytes / (1024 * 1024),
438                required_memory / (1024 * 1024)
439            );
440
441            Ok(())
442        }
443        None => {
444            // Cannot determine memory availability - log warning but allow operation
445            log::warn!(
446                "Cannot determine available memory. Proceeding with export of {} MB database. \
447                Monitor memory usage carefully.",
448                database_size_bytes / (1024 * 1024)
449            );
450
451            Ok(())
452        }
453    }
454}
455
456#[cfg(test)]
457mod tests {
458    use super::*;
459
460    #[test]
461    fn test_format_bytes() {
462        assert_eq!(format_bytes(0), "0 B");
463        assert_eq!(format_bytes(512), "512 B");
464        assert_eq!(format_bytes(1024), "1.0 KB");
465        assert_eq!(format_bytes(1536), "1.5 KB");
466        assert_eq!(format_bytes(1048576), "1.0 MB");
467    }
468
469    #[test]
470    fn test_validate_sql() {
471        assert!(validate_sql("SELECT * FROM users").is_ok());
472        assert!(validate_sql("INSERT INTO users (name) VALUES ('test')").is_ok());
473        assert!(validate_sql("DROP TABLE users").is_err());
474        assert!(validate_sql("DELETE FROM users WHERE id = 1").is_err());
475    }
476
477    #[test]
478    fn test_normalize_db_name() {
479        // Already has .db suffix - should be unchanged
480        assert_eq!(normalize_db_name("mydb.db"), "mydb.db");
481        assert_eq!(normalize_db_name("test.db"), "test.db");
482
483        // Missing .db suffix - should be added
484        assert_eq!(normalize_db_name("mydb"), "mydb.db");
485        assert_eq!(normalize_db_name("test"), "test.db");
486
487        // Edge cases
488        assert_eq!(normalize_db_name(""), ".db");
489        assert_eq!(normalize_db_name("a"), "a.db");
490        assert_eq!(normalize_db_name("my.database"), "my.database.db");
491
492        // Important: suffix must be exactly ".db", not just contain "db"
493        assert_eq!(normalize_db_name("mydb_backup"), "mydb_backup.db");
494        assert_eq!(normalize_db_name("testdb"), "testdb.db");
495    }
496
497    #[test]
498    fn test_normalize_db_name_idempotent() {
499        // Normalization should be idempotent - applying twice gives same result
500        let names = vec!["mydb", "test.db", "complex.name.db", "simple"];
501        for name in names {
502            let once = normalize_db_name(name);
503            let twice = normalize_db_name(&once);
504            assert_eq!(
505                once, twice,
506                "normalize_db_name should be idempotent for '{}'",
507                name
508            );
509        }
510    }
511}