Add Docker DFS tests, fix 3 bugs, update docs

Docker: two Samba containers (smb-dfs-root:10456 with msdfs link,
smb-dfs-target:10457 with actual files). 4 integration tests.

Bugs fixed during Docker testing:
- IOCTL InputOffset double-counted Header::SIZE (STATUS_INVALID_PARAMETER)
- DFS paths missing server\share prefix (Tree::format_path)
- Cross-server routing matched hostname-only instead of addr:port

New: ClientConfig.dfs_target_overrides for Docker/non-standard ports.

Docs: README moves DFS to "What it does". AGENTS.md, tests/CLAUDE.md,
msg/CLAUDE.md, client/CLAUDE.md all updated.

Author: vdavid

AGENTS.md

@@ -52,6 +52,7 @@ src/
     cancel.rs             # CancelRequest
     oplock_break.rs       # OplockBreakNotification/Acknowledgment
     transform.rs          # TransformHeader (encryption), CompressionTransformHeader
+    dfs.rs                # DFS referral request/response wire format
 
   transport/              # Transport abstraction
     mod.rs                # Transport trait (split send/receive)
@@ -81,6 +82,7 @@ src/
     pipeline.rs           # Unified operation pipeline
     directory.rs          # Directory listing helpers
     shares.rs             # Share enumeration (IPC$ + srvsvc RPC)
+    dfs.rs                # DFS referral IOCTL, DfsResolver with TTL cache
 
 tests/
   pack_roundtrip.rs       # Property-based tests for pack/unpack
@@ -205,7 +207,7 @@ See `tests/CLAUDE.md` for the full testing guide. Quick reference:
 
 ### Docker test containers
 
-12 Samba containers in `tests/docker/internal/`, exercising the full protocol stack:
+13 Samba containers in `tests/docker/internal/`, exercising the full protocol stack:
 
 | Container             | Port  | What it tests                                 |
 |-----------------------|-------|-----------------------------------------------|
@@ -220,6 +222,8 @@ See `tests/CLAUDE.md` for the full testing guide. Quick reference:
 | smb-50shares          | 10453 | 50 shares, RPC enumeration at scale           |
 | smb-maxreadsize       | 10454 | 64 KB max read/write, chunking edge cases     |
 | smb-encryption-aes128 | 10455 | Mandatory encryption (AES-128-CCM, SMB 3.0.2) |
+| smb-dfs-root          | 10456 | DFS namespace root with msdfs link            |
+| smb-dfs-target        | 10457 | DFS target server with actual files            |
 
 ### Tested hardware
 

README.md

@@ -33,15 +33,14 @@ slow because it sends one read at a time. Native OS SMB clients pipeline their r
 - Streaming downloads and uploads with progress reporting and cancellation
 - File watching (CHANGE_NOTIFY for live directory updates)
 - Disk space queries (total, free, used)
