SMB: Route file ops through smb2 via SmbVolume

Very exciting! And it works!

- Add `SmbVolume` implementing `Volume` trait, backed by direct smb2 protocol I/O
- "Sneaky mount": OS mount stays for Finder/Terminal compat, Cmdr ops use smb2 (~4x faster)
- `Mutex<Option<(SmbClient, Tree)>>` with `Handle::block_on` bridging (MtpVolume pattern)
- `ConnectionState` (Direct/OsMount/Disconnected) with atomic lock-free reads
- `local_path()` returns `None` so copy strategy uses smb2 streaming, not OS mount
- Add `on_unmount()` to `Volume` trait for cleanup on external eject
- Add `register_if_absent()` to `VolumeManager` to prevent watcher overwriting SmbVolume
- Watcher calls `on_unmount()` before unregistering, uses `register_if_absent` for mounts
- Mount command establishes parallel smb2 session, registers `SmbVolume` (best-effort)
- 25 unit tests for type mappings, error classification, state machine, path conversion

Author: vdavid

apps/desktop/src-tauri/src/commands/network.rs

@@ -264,23 +264,100 @@ use crate::network::mount::{self, MountError, MountResult};
 /// provided, they are used for authentication. If the share is already mounted,
 /// returns the existing mount path without re-mounting.
 ///
+/// After a successful OS mount, also establishes a direct smb2 connection and
+/// registers the share as an `SmbVolume` in the `VolumeManager`. This means
+/// Cmdr's own file operations go through smb2 (fast), while Finder/Terminal
+/// use the OS mount (compatible). If smb2 connection fails, the volume falls
+/// through to a regular `LocalPosixVolume` (registered by the watcher).
+///
 /// # Arguments
 /// * `server` - Server hostname or IP address
 /// * `share` - Name of the share to mount
 /// * `username` - Optional username for authentication
 /// * `password` - Optional password for authentication
+/// * `port` - SMB port (default 445)
 /// * `timeout_ms` - Optional timeout in milliseconds (default: 20000)
 ///
 /// # Returns
 /// * `Ok(MountResult)` - Mount successful, with path to mount point
 /// * `Err(MountError)` - Mount failed with specific error type
 #[tauri::command]
+#[allow(
+    clippy::too_many_arguments,
+    reason = "Tauri command requires all parameters to be top-level"
+)]
 pub async fn mount_network_share(
     server: String,
     share: String,
     username: Option<String>,
     password: Option<String>,
+    port: Option<u16>,
     timeout_ms: Option<u64>,
 ) -> Result<MountResult, MountError> {
-    mount::mount_share(server, share, username, password, timeout_ms).await
+    let result = mount::mount_share(
+        server.clone(),
+        share.clone(),
+        username.clone(),
+        password.clone(),
+        timeout_ms,
+    )
+    .await?;
+
+    // Try to establish a direct smb2 connection and register as SmbVolume.
+    // If this fails, the FSEvents watcher will register a LocalPosixVolume
+    // as fallback (slower but still functional).
+    register_smb_volume(
+        &server,
+        &share,
+        &result.mount_path,
+        username.as_deref(),
+        password.as_deref(),
+        port.unwrap_or(445),
+    )
+    .await;
+
+    Ok(result)
+}
+
+/// Tries to establish a direct smb2 connection and register as `SmbVolume`.
+///
+/// Best-effort: logs a warning and returns quietly on failure. The FSEvents
+/// watcher will register a `LocalPosixVolume` as fallback.
+async fn register_smb_volume(
+    server: &str,
+    share: &str,
+    mount_path: &str,
+    username: Option<&str>,
+    password: Option<&str>,
+    port: u16,
+) {
+    use crate::file_system::get_volume_manager;
+    use crate::file_system::volume::smb::connect_smb_volume;
+    use std::sync::Arc;
+
+    log::debug!(
+        "Establishing smb2 connection for SmbVolume: {}:{}/{}",
+        server,
+        port,
+        share
+    );
+
+    match connect_smb_volume(share, mount_path, server, share, username, password, port).await {
+        Ok(volume) => {
+            let volume_id = crate::volumes::path_to_id(mount_path);
+            // Use register (overwrite) so SmbVolume always wins over any
+            // LocalPosixVolume the watcher may have registered in the race window.
+            get_volume_manager().register(&volume_id, Arc::new(volume));
+            log::info!("Registered SmbVolume for {} (id={})", mount_path, volume_id);
+        }
+        Err(e) => {
+            log::warn!(
+                "Failed to establish smb2 connection for {}/{}: {}. \
+                 Falling back to LocalPosixVolume via OS mount.",
+                server,
+                share,
+                e
+            );
+        }
+    }
 }

apps/desktop/src-tauri/src/file_system/mod.rs

@@ -36,6 +36,9 @@ pub use listing::get_paths_at_indices;
 #[cfg(any(target_os = "macos", target_os = "linux"))]
 #[allow(unused_imports, reason = "Public API re-exports for future use")]
 pub use volume::MtpVolume;
