test(qwp): dedupe SF tmp-dir fixtures; name the sparse-tail cause in the FSN-gap error

Follow-up on the PR #64 review minors.

m3: MmapSegmentTest and MmapSegmentRecoveryFaultTest carried verbatim
copies of the native tmp-dir setUp/tearDown (~28 lines each). Hoist them
into TestUtils.createTmpDir / removeTmpDir so both classes and any future
SF cursor test share one implementation.

m5: the FSN-gap MmapSegmentException fired on a sealed segment that
under-recovered (a sparse/unbacked or media-truncated tail), but its
message and comment blamed only "partial-write/manual-deletion". Name the
truncated-tail cause and ask operators to check disk health, matching the
diagnostics-honesty wording already added to the scanFrames WARN.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: puzpuzpuz

core/src/main/java/io/questdb/client/cutlass/qwp/client/sf/cursor/SegmentRing.java

@@ -265,8 +265,12 @@ public static SegmentRing openExisting(String sfDir, long maxBytesPerSegment) {
             // pivot would degrade back to O(N²) on exactly that common case.
             sortByBaseSeq(opened, 0, opened.size());
             // Sanity: the recovered segments must form a contiguous FSN range.
-            // Detect gaps so a partial-write/manual-deletion mishap doesn't
-            // silently produce duplicate or missing FSNs after recovery.
+            // Detect gaps so they don't silently produce duplicate or missing
+            // FSNs after recovery. A gap means a segment went missing (a
+            // manual deletion) or a sealed segment under-recovered -- its tail
+            // was cut short by a sparse/unbacked page or a mid-file media error
+            // (bad sector), the same class of fault scanFrames tolerates on the
+            // active segment but which corrupts the range on a sealed one.
             for (int i = 1, n = opened.size(); i < n; i++) {
                 MmapSegment prev = opened.get(i - 1);
                 MmapSegment curr = opened.get(i);
@@ -276,7 +280,10 @@ public static SegmentRing openExisting(String sfDir, long maxBytesPerSegment) {
                             "FSN gap in recovered segments: prev baseSeq=" + prev.baseSeq()
                                     + " frameCount=" + prev.frameCount()
                                     + " expected next baseSeq=" + expected
-                                    + " but got " + curr.baseSeq());
+                                    + " but got " + curr.baseSeq()
+                                    + " -- a segment was deleted, or a sealed segment's tail was"
+                                    + " truncated (sparse/unbacked page or disk media error);"
+                                    + " check disk health");
                 }
             }
             // The newest segment becomes the active. Even if it's full, that's OK:

core/src/test/java/io/questdb/client/test/cutlass/qwp/client/sf/cursor/MmapSegmentRecoveryFaultTest.java

@@ -34,8 +34,6 @@
 import org.junit.Before;
 import org.junit.Test;
 
-import java.nio.file.Paths;
-
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertTrue;
 import static org.junit.Assert.fail;
