feat(extend-app-start): [1/4] Add IAppStartExtender bridge

sentry/api/sentry.api

@@ -796,6 +796,12 @@ public final class io/sentry/HubScopesWrapper : io/sentry/IHub {
 	public fun withScope (Lio/sentry/ScopeCallback;)V
 }
 
+public abstract interface class io/sentry/IAppStartExtender {
+	public abstract fun extendAppStart ()V
+	public abstract fun finishExtendedAppStart ()V
+	public abstract fun getExtendedAppStartSpan ()Lio/sentry/ISpan;
+}
+
 public abstract interface class io/sentry/IConnectionStatusProvider : java/io/Closeable {
 	public abstract fun addConnectionStatusObserver (Lio/sentry/IConnectionStatusProvider$IConnectionStatusObserver;)Z
 	public abstract fun getConnectionStatus ()Lio/sentry/IConnectionStatusProvider$ConnectionStatus;
@@ -1543,6 +1549,13 @@ public final class io/sentry/MonitorScheduleUnit : java/lang/Enum {
 	public static fun values ()[Lio/sentry/MonitorScheduleUnit;
 }
 
+public final class io/sentry/NoOpAppStartExtender : io/sentry/IAppStartExtender {
+	public fun extendAppStart ()V
+	public fun finishExtendedAppStart ()V
+	public fun getExtendedAppStartSpan ()Lio/sentry/ISpan;
+	public static fun getInstance ()Lio/sentry/NoOpAppStartExtender;
+}
+
 public final class io/sentry/NoOpCompositePerformanceCollector : io/sentry/CompositePerformanceCollector {
 	public fun close ()V
 	public static fun getInstance ()Lio/sentry/NoOpCompositePerformanceCollector;
@@ -3603,6 +3616,7 @@ public class io/sentry/SentryOptions {
 	public fun addScopeObserver (Lio/sentry/IScopeObserver;)V
 	public static fun empty ()Lio/sentry/SentryOptions;
 	public fun findPersistingScopeObserver ()Lio/sentry/cache/PersistingScopeObserver;
+	public fun getAppStartExtender ()Lio/sentry/IAppStartExtender;
 	public fun getBackpressureMonitor ()Lio/sentry/backpressure/IBackpressureMonitor;
 	public fun getBeforeBreadcrumb ()Lio/sentry/SentryOptions$BeforeBreadcrumbCallback;
 	public fun getBeforeEnvelopeCallback ()Lio/sentry/SentryOptions$BeforeEnvelopeCallback;
@@ -3749,6 +3763,7 @@ public class io/sentry/SentryOptions {
 	public fun isTraceSampling ()Z
 	public fun isTracingEnabled ()Z
 	public fun merge (Lio/sentry/ExternalOptions;)V
+	public fun setAppStartExtender (Lio/sentry/IAppStartExtender;)V
 	public fun setAttachServerName (Z)V
 	public fun setAttachStacktrace (Z)V
 	public fun setAttachThreads (Z)V

sentry/src/main/java/io/sentry/IAppStartExtender.java

@@ -0,0 +1,34 @@
+package io.sentry;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Bridges the {@code Sentry.extendAppStart()} / {@code Sentry.finishExtendedAppStart()} / {@code
+ * Sentry.getExtendedAppStartSpan()} static API to the Android implementation. The default
+ * implementation ({@link NoOpAppStartExtender}) does nothing, so the API is a no-op on platforms
+ * that don't provide an app start measurement.
+ */
+@ApiStatus.Internal
+public interface IAppStartExtender {
+
+  /**
+   * Begins extending the app start. Intended to be called from {@code Application.onCreate} right
+   * after SDK init. No-ops if the app start already finished, none is in progress, or it was
+   * already extended (first call wins).
+   */
+  void extendAppStart();
+
+  /**
+   * Finishes the extended app start, allowing the app start transaction to complete. No-ops if the
+   * app start was not extended or this was already called.
+   */
+  void finishExtendedAppStart();
+
+  /**
+   * Returns the active extended app start span to attach child spans to, or {@code null} when the
+   * app start is not currently being extended.
+   */
+  @Nullable
+  ISpan getExtendedAppStartSpan();
+}

sentry/src/main/java/io/sentry/NoOpAppStartExtender.java

@@ -0,0 +1,28 @@
+package io.sentry;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+@ApiStatus.Internal
+public final class NoOpAppStartExtender implements IAppStartExtender {
+
+  private static final @NotNull NoOpAppStartExtender instance = new NoOpAppStartExtender();
+
+  private NoOpAppStartExtender() {}
+
+  public static @NotNull NoOpAppStartExtender getInstance() {
+    return instance;
+  }
+
+  @Override
+  public void extendAppStart() {}
+
+  @Override
+  public void finishExtendedAppStart() {}
+
+  @Override
+  public @Nullable ISpan getExtendedAppStartSpan() {
+    return null;
+  }
+}

sentry/src/main/java/io/sentry/SentryOptions.java

@@ -529,6 +529,9 @@ public class SentryOptions {
   private @NotNull FullyDisplayedReporter fullyDisplayedReporter =
       FullyDisplayedReporter.getInstance();
 
+  /** Bridges the app start extension API to the Android implementation. */
+  private @NotNull IAppStartExtender appStartExtender = NoOpAppStartExtender.getInstance();
+
   private @NotNull IConnectionStatusProvider connectionStatusProvider =
       new NoOpConnectionStatusProvider();
 
@@ -2653,6 +2656,21 @@ public void setFullyDisplayedReporter(
     this.fullyDisplayedReporter = fullyDisplayedReporter;
   }
 
+  /**
+   * Gets the app start extender, which bridges the app start extension API to its implementation.
+   *
+   * @return the app start extender.
+   */
+  @ApiStatus.Internal
+  public @NotNull IAppStartExtender getAppStartExtender() {
+    return appStartExtender;
+  }
+
+  @ApiStatus.Internal
+  public void setAppStartExtender(final @NotNull IAppStartExtender appStartExtender) {
+    this.appStartExtender = appStartExtender;
+  }
+
   /**
    * Whether OPTIONS requests should be traced.
    *

sentry/src/test/java/io/sentry/NoOpAppStartExtenderTest.kt

@@ -0,0 +1,17 @@
+package io.sentry
+
+import kotlin.test.Test
+import kotlin.test.assertNull
+
+class NoOpAppStartExtenderTest {
+  private val extender = NoOpAppStartExtender.getInstance()
+
+  @Test fun `extendAppStart does not throw`() = extender.extendAppStart()
+
+  @Test fun `finishExtendedAppStart does not throw`() = extender.finishExtendedAppStart()
+
+  @Test
+  fun `getExtendedAppStartSpan returns null`() {
+    assertNull(extender.extendedAppStartSpan)
+  }
+}

sentry/src/test/java/io/sentry/SentryOptionsTest.kt

@@ -645,6 +645,26 @@ class SentryOptionsTest {
     assertEquals(FullyDisplayedReporter.getInstance(), SentryOptions().fullyDisplayedReporter)
   }
 
+  @Test
+  fun `when options are initialized, appStartExtender defaults to noop`() {
+    assertEquals(NoOpAppStartExtender.getInstance(), SentryOptions().appStartExtender)
+  }
+
+  @Test
+  fun `when appStartExtender is set, it's returned as well`() {
+    val options = SentryOptions()
+    val customExtender =
+      object : IAppStartExtender {
+        override fun extendAppStart() = Unit
+
+        override fun finishExtendedAppStart() = Unit
+
+        override fun getExtendedAppStartSpan(): ISpan = NoOpSpan.getInstance()
+      }
+    options.appStartExtender = customExtender
+    assertEquals(customExtender, options.appStartExtender)
+  }
+
   @Test
   fun `when options are initialized, connectionStatusProvider is not null and default to noop`() {
     assertNotNull(SentryOptions().connectionStatusProvider)