Fix FtpFileObject.exists() returning true for root-level folders after connection drop (#757)

* [VFS] Fix FtpFileObject.exists() returning true for root-level folders after connection drop

setFTPFile() blindly assumed that root-level directories (where
getParent() returns null) always exist by creating a synthetic FTPFile
with DIRECTORY_TYPE. This caused exists() to return true even after the
FTP connection was lost.

Fix: add verifyRootDirectory() which uses CWD "." to verify the
directory exists on the server. CWD "." checks the current directory
(the logical VFS root) which is correct for both configurations:
- userDirIsRoot=true: current dir is the user's login directory
- userDirIsRoot=false: current dir is "/" (set by the factory CWD)

Using "." rather than "/" avoids a semantic mismatch on non-chroot
servers with userDirIsRoot=true, where "/" would go to the actual
server root instead of the user's login directory.

Add FtpClient.changeDirectory() default method and FTPClientWrapper
implementation to support CWD from FtpFileObject.

* Fix Javadoc since tag.

---------

Co-authored-by: Gary Gregory <garydgregory@users.noreply.github.com>

Author: ilang

commons-vfs2/src/main/java/org/apache/commons/vfs2/provider/ftp/FTPClientWrapper.java

@@ -64,6 +64,17 @@ protected FTPClientWrapper(final GenericFileName rootFileName, final FileSystemO
         getFtpClient(); // fail-fast
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean changeDirectory(final String relPath) throws IOException {
+        try {
+            return getFtpClient().changeWorkingDirectory(relPath);
+        } catch (final IOException e) {
+            disconnect();
+            return getFtpClient().changeWorkingDirectory(relPath);
+        }
+    }
+
     @Override
     public boolean abort() throws IOException {
         try {

commons-vfs2/src/main/java/org/apache/commons/vfs2/provider/ftp/FtpClient.java

@@ -58,6 +58,18 @@ public interface FtpClient {
      */
     boolean completePendingCommand() throws IOException;
 
+    /**
+     * Changes the current working directory of the FTP session.
+     *
+     * @param relPath The pathname of the directory to change to.
+     * @return true if successfully completed, false if not.
+     * @throws IOException If an I/O error occurs.
+     * @since 2.12.0
+     */
+    default boolean changeDirectory(String relPath) throws IOException {
+        return false;
+    }
+
     /**
      * Deletes a file on the FTP server.
      *

commons-vfs2/src/main/java/org/apache/commons/vfs2/provider/ftp/FtpFileObject.java

@@ -631,11 +631,39 @@ private void setFTPFile(final boolean flush) throws IOException {
             if (parent != null) {
                 newFileInfo = parent.getChildFile(UriParser.decode(getName().getBaseName()), flush);
             } else {
-                // Assume the root is a directory and exists
-                newFileInfo = new FTPFile();
-                newFileInfo.setType(FTPFile.DIRECTORY_TYPE);
+                // Root-level resource: no parent to query via getChildFile().
+                // Verify the directory exists using CWD, which is a lightweight
+                // control-channel command (no data transfer). Previously this
+                // assumed the root always exists, causing exists() to return true
+                // for non-existent FTP folders.
+                newFileInfo = verifyRootDirectory();
             }
             ftpFile = newFileInfo == null ? UNKNOWN : newFileInfo;
         }
     }
+
+    /**
+     * Verifies a root-level FTP directory exists by attempting to CWD into it.
+     * Returns an FTPFile with DIRECTORY_TYPE if CWD succeeds, or {@code null} if it fails.
+     * <p>
+     * Uses CWD "." (the current directory) rather than CWD "/" to verify
+     * the logical root. With {@code userDirIsRoot=true}, the logical root
+     * is the user's login directory, not the server root "/".
+     * </p>
+     */
+    private FTPFile verifyRootDirectory() throws IOException {
+        final FtpClient client = getAbstractFileSystem().getClient();
+        try {
+            // relPath is always null for the root (constructor maps "." to null),
+            // so this always resolves to CWD ".". The relPath check is defensive.
+            if (client.changeDirectory(relPath != null ? relPath : ".")) {
+                final FTPFile result = new FTPFile();
+                result.setType(FTPFile.DIRECTORY_TYPE);
+                return result;
+            }
+            return null;
+        } finally {
+            getAbstractFileSystem().putClient(client);
+        }
+    }
 }

commons-vfs2/src/test/java/org/apache/commons/vfs2/provider/ftp/FtpRootExistsOnDisconnectTest.java

@@ -0,0 +1,108 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.vfs2.provider.ftp;
+
+import java.time.Duration;
+
+import org.apache.commons.vfs2.FileObject;
+import org.apache.commons.vfs2.FileSystemException;
+import org.apache.commons.vfs2.FileSystemOptions;
+import org.apache.commons.vfs2.VfsTestUtils;
+import org.apache.commons.vfs2.impl.DefaultFileSystemManager;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Tests {@link FtpFileObject#exists()} for root-level FTP folders where {@code getParent()} returns {@code null}.
+ * <p>
+ * Regression test for the bug in {@link FtpFileObject} where {@code setFTPFile()} blindly assumed that root-level
+ * directories exist ({@code setType(DIRECTORY_TYPE)}) without verifying on the server. This caused {@code exists()} to
+ * return {@code true} even after the FTP connection was lost, while non-root folders correctly reported the connection
+ * failure via {@link FileSystemException}.
+ * </p>
+ */
+public class FtpRootExistsOnDisconnectTest {
+
+    @BeforeEach
+    public void setUp() throws Exception {
+        FtpProviderTest.setUpClass(VfsTestUtils.getTestDirectory(), null, null);
+    }
+
+    @AfterEach
+    public void tearDown() {
+        FtpProviderTest.tearDownClass();
+    }
+
+    private static FileSystemOptions createOptions() {
+        final FileSystemOptions options = new FileSystemOptions();
+        final FtpFileSystemConfigBuilder builder = FtpFileSystemConfigBuilder.getInstance();
+        builder.setUserDirIsRoot(options, true);
+        builder.setPassiveMode(options, true);
+        builder.setConnectTimeout(options, Duration.ofSeconds(10));
+        return options;
+    }
+
+    /**
+     * Tests that {@code exists()} returns {@code true} when the server is running, and does not silently return
+     * {@code true} after the FTP connection is lost.
+     * <p>
+     * With {@code userDirIsRoot=true}, the root's {@code getParent()} returns {@code null}, which triggers the
+     * {@code verifyRootDirectory()} code path in {@code setFTPFile()}.
+     * </p>
+     * <p>
+     * Before the fix, {@code setFTPFile()} set {@code type=DIRECTORY} when {@code getParent()} returned {@code null},
+     * without contacting the server. After the fix, {@code setFTPFile()} uses CWD to verify, which fails on a dead
+     * connection.
+     * </p>
+     */
+    @Test
+    public void testRootExistsFailsWhenConnectionDropped() throws Exception {
+        try (final DefaultFileSystemManager manager = new DefaultFileSystemManager()) {
+            manager.addProvider("ftp", new FtpFileProvider());
+            manager.init();
+            final FileObject root = manager.resolveFile(FtpProviderTest.getConnectionUri(), createOptions());
+
+            // Verify precondition: with userDirIsRoot=true, getParent() returns null,
+            // which is the code path this test exercises.
+            Assertions.assertNull(root.getParent(),
+                "Root folder's getParent() should return null with userDirIsRoot=true");
+
+            // Verify the root exists initially.
+            Assertions.assertTrue(root.exists(), "Root should exist while server is running");
+
+            // Stop the server to simulate a connection drop.
+            FtpProviderTest.tearDownClass();
+
+            // exists() must throw FileSystemException on the dead connection.
+            // The first call may still succeed if the MINA server processes one last
+            // CWD during graceful shutdown, but the second call must fail.
+            boolean threwException = false;
+            for (int i = 0; i < 2 && !threwException; i++) {
+                root.refresh();
+                try {
+                    root.exists();
+                } catch (final FileSystemException expected) {
+                    threwException = true;
+                }
+            }
+            Assertions.assertTrue(threwException,
+                "exists() must throw FileSystemException after FTP connection is lost");
+        }
+    }
+}