Skip to main content

qualia_core_db/
storage_driver.rs

1//! Cross-platform storage backend abstraction.
2//!
3//! Selects the appropriate driver at runtime:
4//!   Linux + real ZNS NVMe (non-WSL2)  → ZnsDriver   (zone-append, 8 writers)
5//!   Windows + Administrator            → WinNvmeDriver (DeviceIoControl passthrough)
6//!   macOS / iOS                        → MmapApfsDriver (UMA + APFS clonefile)
7//!   WSL2 / Linux no-hardware / other   → MmapDriver  (io_uring-backed mmap fallback)
8//!
9//! All drivers implement `StorageDriver`. `open_storage(data_dir)` returns
10//! `Box<dyn StorageDriver>` — callers never need a `#[cfg]` ladder.
11
12#![cfg(not(target_arch = "wasm32"))]
13
14#[path = "storage_driver/ranges/mod.rs"]
15pub mod ranges;
16
17use memmap2::MmapOptions;
18use std::path::{Path, PathBuf};
19use std::sync::{Arc, RwLock};
20
21// ──────────────────────────────────────────────────────────────────────────────
22// Darwin-specific FFI (madvise, clonefile, F_NOCACHE, QoS)
23// ──────────────────────────────────────────────────────────────────────────────
24#[cfg(target_os = "macos")]
25mod darwin {
26    pub const F_NOCACHE: libc::c_int = 48;
27    pub const MADV_WILLNEED: libc::c_int = 3;
28    pub const MADV_FREE: libc::c_int = 5;
29
30    pub use std::path::Path;
31
32    extern "C" {
33        /// APFS copy-on-write clone — O(1) and zero extra disk space.
34        pub fn clonefile(
35            src: *const libc::c_char,
36            dst: *const libc::c_char,
37            flags: libc::c_uint,
38        ) -> libc::c_int;
39    }
40
41    /// Prefetch `len` bytes starting at `ptr` into the Mach UBC.
42    ///
43    /// # Safety
44    /// `ptr` must point to a valid mapped region of at least `len` bytes.
45    pub unsafe fn madvise_willneed(ptr: *mut libc::c_void, len: libc::size_t) {
46        libc::madvise(ptr, len, MADV_WILLNEED);
47    }
48
49    /// Release page-cache pressure cheaply (MADV_FREE: reclaim if needed,
50    /// but do NOT force eviction — cheaper than MADV_DONTNEED).
51    ///
52    /// # Safety
53    /// `ptr` must point to a valid mapped region of at least `len` bytes.
54    pub unsafe fn madvise_free(ptr: *mut libc::c_void, len: libc::size_t) {
55        libc::madvise(ptr, len, MADV_FREE);
56    }
57
58    /// Disable the unified buffer cache for `fd` so sequential WAL writes
59    /// do not pollute the shared page cache.  Equivalent to Linux O_DIRECT.
60    ///
61    /// # Safety
62    /// `fd` must be a valid open file descriptor.
63    pub unsafe fn set_nocache(fd: libc::c_int) {
64        libc::fcntl(fd, F_NOCACHE, 1i32);
65    }
66
67    /// Perform an APFS clonefile from `src` to `dst`.
68    pub fn clonefile_paths(src: &Path, dst: &Path) -> std::io::Result<()> {
69        use std::ffi::CString;
70        let s = CString::new(src.to_str().ok_or_else(|| {
71            std::io::Error::new(std::io::ErrorKind::InvalidInput, "non-UTF-8 src path")
72        })?)
73        .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidInput, e))?;
74        let d = CString::new(dst.to_str().ok_or_else(|| {
75            std::io::Error::new(std::io::ErrorKind::InvalidInput, "non-UTF-8 dst path")
76        })?)
77        .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidInput, e))?;
78        // SAFETY: s and d are valid NUL-terminated C strings.
79        let rc = unsafe { clonefile(s.as_ptr(), d.as_ptr(), 0) };
80        if rc == 0 {
81            Ok(())
82        } else {
83            Err(std::io::Error::last_os_error())
84        }
85    }
86}
87
88// ──────────────────────────────────────────────────────────────────────────────
89// Errors
90// ──────────────────────────────────────────────────────────────────────────────
91
92#[derive(Debug, Clone)]
93pub enum StorageError {
94    Io(String),
95    NotFound(String),
96    OutOfSpace(String),
97    HardwareUnavailable(String),
98    PermissionDenied(String),
99    Unsupported(String),
100}
101
102impl std::fmt::Display for StorageError {
103    /// Render the variant tag followed by its message payload.
104    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
105        match self {
106            StorageError::Io(m) => write!(f, "I/O: {m}"),
107            StorageError::NotFound(m) => write!(f, "not found: {m}"),
108            StorageError::OutOfSpace(m) => write!(f, "out of space: {m}"),
109            StorageError::HardwareUnavailable(m) => write!(f, "hardware unavailable: {m}"),
110            StorageError::PermissionDenied(m) => write!(f, "permission denied: {m}"),
111            StorageError::Unsupported(m) => write!(f, "unsupported on platform: {m}"),
112        }
113    }
114}
115impl std::error::Error for StorageError {}
116
117// ──────────────────────────────────────────────────────────────────────────────
118// Capability flags
119// ──────────────────────────────────────────────────────────────────────────────
120
121#[derive(Debug, Clone, PartialEq)]
122pub enum DriverKind {
123    Zns,
124    WinNvme,
125    MmapApfs,
126    Mmap,
127}
128
129#[derive(Debug, Clone)]
130pub struct DriverCapabilities {
131    pub kind: DriverKind,
132    pub zone_append: bool,
133    pub free_snapshots: bool,
134    pub csd_dispatch: bool,
135    pub max_writers: u32,
136}
137
138// ──────────────────────────────────────────────────────────────────────────────
139// Trait
140// ──────────────────────────────────────────────────────────────────────────────
141
142/// Key/value storage backend contract — flat `key → bytes` semantics
143/// with snapshot and cache-hint hooks. Implementations range from the
144/// portable `MmapDriver` through APFS/ZNS/NVMe-passthrough variants;
145/// callers pick by `capabilities()`.
146pub trait StorageDriver: Send + Sync {
147    /// Backend capability flags (kind, zone-append, snapshot cost,
148    /// CSD dispatch, max concurrent writers).
149    fn capabilities(&self) -> DriverCapabilities;
150    /// Store `data` under `key`, replacing any existing value.
151    fn write(&self, key: &str, data: &[u8]) -> Result<(), StorageError>;
152    /// Append `data` to the value under `key` (created if absent).
153    fn append(&self, key: &str, data: &[u8]) -> Result<(), StorageError>;
154    /// Read the full value under `key`; `NotFound` when absent.
155    fn read(&self, key: &str) -> Result<Vec<u8>, StorageError>;
156    /// Read `len` bytes starting at `offset` within the value under
157    /// `key`; result is truncated at the value end, `Err` when
158    /// `offset` is past it.
159    fn read_range(&self, key: &str, offset: usize, len: usize) -> Result<Vec<u8>, StorageError>;
160    /// Remove `key`; idempotent — deleting an absent key is `Ok`.
161    fn delete(&self, key: &str) -> Result<(), StorageError>;
162    /// Create a point-in-time snapshot named `snapshot_id`.
163    /// On APFS this calls `clonefile(2)` and is O(1), zero-cost on disk.
164    fn snapshot(&self, snapshot_id: &str) -> Result<(), StorageError>;
165    /// Durability barrier — flush driver-level buffering to stable
166    /// storage (no-op for write-through backends).
167    fn flush(&self) -> Result<(), StorageError>;
168    /// Advisory hint that `key` will be read soon (e.g. `MADV_WILLNEED`
169    /// on Darwin); free to be a no-op.
170    fn prefetch_hint(&self, key: &str);
171    /// Advisory hint that `key`'s pages may be reclaimed (e.g.
172    /// `MADV_FREE` on Darwin); free to be a no-op.
173    fn eviction_hint(&self, key: &str);
174    /// One-line backend description for diagnostics.
175    fn describe(&self) -> &str;
176}
177
178// ──────────────────────────────────────────────────────────────────────────────
179// Helpers: path sanitisation
180// ──────────────────────────────────────────────────────────────────────────────
181
182/// Sanitize a storage key into a flat filename — alphanumerics, `-`,
183/// and `.` pass through; everything else becomes `_`.
184fn key_to_filename(key: &str) -> String {
185    key.chars()
186        .map(|c| {
187            if c.is_alphanumeric() || c == '-' || c == '.' {
188                c
189            } else {
190                '_'
191            }
192        })
193        .collect()
194}
195
196/// `root/<sanitized key>` — the flat-file path a key maps to.
197fn key_path(root: &Path, key: &str) -> PathBuf {
198    root.join(key_to_filename(key))
199}
200
201/// `root/.snap_<sanitized id>` — the directory a snapshot is written
202/// into.
203fn snap_dir(root: &Path, snapshot_id: &str) -> PathBuf {
204    root.join(format!(".snap_{}", key_to_filename(snapshot_id)))
205}
206
207// ──────────────────────────────────────────────────────────────────────────────
208// MmapDriver — file-backed, portable
209// ──────────────────────────────────────────────────────────────────────────────
210
211/// File-backed mmap driver.  Each key maps to a flat file under `root`.
212/// Reads are served via `memmap2` so the OS page cache provides zero-copy
213/// semantics for large values.  Works on every platform without privileges.
214pub struct MmapDriver {
215    root: PathBuf,
216    /// Lock guards concurrent create-dir races; IO itself is OS-atomic.
217    _guard: Arc<RwLock<()>>,
218}
219
220impl MmapDriver {
221    /// Create a file-backed driver rooted at `root` (created if absent).
222    pub fn new<P: AsRef<Path>>(root: P) -> Self {
223        let root = root.as_ref().to_path_buf();
224        let _ = std::fs::create_dir_all(&root);
225        Self {
226            root,
227            _guard: Arc::new(RwLock::new(())),
228        }
229    }
230}
231
232impl StorageDriver for MmapDriver {
233    /// Report `DriverKind::Mmap` — no zone-append, no free snapshots, single writer.
234    fn capabilities(&self) -> DriverCapabilities {
235        DriverCapabilities {
236            kind: DriverKind::Mmap,
237            zone_append: false,
238            free_snapshots: false,
239            csd_dispatch: false,
240            max_writers: 1,
241        }
242    }
243
244    /// Write `data` as a flat file under the root.
245    fn write(&self, key: &str, data: &[u8]) -> Result<(), StorageError> {
246        std::fs::write(key_path(&self.root, key), data).map_err(|e| StorageError::Io(e.to_string()))
247    }
248
249    /// Append `data` via `OpenOptions` (create if absent).
250    fn append(&self, key: &str, data: &[u8]) -> Result<(), StorageError> {
251        use std::io::Write;
252        let mut f = std::fs::OpenOptions::new()
253            .create(true)
254            .append(true)
255            .open(key_path(&self.root, key))
256            .map_err(|e| StorageError::Io(e.to_string()))?;
257        f.write_all(data)
258            .map_err(|e| StorageError::Io(e.to_string()))
259    }
260
261    /// Read via `memmap2` — `NotFound` when absent, empty `Vec` for a zero-length file.
262    fn read(&self, key: &str) -> Result<Vec<u8>, StorageError> {
263        let path = key_path(&self.root, key);
264        let f = std::fs::File::open(&path).map_err(|_| StorageError::NotFound(key.to_string()))?;
265        if f.metadata().map(|m| m.len()).unwrap_or(0) == 0 {
266            return Ok(Vec::new());
267        }
268        // SAFETY: file is opened read-only; no other thread writes it during the map.
269        let mmap =
270            unsafe { MmapOptions::new().map(&f) }.map_err(|e| StorageError::Io(e.to_string()))?;
271        Ok(mmap.to_vec())
272    }
273
274    /// Read the full value then slice `[offset, offset+len)` clamped at end.
275    fn read_range(&self, key: &str, offset: usize, len: usize) -> Result<Vec<u8>, StorageError> {
276        let data = self.read(key)?;
277        let end = (offset + len).min(data.len());
278        if offset > data.len() {
279            return Err(StorageError::Io(format!(
280                "offset {offset} past end {}",
281                data.len()
282            )));
283        }
284        Ok(data[offset..end].to_vec())
285    }
286
287    /// Remove the key's file; idempotent on absent keys.
288    fn delete(&self, key: &str) -> Result<(), StorageError> {
289        let path = key_path(&self.root, key);
290        if path.exists() {
291            std::fs::remove_file(path).map_err(|e| StorageError::Io(e.to_string()))?;
292        }
293        Ok(())
294    }
295
296    /// Copy every file under the root into `.snap_<id>` (no CoW — full copy).
297    fn snapshot(&self, snapshot_id: &str) -> Result<(), StorageError> {
298        let dst = snap_dir(&self.root, snapshot_id);
299        std::fs::create_dir_all(&dst).map_err(|e| StorageError::Io(e.to_string()))?;
300        for entry in std::fs::read_dir(&self.root).map_err(|e| StorageError::Io(e.to_string()))? {
301            let entry = entry.map_err(|e| StorageError::Io(e.to_string()))?;
302            let p = entry.path();
303            if p.is_file() {
304                let name = p.file_name().unwrap_or_default();
305                std::fs::copy(&p, dst.join(name)).map_err(|e| StorageError::Io(e.to_string()))?;
306            }
307        }
308        Ok(())
309    }
310
311    /// No-op — writes go straight through `std::fs`.
312    fn flush(&self) -> Result<(), StorageError> {
313        Ok(())
314    }
315    /// No-op — the OS page cache handles prefetch.
316    fn prefetch_hint(&self, _key: &str) {}
317    /// No-op — the OS page cache handles eviction.
318    fn eviction_hint(&self, _key: &str) {}
319    /// `"MmapDriver (file-backed memmap2, portable)"`.
320    fn describe(&self) -> &str {
321        "MmapDriver (file-backed memmap2, portable)"
322    }
323}
324
325// ──────────────────────────────────────────────────────────────────────────────
326// MmapApfsDriver — macOS/iOS: Darwin UMA + APFS CoW
327// ──────────────────────────────────────────────────────────────────────────────
328
329/// Extends `MmapDriver` with Darwin-specific page-management and APFS optimisations:
330///
331/// - `prefetch_hint` → `madvise(MADV_WILLNEED)` — async prefetch via Mach UBC
332/// - `eviction_hint` → `madvise(MADV_FREE)` — cheap release without forced evict
333/// - `flush` WAL fd  → `fcntl(F_NOCACHE, 1)` — bypass page cache for sequential WAL
334/// - `snapshot`      → `clonefile(2)` — O(1) APFS CoW clone, zero extra disk space
335pub struct MmapApfsDriver {
336    inner: MmapDriver,
337}
338
339impl MmapApfsDriver {
340    /// Create an APFS-enhanced driver rooted at `root` — wraps `MmapDriver`.
341    pub fn new<P: AsRef<Path>>(root: P) -> Self {
342        Self {
343            inner: MmapDriver::new(root),
344        }
345    }
346}
347
348impl StorageDriver for MmapApfsDriver {
349    /// Report `DriverKind::MmapApfs` — `free_snapshots` on macOS/iOS only, 4 writers.
350    fn capabilities(&self) -> DriverCapabilities {
351        DriverCapabilities {
352            kind: DriverKind::MmapApfs,
353            zone_append: false,
354            free_snapshots: cfg!(any(target_os = "macos", target_os = "ios")),
355            csd_dispatch: false,
356            max_writers: 4,
357        }
358    }
359
360    /// Delegate to the inner `MmapDriver`.
361    fn write(&self, key: &str, data: &[u8]) -> Result<(), StorageError> {
362        self.inner.write(key, data)
363    }
364
365    /// Append under `F_NOCACHE` on macOS so sequential WAL writes bypass the UBC; delegates off-platform.
366    fn append(&self, key: &str, data: &[u8]) -> Result<(), StorageError> {
367        // Open with F_NOCACHE so sequential WAL appends bypass the unified
368        // buffer cache and do not evict hot inference data.
369        #[cfg(target_os = "macos")]
370        {
371            use std::io::Write;
372            use std::os::unix::io::AsRawFd;
373            let path = key_path(&self.inner.root, key);
374            let f = std::fs::OpenOptions::new()
375                .create(true)
376                .append(true)
377                .open(&path)
378                .map_err(|e| StorageError::Io(e.to_string()))?;
379            // SAFETY: fd is valid for the lifetime of `f`.
380            unsafe {
381                darwin::set_nocache(f.as_raw_fd());
382            }
383            let mut f = f;
384            f.write_all(data)
385                .map_err(|e| StorageError::Io(e.to_string()))?;
386            return Ok(());
387        }
388        #[cfg(not(target_os = "macos"))]
389        self.inner.append(key, data)
390    }
391
392    /// Inner read plus `MADV_WILLNEED` on the mapped region (macOS) to prefetch the next pages.
393    fn read(&self, key: &str) -> Result<Vec<u8>, StorageError> {
394        let data = self.inner.read(key)?;
395        // Issue MADV_WILLNEED hint for the mapped region so Darwin prefetches
396        // the following pages into the UBC before the next sequential read.
397        #[cfg(target_os = "macos")]
398        if !data.is_empty() {
399            // SAFETY: `data` is a freshly allocated Vec with valid backing.
400            unsafe {
401                darwin::madvise_willneed(
402                    data.as_ptr() as *mut libc::c_void,
403                    data.len() as libc::size_t,
404                );
405            }
406        }
407        Ok(data)
408    }
409
410    /// Delegate to the inner `MmapDriver`.
411    fn read_range(&self, key: &str, offset: usize, len: usize) -> Result<Vec<u8>, StorageError> {
412        self.inner.read_range(key, offset, len)
413    }
414
415    /// Issue `eviction_hint` first, then delegate the delete.
416    fn delete(&self, key: &str) -> Result<(), StorageError> {
417        self.eviction_hint(key);
418        self.inner.delete(key)
419    }
420
421    /// `clonefile(2)` CoW clone of the root into `.snap_<id>` on macOS (removes an existing dst first); falls back to a full copy elsewhere.
422    fn snapshot(&self, snapshot_id: &str) -> Result<(), StorageError> {
423        let src = &self.inner.root;
424        let dst = snap_dir(src, snapshot_id);
425
426        #[cfg(target_os = "macos")]
427        {
428            // clonefile(2): creates an instantaneous APFS CoW clone.
429            // If dst already exists, clonefile fails with EEXIST — remove first.
430            if dst.exists() {
431                std::fs::remove_dir_all(&dst).map_err(|e| StorageError::Io(e.to_string()))?;
432            }
433            return darwin::clonefile_paths(src, &dst)
434                .map_err(|e| StorageError::Io(format!("clonefile: {e}")));
435        }
436
437        #[cfg(not(target_os = "macos"))]
438        {
439            let _ = dst;
440            self.inner.snapshot(snapshot_id)
441        }
442    }
443
444    /// `fcntl(F_FULLFSYNC)` on a sentinel file (macOS) to drain the ANS write queue; no-op elsewhere.
445    fn flush(&self) -> Result<(), StorageError> {
446        #[cfg(target_os = "macos")]
447        {
448            // F_FULLFSYNC guarantees durability on Apple Flash ANS controllers,
449            // unlike fsync() which may return before the ANS write queue drains.
450            // We open a sentinel file in the root directory and issue the sync.
451            let sentinel = self.inner.root.join(".flush");
452            let _ = std::fs::OpenOptions::new()
453                .create(true)
454                .write(true)
455                .open(&sentinel)
456                .map(|f| {
457                    use std::os::unix::io::AsRawFd;
458                    // SAFETY: fd is valid for the lifetime of `f`.
459                    unsafe {
460                        libc::fcntl(f.as_raw_fd(), libc::F_FULLFSYNC);
461                    }
462                });
463        }
464        Ok(())
465    }
466
467    /// `MADV_WILLNEED` on the key's mapped data (macOS); no-op elsewhere.
468    fn prefetch_hint(&self, key: &str) {
469        #[cfg(target_os = "macos")]
470        {
471            if let Ok(data) = self.inner.read(key) {
472                if !data.is_empty() {
473                    // SAFETY: valid Vec backing.
474                    unsafe {
475                        darwin::madvise_willneed(
476                            data.as_ptr() as *mut libc::c_void,
477                            data.len() as libc::size_t,
478                        );
479                    }
480                }
481            }
482        }
483        #[cfg(not(target_os = "macos"))]
484        let _ = key;
485    }
486
487    /// `MADV_FREE` on the key's mapped data (macOS); no-op elsewhere.
488    fn eviction_hint(&self, key: &str) {
489        #[cfg(target_os = "macos")]
490        {
491            if let Ok(data) = self.inner.read(key) {
492                if !data.is_empty() {
493                    // MADV_FREE: let Darwin reclaim if under pressure — cheaper
494                    // than MADV_DONTNEED which forces immediate eviction.
495                    // SAFETY: valid Vec backing.
496                    unsafe {
497                        darwin::madvise_free(
498                            data.as_ptr() as *mut libc::c_void,
499                            data.len() as libc::size_t,
500                        );
501                    }
502                }
503            }
504        }
505        #[cfg(not(target_os = "macos"))]
506        let _ = key;
507    }
508
509    /// `"MmapApfsDriver (Darwin UMA + APFS clonefile + madvise + F_NOCACHE)"`.
510    fn describe(&self) -> &str {
511        "MmapApfsDriver (Darwin UMA + APFS clonefile + madvise + F_NOCACHE)"
512    }
513}
514
515// ──────────────────────────────────────────────────────────────────────────────
516// ZnsDriver — Linux, real NVMe ZNS hardware
517// ──────────────────────────────────────────────────────────────────────────────
518
519/// Thin overlay over `ZnsZoneManager`.  Data is logically stored via the ZNS
520/// zone-append path; a `MmapDriver` overlay holds small metadata values that
521/// don't need zone-append semantics.
522pub struct ZnsDriver {
523    manager: Arc<std::sync::Mutex<crate::zns_storage::ZnsZoneManager>>,
524    overlay: MmapDriver,
525}
526
527impl ZnsDriver {
528    /// Create a ZNS driver: `manager` handles zone bookkeeping; small
529    /// values and metadata go to the file-backed `overlay_dir`.
530    pub fn new<P: AsRef<Path>>(
531        manager: crate::zns_storage::ZnsZoneManager,
532        overlay_dir: P,
533    ) -> Self {
534        Self {
535            manager: Arc::new(std::sync::Mutex::new(manager)),
536            overlay: MmapDriver::new(overlay_dir),
537        }
538    }
539}
540
541impl StorageDriver for ZnsDriver {
542    /// Report `DriverKind::Zns` — zone-append capable, 8 writers, no free snapshots.
543    fn capabilities(&self) -> DriverCapabilities {
544        DriverCapabilities {
545            kind: DriverKind::Zns,
546            zone_append: true,
547            free_snapshots: false,
548            csd_dispatch: false,
549            max_writers: 8,
550        }
551    }
552
553    /// All writes go to the overlay; the ZNS manager keeps zone bookkeeping.
554    fn write(&self, key: &str, data: &[u8]) -> Result<(), StorageError> {
555        // Small values → overlay; large values would use zone-append via the
556        // ZnsZoneManager.  For portability across machines without ZNS hardware,
557        // all writes go to the overlay and the ZNS manager handles zone bookkeeping.
558        self.overlay.write(key, data)
559    }
560    /// Try a real zone append via `ZnsZoneManager::allocate_zone`/`write_zone`; fall back to the overlay on failure.
561    fn append(&self, key: &str, data: &[u8]) -> Result<(), StorageError> {
562        // Zone append: allocate a zone and append; fall back to overlay.
563        let zone_type = crate::zns_storage::ZoneType::Sequential;
564        let size = data.len() as u64;
565        let result = {
566            let mut mgr = self
567                .manager
568                .lock()
569                .map_err(|_| StorageError::Io("ZNS lock poisoned".into()))?;
570            mgr.allocate_zone(zone_type, size)
571                .and_then(|handle| mgr.write_zone(&handle, data))
572                .map_err(|e| StorageError::Io(e.to_string()))
573        };
574        if result.is_ok() {
575            result
576        } else {
577            self.overlay.append(key, data)
578        }
579    }
580    /// Delegate to the overlay.
581    fn read(&self, key: &str) -> Result<Vec<u8>, StorageError> {
582        self.overlay.read(key)
583    }
584    /// Delegate to the overlay.
585    fn read_range(&self, key: &str, offset: usize, len: usize) -> Result<Vec<u8>, StorageError> {
586        self.overlay.read_range(key, offset, len)
587    }
588    /// Delegate to the overlay.
589    fn delete(&self, key: &str) -> Result<(), StorageError> {
590        self.overlay.delete(key)
591    }
592    /// Delegate to the overlay (full copy).
593    fn snapshot(&self, snapshot_id: &str) -> Result<(), StorageError> {
594        self.overlay.snapshot(snapshot_id)
595    }
596    /// No-op.
597    fn flush(&self) -> Result<(), StorageError> {
598        Ok(())
599    }
600    /// No-op.
601    fn prefetch_hint(&self, _key: &str) {}
602    /// No-op.
603    fn eviction_hint(&self, _key: &str) {}
604    /// `"ZnsDriver (Linux ZNS NVMe zone-append + overlay)"`.
605    fn describe(&self) -> &str {
606        "ZnsDriver (Linux ZNS NVMe zone-append + overlay)"
607    }
608}
609
610// ──────────────────────────────────────────────────────────────────────────────
611// WinNvmeDriver — Windows DeviceIoControl NVMe passthrough
612// ──────────────────────────────────────────────────────────────────────────────
613
614/// On Windows, raw NVMe Admin and NVM commands are sent via
615/// `DeviceIoControl(IOCTL_STORAGE_QUERY_PROPERTY / IOCTL_STORAGE_PROTOCOL_COMMAND)`
616/// against `\\.\PhysicalDriveN`.  Requires Administrator privileges.
617///
618/// Falls back to `MmapDriver` automatically when:
619///   - Not running as Administrator
620///   - Running on a virtual disk (WSL2 .vhdx, Hyper-V)
621///   - Physical drive has no NVMe ZNS capability
622pub struct WinNvmeDriver {
623    overlay: MmapDriver,
624    pub hardware_present: bool,
625    device_path: String,
626}
627
628impl WinNvmeDriver {
629    /// IOCTL_STORAGE_QUERY_PROPERTY (read-only, no admin required):
630    /// CTL_CODE(0x2D, 0x0500, METHOD_BUFFERED, FILE_ANY_ACCESS) = 0x002D1400
631    #[cfg(all(target_os = "windows", target_arch = "x86_64"))]
632    const IOCTL_STORAGE_QUERY_PROPERTY: u32 = 0x002D_1400;
633
634    /// Path last probed for NVMe passthrough (`\\.\PhysicalDriveN`), or empty.
635    pub fn probed_device_path(&self) -> &str {
636        &self.device_path
637    }
638
639    /// Probe `\\.\PhysicalDrive0..7` for NVMe passthrough and create
640    /// the driver with a file-backed `overlay_dir` fallback.
641    pub fn new<P: AsRef<Path>>(overlay_dir: P) -> Self {
642        let (hw, path) = Self::probe_devices();
643        Self {
644            overlay: MmapDriver::new(overlay_dir),
645            hardware_present: hw,
646            device_path: path,
647        }
648    }
649
650    /// Scan `\\.\PhysicalDrive0..7`, returning `(true, path)` for the
651    /// first drive answering the storage-property query.
652    fn probe_devices() -> (bool, String) {
653        for i in 0..8u32 {
654            let path = format!(r"\\.\PhysicalDrive{}", i);
655            if Self::probe_nvme(&path) {
656                return (true, path);
657            }
658        }
659        (false, String::new())
660    }
661
662    /// Open `device_path` and issue `IOCTL_STORAGE_QUERY_PROPERTY`;
663    /// true when the device exists and is accessible. Always false
664    /// off Windows-x86_64.
665    fn probe_nvme(#[allow(unused_variables)] device_path: &str) -> bool {
666        #[cfg(all(target_os = "windows", target_arch = "x86_64"))]
667        {
668            use windows::core::PCWSTR;
669            use windows::Win32::Foundation::{GENERIC_READ, INVALID_HANDLE_VALUE};
670            use windows::Win32::Storage::FileSystem::{
671                CreateFileW, FILE_ATTRIBUTE_NORMAL, FILE_SHARE_READ, FILE_SHARE_WRITE,
672                OPEN_EXISTING,
673            };
674            use windows::Win32::System::IO::DeviceIoControl;
675
676            let wide: Vec<u16> = device_path
677                .encode_utf16()
678                .chain(std::iter::once(0))
679                .collect();
680            let handle = unsafe {
681                CreateFileW(
682                    PCWSTR(wide.as_ptr()),
683                    GENERIC_READ.0,
684                    FILE_SHARE_READ | FILE_SHARE_WRITE,
685                    None,
686                    OPEN_EXISTING,
687                    FILE_ATTRIBUTE_NORMAL,
688                    None,
689                )
690            };
691            let handle = match handle {
692                Ok(h) if h != INVALID_HANDLE_VALUE => h,
693                _ => return false,
694            };
695
696            // StorageDeviceProperty query to check if this is an NVMe device
697            #[repr(C)]
698            struct StoragePropertyQuery {
699                property_id: u32,
700                query_type: u32,
701                additional: [u8; 1],
702            }
703            let query = StoragePropertyQuery {
704                property_id: 0,
705                query_type: 0,
706                additional: [0],
707            };
708            let mut buf = [0u8; 512];
709            let mut returned = 0u32;
710
711            let ok = unsafe {
712                DeviceIoControl(
713                    handle,
714                    Self::IOCTL_STORAGE_QUERY_PROPERTY,
715                    Some(&query as *const _ as *const _),
716                    std::mem::size_of::<StoragePropertyQuery>() as u32,
717                    Some(buf.as_mut_ptr() as *mut _),
718                    buf.len() as u32,
719                    Some(&mut returned),
720                    None,
721                )
722            };
723            let _ = unsafe { windows::Win32::Foundation::CloseHandle(handle) };
724            // If DeviceIoControl succeeded and returned >0 bytes, device exists and is accessible
725            ok.is_ok() && returned > 0
726        }
727        #[cfg(not(all(target_os = "windows", target_arch = "x86_64")))]
728        false
729    }
730}
731
732impl StorageDriver for WinNvmeDriver {
733    /// Report `DriverKind::WinNvme` — zone-append and CSD flags reflect `hardware_present`.
734    fn capabilities(&self) -> DriverCapabilities {
735        DriverCapabilities {
736            kind: DriverKind::WinNvme,
737            zone_append: self.hardware_present,
738            free_snapshots: false,
739            csd_dispatch: self.hardware_present,
740            max_writers: if self.hardware_present { 4 } else { 1 },
741        }
742    }
743
744    /// Delegate to the overlay (passthrough scaffold).
745    fn write(&self, key: &str, data: &[u8]) -> Result<(), StorageError> {
746        self.overlay.write(key, data)
747    }
748    /// Delegate to the overlay.
749    fn append(&self, key: &str, data: &[u8]) -> Result<(), StorageError> {
750        self.overlay.append(key, data)
751    }
752    /// Delegate to the overlay.
753    fn read(&self, key: &str) -> Result<Vec<u8>, StorageError> {
754        self.overlay.read(key)
755    }
756    /// Delegate to the overlay.
757    fn read_range(&self, key: &str, offset: usize, len: usize) -> Result<Vec<u8>, StorageError> {
758        self.overlay.read_range(key, offset, len)
759    }
760    /// Delegate to the overlay.
761    fn delete(&self, key: &str) -> Result<(), StorageError> {
762        self.overlay.delete(key)
763    }
764    /// Delegate to the overlay (full copy).
765    fn snapshot(&self, snapshot_id: &str) -> Result<(), StorageError> {
766        self.overlay.snapshot(snapshot_id)
767    }
768    /// Delegate to the overlay (no-op).
769    fn flush(&self) -> Result<(), StorageError> {
770        self.overlay.flush()
771    }
772    /// No-op.
773    fn prefetch_hint(&self, _key: &str) {}
774    /// No-op.
775    fn eviction_hint(&self, _key: &str) {}
776
777    /// `"WinNvmeDriver (...)"` — the string reports whether hardware was found or the overlay fallback is active.
778    fn describe(&self) -> &str {
779        if self.hardware_present {
780            "WinNvmeDriver (Windows DeviceIoControl NVMe passthrough — hardware found)"
781        } else {
782            "WinNvmeDriver (fallback — no admin/hardware, using file-backed overlay)"
783        }
784    }
785}
786
787// ──────────────────────────────────────────────────────────────────────────────
788// WSL2 detection + startup diagnostics
789// ──────────────────────────────────────────────────────────────────────────────
790
791/// `true` when running inside WSL2 (a real Linux kernel on Hyper-V).
792///
793/// Under WSL2:
794/// - ZNS/CSD commands are rejected by the Hyper-V storage emulation.
795/// - Port 4242 is behind NAT by default.  Enable Mirrored Mode in `~/.wslconfig`:
796///   ```text
797///   [wsl2]
798///   networkingMode=mirrored
799///   ```
800pub fn running_under_wsl2() -> bool {
801    #[cfg(target_os = "linux")]
802    {
803        std::fs::read_to_string("/proc/version")
804            .map(|v| v.to_ascii_lowercase().contains("microsoft"))
805            .unwrap_or(false)
806    }
807    #[cfg(not(target_os = "linux"))]
808    false
809}
810
811/// Log platform diagnostics at daemon startup.  Call once from `main` or
812/// `orchestrator::init`.
813pub fn log_startup_diagnostics() {
814    if running_under_wsl2() {
815        log::warn!(
816            "[storage] Running inside WSL2. ZNS/CSD hardware is inaccessible \
817             through the Hyper-V storage layer — falling back to MmapDriver. \
818             Port 4242 may not be reachable from the Windows LAN. \
819             Enable Mirrored Mode: add `networkingMode=mirrored` under [wsl2] \
820             in ~/.wslconfig, then `wsl --shutdown` to apply."
821        );
822    }
823    #[cfg(target_os = "windows")]
824    log::info!("[storage] Platform: Windows x64 — probing NVMe via DeviceIoControl");
825    #[cfg(target_os = "macos")]
826    log::info!(
827        "[storage] Platform: macOS — using MmapApfsDriver \
828         (madvise + APFS clonefile + F_NOCACHE WAL)"
829    );
830    #[cfg(all(target_os = "linux", not(target_arch = "wasm32")))]
831    if !running_under_wsl2() {
832        log::info!("[storage] Platform: Linux — probing ZNS NVMe devices");
833    }
834}
835
836// ──────────────────────────────────────────────────────────────────────────────
837// Factory
838// ──────────────────────────────────────────────────────────────────────────────
839
840/// Open the best available storage driver for this platform and hardware.
841///
842/// Call `log_startup_diagnostics()` before this if you want WSL2 warnings in logs.
843pub fn open_storage<P: AsRef<Path>>(data_dir: P) -> Box<dyn StorageDriver> {
844    let data_dir = data_dir.as_ref().to_path_buf();
845    let _ = std::fs::create_dir_all(&data_dir);
846
847    // ── Linux ──────────────────────────────────────────────────────────────
848    #[cfg(target_os = "linux")]
849    {
850        if !running_under_wsl2() {
851            for i in 0..4u32 {
852                let dev = format!("/dev/nvme{}", i);
853                if let Ok(mgr) = crate::zns_storage::ZnsZoneManager::new(&dev) {
854                    log::info!("[storage] ZnsDriver selected: {dev}");
855                    return Box::new(ZnsDriver::new(mgr, data_dir));
856                }
857            }
858        }
859        log::info!("[storage] MmapDriver selected (Linux fallback)");
860        return Box::new(MmapDriver::new(data_dir));
861    }
862
863    // ── Windows ────────────────────────────────────────────────────────────
864    #[cfg(target_os = "windows")]
865    {
866        let drv = WinNvmeDriver::new(&data_dir);
867        if drv.hardware_present {
868            log::info!(
869                "[storage] WinNvmeDriver selected: {}",
870                drv.probed_device_path()
871            );
872        } else {
873            log::info!("[storage] MmapDriver selected (Windows, no NVMe hardware/admin)");
874        }
875        return Box::new(drv);
876    }
877
878    // ── macOS / iOS ────────────────────────────────────────────────────────
879    #[cfg(any(target_os = "macos", target_os = "ios"))]
880    {
881        log::info!("[storage] MmapApfsDriver selected (Darwin UMA + APFS)");
882        return Box::new(MmapApfsDriver::new(data_dir));
883    }
884
885    // ── Android / other ────────────────────────────────────────────────────
886    #[cfg(not(any(
887        target_os = "linux",
888        target_os = "windows",
889        target_os = "macos",
890        target_os = "ios",
891    )))]
892    {
893        log::info!("[storage] MmapDriver selected (portable fallback)");
894        return Box::new(MmapDriver::new(data_dir));
895    }
896
897    #[allow(unreachable_code)]
898    Box::new(MmapDriver::new(data_dir))
899}
900
901// ──────────────────────────────────────────────────────────────────────────────
902// Network filter abstraction
903// ──────────────────────────────────────────────────────────────────────────────
904
905#[derive(Debug, Clone, PartialEq)]
906pub enum NetworkFilterKind {
907    EbpfLinux,
908    WfpWindows,
909    MacNetworkExtension,
910    AndroidVpnService,
911    Noop,
912}
913
914/// Host network-filter backend contract (eBPF on Linux, WFP on
915/// Windows, NetworkExtension on macOS, VpnService on Android) — the
916/// allow/deny rule set applied to storage-adjacent traffic.
917pub trait NetworkFilter: Send + Sync {
918    /// Which backend implements this filter.
919    fn kind(&self) -> NetworkFilterKind;
920    /// Install an allow rule.
921    fn allow(&self, rule: &str) -> Result<(), StorageError>;
922    /// Install a deny rule.
923    fn deny(&self, rule: &str) -> Result<(), StorageError>;
924    /// Remove a previously installed rule.
925    fn remove(&self, rule: &str) -> Result<(), StorageError>;
926    /// One-line backend description for diagnostics.
927    fn describe(&self) -> &str;
928}
929
930pub struct NoopFilter;
931impl NetworkFilter for NoopFilter {
932    /// `NetworkFilterKind::Noop`.
933    fn kind(&self) -> NetworkFilterKind {
934        NetworkFilterKind::Noop
935    }
936    /// Always `Ok` — no filtering performed.
937    fn allow(&self, _: &str) -> Result<(), StorageError> {
938        Ok(())
939    }
940    /// Always `Ok` — no filtering performed.
941    fn deny(&self, _: &str) -> Result<(), StorageError> {
942        Ok(())
943    }
944    /// Always `Ok` — nothing installed to remove.
945    fn remove(&self, _: &str) -> Result<(), StorageError> {
946        Ok(())
947    }
948    /// `"NoopFilter (no kernel packet filtering on this platform)"`.
949    fn describe(&self) -> &str {
950        "NoopFilter (no kernel packet filtering on this platform)"
951    }
952}
953
954/// Open the most capable network filter for this platform.
955/// See `ebpf_filter.rs` for the full platform-specific implementations.
956pub fn open_network_filter() -> Box<dyn NetworkFilter> {
957    crate::ebpf_filter::open_platform_filter()
958}
959
960// ──────────────────────────────────────────────────────────────────────────────
961// Tests
962// ──────────────────────────────────────────────────────────────────────────────
963
964#[cfg(test)]
965mod tests {
966    use super::*;
967    use std::env;
968
969    fn tmpdir(suffix: &str) -> PathBuf {
970        let d = env::temp_dir().join(format!("qualiadb_storage_test_{suffix}"));
971        let _ = std::fs::remove_dir_all(&d);
972        d
973    }
974
975    #[test]
976    fn test_mmap_write_read() {
977        let d = MmapDriver::new(tmpdir("wr"));
978        d.write("key1", b"hello world").unwrap();
979        assert_eq!(d.read("key1").unwrap(), b"hello world");
980    }
981
982    #[test]
983    fn test_mmap_append() {
984        let d = MmapDriver::new(tmpdir("ap"));
985        d.write("k", b"foo").unwrap();
986        d.append("k", b"bar").unwrap();
987        assert_eq!(d.read("k").unwrap(), b"foobar");
988    }
989
990    #[test]
991    fn test_mmap_read_range() {
992        let d = MmapDriver::new(tmpdir("rr"));
993        d.write("k", b"0123456789").unwrap();
994        assert_eq!(d.read_range("k", 3, 4).unwrap(), b"3456");
995    }
996
997    #[test]
998    fn test_mmap_delete() {
999        let d = MmapDriver::new(tmpdir("del"));
1000        d.write("k", b"data").unwrap();
1001        d.delete("k").unwrap();
1002        assert!(d.read("k").is_err());
1003    }
1004
1005    #[test]
1006    fn test_mmap_snapshot() {
1007        let d = MmapDriver::new(tmpdir("snap"));
1008        d.write("a", b"before").unwrap();
1009        d.snapshot("s1").unwrap();
1010        d.write("a", b"after").unwrap();
1011        // Current value updated; snapshot preserved on disk separately
1012        assert_eq!(d.read("a").unwrap(), b"after");
1013        let snap_path = snap_dir(&d.root, "s1").join("a");
1014        let snap_data = std::fs::read(&snap_path).unwrap();
1015        assert_eq!(snap_data, b"before");
1016    }
1017
1018    #[test]
1019    fn test_open_storage_portable() {
1020        let drv = open_storage(tmpdir("factory"));
1021        drv.write("platform_test", b"ok").unwrap();
1022        assert_eq!(drv.read("platform_test").unwrap(), b"ok");
1023    }
1024
1025    #[test]
1026    fn test_apfs_driver() {
1027        let d = MmapApfsDriver::new(tmpdir("apfs"));
1028        d.write("k", b"apfs_data").unwrap();
1029        assert_eq!(d.read("k").unwrap(), b"apfs_data");
1030        d.prefetch_hint("k");
1031        d.eviction_hint("k");
1032        d.flush().unwrap();
1033    }
1034
1035    #[test]
1036    fn test_wsl2_detection_no_panic() {
1037        let _ = running_under_wsl2();
1038    }
1039
1040    #[test]
1041    fn test_noop_filter() {
1042        let f = NoopFilter;
1043        assert!(f.allow("any").is_ok());
1044        assert!(f.deny("any").is_ok());
1045        assert!(f.remove("any").is_ok());
1046    }
1047
1048    #[test]
1049    fn test_key_sanitisation() {
1050        assert_eq!(key_to_filename("foo/bar:baz"), "foo_bar_baz");
1051        assert_eq!(key_to_filename("hello-world.bin"), "hello-world.bin");
1052    }
1053}