+#[cfg(any(target_os = "macos", target_os = "linux"))]
+#[allow(unused_imports, reason = "Public API re-exports for future use")]
+pub use volume::SmbVolume;
 #[allow(unused_imports, reason = "Public API re-exports for future use")]
 pub use volume::manager::VolumeManager;
 #[allow(unused_imports, reason = "Public API re-exports for future use")]

apps/desktop/src-tauri/src/file_system/volume/CLAUDE.md

@@ -14,6 +14,7 @@ Every file system operation (listing, copy, rename, delete, indexing, watching)
 | `manager.rs` | `VolumeManager` — thread-safe `RwLock<HashMap>` registry; supports a default volume |
 | `local_posix.rs` | `LocalPosixVolume` — real filesystem; delegates listing to `file_system::listing`, indexing to `indexing::scanner`, watching to `indexing::watcher` (FSEvents), copy scanning via `walkdir`. Uses `libc::statvfs` FFI for space info. |
 | `mtp.rs` | `MtpVolume` — MTP device storage; synchronous `Volume` trait bridged to async MTP calls via `tokio::runtime::Handle::block_on`. Gated with `#[cfg(any(target_os = "macos", target_os = "linux"))]`. |
+| `smb.rs` | `SmbVolume` — SMB share storage; synchronous `Volume` trait bridged to async smb2 calls via `Handle::block_on`. Uses `Mutex<Option<(SmbClient, Tree)>>` + `AtomicU8` connection state. Gated with `#[cfg(any(target_os = "macos", target_os = "linux"))]`. |
 | `in_memory.rs` | `InMemoryVolume` — `RwLock<HashMap>` store for tests; also used for stress tests (`with_file_count`) |
 
 ## Architecture
@@ -23,6 +24,7 @@ VolumeManager (registry)
   └─ Arc<dyn Volume>
         ├─ LocalPosixVolume   → real FS, FSEvents watcher, jwalk scanner
         ├─ MtpVolume          → async MTP ops via block_on (spawn_blocking context)