@@ -81,32 +79,12 @@ public class MmapSegmentRecoveryFaultTest {
 
     @Before
     public void setUp() {
-        tmpDir = Paths.get(System.getProperty("java.io.tmpdir"),
-                "qdb-mmap-recover-" + System.nanoTime()).toString();
-        assertEquals(0, Files.mkdir(tmpDir, Files.DIR_MODE_DEFAULT));
+        tmpDir = TestUtils.createTmpDir("qdb-mmap-recover-");
     }
 
     @After
     public void tearDown() {
-        if (tmpDir == null) {
-            return;
-        }
-        long find = Files.findFirst(tmpDir);
-        if (find > 0) {
-            try {
-                int rc = 1;
-                while (rc > 0) {
-                    String name = Files.utf8ToString(Files.findName(find));
-                    if (name != null && !".".equals(name) && !"..".equals(name)) {
-                        Files.remove(tmpDir + "/" + name);
-                    }
-                    rc = Files.findNext(find);
-                }
-            } finally {
-                Files.findClose(find);
-            }
-        }
-        Files.remove(tmpDir);
+        TestUtils.removeTmpDir(tmpDir);
     }
 
     /**

core/src/test/java/io/questdb/client/test/cutlass/qwp/client/sf/cursor/MmapSegmentTest.java

@@ -35,8 +35,6 @@
 import org.junit.Before;
 import org.junit.Test;
 
-import java.nio.file.Paths;
-
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertNotEquals;
@@ -49,32 +47,12 @@ public class MmapSegmentTest {
 
     @Before
     public void setUp() {
-        tmpDir = Paths.get(System.getProperty("java.io.tmpdir"),
-                "qdb-mmap-seg-" + System.nanoTime()).toString();
-        assertEquals(0, Files.mkdir(tmpDir, Files.DIR_MODE_DEFAULT));
+        tmpDir = TestUtils.createTmpDir("qdb-mmap-seg-");
     }
 
     @After
     public void tearDown() {
-        if (tmpDir == null) {
-            return;
-        }
-        long find = Files.findFirst(tmpDir);
-        if (find > 0) {
-            try {
-                int rc = 1;
-                while (rc > 0) {
-                    String name = Files.utf8ToString(Files.findName(find));
-                    if (name != null && !".".equals(name) && !"..".equals(name)) {
-                        Files.remove(tmpDir + "/" + name);
-                    }
-                    rc = Files.findNext(find);
-                }
-            } finally {
-                Files.findClose(find);
-            }
-        }
-        Files.remove(tmpDir);
+        TestUtils.removeTmpDir(tmpDir);
     }
 
     @Test

core/src/test/java/io/questdb/client/test/tools/TestUtils.java

@@ -24,6 +24,7 @@
 
 package io.questdb.client.test.tools;
 
+import io.questdb.client.std.Files;
 import io.questdb.client.std.MemoryTag;
 import io.questdb.client.std.QuietCloseable;
 import io.questdb.client.std.Rnd;
@@ -139,6 +140,18 @@ public static long beHexToLong(String hex) {
         return Long.parseLong(reverseBeHex(hex), 16);
     }
 
+    /**
+     * Creates a unique temp directory under {@code java.io.tmpdir}, named
+     * {@code prefix + <nanoTime>}, and returns its path. Pair with
+     * {@link #removeTmpDir(String)} in {@code tearDown}.
+     */
+    public static String createTmpDir(String prefix) {
+        String dir = Paths.get(System.getProperty("java.io.tmpdir"),
+                prefix + System.nanoTime()).toString();
+        Assert.assertEquals(0, Files.mkdir(dir, Files.DIR_MODE_DEFAULT));
+        return dir;
+    }
+
     @NotNull
     public static Rnd generateRandom(Logger log) {
         return generateRandom(log, System.nanoTime(), System.currentTimeMillis());
@@ -172,6 +185,36 @@ public static String ipv4ToString(int ip) {
         return ((ip >> 24) & 0xff) + "." + ((ip >> 16) & 0xff) + "." + ((ip >> 8) & 0xff) + "." + (ip & 0xff);
     }
 
+    /**
+     * Flat (non-recursive) cleanup for a directory created by
+     * {@link #createTmpDir(String)}: removes every entry in {@code tmpDir}
+     * (the SF cursor tests only write flat {@code .sfa}/{@code .corrupt}
+     * files) and then the directory itself. A {@code null} argument is a
+     * no-op, so it is safe to call from {@code tearDown} before {@code setUp}
+     * ran.
+     */
+    public static void removeTmpDir(String tmpDir) {
+        if (tmpDir == null) {
+            return;
+        }
+        long find = Files.findFirst(tmpDir);
+        if (find > 0) {
+            try {
+                int rc = 1;
+                while (rc > 0) {
+                    String name = Files.utf8ToString(Files.findName(find));
+                    if (name != null && !".".equals(name) && !"..".equals(name)) {
+                        Files.remove(tmpDir + "/" + name);
+                    }
+                    rc = Files.findNext(find);
+                }
+            } finally {
+                Files.findClose(find);
+            }
+        }
+        Files.remove(tmpDir);
+    }
+
     /**
      * Java 8 stand-in for {@code String.repeat(int)} (added in Java 11).
      */