+- DFS path resolution (standalone DFS with transparent referral follow-through)
 - Reconnection after network failures
 - Auto-flush on writes (data safety for family photos and company docs)
 
 ## What it doesn't do (yet)
 
 If you need any of these, check the [`smb`](https://crates.io/crates/smb) crate which supports them:
 
-- **DFS path resolution**: returns `Error::DfsReferralRequired` with the path so you can handle it yourself. Full
-  automatic DFS follow-through is planned for post-1.0.
 - **Multi-channel**: multiple TCP connections to the same server for higher throughput. Planned for post-1.0.
 - **QUIC transport**: SMB over QUIC for Azure Files and Windows Server 2022+ over the internet
 - **RDMA transport**: datacenter-only, ultra-low-latency storage
@@ -183,7 +182,7 @@ Add to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-smb2 = "0.1"
+smb2 = "0.2"
 ```
 
 You'll also need an async runtime. The library is runtime-agnostic, but [tokio](https://github.com/tokio-rs/tokio) is
@@ -286,7 +285,8 @@ The benchmark tool is included at `benchmarks/smb/`. Run with `cargo run -p smb-
 | Limitation            | Details                                                           |
 |-----------------------|-------------------------------------------------------------------|
 | No credential cache   | Kerberos tickets are fetched fresh each connection (no ccache)    |
-| No DFS follow-through | Returns `Error::DfsReferralRequired` with the path, you handle it |
+| No domain-based DFS   | Standalone DFS links work; AD domain-based DFS namespaces are not supported |
+| No DFS target failback | Uses the first reachable target; no automatic failback to preferred targets |
 | No multi-channel      | Single TCP connection per client                                  |
 | No QUIC/RDMA          | TCP only (covers ~99% of use cases)                               |
 | SMB1 not supported    | SMB2/3 only (SMB1 is deprecated and insecure)                     |
@@ -297,7 +297,7 @@ The benchmark tool is included at `benchmarks/smb/`. Run with `cargo run -p smb-
 ### vs `smb` crate
 
 The [`smb`](https://crates.io/crates/smb) crate is the most complete Rust SMB2 option right now. It covers more features
-than `smb2` (DFS, multi-channel, QUIC, RDMA). If you need those, use it.
+than `smb2` (multi-channel, QUIC, RDMA). If you need those, use it.
 
 But for the common case (connect to a NAS, move files around), `smb2` is a better fit:
 

benchmarks/smb/src/smb2_runner.rs

@@ -26,6 +26,7 @@ pub async fn connect(target: &Target) -> Result<(SmbClient, Tree), String> {
         auto_reconnect: false,
         compression: true,
         dfs_enabled: true,
+        dfs_target_overrides: std::collections::HashMap::new(),
     };
 
     let mut client = SmbClient::connect(config)

docs/migration-from-smb-crate.md

@@ -48,6 +48,7 @@ let mut client = smb2::SmbClient::connect(smb2::ClientConfig {
     auto_reconnect: false,
     compression: true,
     dfs_enabled: true,
+    dfs_target_overrides: std::collections::HashMap::new(),
 }).await?;
 ```
 

src/client/CLAUDE.md

@@ -122,3 +122,6 @@ Tree-level encryption: `connect_share()` checks the share's encrypt flag and act
 - **Compound encryption wraps the entire chain**: One TRANSFORM_HEADER for all sub-requests concatenated, not per sub-request.
 - **Share-level encryption**: If a share has `SMB2_SHAREFLAG_ENCRYPT_DATA`, encryption is activated even if the session didn't require it.
 - **FileDownload/FileUpload can leak handles on drop**: Rust has no async drop. If not consumed fully, the file handle leaks. The types log a warning.
+- **DFS paths must include server\share prefix**: When `SMB2_FLAGS_DFS_OPERATIONS` is set, the server expects the path to start with `server\share\` (MS-SMB2 3.2.4.3). `Tree::format_path()` handles this automatically for DFS shares. Without the prefix, Samba strips the first two path components, leading to wrong file opens.
+- **DFS redirect changes the tree in-place**: After a DFS redirect, `tree.server`, `tree.share_name`, and `tree.tree_id` all change. Subsequent operations on the same tree use the target server directly -- they must use target-relative paths, not the original DFS paths.
+- **tree.server stores addr:port**: The `server` field on `Tree` stores the full `addr:port` string (not just hostname) so `connection_for_tree` can distinguish servers that share the same hostname but use different ports.

src/client/mod.rs

@@ -78,6 +78,16 @@ pub struct ClientConfig {
     /// connect to the target server, and retry the operation.
     /// Default: true.
     pub dfs_enabled: bool,
+    /// Override addresses for DFS target servers.
+    ///
+    /// Maps server hostnames (as they appear in DFS referrals) to
+    /// `host:port` socket addresses. Useful when DFS targets use
+    /// internal hostnames that the client can't resolve, or when
+    /// port mapping is needed (for example, Docker test environments).
+    ///
+    /// Default: empty (use the server hostname from the referral
+    /// with port 445).
+    pub dfs_target_overrides: std::collections::HashMap<String, String>,
 }
 
 /// A connection to a specific server with its authenticated session.
@@ -137,7 +147,7 @@ impl SmbClient {
             conn.compression_enabled()
         );
 
-        let primary_server = conn.server_name().to_string();
+        let primary_server = config.addr.clone();
 
         Ok(SmbClient {
             config,
@@ -152,7 +162,7 @@ impl SmbClient {
     /// Connect using an existing connection and session (for testing).
     #[cfg(test)]
     pub(crate) fn from_parts(config: ClientConfig, conn: Connection, session: Session) -> Self {
-        let primary_server = conn.server_name().to_string();
+        let primary_server = config.addr.clone();
         SmbClient {
             config,
             conn,
@@ -178,7 +188,8 @@ impl SmbClient {
     /// and encryption is not already active, encryption is activated
     /// using the session's keys.
     pub async fn connect_share(&mut self, share_name: &str) -> Result<Tree> {
-        let tree = Tree::connect(&mut self.conn, share_name).await?;
+        let mut tree = Tree::connect(&mut self.conn, share_name).await?;
+        tree.server = self.primary_server.clone();
 
         // Activate encryption if the share requires it and it's not already active.
         // Fall back to AES-128-CCM if the server didn't send an encryption
@@ -230,7 +241,7 @@ impl SmbClient {
         )
         .await?;
 
-        self.primary_server = conn.server_name().to_string();
+        self.primary_server = self.config.addr.clone();
         self.conn = conn;
         self.session = session;
         self.extra_connections.clear();
@@ -305,9 +316,16 @@ impl SmbClient {
         tree: &mut Tree,
         original_path: &str,
     ) -> Result<String> {
-        let server = tree.server.clone();
+        // Extract hostname (strip port) for UNC path construction.
+        let hostname = tree
+            .server
+            .split(':')
+            .next()
+            .unwrap_or(&tree.server)
+            .to_string();
         let share = tree.share_name.clone();
-        let unc_path = format!("\\\\{}\\{}\\{}", server, share, original_path);
+        let normalized = original_path.replace('/', "\\");
+        let unc_path = format!("\\\\{}\\{}\\{}", hostname, share, normalized);
 
         debug!("dfs: resolving {}", unc_path);
 
@@ -329,7 +347,12 @@ impl SmbClient {
         // Try each target (multi-target failover).
         let mut last_error = None;
         for resolved in &resolved_list {
-            let target_addr = format!("{}:{}", resolved.server, resolved.port);
+            let target_addr = self
+                .config
+                .dfs_target_overrides
+                .get(&resolved.server)
+                .cloned()
+                .unwrap_or_else(|| format!("{}:{}", resolved.server, resolved.port));
 
             // Get or create connection to target server.
             match self.ensure_connection(&target_addr).await {
@@ -402,7 +425,12 @@ impl SmbClient {
                 .conn
         };
 
-        Tree::connect(conn, share).await
+        let mut tree = Tree::connect(conn, share).await?;
+        // Override server to the full addr:port so connection_for_tree
+        // can distinguish targets that share the same hostname but
+        // use different ports (for example, Docker port-mapped containers).
+        tree.server = target_addr.to_string();
+        Ok(tree)
     }
 
     /// Check whether a DFS retry should be attempted for the given error.
@@ -1023,6 +1051,7 @@ pub async fn connect(addr: &str, username: &str, password: &str) -> Result<SmbCl
         auto_reconnect: false,
         compression: true,
         dfs_enabled: true,
+        dfs_target_overrides: std::collections::HashMap::new(),
     })
     .await
 }
@@ -1175,6 +1204,7 @@ mod tests {
             auto_reconnect: false,
             compression: true,
             dfs_enabled: true,
+            dfs_target_overrides: std::collections::HashMap::new(),
         };
 
         SmbClient::from_parts(config, conn, session)
@@ -1293,6 +1323,7 @@ mod tests {
             auto_reconnect: true,
             compression: true,
             dfs_enabled: true,
+            dfs_target_overrides: std::collections::HashMap::new(),
         };
 
         let client = SmbClient::from_parts(config, conn, session);