+        ├─ SmbVolume          → async smb2 ops via block_on (direct protocol, not OS mount)
         └─ InMemoryVolume     → HashMap, test/stress use only
 ```
 
@@ -35,7 +37,8 @@ Optional methods default to `Err(VolumeError::NotSupported)` or `false`, so new
 - `supports_watching()` — enables the `notify`-based *listing* file watcher in `operations.rs` (separate from the `VolumeWatcher` trait used for drive indexing). `MtpVolume` returns `false` (it has its own USB event loop).
 - `supports_export()` — enables copy/move UI. Both local and MTP return `true`.
 - `supports_streaming()` — enables chunked MTP-to-MTP transfers. Only `MtpVolume` returns `true`.
-- `local_path()` — returns `Some` only for local volumes; allows `copyfile(2)` fast-path in copy operations.
+- `local_path()` — returns `Some` only for local volumes; allows `copyfile(2)` fast-path in copy operations. `SmbVolume` returns `None` so copies go through smb2 instead of the slow OS mount.
+- `on_unmount()` — lifecycle hook called before unregistration. `SmbVolume` uses it to disconnect its smb2 session. Default is no-op.
 - `scanner()` / `watcher()` — drive indexing hooks; `None` by default.
 
 ## Path handling gotchas
@@ -63,6 +66,9 @@ Optional methods default to `Err(VolumeError::NotSupported)` or `false`, so new
 **Decision**: `VolumeManager` uses `RwLock<HashMap>` (not `DashMap` or `Mutex`)
 **Why**: Volume registration/unregistration is rare (mount/unmount events); reads are frequent (every file operation resolves a volume). `RwLock` gives concurrent read access without pulling in an extra dependency. `DashMap` would work but is heavier than needed for a registry that rarely exceeds ~10 entries.
 
+**Decision**: `VolumeManager::register_if_absent` for watcher registrations
+**Why**: When the mount flow pre-registers an `SmbVolume`, the FSEvents watcher would overwrite it with a `LocalPosixVolume` via `register`. `register_if_absent` is a no-op if a volume is already registered, preserving the `SmbVolume`. The existing `register` (overwrite) is kept for explicit replacement (like SmbVolume replacing itself on reconnect).
+
 **Decision**: `MtpVolume` bridges sync `Volume` trait to async MTP calls via `Handle::block_on`
 **Why**: The `Volume` trait is synchronous because local filesystem ops are blocking and shouldn't touch the async executor. MTP operations are inherently async (USB bulk transfers), so `block_on` bridges the gap. This is safe because MTP methods are always called from `spawn_blocking` contexts (separate OS thread pool), avoiding nested-runtime panics.
 
@@ -83,10 +89,20 @@ Optional methods default to `Err(VolumeError::NotSupported)` or `false`, so new
 **Gotcha**: `MtpVolume::get_metadata` returns `NotSupported`
 **Why**: MTP has no single-file stat call — you must list the parent directory and search for the entry by name. The listing pipeline doesn't use `get_metadata` during normal browsing (it gets metadata from `list_directory` results), so implementing it would add an expensive round-trip for a code path that's currently unused.
 
+**Decision**: `SmbVolume` uses `Mutex<Option<(SmbClient, Tree)>>`, not `RwLock`
+**Why**: Every `SmbClient` method takes `&mut self` — there is no read-only access path. An `RwLock` where you only ever take write locks is strictly worse than a `Mutex` (higher overhead). The `Option` allows graceful cleanup on disconnect (set to `None`).
+
+**Decision**: `SmbVolume::local_path()` returns `None`
+**Why**: `local_path()` is checked in `volume_copy.rs` to decide whether to use native OS copy APIs. If SmbVolume returned `Some(mount_path)`, copies would go through the slow OS mount — exactly what we're trying to avoid. `root()` still returns the mount path for frontend path resolution.
+
+**Decision**: `on_unmount()` trait method instead of `Any` downcasting
+**Why**: Avoids runtime type checking, extensible for future volume types (S3, FTP might also need cleanup), consistent with the trait's design of optional methods with default no-ops.
+
 ## Testing
 
 - `in_memory_test.rs` — unit tests for `InMemoryVolume` (CRUD, sorting, concurrency, stress 50k entries)
 - `inmemory_test.rs` — integration tests combining `InMemoryVolume` + `VolumeManager`, streaming state, sort helpers
 - `local_posix_test.rs` — real-FS tests (write ops, symlinks, copy, space info) using `std::env::temp_dir()`
 - `manager.rs` inline tests — concurrent registration/read/write-mix scenarios
 - `mtp.rs` inline tests — path conversion and capability flags (no device needed)
+- `smb.rs` inline tests — type mapping (DirectoryEntry→FileEntry, FsInfo→SpaceInfo, Error→VolumeError), connection state transitions, path conversion, capability flags (no server needed)

apps/desktop/src-tauri/src/file_system/volume/manager.rs

@@ -33,6 +33,25 @@ impl VolumeManager {
         }
     }
 
+    /// Registers a volume only if no volume with this ID exists yet.
+    ///
+    /// Returns `true` if the volume was registered, `false` if a volume
+    /// with this ID already exists (the existing volume is kept).
+    pub fn register_if_absent(&self, id: &str, volume: Arc<dyn Volume>) -> bool {
+        if let Ok(mut volumes) = self.volumes.write() {
+            use std::collections::hash_map::Entry;
+            match volumes.entry(id.to_string()) {
+                Entry::Occupied(_) => false,
+                Entry::Vacant(e) => {
+                    e.insert(volume);
+                    true
+                }
+            }
+        } else {
+            false
+        }
+    }
+
     /// Unregisters a volume by ID.
     ///
     /// If this was the default volume, the default is cleared.
@@ -185,6 +204,29 @@ mod tests {
         assert!(list.iter().any(|(id, name)| id == "vol2" && name == "Volume Two"));
     }
 
+    #[test]
+    fn test_register_if_absent_new_volume() {
+        let manager = VolumeManager::new();
+        let volume = Arc::new(InMemoryVolume::new("Test Volume"));
+
+        assert!(manager.register_if_absent("test", volume));
+        assert_eq!(manager.count(), 1);
+        assert_eq!(manager.get("test").unwrap().name(), "Test Volume");
+    }
+
+    #[test]
+    fn test_register_if_absent_existing_volume_keeps_original() {
+        let manager = VolumeManager::new();
+        let original = Arc::new(InMemoryVolume::new("Original"));
+        let replacement = Arc::new(InMemoryVolume::new("Replacement"));
+
+        manager.register("test", original);
+        assert!(!manager.register_if_absent("test", replacement));
+
+        // Original should be kept
+        assert_eq!(manager.get("test").unwrap().name(), "Original");
+    }
+
     #[test]
     fn test_multiple_volumes() {
         let manager = VolumeManager::new();

apps/desktop/src-tauri/src/file_system/volume/mod.rs

@@ -250,6 +250,16 @@ pub trait Volume: Send + Sync {
         Err(VolumeError::NotSupported)
     }
 
+    // ========================================
+    // Lifecycle: Optional, default no-op
+    // ========================================
+
+    /// Called when the volume is about to be unmounted/unregistered.
+    ///
+    /// Implementations can use this to clean up resources (disconnect network
+    /// sessions, cancel background tasks, etc.). Default is a no-op.
+    fn on_unmount(&self) {}
+
     // ========================================
     // Watching: Optional, default no-op
     // ========================================
@@ -370,11 +380,15 @@ mod local_posix;
 pub(crate) mod manager;
 #[cfg(any(target_os = "macos", target_os = "linux"))]
 mod mtp;
+#[cfg(any(target_os = "macos", target_os = "linux"))]
+pub(crate) mod smb;
 
 pub use in_memory::InMemoryVolume;
 pub use local_posix::LocalPosixVolume;
 #[cfg(any(target_os = "macos", target_os = "linux"))]
 pub use mtp::MtpVolume;
+#[cfg(any(target_os = "macos", target_os = "linux"))]
+pub use smb::SmbVolume;
 
 // Re-export types defined in this module for convenience
 // (they're already public since defined in mod.rs)