ref(core): Encapsulate lazy dir creation in a LazyDirectory value object (JAVA-613)

Replace the duplicated "create the dir if it does not exist" idiom in the
envelope cache, outbox file observer, and startup-crash-marker paths with a
single LazyDirectory type that materializes the directory on first access.

CacheStrategy now owns its directory as a LazyDirectory: write paths call
getOrCreate(), while path-building and validity checks use getFile() so they
do not create the directory as a side effect.

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

Author: runningcode

sentry-android-core/src/main/java/io/sentry/android/core/EnvelopeFileObserverIntegration.java

@@ -10,9 +10,9 @@
 import io.sentry.SentryLevel;
 import io.sentry.SentryOptions;
 import io.sentry.util.AutoClosableReentrantLock;
+import io.sentry.util.LazyDirectory;
 import io.sentry.util.Objects;
 import java.io.Closeable;
-import java.io.File;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 import org.jetbrains.annotations.TestOnly;
@@ -68,12 +68,9 @@ private void startOutboxSender(
       final @NotNull IScopes scopes,
       final @NotNull SentryOptions options,
       final @NotNull String path) {
-    // Create the outbox dir lazily here (on the executor) so the observer can watch it for
-    // envelopes written by hybrid SDKs, instead of blocking Sentry.init on the mkdirs.
-    final File outboxDir = new File(path);
-    if (!outboxDir.isDirectory()) {
-      outboxDir.mkdirs();
-    }
+    // Materialize the outbox dir here (on the executor) so the observer can watch it for envelopes
+    // written by hybrid SDKs, instead of blocking Sentry.init on the mkdirs.
+    new LazyDirectory(path).getOrCreate();
 
     final OutboxSender outboxSender =
         new OutboxSender(

sentry-android-core/src/main/java/io/sentry/android/core/cache/AndroidEnvelopeCache.java

@@ -18,6 +18,7 @@
 import io.sentry.transport.ICurrentDateProvider;
 import io.sentry.util.FileUtils;
 import io.sentry.util.HintUtils;
+import io.sentry.util.LazyDirectory;
 import io.sentry.util.Objects;
 import java.io.File;
 import java.io.FileNotFoundException;
@@ -93,7 +94,7 @@ private boolean storeInternalAndroid(@NotNull SentryEnvelope envelope, @NotNull
 
   @TestOnly
   public @NotNull File getDirectory() {
-    return directory;
+    return directory.getFile();
   }
 
   private void writeStartupCrashMarkerFile() {
@@ -106,14 +107,11 @@ private void writeStartupCrashMarkerFile() {
           .log(DEBUG, "Outbox path is null, the startup crash marker file will not be written");
       return;
     }
-    final File crashMarkerFile = new File(outboxPath, STARTUP_CRASH_MARKER_FILE);
+    // The outbox dir is no longer created during Sentry.init, so materialize it here in case the
+    // native SDK (which normally creates it) is disabled.
+    final File outboxDir = new LazyDirectory(outboxPath).getOrCreate();
+    final File crashMarkerFile = new File(outboxDir, STARTUP_CRASH_MARKER_FILE);
     try {
-      // The outbox dir is no longer created during Sentry.init, so ensure it exists here in case
-      // the native SDK (which normally creates it) is disabled.
-      final File outboxDir = crashMarkerFile.getParentFile();
-      if (outboxDir != null && !outboxDir.isDirectory()) {
-        outboxDir.mkdirs();
-      }
       crashMarkerFile.createNewFile();
     } catch (Throwable e) {
       options.getLogger().log(ERROR, "Error writing the startup crash marker file to the disk", e);

sentry/api/sentry.api

@@ -7757,6 +7757,12 @@ public final class io/sentry/util/JsonSerializationUtils {
 	public static fun calendarToMap (Ljava/util/Calendar;)Ljava/util/Map;
 }
 
+public final class io/sentry/util/LazyDirectory {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getFile ()Ljava/io/File;
+	public fun getOrCreate ()Ljava/io/File;
+}
+
 public final class io/sentry/util/LazyEvaluator {
 	public fun <init> (Lio/sentry/util/LazyEvaluator$Evaluator;)V
 	public fun getValue ()Ljava/lang/Object;

sentry/src/main/java/io/sentry/cache/CacheStrategy.java

@@ -10,6 +10,7 @@
 import io.sentry.SentryOptions;
 import io.sentry.Session;
 import io.sentry.clientreport.DiscardReason;
+import io.sentry.util.LazyDirectory;
 import io.sentry.util.LazyEvaluator;
 import io.sentry.util.Objects;
 import java.io.BufferedInputStream;
@@ -39,7 +40,7 @@ abstract class CacheStrategy {
   protected @NotNull SentryOptions options;
   protected final @NotNull LazyEvaluator<ISerializer> serializer =
       new LazyEvaluator<>(() -> options.getSerializer());
-  protected final @NotNull File directory;
+  protected final @NotNull LazyDirectory directory;
   private final int maxSize;
 
   CacheStrategy(
@@ -49,7 +50,7 @@ abstract class CacheStrategy {
     Objects.requireNonNull(directoryPath, "Directory is required.");
     this.options = Objects.requireNonNull(options, "SentryOptions is required.");
 
-    this.directory = new File(directoryPath);
+    this.directory = new LazyDirectory(directoryPath);
 
     this.maxSize = maxSize;
   }
@@ -60,13 +61,12 @@ abstract class CacheStrategy {
    * @return true if valid and has permissions or false otherwise
    */
   protected boolean isDirectoryValid() {
-    if (!directory.isDirectory() || !directory.canWrite() || !directory.canRead()) {
+    final File dir = directory.getFile();
+    if (!dir.isDirectory() || !dir.canWrite() || !dir.canRead()) {
       options
           .getLogger()
           .log(
-              ERROR,
-              "The directory for caching files is inaccessible.: %s",
-              directory.getAbsolutePath());
+              ERROR, "The directory for caching files is inaccessible.: %s", dir.getAbsolutePath());
       return false;
     }
     return true;

sentry/src/main/java/io/sentry/cache/EnvelopeCache.java

@@ -110,14 +110,12 @@ private boolean storeInternal(final @NotNull SentryEnvelope envelope, final @Not
     Objects.requireNonNull(envelope, "Envelope is required.");
 
     // Create the cache dir lazily on the first write so Sentry.init doesn't block on the mkdirs.
-    if (!directory.isDirectory()) {
-      directory.mkdirs();
-    }
+    final String directoryPath = directory.getOrCreate().getAbsolutePath();
 
     rotateCacheIfNeeded(allEnvelopeFiles());
 
-    final File currentSessionFile = getCurrentSessionFile(directory.getAbsolutePath());
-    final File previousSessionFile = getPreviousSessionFile(directory.getAbsolutePath());
+    final File currentSessionFile = getCurrentSessionFile(directoryPath);
+    final File previousSessionFile = getPreviousSessionFile(directoryPath);
 
     if (HintUtils.hasType(hint, SessionEnd.class)) {
       if (!currentSessionFile.delete()) {
@@ -204,7 +202,7 @@ private boolean storeInternal(final @NotNull SentryEnvelope envelope, final @Not
   @SuppressWarnings("JavaUtilDate")
   private void tryEndPreviousSession(final @NotNull Hint hint) {
     final Object sdkHint = HintUtils.getSentrySdkHint(hint);
-    final File previousSessionFile = getPreviousSessionFile(directory.getAbsolutePath());
+    final File previousSessionFile = getPreviousSessionFile(directory.getFile().getAbsolutePath());
 
     if (previousSessionFile.exists()) {
       options.getLogger().log(WARNING, "Previous session is not ended, we'd need to end it.");
@@ -390,7 +388,7 @@ public void discard(final @NotNull SentryEnvelope envelope) {
         fileNameMap.put(envelope, fileName);
       }
 
-      return new File(directory.getAbsolutePath(), fileName);
+      return new File(directory.getFile().getAbsolutePath(), fileName);
     }
   }
 
@@ -436,7 +434,7 @@ public void discard(final @NotNull SentryEnvelope envelope) {
     if (isDirectoryValid()) {
       // lets filter the session.json here
       final File[] files =
-          directory.listFiles((__, fileName) -> fileName.endsWith(SUFFIX_ENVELOPE_FILE));
+          directory.getFile().listFiles((__, fileName) -> fileName.endsWith(SUFFIX_ENVELOPE_FILE));
       if (files != null) {
         return files;
       }

sentry/src/main/java/io/sentry/util/LazyDirectory.java

@@ -0,0 +1,33 @@
+package io.sentry.util;
+
+import java.io.File;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * A filesystem directory that is created on demand rather than up front, so the (potentially
+ * blocking) {@code mkdirs()} runs on the thread that first writes into it instead of on the SDK
+ * init thread.
+ */
+@ApiStatus.Internal
+public final class LazyDirectory {
+
+  private final @NotNull File file;
+
+  public LazyDirectory(final @NotNull String path) {
+    this.file = new File(path);
+  }
+
+  /** Returns the directory without touching the filesystem. */
+  public @NotNull File getFile() {
+    return file;
+  }
+
+  /** Returns the directory, creating it and any missing parents if it does not exist yet. */
+  public @NotNull File getOrCreate() {
+    if (!file.isDirectory()) {
+      file.mkdirs();
+    }
+    return file;
+  }
+}

sentry/src/test/java/io/sentry/cache/EnvelopeCacheTest.kt

@@ -466,7 +466,7 @@ class EnvelopeCacheTest {
     cache.store(envelopeA, Hint())
     cache.store(envelopeB, Hint())
 
-    assertEquals(2, cache.directory.list()?.size)
+    assertEquals(2, cache.directory.file.list()?.size)
   }
 
   @Test

sentry/src/test/java/io/sentry/util/LazyDirectoryTest.kt

@@ -0,0 +1,35 @@
+package io.sentry.util
+
+import com.google.common.truth.Truth.assertThat
+import java.nio.file.Files
+import kotlin.test.Test
+
+class LazyDirectoryTest {
+  @Test
+  fun `getFile does not create the directory`() {
+    val path = Files.createTempDirectory("lazy-dir-test").resolve("outbox")
+    val lazyDirectory = LazyDirectory(path.toString())
+
+    assertThat(lazyDirectory.file.exists()).isFalse()
+  }
+
+  @Test
+  fun `getOrCreate creates the directory and any missing parents`() {
+    val path = Files.createTempDirectory("lazy-dir-test").resolve("nested").resolve("outbox")
+    val lazyDirectory = LazyDirectory(path.toString())
+
+    val created = lazyDirectory.getOrCreate()
+
+    assertThat(created.isDirectory).isTrue()
+    assertThat(created.absolutePath).isEqualTo(path.toFile().absolutePath)
+  }
+
+  @Test
+  fun `getOrCreate is idempotent when the directory already exists`() {
+    val path = Files.createTempDirectory("lazy-dir-test").resolve("outbox")
+    val lazyDirectory = LazyDirectory(path.toString())
+
+    assertThat(lazyDirectory.getOrCreate().isDirectory).isTrue()
+    assertThat(lazyDirectory.getOrCreate().isDirectory).isTrue()
+  }
+}